@botpress/adk-cli 1.19.0-beta.3 → 1.19.0-beta.5

package/dist/mcp-server-n1asyzhv.md

@@ -0,0 +1,112 @@
+# ADK MCP Server
+
+The ADK includes a built-in MCP (Model Context Protocol) server that enables AI assistants like Claude Code, Cursor, and VS Code to interact with your ADK project.
+
+## Quick Setup
+
+```bash
+# From your ADK project root (auto-detects project)
+adk mcp:init --all
+
+# Or specify project directory (for monorepos)
+adk mcp:init --all --project-dir ./bot
+```
+
+This generates configuration files for:
+- **Claude Code**: `.mcp.json`
+- **VS Code**: `.vscode/mcp.json`
+- **Cursor**: `.cursor/mcp.json`
+
+## What It Provides
+
+Once configured, AI assistants gain tools to:
+
+- **Debug** - Query traces, get dev logs, check build status
+- **Test** - Send messages to your running bot and receive responses
+- **Discover** - Search and explore integrations on the Botpress Hub
+- **Manage** - Add integrations, start workflows, get agent info
+- **Docs** - Search Botpress documentation (proxied from Mintlify)
+
+The MCP server exposes its own tool descriptions - your AI assistant will see what's available.
+
+> **Current limitation:** The MCP server is useful for inspection, testing, and project-aware tooling, but its init flow is not the most reliable unattended bootstrap path right now. The MCP `adk_init_project` tool is out of sync with the CLI template names and can still fall into interactive login/link flows. For scripted setup, prefer the shell flow: `adk login --token "$BOTPRESS_TOKEN"`, then `adk init <name> --yes --skip-link`.
+
+## Commands
+
+### adk mcp
+
+Start the MCP server (called automatically by AI assistants via config).
+
+```bash
+adk mcp [--cwd <path>]
+```
+
+### adk mcp:init
+
+Generate MCP configuration files.
+
+```bash
+adk mcp:init [options]
+```
+
+**Options:**
+- `--tool <name>` - Generate for specific tool (claude-code, vscode, cursor)
+- `--all` - Generate for all supported tools
+- `--force` - Overwrite existing config
+- `--project-dir <path>` - ADK project subdirectory (for monorepos)
+
+## Monorepo Setup
+
+When your ADK project is in a subdirectory:
+
+```
+my-monorepo/
+├── bot/              # ADK project (agent.config.ts here)
+├── frontend/
+└── .mcp.json         # Config created at root
+```
+
+The generated config includes `--cwd` to target the correct directory:
+
+```json
+{
+  "mcpServers": {
+    "adk": {
+      "command": "adk",
+      "args": ["mcp", "--cwd", "./bot"]
+    }
+  }
+}
+```
+
+## Requirements
+
+- **ADK CLI** installed and in PATH
+- **For project tools:** Valid ADK project with `agent.config.ts`
+- **For messaging/workflow tools:** `adk dev` server running on the default console port `3001`
+
+## Troubleshooting
+
+**"Not in an ADK project directory"**
+- Ensure `--cwd` points to directory with `agent.config.ts`
+
+**"Dev server is not running"**
+- Start the dev server: `adk dev`
+
+**"MCP can connect, but messaging/workflow tools fail"**
+- Use the default console port: `adk dev --port-console 3001`
+- Current MCP dev-server-backed tools assume `http://localhost:3001`
+
+**"No chat or webchat integration found"**
+- Add an integration: `adk add chat` or `adk add webchat`
+
+**Inspect the MCP server:**
+
+```bash
+npx @modelcontextprotocol/inspector adk mcp
+```
+
+## See Also
+
+- **[CLI Reference](./cli.md)** - All ADK CLI commands
+- **[Agent Configuration](./agent-config.md)** - agent.config.ts setup