@agiflowai/clawdbot-mcp-plugin 0.1.0

package/README.md

@@ -0,0 +1,188 @@
+# @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
+
+```bash
+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`):
+
+```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`:
+
+```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:
+
+```typescript
+// 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:
+
+```typescript
+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
+
+```bash
+# 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](../../CONTRIBUTING.md) for development guidelines.

package/clawdbot.plugin.json

@@ -0,0 +1,36 @@
+{
+  "id": "clawdbot-mcp-plugin",
+  "name": "MCP Server Bridge",
+  "description": "Enables Model Context Protocol (MCP) server integration with progressive tool disclosure",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "configFilePath": {
+        "type": "string",
+        "description": "Path to mcp-config.yaml file (supports one-mcp's YAML format)",
+        "default": ".clawdbot/mcp-config.yaml"
+      },
+      "serverId": {
+        "type": "string",
+        "description": "Unique identifier for the toolkit",
+        "default": "clawdbot-mcp"
+      },
+      "noCache": {
+        "type": "boolean",
+        "description": "Disable configuration caching",
+        "default": false
+      }
+    }
+  },
+  "uiHints": {
+    "configFilePath": {
+      "label": "MCP Config File Path",
+      "placeholder": ".clawdbot/mcp-config.yaml"
+    },
+    "serverId": {
+      "label": "Server ID",
+      "placeholder": "clawdbot-mcp"
+    }
+  }
+}

package/dist/index-BTWlYpm4.d.cts

