MCP To LangChain Tools Conversion Utility / TypeScript

MCP 到 LangChain 工具转换库 / TypeScript

一个简单、轻量的库，用于在 LangChain 中使用 Model Context Protocol (MCP) 服务工具。

项目状态

本库目前支持 MCP 协议版本 2025-03-26。 它不支持 MCP 2026-07-28 规范。

对于新项目，我们建议使用 LangChain 官方的 LangChain.js MCP Adapters 库， 它为 LangChain 提供了全面的 MCP 集成。

本项目目前处于维护 / 休眠模式。现有用户可以在兼容 2025-03-26 规范的 MCP 服务上继续使用它， 但新的 MCP 协议功能将不会在此处积极实现。

简介

一个简单、轻量的库，用于在 LangChain 中使用 Model Context Protocol (MCP) 服务工具。

它的简洁性和额外功能，例如 面向大模型兼容性的工具 schema 调整 和工具调用日志记录， 使其成为你进行实验和自定义的实用基础。 然而，它只支持工具调用的文本结果，不支持 MCP 中除工具之外的其他功能。

LangChain 的官方 LangChain.js MCP Adapters 库 已发布，它支持与 LangChain 的全面集成。 对于新项目，它是 LangChain 推荐的 MCP 集成路径。

前置条件

• Node.js 18+
• [可选] npm 7+ (npx) 用于运行基于 Node.js 包的本地 MCP 服务
• [可选] 已安装 uv (uvx) 用于运行基于 Python 的本地（stdio）MCP 服务

安装

npm i @h1deya/langchain-mcp-tools

快速开始

convertMcpToLangchainTools() 工具函数接受 MCP 服务配置， 其结构与 Claude for Desktop 相同， 但仅包含 mcpServers 属性的内容， 并以 JS Object 表示，例如：

const mcpServers: McpServersConfig = {
  filesystem: {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
  },
  fetch: {
    command: 'uvx',
    args: ['mcp-server-fetch'],
  },
  'brave-search': {
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-brave-search'],
    env: { BRAVE_API_KEY: process.env.BRAVE_API_KEY || '' },
  },
  github: {
    type: 'http',
    url: 'https://api.githubcopilot.com/mcp/',
    headers: {
      Authorization: `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`,
    },
  },
  notion: {
    // For MCP servers that require OAuth, consider using "mcp-remote"
    command: 'npx',
    args: ['-y', 'mcp-remote', 'https://mcp.notion.com/mcp'],
  },
}

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  // Perform provider-specific JSON schema transformations to prevent schema compatibility issues
  llmProvider: 'google_gemini',
  // llmProvider: "openai"
  // llmProvider: "anthropic"  // no transformations
  // llmProvider: "xai"  // no transformations
  // llmProvider: "none"  // for others (default)
})

该工具函数会并行初始化所有指定的 MCP 服务， 并通过从这些服务收集可用的 MCP 工具， 将它们包装为 LangChain 工具， 从而返回 LangChain Tools （tools: StructuredTool[]）。

当指定 llmProvider 选项时，它会针对 MCP 工具执行 特定于大模型提供方的 schema 转换，以防止 schema 兼容性问题。 在执行过程中遇到 schema 相关的警告/错误时，请设置此选项。
详情见下文。

它还会返回一个异步回调函数（cleanup: McpServerCleanupFn）， 在完成后调用以关闭所有 MCP 服务会话。

返回的工具可与 LangChain 一起使用，例如：

// import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
const model = new ChatGoogleGenerativeAI({ model: 'gemini-2.5-flash' })

// import { createAgent } from "langchain";
const agent = createAgent({
  model,
  tools,
})

返回的 cleanup 函数会妥善处理资源清理：

• 并发关闭所有 MCP 服务连接，并记录任何清理失败
• 即使某些服务失败，也会继续清理剩余服务
• 使用完这些工具后应始终调用它

它通常在 finally 块中调用：

let mcpCleanup: McpServerCleanupFn | undefined

try {
  const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers)
  mcpCleanup = cleanup
  // Use tools with your LLM
} finally {
  // Always cleanup, even if errors occur
  await mcpCleanup?.()
}

一个简单可用的使用示例可在 langchain-mcp-tools-ts-usage 仓库中的此示例中找到

