# @botuyo/mcp — BotUyo MCP Server

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

[![npm version](https://img.shields.io/npm/v/@botuyo/mcp.svg)](https://www.npmjs.com/package/@botuyo/mcp)

## Quickstart

For the next release's schema discovery, configuration updates, virtual tools and navigation example, see [Tool contracts](docs/tool-contracts.md). The new contracts require the matching backend.

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

```sh
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:**

```json
{
  "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`.

| Client | Config 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`:

```sh
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

```sh
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](#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

| Tool | Description |
|---|---|
| `list_agents` | List all agents in the tenant |
| `get_agent` | Get an agent's full config (identity, stages, enabled tools) |
| `get_agent_status` | Channel connection status + admin link to connect missing channels |
| `create_agent` | Create a new agent |
| `update_agent` | Update identity (tone, language, objective, custom instructions) |
| `delete_agent` | Soft-delete an agent (irreversible; requires explicit confirmation) |
| `publish_agent` | Publish or unpublish an agent (live vs draft) |
| `example_agent` | Return 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.

| Tool | Description |
|---|---|
| `list_agent_families` | List agent families in the tenant |
| `get_agent_family` | Get a family's shared base + all its variants |
| `create_agent_family` | Create a family with a shared base and an initial set of variants |
| `update_family_base` | Replace the shared base (re-materializes every variant) |
| `add_family_variant` | Add a new variant (materialized into a draft agent) |
| `update_family_variant` | Update a variant's label / overrides / handoff targets / order |
| `remove_family_variant` | Remove a variant (cannot remove the entry variant) |
| `publish_agent_family` | Publish the family and all its member agents |
| `delete_agent_family` | Delete a family and all its agents (irreversible; requires confirmation) |
| `export_agent_family` | Export a portable family JSON (base + variants) to a local file |
| `import_agent_family` | Replace a family's base + variants from JSON (full replace), or create a new family from a folder/payload |
| `audit_agent_family` | Read-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

| Tool | Description |
|---|---|
| `upsert_stage` | Create or update a named stage in the agent's conversation graph |

### Tools & capabilities

| Tool | Description |
|---|---|
| `list_available_tools` | List tools available to your tenant (core + custom) |
| `update_enabled_tools` | Enable/disable tools on an agent |
| `get_tools_catalog` | Full tool catalog with metadata (configurable, multi-instance, schema, required integrations) |
| `configure_agent_tool` | Create/update a tool's config on an agent (single or multi-instance) |
| `list_tool_configs` | List an agent's tool configs, grouped |
| `get_tool_config` | View the full config of a specific tool on an agent |
| `remove_tool_config` | Remove a tool's configuration |

### Knowledge base

| Tool | Description |
|---|---|
| `list_knowledge_documents` | List knowledge base documents |
| `ingest_knowledge_url` | Ingest a URL into the knowledge base |
| `associate_knowledge_to_agent` | Link knowledge document IDs to an agent |
| `delete_knowledge_document` | Delete a knowledge document and all its chunks |

### Templates

| Tool | Description |
|---|---|
| `list_templates` | List agent templates by industry |
| `create_from_template` | Create a new agent from a template |

### Import / export

| Tool | Description |
|---|---|
| `export_agent_json` | Export an agent's full config as editable JSON |
| `import_agent_json` | Replace an agent's full config from JSON (full overwrite) |

### Avatar & media

| Tool | Description |
|---|---|
| `list_avatars` | List the free 3D avatars in the catalog |
| `select_avatar` | Set a 3D avatar for an agent (catalog ID or custom .glb/.vrm URL) |
| `upload_agent_media` | Upload a local image to the CDN as an agent's avatar/logo |

### Versioning

| Tool | Description |
|---|---|
| `list_agent_versions` | List an agent's saved version snapshots |
| `restore_agent_version` | Roll 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**.

| Tool | Description |
|---|---|
| `list_channels` | List the tenant's channels + status. Never returns secret values — only `credentialsSet` (which keys are configured) |
| `connect_channel` | Connect a channel (WhatsApp, Telegram, Discord, Web, …) with its credentials. Validated against the provider API and stored server-side |
| `disconnect_channel` | Disconnect 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](https://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**.

| Tool | Description |
|---|---|
| `list_integrations` | List the integration catalog (available) + the tenant's installed integrations. Never returns secret values — only `configKeys` (which config keys are set) |
| `configure_integration` | Install or update an integration with its config/secret (validated against the provider, stored server-side). Accepts literal `config` or `configFromEnv` (env-var reference) |
| `remove_integration` | Uninstall 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

| Tool | Description |
|---|---|
| `switch_tenant` | Switch the active tenant for the session |

## Roles

| Role | Read | Write | Publish |
|---|---|---|---|
| `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)). Channels that need an **interactive flow** (WhatsApp/Instagram Embedded Signup with QR scans or OAuth consent) must still be connected from [admin.botuyo.com](https://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

```sh
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:

```sh
npm run inspect
```

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Please note that this project follows a [Code of Conduct](CODE_OF_CONDUCT.md).

## Security

To report a vulnerability, see [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE) © BotUyo