convez.ai
MCP ServerAutomaçãoIntermediário
MarcoAR1

BotUyo MCP Server

MarcoAR1/botuyo-mcp

Crie e gerencie agentes de IA via MCP sem deixar seu editor

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para criar e gerenciar agentes de IA diretamente de ferramentas de codificação (Cursor, VS Code, Claude Desktop) sem necessidade de clonar ou compilar. Oferece 48 ferramentas para construir, configurar e publicar agentes com autenticação OAuth integrada.

Instalação

$npx convez-ai MarcoAR1/botuyo-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Construir agentes conversacionais customizados para múltiplos tenants
  • Gerenciar estágios de conversa e fluxos de escalação com IA
  • Integrar ferramentas e canais (SearchKnowledgeBase, EscalateToHuman) em agentes

Veredito

Ferramenta robusta e bem documentada para automatizar criação de agentes IA desde o editor, com setup simplificado e autenticação segura. Destaca-se pela integração native com IDEs populares e esquema autodescritivo de 48 ferramentas.

README

A tradução para o português deste README ainda está na fila.

@botuyo/mcp — BotUyo MCP Server

Create and manage BotUyo AI agents directly from your AI coding tools — no cloning, no building.

npm version

Quickstart

For the next release's schema discovery, configuration updates, virtual tools and navigation example, see Tool contracts. The new contracts require the matching backend.

The fastest way — one command configures your editor and logs you in:

npx @botuyo/mcp setup

It auto-detects your editor (Cursor, VS Code / Antigravity, Claude Desktop), writes the MCP config, and walks you through authentication.

Manual setup

1. Add the BotUyo server to your MCP client config:

{
  "mcpServers": {
    "botuyo": {
      "command": "npx",
      "args": ["-y", "@botuyo/mcp"]
    }
  }
}

No API key goes in the config — authentication is handled by the auth/login commands below. Some clients (Cursor, VS Code) use the servers key instead of mcpServers.

ClientConfig file
Cursor.cursor/mcp.json
VS Code / Antigravity.vscode/mcp.json
Claude Desktop~/.config/claude/claude_desktop_config.json (Windows: %AppData%\Claude\claude_desktop_config.json)
Windsurf~/.codeium/windsurf/mcp_config.json

2. Authenticate once — saves a token to ~/.botuyo/credentials.json:

npx @botuyo/mcp auth     # browser OAuth (recommended)
# or
npx @botuyo/mcp login    # email + password in the terminal

The running MCP server picks up your session automatically — no restart needed. Tokens last 7 days; re-run auth or login to refresh.

Start building agents

Once connected, ask your AI assistant things like:

"Create a new agent called 'Soporte' for my tenant" "Update Mar's objective to focus on sales" "Add a welcomeStage that greets guests in Spanish" "Enable the EscalateToHuman and SearchKnowledgeBase tools on Mar" "Publish the agent"

CLI commands

npx @botuyo/mcp setup          # Configure your editor + authenticate (recommended)
npx @botuyo/mcp auth           # Login via browser (OAuth)
npx @botuyo/mcp login          # Login via email + password
npx @botuyo/mcp tenants        # List your tenants
npx @botuyo/mcp switch-tenant  # Switch the active tenant
npx @botuyo/mcp whoami         # Show the current session
npx @botuyo/mcp logout         # Clear stored credentials

The server resolves your JWT from BOTUYO_TOKEN, falling back to ~/.botuyo/credentials.json. The backend URL defaults to https://api.botuyo.com (override with BOTUYO_API_URL).

Available tools

The server exposes 48 tools. Read tools (list_*, get_*, export_*, audit_*) need viewer+; write/publish tools need developer+; channel & integration connect/configure need admin+ (see Roles).

For AI assistants / IDE agents: every tool is self-describing — its inputSchema lists the exact arguments (with required) and its description states role requirements and side effects. Discover the live catalog with the MCP tools/list request; you never need to hardcode tool names. A typical build flow is create_agent → update_agent (identity/voice) → upsert_stage (conversation graph) → update_enabled_tools / configure_agent_tool (capabilities) → publish_agent. Use example_agent to see a fully documented reference config, and audit_agent_family to validate before publishing.

Agents

ToolDescription
list_agentsList all agents in the tenant
get_agentGet an agent's full config (identity, stages, enabled tools)
get_agent_statusChannel connection status + admin link to connect missing channels
create_agentCreate a new agent
update_agentUpdate identity (tone, language, objective, custom instructions)
delete_agentSoft-delete an agent (irreversible; requires explicit confirmation)
publish_agentPublish or unpublish an agent (live vs draft)
example_agentReturn a fully documented example agent config (read-only reference)

Agent families

A family is one logical agent with a shared base config plus multiple variants (each variant stores only its overrides and is materialized into a real agent) — ideal for a single assistant offered in several levels or flavors.