如需亲自动手实验 MCP 服务集成， 请尝试这个使用本库构建的 MCP 客户端命令行工具

此工具的 Python 等价实现可在 此处获取

API 参考

可在此处找到

变更日志

可在此处找到

可用的使用示例

可在 langchain-mcp-tools-ts-usage 仓库中的此示例中找到

从源码构建

详情请参见 README_DEV.md。

简介

本包旨在简化 Model Context Protocol (MCP) 服务工具与 LangChain / TypeScript 的配合使用。

Model Context Protocol (MCP) 是事实上的行业标准， 它通过支持集成外部工具和资源（包括数据库、云存储、GitHub、Docker、Slack 等）， 极大地扩展了大模型的应用范围。 目前已有相当多实用的 MCP 服务可用。
请参阅官方网站上的 MCP 服务列表。

本工具的目标是让这些众多的 MCP 服务能够轻松地从 LangChain 访问。
它包含一个工具函数 convertMcpToLangchainTools()。
这个异步函数会处理指定的多个 MCP 服务的并行初始化， 并将其可用工具转换为 LangChain 兼容的工具数组。 它还会执行特定于大模型提供方的 schema 转换， 以防止 schema 兼容性问题

有关如何使用本库的详细信息，请参阅以下文档： "Supercharging LangChain: Integrating 2000+ MCP with ReAct"。

MCP 协议支持

本库支持 MCP 协议 2025-03-26 版本，并保持与 2024-11-05 版本的向后兼容性。 在传输方式选择和向后兼容性方面，本库遵循官方 MCP 规范。

本库不支持 MCP 2026-07-28 规范。 2026-07-28 更新需要对 MCP 客户端行为和 TypeScript SDK 集成做出重大变更，本项目并未积极跟进这些 新的协议特性。

如需与 LangChain 进行新的 MCP 集成，请使用 LangChain 官方的 LangChain.js MCP Adapters 库。

局限性

• 工具返回类型：目前仅支持工具调用的文本结果。 本库使用 LangChain 的 response_format: 'content'（默认值），该选项仅支持文本字符串。 虽然 MCP 工具可以返回多种内容类型（文本、图像等），但本库目前只过滤并使用文本内容。
• MCP 特性：仅支持 MCP Tools。其他 MCP 特性，如 Resources、Prompts 和 Sampling，尚未实现。

注意事项

• 大模型兼容性与 Schema 转换：本库可以执行 Schema 转换以兼容大模型。 详情见下文。
• 传递 PATH 环境变量：如果未显式提供，本库会自动将 PATH 环境变量添加到本地服务配置中，以确保服务能够找到所需的可执行文件。

特性

本地 MCP 服务的环境变量配置

如果你需要通过环境变量向本地 MCP 服务传递 API 密钥或其他配置， 请参考以下示例：

  brave: {
    command: "npx",
    args: [ "-y", "@modelcontextprotocol/server-brave-search"],
    env: { "BRAVE_API_KEY": process.env.BRAVE_API_KEY || "" }
  },

注意：如果未显式提供，本库会自动将 PATH 环境变量添加到本地服务配置中，以确保服务能够找到所需的可执行文件。

本地 MCP 服务的 stderr 重定向

新增了一个键 "stderr"，用于指定本地 MCP 服务的 stderr 重定向到的文件描述符。

const logPath = `mcp-server-${serverName}.log`
const logFd = fs.openSync(logPath, 'w')
mcpServers[serverName].stderr = logFd

使用示例见此处。
键名 stderr 源自 TypeScript SDK 的 StdioServerParameters。

本地 MCP 服务的工作目录配置

启动本地 MCP 服务时使用的工作目录 可以通过 "cwd" 键指定，如下所示：

    "local-server-name": {
      command: "...",
      args: [...],
      cwd: "/working/directory"  // the working dir to be use by the server
    },

键名 cwd 源自 TypeScript SDK 的 StdioServerParameters。

传输方式选择优先级

本库按以下优先级顺序选择传输方式：

1. 显式的 transport/type 字段（如果提供了 URL，则必须与 URL 协议匹配）
2. URL 协议自动检测（http/https → StreamableHTTP → SSE，ws/wss → WebSocket）
3. 存在命令 → Stdio 传输（本地 MCP 服务）
4. 以上均不匹配则报错

