@elizaos/plugin-mcp 1.3.5 → 2.0.0-alpha.1

package/README.md

@@ -1,275 +0,0 @@
-# MCP Plugin for ElizaOS
-
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org)
-
-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.
-
-## 🔍 What is MCP?
-
-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
-```
-
-- **pnpm**
-
-```bash
-pnpm install @elizaos/plugin-mcp
-```
-
-- **yarn**
-
-```bash
-yarn add @elizaos/plugin-mcp
-```
-
-- **bun**
-
-```bash
-bun add @elizaos/plugin-mcp
-```
-
-## 🚀 Usage
-
-1. Add the plugin to your character configuration:
-
-```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`** - Modern Streamable HTTP transport (recommended)
-- **`sse`** - Legacy Server-Sent Events transport (deprecated, use `streamable-http` instead)  
-- **`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-modern-server": {
-        "type": "streamable-http",
-        "url": "https://example.com/mcp"
-      },
-      "my-local-server": {
-        "type": "http",
-        "url": "http://localhost:3000",
-        "timeout": 30
-      },
-      "my-legacy-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": {
-        "github": {
-          "type": "stdio",
-          "command": "npx",
-          "args": ["-y", "@modelcontextprotocol/server-github"],
-          "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>"
-          }
-        }
-      },
-      "maxRetries": 2
-    }
-  }
-}
-```
-
-## 🔒 Security Considerations
-
-Please be aware that MCP servers can execute arbitrary code, so only connect to servers you trust.
-
-## 🔍 Troubleshooting
-
-If you encounter issues with the MCP plugin:
-
-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
-
-## 👥 Contributing
-
-Thanks for considering contributing to our project!
-
-### How to Contribute
-
-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.
-
-### Commit Guidelines
-
-We use [Conventional Commits](https://www.conventionalcommits.org/) for our commit messages:
-
-- `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...
-
-## 📄 License
-
-This plugin is released under the same license as ElizaOS.

package/dist/actions/callToolAction.d.ts

@@ -1,3 +0,0 @@
-import { type Action } from '@elizaos/core';
-export declare const callToolAction: Action;
-//# sourceMappingURL=callToolAction.d.ts.map

package/dist/actions/callToolAction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"callToolAction.d.ts","sourceRoot":"","sources":["../../src/actions/callToolAction.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EAOZ,MAAM,eAAe,CAAC;AAQvB,eAAO,MAAM,cAAc,EAAE,MAsK5B,CAAC"}

package/dist/actions/readResourceAction.d.ts

@@ -1,3 +0,0 @@
-import { type Action } from '@elizaos/core';
-export declare const readResourceAction: Action;
-//# sourceMappingURL=readResourceAction.d.ts.map

package/dist/actions/readResourceAction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"readResourceAction.d.ts","sourceRoot":"","sources":["../../src/actions/readResourceAction.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAqDvB,eAAO,MAAM,kBAAkB,EAAE,MAiLhC,CAAC"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,MAAM,EAAU,MAAM,eAAe,CAAC;AAOxE,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,QAAA,MAAM,SAAS,EAAE,MAWhB,CAAC;AAEF,eAAe,SAAS,CAAC"}