@@ -0,0 +1,144 @@
+//#region src/types/index.d.ts
+/**
+ * @agiflowai/clawdbot-mcp-plugin - Type Definitions
+ *
+ * DESIGN PATTERNS:
+ * - Interface segregation: Keep interfaces focused and minimal
+ * - Type composition: Build complex types from simple primitives
+ * - Generics: Use type parameters for reusable, type-safe abstractions
+ *
+ * CODING STANDARDS:
+ * - Use PascalCase for type/interface names
+ * - Prefix interfaces with 'I' only for abstract contracts
+ * - Document complex types with JSDoc comments
+ * - Export all public types
+ *
+ * AVOID:
+ * - Any type unless absolutely necessary
+ * - Overly complex type gymnastics
+ * - Coupling types to implementation details
+ */
+/**
+ * Clawdbot plugin configuration for one-mcp bridge.
+ * Simple config that just points to an mcp-config.yaml file.
+ */
+interface PluginConfig {
+  /** Path to mcp-config.yaml file (supports one-mcp's YAML format) */
+  configFilePath?: string;
+  /** Unique identifier for the toolkit */
+  serverId?: string;
+  /** Disable configuration caching */
+  noCache?: boolean;
+}
+/**
+ * Tool definition for Clawdbot tool registration.
+ * Defines the structure and behavior of a Clawdbot tool.
+ */
+interface ToolDefinition {
+  /** Unique tool name identifier */
+  name: string;
+  /** Human-readable tool description */
+  description: string;
+  /** JSON Schema for tool input parameters */
+  parameters: Record<string, unknown>;
+  /**
+   * Tool execution function
+   * @param id - Execution ID
+   * @param params - Tool input parameters
+   * @returns Tool execution result
+   */
+  execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/**
+ * Tool execution result returned to Clawdbot.
+ * Matches MCP SDK CallToolResult structure.
+ */
+interface ToolResult {
+  /** Result content array (can contain text, images, resources, etc.) */
+  content: Array<Record<string, unknown>>;
+  /** Whether the result represents an error */
+  isError?: boolean;
+}
+/**
+ * Tool registration options for Clawdbot.
+ * Note: The name field must match ToolDefinition.name for proper registration.
+ */
+interface ToolOptions {
+  /** Tool name identifier (must match ToolDefinition.name) */
+  name: string;
+}
+/**
+ * Service definition for Clawdbot lifecycle management.
+ * Services can perform startup and cleanup tasks.
+ */
+interface ServiceDefinition {
+  /** Unique service identifier */
+  id: string;
+  /**
+   * Service startup function
+   * Called when the gateway starts
+   */
+  start: () => Promise<void> | void;
+  /**
+   * Service shutdown function
+   * Called when the gateway stops
+   */
+  stop: () => Promise<void> | void;
+}
+/**
+ * Clawdbot API interface for plugin integration.
+ * Provides methods for registering tools and services with the Clawdbot gateway.
+ */
+interface ClawdbotApi {
+  /**
+   * Plugin configuration object.
+   * Contains the configuration values for this plugin from clawdbot.json.
+   * Always present, even if empty object when no config provided.
+   */
+  pluginConfig: PluginConfig;
+  /**
+   * Register a tool with the Clawdbot gateway
+   * @param toolDef - The tool definition with name, description, and execute function
+   * @param options - Tool registration options with name identifier
+   * @example
+   * ```typescript
+   * api.registerTool(
+   *   {
+   *     name: 'mcp__describe_tools',
+   *     description: 'Describe available MCP tools',
+   *     parameters: { type: 'object', properties: {...} },
+   *     execute: async (id, params) => ({
+   *       content: [{ type: 'text', text: 'Tool list...' }]
+   *     })
+   *   },
+   *   { name: 'mcp__describe_tools' }
+   * );
+   * ```
+   */
+  registerTool: (toolDef: ToolDefinition, options: ToolOptions) => void;
+  /**
+   * Register a service for lifecycle management
+   * @param service - The service definition with start and stop methods
+   */
+  registerService: (service: ServiceDefinition) => void;
+  /** Logging interface for plugin diagnostics */
+  logger: {
+    /**
+     * Log informational messages
+     * @param args - Message and optional additional data (strings, numbers, booleans)
+     */
+    info: (...args: (string | number | boolean)[]) => void;
+    /**
+     * Log error messages
+     * @param args - Error message and optional error details
+     */
+    error: (...args: (string | Error)[]) => void;
+    /**
+     * Log warning messages
+     * @param args - Warning message and optional additional data
+     */
+    warn: (...args: (string | number | boolean)[]) => void;
+  };
+}
+//#endregion
+export { ToolOptions as a, ToolDefinition as i, PluginConfig as n, ToolResult as o, ServiceDefinition as r, ClawdbotApi as t };

package/dist/index-Ca12Wuvd.d.ts

@@ -0,0 +1,144 @@
+//#region src/types/index.d.ts
+/**
+ * @agiflowai/clawdbot-mcp-plugin - Type Definitions
+ *
+ * DESIGN PATTERNS:
+ * - Interface segregation: Keep interfaces focused and minimal
+ * - Type composition: Build complex types from simple primitives
+ * - Generics: Use type parameters for reusable, type-safe abstractions
+ *
+ * CODING STANDARDS:
+ * - Use PascalCase for type/interface names
+ * - Prefix interfaces with 'I' only for abstract contracts
+ * - Document complex types with JSDoc comments
+ * - Export all public types
+ *
+ * AVOID:
+ * - Any type unless absolutely necessary
+ * - Overly complex type gymnastics
+ * - Coupling types to implementation details
+ */
+/**
+ * Clawdbot plugin configuration for one-mcp bridge.
+ * Simple config that just points to an mcp-config.yaml file.
+ */
+interface PluginConfig {
+  /** Path to mcp-config.yaml file (supports one-mcp's YAML format) */
+  configFilePath?: string;
+  /** Unique identifier for the toolkit */
+  serverId?: string;
+  /** Disable configuration caching */
+  noCache?: boolean;
+}
+/**
+ * Tool definition for Clawdbot tool registration.
+ * Defines the structure and behavior of a Clawdbot tool.
+ */
+interface ToolDefinition {
+  /** Unique tool name identifier */
+  name: string;
+  /** Human-readable tool description */
+  description: string;
+  /** JSON Schema for tool input parameters */
+  parameters: Record<string, unknown>;
+  /**
+   * Tool execution function
+   * @param id - Execution ID
+   * @param params - Tool input parameters
+   * @returns Tool execution result
+   */
+  execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/**
+ * Tool execution result returned to Clawdbot.
+ * Matches MCP SDK CallToolResult structure.
+ */
+interface ToolResult {
+  /** Result content array (can contain text, images, resources, etc.) */
+  content: Array<Record<string, unknown>>;
+  /** Whether the result represents an error */
+  isError?: boolean;
+}
+/**
+ * Tool registration options for Clawdbot.
+ * Note: The name field must match ToolDefinition.name for proper registration.
+ */
+interface ToolOptions {
+  /** Tool name identifier (must match ToolDefinition.name) */
+  name: string;
+}
+/**
+ * Service definition for Clawdbot lifecycle management.
+ * Services can perform startup and cleanup tasks.
+ */
+interface ServiceDefinition {
+  /** Unique service identifier */
+  id: string;
+  /**
+   * Service startup function
+   * Called when the gateway starts
+   */
+  start: () => Promise<void> | void;
+  /**
+   * Service shutdown function
+   * Called when the gateway stops
+   */
+  stop: () => Promise<void> | void;
+}
+/**
+ * Clawdbot API interface for plugin integration.
+ * Provides methods for registering tools and services with the Clawdbot gateway.
+ */
+interface ClawdbotApi {
+  /**
+   * Plugin configuration object.
+   * Contains the configuration values for this plugin from clawdbot.json.
+   * Always present, even if empty object when no config provided.
+   */
+  pluginConfig: PluginConfig;
+  /**
+   * Register a tool with the Clawdbot gateway
+   * @param toolDef - The tool definition with name, description, and execute function
+   * @param options - Tool registration options with name identifier
+   * @example
+   * ```typescript
+   * api.registerTool(
+   *   {
+   *     name: 'mcp__describe_tools',
+   *     description: 'Describe available MCP tools',
+   *     parameters: { type: 'object', properties: {...} },
+   *     execute: async (id, params) => ({
+   *       content: [{ type: 'text', text: 'Tool list...' }]
+   *     })
+   *   },
+   *   { name: 'mcp__describe_tools' }
+   * );
+   * ```
+   */
+  registerTool: (toolDef: ToolDefinition, options: ToolOptions) => void;
+  /**
+   * Register a service for lifecycle management
+   * @param service - The service definition with start and stop methods
+   */
+  registerService: (service: ServiceDefinition) => void;
+  /** Logging interface for plugin diagnostics */
+  logger: {
+    /**
+     * Log informational messages
+     * @param args - Message and optional additional data (strings, numbers, booleans)
+     */
+    info: (...args: (string | number | boolean)[]) => void;
+    /**
+     * Log error messages
+     * @param args - Error message and optional error details
+     */
+    error: (...args: (string | Error)[]) => void;
+    /**
+     * Log warning messages
+     * @param args - Warning message and optional additional data
+     */
+    warn: (...args: (string | number | boolean)[]) => void;
+  };
+}
+//#endregion
+export { ToolOptions as a, ToolDefinition as i, PluginConfig as n, ToolResult as o, ServiceDefinition as r, ClawdbotApi as t };

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { a as ToolOptions, i as ToolDefinition, n as PluginConfig, o as ToolResult, r as ServiceDefinition, t as ClawdbotApi } from "./index-BTWlYpm4.cjs";
+export { ClawdbotApi, PluginConfig, ServiceDefinition, ToolDefinition, ToolOptions, ToolResult };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { a as ToolOptions, i as ToolDefinition, n as PluginConfig, o as ToolResult, r as ServiceDefinition, t as ClawdbotApi } from "./index-Ca12Wuvd.js";
+export { ClawdbotApi, PluginConfig, ServiceDefinition, ToolDefinition, ToolOptions, ToolResult };

package/dist/index.js

@@ -0,0 +1 @@
+export {  };