STARWARCLOUD STARWAR.AI
返回市场
ai-sdk-mcp-桥接器

ai-sdk-mcp-桥接器

作者：vrknetha22 星标更新：2025-02-05
安装使用来源：spider==github.com

项目介绍

AISDK MCP Bridge

一个桥接包，使模型上下文协议（MCP）与AI SDK之间无缝集成，允许MCP服务器和AI模型之间的高效通信和工具执行。

npm 版本 许可证：MIT

功能

  • 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"
      }
    }
  }
}
  1. 在代码中导入并使用桥接：
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 {
    // 初始化MCP
    await initializeMcp({ debug: true });

    // 获取来自所有服务器的工具
    const allTools = await getMcpTools({ debug:  true });

    // 或者从特定服务器获取工具
    const twitterTools = await getMcpTools({
      debug: true,
      serverName: 'twitter-mcp',
    });

    // 使用AI SDK中的工具
    const result = await generateText({
      model: google('gemini-1.5-pro'),
      messages: [
        {
          role: 'system',
          content:
            '您是一个使用各种工具帮助用户的AI助手。',
        },
        {
          role: 'user',
          content: '您的任务描述在这里',
        },
      ],
      tools: twitterTools, // 或者allTools以使用所有可用工具
    });

    console.log('结果:', result.text);
  } finally {
    // 清理资源
    await cleanupMcp();
  }
}

main().catch(error => {
  console.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; // mcp.config.json的路径
  debug?: boolean; // 启用调试日志
}

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

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

interface ToolOptions {
  debug?: boolean; // 启用调试日志
  serverName?: string; // 可选的服务器名称，用于从特定服务器获取工具
}

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

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

// 示例
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环境变量来启用详细的调试日志：

# 启用所有调试日志
DEBUG=* npm start

# 启用MCP调试日志
DEBUG=mcp npm start

# 启用所有MCP命名空间日志
DEBUG=mcp:* npm start

调试日志将显示：

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

日志类型

日志系统支持三种类型的日志：

  • info：一般操作信息
  • debug：详细的调试信息（需要DEBUG环境变量）
  • error：错误消息和堆栈跟踪（始终记录）

日志文件

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

[时间戳] [类型] 消息
{可选的JSON数据}

开发

先决条件

  • 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以获取更改列表和迁移指南。

安全性

对于安全问题，请发送电子邮件至ravi@caw.tech，而不是使用公共问题追踪器。

作者

也请参阅参与此项目的贡献者名单。

致谢

  • AI SDK团队提供了出色的SDK
  • MCP社区提供了协议规范
  • 所有帮助过这个项目的贡献者

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。