AISDK MCP Bridge

AISDK MCP Bridge

一个桥接程序包，可在 Model Context Protocol（MCP）与 AI SDK 之间实现无缝集成，让 MCP 服务与 AI 模型之间能够高效通信并执行工具。

功能特性

• MCP 服务与 AI SDK 之间的无缝集成
• 支持多种 MCP 服务类型（Node.js、Python、UVX）
• 支持多个服务，各自独立配置
• 通过 mcp.config.json 灵活配置
• 支持 TypeScript，并提供完整类型定义
• 强大的错误处理和日志记录
• 易于使用的工具执行 API

安装

npm install aisdk-mcp-bridge

快速开始

1. 在项目根目录中创建 mcp.config.json 文件：

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@enescinar/twitter-mcp"],
      "env": {
        "API_KEY": "your-twitter-api-key",
        "API_SECRET_KEY": "your-twitter-api-secret",
        "ACCESS_TOKEN": "your-twitter-access-token",
        "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
      }
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "mcp-server-firecrawl"],
      "env": {
        "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
        "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
      }
    }
  }
}

2. 在代码中导入并使用桥接程序：

import { generateText } from 'ai';
import { google } from '@ai-sdk/google';
import { getMcpTools, cleanupMcp, initializeMcp } from 'aisdk-mcp-bridge';
import dotenv from 'dotenv';
dotenv.config();

async function main() {
  try {
    // Initialize MCP
    await initializeMcp({ debug: true });

    // Get tools from all servers
    const allTools = await getMcpTools({ debug: true });

    // Or get tools from a specific server
    const twitterTools = await getMcpTools({
      debug: true,
      serverName: 'twitter-mcp',
    });

    // Use tools with AI SDK
    const result = await generateText({
      model: google('gemini-1.5-pro'),
      messages: [
        {
          role: 'system',
          content:
            'You are an AI assistant that uses various tools to help users.',
        },
        {
          role: 'user',
          content: 'Your task description here',
        },
      ],
      tools: twitterTools, // or allTools for all available tools
    });

    console.log('Result:', result.text);
  } finally {
    // Clean up resources
    await cleanupMcp();
  }
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

配置

mcp.config.json 文件支持配置多个服务和通信模式。每个服务都可以单独配置。

服务配置示例：

Twitter MCP 服务

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@enescinar/twitter-mcp"],
      "env": {
        "API_KEY": "your-twitter-api-key",
        "API_SECRET_KEY": "your-twitter-api-secret",
        "ACCESS_TOKEN": "your-twitter-access-token",
        "ACCESS_TOKEN_SECRET": "your-twitter-access-token-secret"
      }
    }
  }
}

Firecrawl 服务

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "mcp-server-firecrawl"],
      "env": {
        "FIRE_CRAWL_API_KEY": "your-firecrawl-api-key",
        "FIRE_CRAWL_API_URL": "https://api.firecrawl.com"
      }
    }
  }
}

SSE 服务

{
  "mcpServers": {
    "sse-server": {
      "command": "node",
      "args": ["./server.js"],
      "mode": "sse",
      "sseOptions": {
        "endpoint": "http://localhost:3000/events",
        "headers": {},
        "reconnectTimeout": 5000
      }
    }
  }
}

服务模式

桥接程序支持不同的通信模式：

1. stdio 模式（默认）

   • 通过标准输入／输出直接通信
   • 最适合简单集成和本地开发
   • 延迟低，所需设置最少

2. SSE 模式（服务器发送事件）

   • 从服务端到客户端的实时单向通信
   • 非常适合流式更新和长时间运行的操作
   • 内置重连处理

API 参考

核心函数

initializeMcp(options?: InitOptions): Promise<void>

使用提供的选项初始化 MCP 服务。

interface InitOptions {
  configPath?: string; // Path to mcp.config.json
  debug?: boolean; // Enable debug logging
}

getMcpTools(options?: ToolOptions): Promise<ToolSet>

从 MCP 服务获取兼容 AI SDK 的工具。

interface ToolOptions {
  debug?: boolean; // Enable debug logging
  serverName?: string; // Optional server name to get tools from a specific server
}

executeMcpFunction(serverName: string, functionName: string, args: Record<string, unknown>): Promise<MCPToolResult>

直接在 MCP 服务上执行指定函数。

// Example
const result = await executeMcpFunction('twitter-mcp', 'postTweet', {
  text: 'Hello from MCP!',
});

核心类型

MCPConfig（MCPServersConfig 的别名）

MCP 服务的配置类型。

interface MCPConfig {
  mcpServers: {
    [key: string]: ServerConfig;
  };
}

ServerConfig

单个 MCP 服务的配置。

interface ServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
  mode?: 'stdio' | 'sse';
  sseOptions?: {
    endpoint: string;
    headers?: Record<string, string>;
    reconnectTimeout?: number;
  };
}

MCPToolResult

MCP 工具执行结果的类型。

interface MCPToolResult {
  success: boolean;
  data?: unknown;
  error?: string;
}

cleanupMcp(): Promise<void>

清理 MCP 资源并关闭所有服务连接。

错误处理

桥接程序包含全面的错误处理机制，涵盖：

• 服务初始化失败
• 通信错误
• 工具执行失败
• 配置问题
• 服务连接问题

日志记录

桥接程序通过以下方式提供详细日志：

• mcp-tools.log：服务端工具执行日志
• 用于调试和错误信息的控制台输出

调试日志

设置 DEBUG 环境变量即可启用详细调试日志：

# Enable all debug logs
DEBUG=* npm start

# Enable MCP debug logs
DEBUG=mcp npm start

# Enable all MCP namespace logs
DEBUG=mcp:* npm start

调试日志将显示：

• 服务初始化和关闭事件
• 工具注册和执行详情
• 与 MCP 服务的通信
• 架构转换和验证
• 包含堆栈跟踪的错误详情
• 性能指标和计时信息

日志类型

日志系统支持以下三种日志类型：

• info：常规运行信息
• debug：详细调试信息（需要设置 DEBUG 环境变量）
• error：错误消息和堆栈跟踪（始终记录）

日志文件

所有日志都会写入 logs/mcp-tools.log，格式如下：

[TIMESTAMP] [TYPE] Message
{Optional JSON data}

开发

先决条件

• Node.js 20.x 或更高版本
• npm 7.x 或更高版本

设置

1. 克隆代码仓库
2. 安装依赖：

npm install

测试

运行测试套件：

npm test

运行指定测试：

npm run test:twitter
npm run test:firecrawl

贡献

欢迎贡献！详情请参阅我们的贡献指南，了解以下内容：

• 设置开发环境
• 编码规范
• 拉取请求流程
• 添加新的 MCP 服务

请注意，本项目采用行为准则发布。参与本项目即表示你同意遵守其中的条款。

支持

如需支持：

1. 查看文档
2. 搜索现有问题
3. 如果问题仍未解决，请创建新问题

更新日志

有关变更列表和迁移指南，请参阅 CHANGELOG.md。

安全

如有安全问题，请发送邮件至 [email protected]，而不要使用公开的问题跟踪器。

作者

• Ravi Kiran - 初始工作 - @vrknetha

另请参阅参与本项目的贡献者列表。

致谢

• 感谢 AI SDK 团队提供出色的 SDK
• 感谢 MCP 社区制定协议规范
• 感谢所有为本项目提供帮助的贡献者

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。