这确保了行为可预测，同时为不同的部署场景提供了灵活性。
注意： SSE 传输自协议 2025-03-26 版本起已弃用；推荐使用 Streamable HTTP。

远程 MCP 服务支持

针对 Streamable HTTP、SSE 和 Websocket 服务的 mcp_servers 配置如下：

    // Auto-detection: tries Streamable HTTP first, falls back to SSE on 4xx errors
    "auto-detect-server": {
        url: `http://${server_host}:${server_port}/...`
    },

    // Explicit Streamable HTTP
    "streamable-http-server": {
        url: `http://${server_host}:${server_port}/...`,
        transport: "streamable_http"
        // type: "http"  // VSCode-style config also works instead of the above
    },

    // Explicit SSE (Note: SSE transport is deprecated)
    "sse-server-name": {
        url: `http://${sse_server_host}:${sse_server_port}/...`,
        transport: "sse"  // or `type: "sse"`
    },

    // WebSocket
    "ws-server-name": {
        url: `ws://${ws_server_host}:${ws_server_port}/...`
        // optionally `transport: "ws"` or `type: "ws"`
    },

"headers" 键可用于向 Streamable HTTP 和 SSE 连接传递 HTTP 头。
如果指定了 streamableHTTPOptions 或 sseOptions，此头配置将被覆盖（详见下文）。

    github: {
      // To avoid auto protocol fallback, specify the protocol explicitly when using authentication
      type: "http",  // or `transport: "http",`
      url: "https://api.githubcopilot.com/mcp/",
      headers: {
        "Authorization": `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`
      }
    },

自动检测行为（默认）：

• 对于未显式指定 transport 的 HTTP/HTTPS URL，库会遵循 MCP 规范建议
• 首先尝试 Streamable HTTP 传输
• 如果 Streamable HTTP 因 4xx 错误失败，则自动回退到 SSE 传输
• 非 4xx 错误（网络问题等）会直接重新抛出，不回退

显式选择传输方式：

• 设置 transport: "streamable_http"（或 VSCode 风格的配置 type: "http"）以强制使用 Streamable HTTP（不回退）
• 设置 transport: "sse" 以强制使用 SSE 传输（SSE 传输已弃用）
• WebSocket URL（ws:// 或 wss://）始终使用 WebSocket 传输

Streamable HTTP 是取代旧版 HTTP+SSE 传输的现代 MCP 传输方式。根据 MCP 官方文档：“自协议版本 2025-03-26 起，SSE 作为独立传输方式已弃用。它已被 Streamable HTTP 取代，后者将 SSE 作为可选流式机制纳入其中。”

快速通过 OAuth 访问远程 MCP 服务

如果你需要使用要求 OAuth 的 MCP 服务，请考虑使用 “mcp-remote”。

    notion: {
      command: "npx",
      args: ["-y", "mcp-remote", "https://mcp.notion.com/mcp"],
    },

Streamable HTTP 连接的身份验证支持

本库支持针对 Streamable HTTP 连接的 OAuth 2.1 身份验证：

import { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'

// Implement your own OAuth client provider
class MyOAuthProvider implements OAuthClientProvider {
  // Implementation details...
}

const mcpServers = {
  'secure-streamable-server': {
    url: 'https://secure-mcp-server.example.com/mcp',
    // To avoid auto protocol fallback, specify the protocol explicitly when using authentication
    transport: 'streamable_http', // or `type: "http",`
    streamableHTTPOptions: {
      // Provide an OAuth client provider
      authProvider: new MyOAuthProvider(),

      // Optionally customize HTTP requests
      requestInit: {
        headers: {
          'X-Custom-Header': 'custom-value',
        },
      },

      // Optionally configure reconnection behavior
      reconnectionOptions: {
        maxReconnectAttempts: 5,
        reconnectDelay: 1000,
      },
    },
  },
}

提供了测试实现：

• Streamable HTTP 身份验证测试：
  • MCP 客户端使用本库：streamable-http-auth-test-client.ts
  • 测试 MCP 服务：streamable-http-auth-test-server.ts

附录

故障排查

1. 启用调试日志：设置 logLevel: "debug" 以查看详细的连接和执行日志
2. 检查服务 stderr：对于本地 MCP 服务，使用 stderr 重定向捕获服务错误输出
3. 测试显式传输方式：尝试强制指定特定传输类型，以隔离自动检测问题
4. 独立验证服务：参考 MCP 文档中的调试部分

调试身份验证

1. 检查你的令牌/凭据 - 大多数身份验证失败是由于令牌过期或错误

2. 验证令牌权限 - 某些 MCP 服务需要特定作用域（例如 GitHub Copilot 许可证）

3. 使用 curl 测试 - 尝试一个简单的 HTTP 请求以验证你的身份验证设置：

   curl -H "Authorization: Bearer your-token" https://api.example.com/mcp/
   

大模型提供商 Schema 兼容性

不同的大模型提供商对函数调用的 JSON Schema 要求不兼容：

• OpenAI 要求：可选字段必须可为 null（.optional() + .nullable()） 以用于函数调用（基于 Structured Outputs API 的要求， 未来 SDK 版本将严格强制执行）
• Google Gemini API：拒绝可为 null 的字段和 $defs 引用，要求严格符合 OpenAPI 3.0 子集
• Anthropic Claude 和 xAI Grok：Schema 要求非常宽松，没有文档化的限制

注意：Google Vertex AI 提供了兼容 OpenAI 的端点，支持更宽松的要求。

实际影响

这给试图跨提供商创建通用 schema 的开发者带来了挑战。

一些 MCP 服务生成的 schema 无法满足所有提供商的要求。
例如，官方 Notion 本地 MCP 服务 @notionhq/notion-mcp-server（版本 1.9.0）和远程服务（位于 "https://mcp.notion.com/mcp"，mcp-remote 0.1.18）会产生：

OpenAI 警告：

Zod field at `#/definitions/read_file/properties/tail` uses `.optional()` without `.nullable()` which is not supported by the API. See: https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses#all-fields-must-be-required
... followed by many more

Gemini 错误：

[GoogleGenerativeAI Error]: Error fetching from https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent: [400 Bad Request] Invalid JSON payload received. Unknown name "exclusiveMaximum" at 'tools[0].function_declarations[14].parameters.properties[1].value': Cannot find field.
... followed by many more

解决方案

新增了 llmProvider 选项，用于执行特定于提供商的 JSON schema 转换：

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  llmProvider: 'openai', // Makes optional fields nullable
  // llmProvider: "google_gemini" // Applies Gemini's strict validation rules
  // llmProvider: "anthropic"     // No transformations needed
})

特性：

• 在应用转换时生成 INFO 级别的日志
• 帮助用户识别潜在的 MCP 服务 schema 改进点
• 未指定 llmProvider 时回退到原始 schema

特定于提供商的转换

提供商	应用的转换
openai	使可选字段可为空，处理联合类型
google_gemini 或 google_genai	过滤无效的必填字段，修复 anyOf 变体，移除不支持的特性
anthropic 和 xai	不进行转换，但 schema 的处理效率略高

对于其他提供商，请尝试不指定该选项：

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers)

参考资料

• OpenAI Function Calling
• Gemini API Schema Requirements
• Anthropic Tool Use

调试与日志记录

该库提供可配置的日志记录，以帮助调试连接和工具执行问题：

// Configure log level
const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  logLevel: 'debug',
})

// Use custom logger
class MyLogger implements McpToolsLogger {
  debug(...args: unknown[]) {
    console.log('[DEBUG]', ...args)
  }
  info(...args: unknown[]) {
    console.log('[INFO]', ...args)
  }
  warn(...args: unknown[]) {
    console.warn('[WARN]', ...args)
  }
  error(...args: unknown[]) {
    console.error('[ERROR]', ...args)
  }
}

const { tools, cleanup } = await convertMcpToLangchainTools(mcpServers, {
  logger: new MyLogger(),
})

可用的日志级别："fatal" | "error" | "warn" | "info" | "debug" | "trace"

面向开发者

有关开发和测试的更多信息，请参阅 README_DEV.md。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

贡献

欢迎提交 Issues 和 pull requests！
特别是，请分享任何与最新版本的 LangChain 和大模型相关的 issue，以及具体的 MCP 服务。