@elizaos/plugin-mcp 2.0.0-beta.1 → 2.0.3-beta.3

package/README.md

@@ -1,201 +1,25 @@
-# MCP Plugin for elizaOS
+# @elizaos/plugin-mcp
 
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org)
+elizaOS plugin that connects an Eliza agent to external [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers and exposes their tools and resources as agent capabilities.
 
-This plugin integrates the Model Context Protocol (MCP) with elizaOS, allowing agents to connect to multiple MCP servers and use their resources, prompts, and tools.
+The plugin starts `McpService`, which connects to one or more MCP servers (stdio, SSE, or streamable-HTTP), discovers their tools and resources, and surfaces them through a single `MCP` action and an `MCP` provider. It is consumed by an elizaOS agent: add it to the character `plugins` array and configure servers under `settings.mcp.servers`.
 
-## 🔍 What is MCP?
+Node-only. `index.browser.ts` is a browser-unavailable entry because the MCP SDK's stdio/SSE transports require Node APIs (`eliza.platforms` is `["node"]`).
 
-The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. It provides a standardized way to connect LLMs with the context they need.
-
-This plugin allows your elizaOS agents to access multiple MCP servers simultaneously, each providing different capabilities:
-
-- **Resources**: Context and data for the agent to reference
-- **Tools**: Functions for the agent to execute
-
-## 📦 Installation
-
-Install the plugin in your elizaOS project:
-
-- **npm**
-
-```bash
-npm install @elizaos/plugin-mcp
-```
-
-- **yarn**
-
-```bash
-yarn add @elizaos/plugin-mcp
-```
-
-- **bun**
+## Install
 
 ```bash
-bun add @elizaos/plugin-mcp
+bun add @elizaos/plugin-mcp   # or: npm install / yarn add
 ```
 
-## 🚀 Usage
+## Usage
 
-1. Add the plugin to your character configuration:
+Add the plugin and declare servers in your character file:
 
 ```json
 {
   "name": "Your Character",
   "plugins": ["@elizaos/plugin-mcp"],
-  "settings": {
-    "mcp": {
-      "servers": {
-        "github": {
-          "type": "stdio",
-          "command": "npx",
-          "args": ["-y", "@modelcontextprotocol/server-github"]
-        }
-      }
-    }
-  }
-}
-```
-
-## ⚙️ Configuration Options
-
-MCP supports multiple transport types for connecting to servers. Each type has its own configuration options.
-
-### Transport Types
-
-- **`streamable-http`** or **`http`** - Streamable HTTP transport (recommended)
-- **`sse`** - Server-Sent Events transport
-- **`stdio`** - Process-based transport using standard input/output
-
-### HTTP Transport Options (streamable-http, http, sse)
-
-| Option    | Type   | Description                                         |
-| --------- | ------ | --------------------------------------------------- |
-| `type`    | string | Transport type: "streamable-http", "http", or "sse" |
-| `url`     | string | The URL of the HTTP/SSE endpoint                    |
-| `timeout` | number | _Optional_ Timeout for connections                  |
-
-### stdio Transport Options
-
-| Option            | Type     | Description                                            |
-| ----------------- | -------- | ------------------------------------------------------ |
-| `type`            | string   | Must be "stdio"                                        |
-| `command`         | string   | _Optional_ The command to run the MCP server           |
-| `args`            | string[] | _Optional_ Command-line arguments for the server       |
-| `env`             | object   | _Optional_ Environment variables to pass to the server |
-| `cwd`             | string   | _Optional_ Working directory to run the server in      |
-| `timeoutInMillis` | number   | _Optional_ Timeout in milliseconds for tool calls      |
-
-### Example Configuration
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "my-http-server": {
-        "type": "streamable-http",
-        "url": "https://example.com/mcp"
-      },
-      "my-local-server": {
-        "type": "http",
-        "url": "http://localhost:3000",
-        "timeout": 30
-      },
-      "my-sse-server": {
-        "type": "sse",
-        "url": "http://localhost:8080"
-      },
-      "my-stdio-server": {
-        "type": "stdio",
-        "command": "mcp-server",
-        "args": ["--config", "config.json"],
-        "cwd": "/path/to/server",
-        "timeoutInMillis": 60000
-      }
-    },
-    "maxRetries": 3
-  }
-}
-```
-
-## 🛠️ Using MCP Capabilities
-
-Once configured, the plugin automatically exposes MCP servers' capabilities to your agent:
-
-### Context Provider
-
-The plugin includes one provider that adds MCP capabilities to the agent's context:
-
-1. **`MCP`**: Lists available servers and their tools and resources
-
-### Actions
-
-The plugin provides two actions for interacting with MCP servers:
-
-1. **`CALL_MCP_TOOL`**: Executes tools from connected MCP servers
-2. **`READ_MCP_RESOURCE`**: Accesses resources from connected MCP servers
-
-## 🔄 Plugin Flow
-
-The following diagram illustrates the MCP plugin's flow for tool selection and execution:
-
-```mermaid
-graph TD
-    %% Starting point - User request
-    start[User Request] --> action[CALL_MCP_TOOL Action]
-
-    %% MCP Server Validation
-    action --> check{MCP Servers Available?}
-    check -->|No| fail[Return No Tools Available]
-
-    %% Tool Selection Flow
-    check -->|Yes| state[Get MCP Provider Data]
-    state --> prompt[Create Tool Selection Prompt]
-
-    %% First Model Use - Tool Selection
-    prompt --> model1[Use Language Model for Tool Selection]
-    model1 --> parse[Parse Selection]
-    parse --> retry{Valid Selection?}
-
-    %% Second Model Use - Retry Selection
-    retry -->|No| feedback[Generate Feedback]
-    feedback --> model2[Use Language Model for Retry]
-    model2 --> parse
-
-    %% Tool Selection Result
-    retry -->|Yes| toolAvailable{Tool Available?}
-    toolAvailable -->|No| fallback[Fallback Response]
-
-    %% Tool Execution Flow
-    toolAvailable -->|Yes| callTool[Call MCP Tool]
-    callTool --> processResult[Process Tool Result]
-
-    %% Memory Creation
-    processResult --> createMemory[Create Memory Record]
-    createMemory --> reasoningPrompt[Create Reasoning Prompt]
-
-    %% Third Model Use - Response Generation
-    reasoningPrompt --> model3[Use Language Model for Response]
-    model3 --> respondToUser[Send Response to User]
-
-    %% Styling
-    classDef model fill:#f9f,stroke:#333,stroke-width:2px;
-    classDef decision fill:#bbf,stroke:#333,stroke-width:2px;
-    classDef output fill:#bfb,stroke:#333,stroke-width:2px;
-
-    class model1,model2,model3 model;
-    class check,retry,toolAvailable decision;
-    class respondToUser,fallback output;
-```
-
-## 📋 Example: Setting Up Multiple MCP Servers
-
-Here's a complete example configuration with multiple MCP servers of both types:
-
-```json
-{
-  "name": "Developer Assistant",
-  "plugins": ["@elizaos/plugin-mcp", "other-plugins"],
   "settings": {
     "mcp": {
       "servers": {
@@ -203,22 +27,11 @@ Here's a complete example configuration with multiple MCP servers of both types:
           "type": "stdio",
           "command": "npx",
           "args": ["-y", "@modelcontextprotocol/server-github"],
-          "env": {
-            "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
-          }
+          "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>" }
         },
-        "puppeteer": {
-          "type": "stdio",
-          "command": "npx",
-          "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
-        },
-        "google-maps": {
-          "type": "stdio",
-          "command": "npx",
-          "args": ["-y", "@modelcontextprotocol/server-google-maps"],
-          "env": {
-            "GOOGLE_MAPS_API_KEY": "<YOUR_API_KEY>"
-          }
+        "my-http-server": {
+          "type": "streamable-http",
+          "url": "https://example.com/mcp"
         }
       },
       "maxRetries": 2
@@ -227,43 +40,59 @@ Here's a complete example configuration with multiple MCP servers of both types:
 }
 ```
 
-## 🔒 Security Considerations
+Config lives entirely in `settings.mcp`, not in environment variables. The host `PATH` is forwarded to stdio child processes automatically. Every server config is validated by `@elizaos/security/mcp-server-config` (`validateMcpServerConfig`) before connect/spawn; configs that fail validation are skipped and logged at error level.
 
-Please be aware that MCP servers can execute arbitrary code, so only connect to servers you trust.
+## Configuration
 
-## 🔍 Troubleshooting
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `mcp.servers` | `Record<string, McpServerConfig>` | — | Map of server name → transport config |
+| `mcp.maxRetries` | `number` | `2` | Max reconnect attempts per server |
 
-If you encounter issues with the MCP plugin:
+Transport config (see `src/types.ts`):
 
-1. Check that your MCP servers are correctly configured and running
-2. Ensure the commands are accessible in the elizaOS environment
-3. Review the logs for connection errors
-4. Verify that the plugin is properly loaded in your character configuration
+- **stdio** — `{ type: "stdio", command, args?, env?, cwd?, timeoutInMillis? }`
+- **HTTP/SSE** — `{ type: "streamable-http" | "http" | "sse", url, timeout? }`
 
-## 👥 Contributing
+## Plugin surface
 
-Thanks for considering contributing to our project!
+- **Action `MCP`** — single entry point for all MCP operations. `action=call_tool` invokes a server tool, `action=read_resource` reads a server resource (`search_actions` / `list_connections` are cloud-runtime-only). Similes include `CALL_MCP_TOOL`, `READ_MCP_RESOURCE`, `USE_TOOL`.
+- **Provider `MCP`** — injects a summary of connected servers, their status, tools, and resources into agent context.
+- **`handleMcpRoutes`** (exported) — HTTP handler for `/api/mcp/*` (config CRUD, marketplace search, runtime status), wired up by the host server, not by the plugin object. The `McpRouteContext` type is also exported.
 
-### How to Contribute
+## src layout
 
-1. Fork the repository.
-2. Create a new branch: `git checkout -b feature-branch-name`.
-3. Make your changes.
-4. Commit your changes using conventional commits.
-5. Push to your fork and submit a pull request.
+```
+src/
+  index.ts              Plugin object — registers McpService, MCP action, MCP provider
+  types.ts              Shared types + config guards (McpSettings, McpServerConfig, …)
+  service.ts            McpService — connection lifecycle, tool calls, resource reads, ping/reconnect
+  provider.ts           MCP provider — connected-server summary for agent state
+  routes-mcp.ts         handleMcpRoutes — /api/mcp/config, /api/mcp/status, marketplace
+  mcp-marketplace.ts    Client for registry.modelcontextprotocol.io (search + details)
+  prompts.ts            Handlebars-style prompt templates
+  actions/mcp.ts        mcpAction handler — op routing
+  templates/            Thin re-export shims over prompts.ts
+  utils/                Selection, validation, processing, error, and JSON helpers
+  tool-compatibility/   Per-provider tool-schema fixup (Anthropic/OpenAI/Google)
+```
+
+## Commands
 
-### Commit Guidelines
+```bash
+bun run build         # bun run build.ts → dist/ (ESM + CJS + .d.ts)
+bun run dev           # hot-rebuild with bun --hot
+bun run test          # vitest run
+bun run typecheck     # tsgo --noEmit
+bun run lint          # biome check --write --unsafe
+bun run format        # biome format --write
+bun run clean         # rm -rf dist .turbo
+```
 
-We use [Conventional Commits](https://www.conventionalcommits.org/) for our commit messages:
+## Security
 
-- `test`: 💍 Adding missing tests
-- `feat`: 🎸 A new feature
-- `fix`: 🐛 A bug fix
-- `chore`: 🤖 Build process or auxiliary tool changes
-- `docs`: ✏️ Documentation only changes
-- `refactor`: 💡 A code change that neither fixes a bug or adds a feature
-- `style`: 💄 Markup, white-space, formatting, missing semi-colons...
+MCP servers can execute arbitrary code, so only connect to servers you trust. Spawn/connect of every configured server is gated on `validateMcpServerConfig` from `@elizaos/security/mcp-server-config`.
 
-## 📄 License
+## License
 
-This plugin is released under the same license as elizaOS.
+MIT.

package/dist/cjs/index.cjs

@@ -558,15 +558,15 @@ var resourceAnalysisTemplate = `{{{mcpProvider.text}}}
 
 # Prompt
 
-You are a helpful assistant responding to a user's request. You've just accessed the resource "{{{uri}}}" to help answer this request.
+Respond to the user's request using the resource "{{{uri}}}".
 
 Original user request: "{{{userMessage}}}"
 
 Resource metadata:
-{{{resourceMeta}}
+{{{resourceMeta}}}
 
 Resource content:
-{{{resourceContent}}
+{{{resourceContent}}}
 
 Instructions:
 1. Analyze how well the resource's content addresses the user's specific question or need
@@ -583,7 +583,7 @@ var resourceSelectionTemplate = `{{{mcpProvider.text}}}
 
 # Prompt
 
-You are an intelligent assistant helping select the right resource to address a user's request.
+Select the right resource to address the user's request.
 
 CRITICAL INSTRUCTIONS:
 1. You MUST specify both a valid serverName AND uri from the list above
@@ -626,7 +626,7 @@ var toolReasoningTemplate = `{{{mcpProvider.text}}}
 
 # Prompt
 
-You are a helpful assistant responding to a user's request. You've just used the "{{{toolName}}}" tool from the "{{{serverName}}}" server to help answer this request.
+Synthesize the result from the "{{{toolName}}}" tool into a response to the user's request.
 
 Original user request: "{{{userMessage}}}"
 
@@ -773,13 +773,11 @@ var ResourceSelectionSchema = {
   properties: {
     serverName: {
       type: "string",
-      minLength: 1,
-      errorMessage: "serverName must not be empty"
+      minLength: 1
     },
     uri: {
       type: "string",
-      minLength: 1,
-      errorMessage: "uri must not be empty"
+      minLength: 1
     },
     reasoning: {
       type: "string"
@@ -1171,13 +1169,11 @@ var toolSelectionNameSchema = {
   properties: {
     serverName: {
       type: "string",
-      minLength: 1,
-      errorMessage: "serverName must not be empty"
+      minLength: 1
     },
     toolName: {
       type: "string",
-      minLength: 1,
-      errorMessage: "toolName must not be empty"
+      minLength: 1
     },
     reasoning: {
       type: "string"
@@ -1223,7 +1219,7 @@ function validateToolSelectionName(parsed, state) {
   const data = basicResult.data;
   const mcpData = state.values.mcp ?? {};
   const server = mcpData[data.serverName];
-  if (!server || server.status !== "connected") {
+  if (server?.status !== "connected") {
     return {
       success: false,
       error: `Server "${data.serverName}" not found or not connected`
@@ -1394,8 +1390,16 @@ async function createToolSelectionName({
   callback,
   mcpProvider
 }) {
+  const stateWithMcp = {
+    ...state,
+    values: {
+      ...state.values,
+      mcp: state.values.mcp ?? mcpProvider.data.mcp,
+      mcpProvider
+    }
+  };
   const toolSelectionPrompt = import_core4.composePromptFromState({
-    state: { ...state, values: { ...state.values, mcpProvider } },
+    state: stateWithMcp,
     template: toolSelectionNameTemplate
   });
   const toolSelectionName = await runtime.useModel(import_core4.ModelType.TEXT_LARGE, {
@@ -1404,10 +1408,10 @@ async function createToolSelectionName({
   return await withModelRetry({
     runtime,
     message,
-    state,
+    state: stateWithMcp,
     callback,
     input: toolSelectionName,
-    validationFn: (parsed) => validateToolSelectionName(parsed, state),
+    validationFn: (parsed) => validateToolSelectionName(parsed, stateWithMcp),
     createFeedbackPromptFn: (originalResponse, errorMessage, composedState, userMessage) => createToolSelectionFeedbackPrompt(typeof originalResponse === "string" ? originalResponse : JSON.stringify(originalResponse), errorMessage, composedState, userMessage),
     failureMsg: "I'm having trouble figuring out the best way to help with your request."
   });
@@ -1894,6 +1898,7 @@ var provider = {
 
 // src/service.ts
 var import_core6 = require("@elizaos/core");
+var import_mcp_server_config = require("@elizaos/security/mcp-server-config");
 var import_client = require("@modelcontextprotocol/sdk/client/index.js");
 var import_sse = require("@modelcontextprotocol/sdk/client/sse.js");
 var import_stdio = require("@modelcontextprotocol/sdk/client/stdio.js");
@@ -1994,15 +1999,28 @@ class McpService extends import_core6.Service {
     }
     return;
   }
+  async filterValidatedServerConfigs(serverConfigs) {
+    const validated = {};
+    for (const [name, config] of Object.entries(serverConfigs)) {
+      const rejection = await import_mcp_server_config.validateMcpServerConfig(config);
+      if (rejection) {
+        import_core6.logger.error({ server: name, rejection }, "Skipping MCP server with invalid or unsafe config");
+        continue;
+      }
+      validated[name] = config;
+    }
+    return validated;
+  }
   async updateServerConnections(serverConfigs) {
+    const safeConfigs = await this.filterValidatedServerConfigs(serverConfigs);
     const currentNames = new Set(this.connections.keys());
-    const newNames = new Set(Object.keys(serverConfigs));
+    const newNames = new Set(Object.keys(safeConfigs));
     for (const name of currentNames) {
       if (!newNames.has(name)) {
         await this.deleteConnection(name);
       }
     }
-    const connectionPromises = Object.entries(serverConfigs).map(async ([name, config]) => {
+    const connectionPromises = Object.entries(safeConfigs).map(async ([name, config]) => {
       const currentConnection = this.connections.get(name);
       if (!currentConnection) {
         await this.initializeConnection(name, config);
@@ -2148,9 +2166,16 @@ class McpService extends import_core6.Service {
   async deleteConnection(name) {
     const connection = this.connections.get(name);
     if (connection) {
-      await connection.transport.close();
-      await connection.client.close();
+      const closeResults = await Promise.allSettled([
+        connection.transport.close(),
+        connection.client.close()
+      ]);
       this.connections.delete(name);
+      for (const result of closeResults) {
+        if (result.status === "rejected") {
+          import_core6.logger.warn({ error: result.reason, serverName: name }, `Failed to close MCP connection resource for "${name}"`);
+        }
+      }
     }
     const state = this.connectionStates.get(name);
     if (state) {
@@ -2168,6 +2193,17 @@ class McpService extends import_core6.Service {
     if (!config.command) {
       throw new Error(`Missing command for stdio MCP server ${name}`);
     }
+    const rejection = await import_mcp_server_config.validateMcpServerConfig({
+      type: "stdio",
+      command: config.command,
+      args: config.args,
+      env: config.env,
+      cwd: config.cwd,
+      timeoutInMillis: config.timeoutInMillis
+    });
+    if (rejection) {
+      throw new Error(`MCP stdio server "${name}" rejected at spawn: ${rejection}`);
+    }
     return new import_stdio.StdioClientTransport({
       command: config.command,
       args: config.args ? [...config.args] : undefined,
@@ -2183,6 +2219,13 @@ class McpService extends import_core6.Service {
     if (!config.url) {
       throw new Error(`Missing URL for HTTP MCP server ${name}`);
     }
+    const rejection = await import_mcp_server_config.validateMcpServerConfig({
+      type: config.type,
+      url: config.url
+    });
+    if (rejection) {
+      throw new Error(`MCP remote server "${name}" rejected at connect: ${rejection}`);
+    }
     return new import_sse.SSEClientTransport(new URL(config.url));
   }
   appendErrorMessage(connection, error) {
@@ -2374,12 +2417,17 @@ async function getMcpServerDetails(name) {
 }
 
 // src/routes-mcp.ts
+var MCP_MARKETPLACE_QUERY_MAX_LENGTH = 200;
+var MCP_MARKETPLACE_SERVER_NAME_MAX_LENGTH = 200;
 function parseClampedInteger(value, options = {}) {
   const raw = value == null ? "" : value.trim();
   if (!raw)
     return Number.isFinite(options.fallback) ? options.fallback : undefined;
-  const parsed = Number.parseInt(raw, 10);
-  if (!Number.isFinite(parsed)) {
+  if (!/^[+-]?\d+$/.test(raw)) {
+    return Number.isFinite(options.fallback) ? options.fallback : undefined;
+  }
+  const parsed = Number(raw);
+  if (!Number.isSafeInteger(parsed)) {
     return Number.isFinite(options.fallback) ? options.fallback : undefined;
   }
   if (options.min !== undefined && parsed < options.min)
@@ -2388,10 +2436,23 @@ function parseClampedInteger(value, options = {}) {
     return options.max;
   return parsed;
 }
+function normalizeBoundedString(value, maxLength, label) {
+  const normalized = value.trim();
+  if (normalized.length > maxLength) {
+    throw new RangeError(`${label} must be ${maxLength} characters or fewer`);
+  }
+  return normalized;
+}
 async function handleMcpRoutes(ctx) {
   const { req, res, method, pathname, url, state, json, error, readJsonBody } = ctx;
   if (method === "GET" && pathname === "/api/mcp/marketplace/search") {
-    const query = url.searchParams.get("q") ?? "";
+    let query;
+    try {
+      query = normalizeBoundedString(url.searchParams.get("q") ?? "", MCP_MARKETPLACE_QUERY_MAX_LENGTH, "Marketplace search query");
+    } catch (err) {
+      error(res, err instanceof Error ? err.message : String(err), 400);
+      return true;
+    }
     const limitStr = url.searchParams.get("limit");
     const limit = limitStr ? parseClampedInteger(limitStr, { min: 1, max: 50, fallback: 30 }) : 30;
     try {
@@ -2406,14 +2467,21 @@ async function handleMcpRoutes(ctx) {
     const serverName = ctx.decodePathComponent(pathname.slice("/api/mcp/marketplace/details/".length), res, "server name");
     if (serverName === null)
       return true;
-    if (!serverName.trim()) {
+    let normalizedServerName;
+    try {
+      normalizedServerName = normalizeBoundedString(serverName, MCP_MARKETPLACE_SERVER_NAME_MAX_LENGTH, "Server name");
+    } catch (err) {
+      error(res, err instanceof Error ? err.message : String(err), 400);
+      return true;
+    }
+    if (!normalizedServerName) {
       error(res, "Server name is required", 400);
       return true;
     }
     try {
-      const details = await getMcpServerDetails(serverName);
+      const details = await getMcpServerDetails(normalizedServerName);
       if (!details) {
-        error(res, `MCP server "${serverName}" not found`, 404);
+        error(res, `MCP server "${normalizedServerName}" not found`, 404);
         return true;
       }
       json(res, { ok: true, server: details });
@@ -2501,6 +2569,12 @@ async function handleMcpRoutes(ctx) {
         error(res, "servers must be a JSON object", 400);
         return true;
       }
+      for (const serverName of Object.keys(body.servers)) {
+        if (ctx.isBlockedObjectKey(serverName)) {
+          error(res, 'Invalid server name: "__proto__", "constructor", and "prototype" are reserved', 400);
+          return true;
+        }
+      }
       const mcpRejection = await ctx.resolveMcpServersRejection(body.servers);
       if (mcpRejection) {
         error(res, mcpRejection, 400);
@@ -2568,10 +2642,14 @@ var mcpPlugin = {
   init: async (_config, _runtime) => {
     import_core8.logger.info("Initializing MCP plugin...");
   },
+  async dispose(runtime) {
+    const svc = runtime.getService(McpService.serviceType);
+    await svc?.stop();
+  },
   services: [McpService],
   actions: [...import_core8.promoteSubactionsToActions(withMcpContext(mcpAction))],
   providers: [provider]
 };
 var src_default = mcpPlugin;
 
-//# debugId=2D70561DBB87DFA464756E2164756E21
+//# debugId=E8D9359237465E8664756E2164756E21