|
| 1 | +# @agiflowai/clawdbot-mcp-plugin |
| 2 | + |
| 3 | +Clawdbot plugin for integrating Model Context Protocol (MCP) servers with progressive tool disclosure. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This plugin bridges the `@agiflowai/one-mcp` package to enable MCP server support in Clawdbot. It exposes only two tools (`mcp__describe_tools` and `mcp__use_tool`) using progressive disclosure, allowing agents to discover and use MCP tools on-demand without cluttering the tool list. |
| 8 | + |
| 9 | +## Features |
| 10 | + |
| 11 | +- **Progressive Disclosure**: Only 2 tools registered (`mcp__describe_tools`, `mcp__use_tool`) |
| 12 | +- **Dynamic Tool Discovery**: Tools are described on-demand, not pre-registered |
| 13 | +- **Multiple MCP Servers**: Connect to multiple MCP servers simultaneously |
| 14 | +- **Skill Support**: Integrate skills from file-based or prompt-based sources |
| 15 | +- **Clean Separation**: Reuses one-mcp as a library dependency (no code duplication) |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +```bash |
| 20 | +npm install @agiflowai/clawdbot-mcp-plugin |
| 21 | +# or |
| 22 | +pnpm add @agiflowai/clawdbot-mcp-plugin |
| 23 | +``` |
| 24 | + |
| 25 | +## Configuration |
| 26 | + |
| 27 | +### Clawdbot Gateway Config |
| 28 | + |
| 29 | +Add the plugin to your Clawdbot configuration (`~/.clawdbot/clawdbot.json`): |
| 30 | + |
| 31 | +```json |
| 32 | +{ |
| 33 | + "plugins": { |
| 34 | + "entries": { |
| 35 | + "clawdbot-mcp-plugin": { |
| 36 | + "enabled": true, |
| 37 | + "config": { |
| 38 | + "configFilePath": "/Users/username/.clawdbot/mcp-config.yaml", |
| 39 | + "serverId": "clawdbot-toolkit", |
| 40 | + "noCache": false |
| 41 | + } |
| 42 | + } |
| 43 | + } |
| 44 | + }, |
| 45 | + "agents": { |
| 46 | + "list": [ |
| 47 | + { |
| 48 | + "id": "main", |
| 49 | + "tools": { |
| 50 | + "allow": [ |
| 51 | + "mcp__describe_tools", |
| 52 | + "mcp__use_tool" |
| 53 | + ] |
| 54 | + } |
| 55 | + } |
| 56 | + ] |
| 57 | + } |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +**Important**: |
| 62 | +- Plugin config must be nested under `"config"` key |
| 63 | +- Plugin ID in `entries` must match the plugin manifest ID: `"clawdbot-mcp-plugin"` |
| 64 | +- Use absolute path for `configFilePath` to avoid path resolution issues |
| 65 | + |
| 66 | +### MCP Server Config |
| 67 | + |
| 68 | +Create `.clawdbot/mcp-config.yaml`: |
| 69 | + |
| 70 | +```yaml |
| 71 | +mcpServers: |
| 72 | + memory: |
| 73 | + name: "Memory Storage" |
| 74 | + instruction: "Simple key-value storage" |
| 75 | + transport: "stdio" |
| 76 | + command: "npx" |
| 77 | + args: ["-y", "@modelcontextprotocol/server-memory"] |
| 78 | + |
| 79 | + filesystem: |
| 80 | + name: "Filesystem Operations" |
| 81 | + instruction: "File operations" |
| 82 | + transport: "stdio" |
| 83 | + command: "npx" |
| 84 | + args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/workspace"] |
| 85 | +``` |
| 86 | +
|
| 87 | +**Note**: `command` and `args` are at top level, NOT nested under `config`. |
| 88 | + |
| 89 | +## Usage |
| 90 | + |
| 91 | +Agents use two tools to access MCP servers: |
| 92 | + |
| 93 | +```typescript |
| 94 | +// 1. Discover tools |
| 95 | +mcp__describe_tools({ toolNames: ["read_file", "write_file"] }) |
| 96 | +
|
| 97 | +// 2. Execute tools |
| 98 | +mcp__use_tool({ |
| 99 | + toolName: "read_file", |
| 100 | + toolArgs: { path: "/path/to/file.txt" } |
| 101 | +}) |
| 102 | +``` |
| 103 | + |
| 104 | +## Architecture |
| 105 | + |
| 106 | +### Plugin Structure |
| 107 | + |
| 108 | +The plugin exports an object (not a function) with the following structure: |
| 109 | + |
| 110 | +```typescript |
| 111 | +const mcpBridgePlugin = { |
| 112 | + id: 'clawdbot-mcp-plugin', |
| 113 | + name: 'MCP Server Bridge', |
| 114 | + description: 'Enables MCP server integration...', |
| 115 | + configSchema: Type.Object({ |
| 116 | + // TypeBox schema for config validation |
| 117 | + }), |
| 118 | + register(api: ClawdbotPluginApi) { |
| 119 | + // Register services and tools |
| 120 | + api.registerService({ id: 'mcp-server', start() {...}, stop() {...} }); |
| 121 | + api.registerTool({ name: 'mcp__describe_tools', ... }, { name: 'mcp__describe_tools' }); |
| 122 | + api.registerTool({ name: 'mcp__use_tool', ... }, { name: 'mcp__use_tool' }); |
| 123 | + } |
| 124 | +}; |
| 125 | +
|
| 126 | +export default mcpBridgePlugin; |
| 127 | +``` |
| 128 | + |
| 129 | +### Plugin Lifecycle |
| 130 | + |
| 131 | +1. **Discovery & Loading**: Gateway scans plugin directories and loads manifests |
| 132 | +2. **Registration**: Gateway calls `plugin.register(api)` with Clawdbot API |
| 133 | +3. **Service Start**: Gateway calls all registered service `start()` methods (async initialization happens here) |
| 134 | +4. **Runtime**: Tools execute and forward requests to one-mcp |
| 135 | +5. **Service Stop**: Gateway calls service `stop()` methods on shutdown |
| 136 | + |
| 137 | +### Progressive Disclosure Pattern |
| 138 | + |
| 139 | +- **Minimal Surface Area**: Only 2 tools exposed to agents |
| 140 | +- **On-Demand Discovery**: Tools are described when requested via `mcp__describe_tools` |
| 141 | +- **Dynamic Description**: Toolkit description generated after MCP servers connect |
| 142 | +- **No Tool Bloat**: Avoid registering hundreds of individual MCP tools |
| 143 | + |
| 144 | +### Key Implementation Details |
| 145 | + |
| 146 | +- **Plugin Object**: Exports object with `register()` method, not a plain function |
| 147 | +- **Tool Registration**: Second parameter must be `{ name: 'tool_name' }`, not `{ optional: false }` |
| 148 | +- **Service Registration**: Use `id:` property, not `name:` |
| 149 | +- **API Access**: Use `api.pluginConfig` (not `api.getConfig()`), `api.logger` (not `api.log`), `api.registerTool`, `api.registerService` |
| 150 | +- **Async Work**: Do all async initialization in `service.start()`, not in `register()` function |
| 151 | + |
| 152 | +## Development |
| 153 | + |
| 154 | +```bash |
| 155 | +# Install dependencies |
| 156 | +pnpm install |
| 157 | +
|
| 158 | +# Build the package |
| 159 | +pnpm build |
| 160 | +
|
| 161 | +# Type check |
| 162 | +pnpm typecheck |
| 163 | +
|
| 164 | +# Run tests |
| 165 | +pnpm test |
| 166 | +``` |
| 167 | + |
| 168 | +## Configuration Schema |
| 169 | + |
| 170 | +The plugin accepts the following configuration options: |
| 171 | + |
| 172 | +- `configFilePath` (string): Path to mcp-config.yaml file (default: `.clawdbot/mcp-config.yaml`) |
| 173 | +- `serverId` (string): Unique identifier for the toolkit (default: `clawdbot-mcp`) |
| 174 | +- `noCache` (boolean): Disable configuration caching (default: `false`) |
| 175 | + |
| 176 | +## Error Handling |
| 177 | + |
| 178 | +- **Connection Failures**: Logged but don't crash the plugin |
| 179 | +- **Tool Execution Errors**: Returned as structured error responses |
| 180 | +- **Configuration Errors**: Validated against JSON schema, fail fast |
| 181 | + |
| 182 | +## License |
| 183 | + |
| 184 | +AGPL-3.0 |
| 185 | + |
| 186 | +## Contributing |
| 187 | + |
| 188 | +See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines. |
0 commit comments