{"id":25060267,"url":"https://github.com/vrknetha/aisdk-mcp-bridge","last_synced_at":"2025-06-12T04:09:03.330Z","repository":{"id":275939262,"uuid":"927679272","full_name":"vrknetha/aisdk-mcp-bridge","owner":"vrknetha","description":"Bridge package enabling seamless integration between Model Context Protocol (MCP) servers and AI SDK tools. Supports multiple server types, real-time communication, and TypeScript.","archived":false,"fork":false,"pushed_at":"2025-02-05T11:24:33.000Z","size":126,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T15:08:31.768Z","etag":null,"topics":["aisdk","functioncalling","mcp","mcp-server","modelcontextprotocol","toolcalling"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vrknetha.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-05T11:08:46.000Z","updated_at":"2025-05-04T10:39:25.000Z","dependencies_parsed_at":"2025-02-07T00:45:35.039Z","dependency_job_id":null,"html_url":"https://github.com/vrknetha/aisdk-mcp-bridge","commit_stats":null,"previous_names":["vrknetha/aisdk-mcp-bridge"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrknetha%2Faisdk-mcp-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrknetha%2Faisdk-mcp-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrknetha%2Faisdk-mcp-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vrknetha%2Faisdk-mcp-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vrknetha","download_url":"https://codeload.github.com/vrknetha/aisdk-mcp-bridge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252902614,"owners_count":21822261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aisdk","functioncalling","mcp","mcp-server","modelcontextprotocol","toolcalling"],"created_at":"2025-02-06T15:57:36.939Z","updated_at":"2025-05-07T15:08:37.727Z","avatar_url":"https://github.com/vrknetha.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (1974 total)","🌐 Web Development","MCP Middleware \u0026 Orchestration"],"sub_categories":["MCP Servers"],"readme":"# AISDK MCP Bridge\n\nA bridge package that enables seamless integration between the Model Context Protocol (MCP) and AI SDK, allowing for efficient communication and tool execution between MCP servers and AI models.\n\n[![npm version](https://badge.fury.io/js/aisdk-mcp-bridge.svg)](https://badge.fury.io/js/aisdk-mcp-bridge)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- Seamless integration between MCP servers and AI SDK\n- Support for various MCP server types (Node.js, Python, UVX)\n- Multi-server support with independent configuration\n- Flexible configuration through `mcp.config.json`\n- TypeScript support with full type definitions\n- Robust error handling and logging\n- Easy-to-use API for tool execution\n\n## Installation\n\n```bash\nnpm install aisdk-mcp-bridge\n```\n\n## Quick Start\n\n1. Create an `mcp.config.json` file in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"twitter-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@enescinar/twitter-mcp\"],\n      \"env\": {\n        \"API_KEY\": \"your-twitter-api-key\",\n        \"API_SECRET_KEY\": \"your-twitter-api-secret\",\n        \"ACCESS_TOKEN\": \"your-twitter-access-token\",\n        \"ACCESS_TOKEN_SECRET\": \"your-twitter-access-token-secret\"\n      }\n    },\n    \"firecrawl\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-server-firecrawl\"],\n      \"env\": {\n        \"FIRE_CRAWL_API_KEY\": \"your-firecrawl-api-key\",\n        \"FIRE_CRAWL_API_URL\": \"https://api.firecrawl.com\"\n      }\n    }\n  }\n}\n```\n\n2. Import and use the bridge in your code:\n\n```typescript\nimport { generateText } from 'ai';\nimport { google } from '@ai-sdk/google';\nimport { getMcpTools, cleanupMcp, initializeMcp } from 'aisdk-mcp-bridge';\nimport dotenv from 'dotenv';\ndotenv.config();\n\nasync function main() {\n  try {\n    // Initialize MCP\n    await initializeMcp({ debug: true });\n\n    // Get tools from all servers\n    const allTools = await getMcpTools({ debug: true });\n\n    // Or get tools from a specific server\n    const twitterTools = await getMcpTools({\n      debug: true,\n      serverName: 'twitter-mcp',\n    });\n\n    // Use tools with AI SDK\n    const result = await generateText({\n      model: google('gemini-1.5-pro'),\n      messages: [\n        {\n          role: 'system',\n          content:\n            'You are an AI assistant that uses various tools to help users.',\n        },\n        {\n          role: 'user',\n          content: 'Your task description here',\n        },\n      ],\n      tools: twitterTools, // or allTools for all available tools\n    });\n\n    console.log('Result:', result.text);\n  } finally {\n    // Clean up resources\n    await cleanupMcp();\n  }\n}\n\nmain().catch(error =\u003e {\n  console.error('Error:', error);\n  process.exit(1);\n});\n```\n\n## Configuration\n\nThe `mcp.config.json` file supports multiple servers and communication modes. Each server can be configured independently.\n\n### Server Configuration Examples:\n\n### Twitter MCP Server\n\n```json\n{\n  \"mcpServers\": {\n    \"twitter-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@enescinar/twitter-mcp\"],\n      \"env\": {\n        \"API_KEY\": \"your-twitter-api-key\",\n        \"API_SECRET_KEY\": \"your-twitter-api-secret\",\n        \"ACCESS_TOKEN\": \"your-twitter-access-token\",\n        \"ACCESS_TOKEN_SECRET\": \"your-twitter-access-token-secret\"\n      }\n    }\n  }\n}\n```\n\n### Firecrawl Server\n\n```json\n{\n  \"mcpServers\": {\n    \"firecrawl\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-server-firecrawl\"],\n      \"env\": {\n        \"FIRE_CRAWL_API_KEY\": \"your-firecrawl-api-key\",\n        \"FIRE_CRAWL_API_URL\": \"https://api.firecrawl.com\"\n      }\n    }\n  }\n}\n```\n\n### SSE Server\n\n```json\n{\n  \"mcpServers\": {\n    \"sse-server\": {\n      \"command\": \"node\",\n      \"args\": [\"./server.js\"],\n      \"mode\": \"sse\",\n      \"sseOptions\": {\n        \"endpoint\": \"http://localhost:3000/events\",\n        \"headers\": {},\n        \"reconnectTimeout\": 5000\n      }\n    }\n  }\n}\n```\n\n## Server Modes\n\nThe bridge supports different communication modes:\n\n1. **stdio Mode** (Default)\n\n   - Direct communication through standard input/output\n   - Best for simple integrations and local development\n   - Low latency and minimal setup required\n\n2. **SSE Mode** (Server-Sent Events)\n   - Real-time, one-way communication from server to client\n   - Ideal for streaming updates and long-running operations\n   - Built-in reconnection handling\n\n## API Reference\n\n### Core Functions\n\n#### `initializeMcp(options?: InitOptions): Promise\u003cvoid\u003e`\n\nInitialize the MCP service with the provided options.\n\n```typescript\ninterface InitOptions {\n  configPath?: string; // Path to mcp.config.json\n  debug?: boolean; // Enable debug logging\n}\n```\n\n#### `getMcpTools(options?: ToolOptions): Promise\u003cToolSet\u003e`\n\nGet AI SDK-compatible tools from MCP servers.\n\n```typescript\ninterface ToolOptions {\n  debug?: boolean; // Enable debug logging\n  serverName?: string; // Optional server name to get tools from a specific server\n}\n```\n\n#### `executeMcpFunction(serverName: string, functionName: string, args: Record\u003cstring, unknown\u003e): Promise\u003cMCPToolResult\u003e`\n\nExecute a specific function on an MCP server directly.\n\n```typescript\n// Example\nconst result = await executeMcpFunction('twitter-mcp', 'postTweet', {\n  text: 'Hello from MCP!',\n});\n```\n\n### Core Types\n\n#### `MCPConfig` (alias for `MCPServersConfig`)\n\nConfiguration type for MCP servers.\n\n```typescript\ninterface MCPConfig {\n  mcpServers: {\n    [key: string]: ServerConfig;\n  };\n}\n```\n\n#### `ServerConfig`\n\nConfiguration for individual MCP servers.\n\n```typescript\ninterface ServerConfig {\n  command: string;\n  args?: string[];\n  env?: Record\u003cstring, string\u003e;\n  mode?: 'stdio' | 'sse';\n  sseOptions?: {\n    endpoint: string;\n    headers?: Record\u003cstring, string\u003e;\n    reconnectTimeout?: number;\n  };\n}\n```\n\n#### `MCPToolResult`\n\nResult type for MCP tool executions.\n\n```typescript\ninterface MCPToolResult {\n  success: boolean;\n  data?: unknown;\n  error?: string;\n}\n```\n\n#### `cleanupMcp(): Promise\u003cvoid\u003e`\n\nClean up MCP resources and close all server connections.\n\n## Error Handling\n\nThe bridge includes comprehensive error handling for:\n\n- Server initialization failures\n- Communication errors\n- Tool execution failures\n- Configuration issues\n- Server connection issues\n\n## Logging\n\nThe bridge provides detailed logging through:\n\n- `mcp-tools.log`: Server-side tool execution logs\n- Console output for debugging and errors\n\n### Debug Logging\n\nYou can enable detailed debug logging by setting the DEBUG environment variable:\n\n```bash\n# Enable all debug logs\nDEBUG=* npm start\n\n# Enable MCP debug logs\nDEBUG=mcp npm start\n\n# Enable all MCP namespace logs\nDEBUG=mcp:* npm start\n```\n\nDebug logs will show:\n\n- Server initialization and shutdown events\n- Tool registration and execution details\n- Communication with MCP servers\n- Schema conversions and validations\n- Error details with stack traces\n- Performance metrics and timing information\n\n### Log Types\n\nThe logging system supports three types of logs:\n\n- `info`: General operational information\n- `debug`: Detailed debugging information (requires DEBUG env variable)\n- `error`: Error messages and stack traces (always logged)\n\n### Log File\n\nAll logs are written to `logs/mcp-tools.log` with the following format:\n\n```\n[TIMESTAMP] [TYPE] Message\n{Optional JSON data}\n```\n\n## Development\n\n### Prerequisites\n\n- Node.js 20.x or higher\n- npm 7.x or higher\n\n### Setup\n\n1. Clone the repository\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n### Testing\n\nRun the test suite:\n\n```bash\nnpm test\n```\n\nRun specific tests:\n\n```bash\n\nnpm run test:twitter\nnpm run test:firecrawl\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- Setting up the development environment\n- Coding standards\n- Pull request process\n- Adding new MCP servers\n\nPlease note that this project is released with a [Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.\n\n## Support\n\nFor support:\n\n1. Check the [documentation](README.md)\n2. Search [existing issues](https://github.com/vrknetha/aisdk-mcp-bridge/issues)\n3. Create a new issue if your problem persists\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes and migration guides.\n\n## Security\n\nFor security issues, please email ravi@caw.tech instead of using the public issue tracker.\n\n## Authors\n\n- **Ravi Kiran** - _Initial work_ - [@vrknetha](https://github.com/vrknetha)\n\nSee also the list of [contributors](https://github.com/vrknetha/aisdk-mcp-bridge/contributors) who participated in this project.\n\n## Acknowledgments\n\n- AI SDK team for their excellent SDK\n- MCP community for the protocol specification\n- All contributors who have helped with the project\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvrknetha%2Faisdk-mcp-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvrknetha%2Faisdk-mcp-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvrknetha%2Faisdk-mcp-bridge/lists"}