@agiflowai/clawdbot-mcp-plugin

Clawdbot plugin for integrating Model Context Protocol (MCP) servers with progressive tool disclosure.

Overview

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.

Features

• Progressive Disclosure: Only 2 tools registered (mcp__describe_tools, mcp__use_tool)
• Dynamic Tool Discovery: Tools are described on-demand, not pre-registered
• Multiple MCP Servers: Connect to multiple MCP servers simultaneously
• Skill Support: Integrate skills from file-based or prompt-based sources
• Clean Separation: Reuses one-mcp as a library dependency (no code duplication)

Installation

npm install @agiflowai/clawdbot-mcp-plugin
# or
pnpm add @agiflowai/clawdbot-mcp-plugin

Configuration

Clawdbot Gateway Config

Add the plugin to your Clawdbot configuration (~/.clawdbot/clawdbot.json):

{
  "plugins": {
    "entries": {
      "clawdbot-mcp-plugin": {
        "enabled": true,
        "config": {
          "configFilePath": "/Users/username/.clawdbot/mcp-config.yaml",
          "serverId": "clawdbot-toolkit",
          "noCache": false
        }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "allow": [
            "mcp__describe_tools",
            "mcp__use_tool"
          ]
        }
      }
    ]
  }
}

Important:

• Plugin config must be nested under "config" key
• Plugin ID in entries must match the plugin manifest ID: "clawdbot-mcp-plugin"
• Use absolute path for configFilePath to avoid path resolution issues

MCP Server Config

Create .clawdbot/mcp-config.yaml:

mcpServers:
  memory:
    name: "Memory Storage"
    instruction: "Simple key-value storage"
    transport: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-memory"]

  filesystem:
    name: "Filesystem Operations"
    instruction: "File operations"
    transport: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/workspace"]

Note: command and args are at top level, NOT nested under config.

Usage

Agents use two tools to access MCP servers:

// 1. Discover tools
mcp__describe_tools({ toolNames: ["read_file", "write_file"] })

// 2. Execute tools
mcp__use_tool({
  toolName: "read_file",
  toolArgs: { path: "/path/to/file.txt" }
})

Architecture

Plugin Structure

The plugin exports an object (not a function) with the following structure:

const mcpBridgePlugin = {
  id: 'clawdbot-mcp-plugin',
  name: 'MCP Server Bridge',
  description: 'Enables MCP server integration...',
  configSchema: Type.Object({
    // TypeBox schema for config validation
  }),
  register(api: ClawdbotPluginApi) {
    // Register services and tools
    api.registerService({ id: 'mcp-server', start() {...}, stop() {...} });
    api.registerTool({ name: 'mcp__describe_tools', ... }, { name: 'mcp__describe_tools' });
    api.registerTool({ name: 'mcp__use_tool', ... }, { name: 'mcp__use_tool' });
  }
};

export default mcpBridgePlugin;

Plugin Lifecycle

1. Discovery & Loading: Gateway scans plugin directories and loads manifests
2. Registration: Gateway calls plugin.register(api) with Clawdbot API
3. Service Start: Gateway calls all registered service start() methods (async initialization happens here)
4. Runtime: Tools execute and forward requests to one-mcp
5. Service Stop: Gateway calls service stop() methods on shutdown

Progressive Disclosure Pattern

• Minimal Surface Area: Only 2 tools exposed to agents
• On-Demand Discovery: Tools are described when requested via mcp__describe_tools
• Dynamic Description: Toolkit description generated after MCP servers connect
• No Tool Bloat: Avoid registering hundreds of individual MCP tools

Key Implementation Details

• Plugin Object: Exports object with register() method, not a plain function
• Tool Registration: Second parameter must be { name: 'tool_name' }, not { optional: false }
• Service Registration: Use id: property, not name:
• API Access: Use api.pluginConfig (not api.getConfig()), api.logger (not api.log), api.registerTool, api.registerService
• Async Work: Do all async initialization in service.start(), not in register() function

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Type check
pnpm typecheck

# Run tests
pnpm test

Configuration Schema

The plugin accepts the following configuration options:

• configFilePath (string): Path to mcp-config.yaml file (default: .clawdbot/mcp-config.yaml)
• serverId (string): Unique identifier for the toolkit (default: clawdbot-mcp)
• noCache (boolean): Disable configuration caching (default: false)

Error Handling

• Connection Failures: Logged but don't crash the plugin
• Tool Execution Errors: Returned as structured error responses
• Configuration Errors: Validated against JSON schema, fail fast

License

AGPL-3.0

Contributing

See CONTRIBUTING.md for development guidelines.