ToolDescription
list_agent_familiesList agent families in the tenant
get_agent_familyGet a family's shared base + all its variants
create_agent_familyCreate a family with a shared base and an initial set of variants
update_family_baseReplace the shared base (re-materializes every variant)
add_family_variantAdd a new variant (materialized into a draft agent)
update_family_variantUpdate a variant's label / overrides / handoff targets / order
remove_family_variantRemove a variant (cannot remove the entry variant)
publish_agent_familyPublish the family and all its member agents
delete_agent_familyDelete a family and all its agents (irreversible; requires confirmation)
export_agent_familyExport a portable family JSON (base + variants) to a local file
import_agent_familyReplace a family's base + variants from JSON (full replace), or create a new family from a folder/payload
audit_agent_familyRead-only config-quality audit of one family (familyId) or all families in the tenant — flags invalid/non-canonical voices, over-long customInstructions, non-URL avatars, deprecated AI models; changes nothing

Conversation flow

ToolDescription
upsert_stageCreate or update a named stage in the agent's conversation graph

Tools & capabilities

ToolDescription
list_available_toolsList tools available to your tenant (core + custom)
update_enabled_toolsEnable/disable tools on an agent
get_tools_catalogFull tool catalog with metadata (configurable, multi-instance, schema, required integrations)
configure_agent_toolCreate/update a tool's config on an agent (single or multi-instance)
list_tool_configsList an agent's tool configs, grouped
get_tool_configView the full config of a specific tool on an agent
remove_tool_configRemove a tool's configuration

Knowledge base

ToolDescription
list_knowledge_documentsList knowledge base documents
ingest_knowledge_urlIngest a URL into the knowledge base
associate_knowledge_to_agentLink knowledge document IDs to an agent
delete_knowledge_documentDelete a knowledge document and all its chunks

Templates

ToolDescription
list_templatesList agent templates by industry
create_from_templateCreate a new agent from a template

Import / export

ToolDescription
export_agent_jsonExport an agent's full config as editable JSON
import_agent_jsonReplace an agent's full config from JSON (full overwrite)

Avatar & media

ToolDescription
list_avatarsList the free 3D avatars in the catalog
select_avatarSet a 3D avatar for an agent (catalog ID or custom .glb/.vrm URL)
upload_agent_mediaUpload a local image to the CDN as an agent's avatar/logo

Versioning

ToolDescription
list_agent_versionsList an agent's saved version snapshots
restore_agent_versionRoll back an agent to a previous version

Channels

Connect messaging channels to the tenant with their secrets. Secrets are write-only — the server stores them and never returns their values; list_channels reports only which credential keys are set. Connect/disconnect require role owner or admin.

ToolDescription
list_channelsList the tenant's channels + status. Never returns secret values — only credentialsSet (which keys are configured)
connect_channelConnect a channel (WhatsApp, Telegram, Discord, Web, …) with its credentials. Validated against the provider API and stored server-side
disconnect_channelDisconnect a channel by id (archives its open conversations)

Passing secrets safely. connect_channel accepts the secret two ways:

  • credentials — literal values, e.g. { "botToken": "123:ABC" }. Simplest, but the secret passes through the conversation/LLM.
  • credentialsFromEnv (recommended for real secrets) — a map of credential key → environment variable name, e.g. { "botToken": "MY_TG_TOKEN" }. The MCP server reads the value from its own environment (set it in your MCP client config), so the secret never appears in the chat.

Channels that require an interactive flow (WhatsApp/Instagram Embedded Signup QR/OAuth) still need admin.botuyo.com. Channels that authenticate with a static token (Telegram, Discord, WhatsApp Cloud API with an existing token, Web) can be connected here.

Integrations

Install and configure the tenant's external integrations (Shopify, PaseoLibre, Google Calendar, email SMTP, …) with their secrets, using the same write-only secret model as channels. Configure/remove require role owner or admin.

ToolDescription
list_integrationsList the integration catalog (available) + the tenant's installed integrations. Never returns secret values — only configKeys (which config keys are set)
configure_integrationInstall or update an integration with its config/secret (validated against the provider, stored server-side). Accepts literal config or configFromEnv (env-var reference)
remove_integrationUninstall an integration by id

Same two secret modes as connect_channel: literal config, or configFromEnv (map config key → env var name resolved from the MCP server environment, keeping the secret out of the chat).

Account

ToolDescription
switch_tenantSwitch the active tenant for the session

Roles

RoleReadWritePublish
owner✅✅✅
admin✅✅✅
developer✅✅✅
viewer✅❌❌

Channels & integrations: connect_channel / disconnect_channel / configure_integration / remove_integration additionally require owner or admin (a developer can build agents but not wire up channel/integration secrets).

Channel Integrations

Channels that authenticate with a static secret — Telegram (bot token), Discord (bot token), WhatsApp Cloud API (existing access token), Web — can be connected directly via the connect_channel tool (see Channels). Channels that need an interactive flow (WhatsApp/Instagram Embedded Signup with QR scans or OAuth consent) must still be connected from admin.botuyo.com.

Use get_agent_status to check which channels are connected (it links to the admin panel for any missing channel), or list_channels for the tenant-wide channel list and status.

Build from source

git clone https://github.com/MarcoAR1/botuyo-mcp.git
cd botuyo-mcp
npm install
npm run build

Test with MCP Inspector

Authenticate first (npx @botuyo/mcp login), then run:

npm run inspect

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Please note that this project follows a Code of Conduct.

Security

To report a vulnerability, see SECURITY.md.

License

MIT © BotUyo

Ver o original no GitHub

Bom para

Relacionados