LangChain.js MCP 适配器版本演进langchain/mcp-adapters 从 0.1 到 1.1.4 的变更全解【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs本文以libs/langchain-mcp-adapters包内的 CHANGELOG.md 为主体逐版本梳理langchain/mcp-adapters从 0.1.0 初始发布到 1.1.4 的完整变更脉络并结合仓库源码client.ts、tools.ts、connection.ts说明每个关键修复与新增选项的底层实现原理帮助你在升级依赖、排查 MCP 连接问题以及理解工具调用链内部行为时快速定位到对应版本与源码位置。一、包定位与版本总览langchain/mcp-adapters是 LangChain.js 仓库中专用于将 Anthropic Model Context ProtocolMCP服务器工具桥接为 LangChain / LangGraph 可用工具的轻量适配层。根据 README.md它的核心能力包括通过 stdio本地进程或 Streamable HTTP远程自动回退 SSE 以兼容旧实现连接 MCP 服务器MultiServerMCPClient支持同时连接多个 MCP 服务器工具可按服务器组织或扁平化访问与 LangChain.js、LangGraph.js 兼容支持文本、图片、嵌入资源等富内容工具输出。当前仓库中该包 package.json 声明的版本为1.1.4运行环境要求node 20.10.0并依赖modelcontextprotocol/sdk ^1.30.0、debug ^4.4.3、zod ^3.25.76 || ^4。CHANGELOG 记录了两个阶段的演进早期 0.1.x 系列2023-03 前后手工维护的变更记录与 1.x 系列1.0.0 起与 LangChain v1.0 对齐由 PR 驱动的语义化变更日志。下表汇总各版本的核心变更后文逐条展开版本类型核心变更1.1.4Patch升级 langgraph 依赖以跟踪序列化修复1.1.3PatchMCPresource_link内容块映射为 LangChain URL 内容块1.1.2Patch简化复杂 JSON Schema 以提升 LLM 兼容性1.1.1Patch升级modelcontextprotocol/sdk以修复 CVE-2025-664141.1.0Minor新增onConnectionError选项保留 RunnableConfig 中的 timeout1.0.3Patch解析 JSON Schema 中的$defs/$refPydantic v2 兼容1.0.2Patch正确向 MCP SDK 传递cwd1.0.1Patch修复moduleResolution: node兼容性1.0.0Major对齐 LangChain v1.00.1.7Patch修复 SSE headers 支持改进 SSE 错误处理0.1.2 / 0.1.0—初始发布stdio/SSE 传输、MultiServerMCPClient、配置支持二、1.1.x 系列连接容错、Schema 兼容与安全修复2.1 版本 1.1.4跟踪 langgraph 序列化修复CHANGELOG 记录 1.1.4 的变更为chore(langgraph): update langgraph deps to track serialization fix。这与 package.json 中的 peer 依赖一致langchain/core: ^1.0.0与langchain/langgraph: ^1.4.13。从源码结构看tools.ts中会import { Command, getCurrentTaskInput } from langchain/langgraph即该包在 LangGraph 环境运行时依赖 langgraph 的状态读取与Command类型升级 peer 依赖版本用于让序列化修复在工具调用链路如afterToolCall返回Command实例中正确生效。2.2 版本 1.1.3resource_link 内容块的 URL 映射1.1.3 的变更是「map mcp resource link content blocks to langchain url content block」。对应实现位于 tools.ts 的_toolOutputToContentBlocks函数中MCPresource_link内容块被转换为type: file、source_type: url的标准文件内容块并携带url来自content.uri与mime_type。这意味着启用useStandardContentBlocks的应用现在可以统一通过标准文件块协议消费「仅含 URI 引用」的资源链接而无需额外处理原始 MCP 结构。2.3 版本 1.1.2为 LLM 简化复杂 JSON Schema1.1.2 的变更是fix(mcp-adapters): simplify complex JSON schemas for LLM compatibility。其实现是 tools.ts 中的simplifyJsonSchemaForLLM函数用于移除 OpenAI 等 LLM 工具调用 API 在顶层不支持的 JSON Schema 模式allOf被深合并deepMergeSchemas进主 schemaanyOf/oneOf若各分支都是对象则合并其 properties且required只保留所有分支的交集体现联合类型「任一匹配即可」的语义if/then/else条件模式被移除但通过extractPropertiesFromConditional从 then/else 分支抽取 properties 合并进来not、$schema、unevaluatedProperties直接剔除转换递归作用于嵌套的 properties、items 与 additionalProperties保证嵌套 schema 同样被简化。这个处理与下一条 1.0.3 的$defs解析共同构成了工具入参 schema 的完整处理管线。2.4 版本 1.1.1升级 MCP SDK 以修复 CVE-2025-664141.1.1 的变更是bump modelcontextprotocol/sdk to address CVE-2025-66414。当前 package.json 中modelcontextprotocol/sdk的版本约束为^1.30.0即安装时解析到的 SDK 版本需覆盖该安全公告。对使用者而言升级到 1.1.1 及以上的langchain/mcp-adapters即间接获得 SDK 的安全修复无需单独处理 SDK 依赖。三、版本 1.1.0onConnectionError与 timeout 传递1.1.0 是 1.x 中唯一的 Minor 版本包含一个新增选项和一个行为修复。3.1 新增onConnectionError选项该选项控制MultiServerMCPClient中某个服务器连接失败时的行为取值为throw默认、ignore或自定义函数。从 client.ts 的initializeConnections方法可以完整看到这一逻辑的实现构造函数中通过 Zod schemaclientConfigSchema定义于 types.ts校验配置#onConnectionError记录策略连接失败的服务器会被加入#failedServers集合在 ignore 模式下后续初始化会直接跳过这些服务器不再重试自定义函数接收{ serverName, error }若函数抛出错误则错误继续向上传播正常返回则视为该服务器被忽略并记录 WARN 日志全部服务器都失败且策略为ignore时仅记录警告WARN: No servers successfully connected...而不抛错。典型用法摘自 README 的错误处理章节关键服务器失败时抛出、可选服务器失败时仅告警const client new MultiServerMCPClient({ mcpServers: { critical-server: { transport: http, url: http://localhost:8000/mcp }, optional-server: { transport: http, url: http://localhost:8001/mcp }, }, onConnectionError: ({ serverName, error }) { if (serverName critical-server) { throw new Error(Critical server ${serverName} failed: ${error}); } console.warn(Optional server ${serverName} failed, continuing...); }, });相关行为可通过 connection.test.ts 与 client.test.ts 中的测试用例验证。3.2 保留 RunnableConfig 中的 timeout另一项变更是preserve timeout from RunnableConfig in MCP tool calls。在 tools.ts 的_callTool中可以看到实现细节ensureConfig()会把timeout转成AbortSignal并删除该字段因此适配层显式从config.metadata.timeoutMs读取数值型 timeout回退到config.timeout再连同config.signal一并封装进 MCP SDK 的RequestOptionsconst numericTimeout (config?.metadata?.timeoutMs as number | undefined) ?? config?.timeout; const requestOptions: RequestOptions { ...(numericTimeout ? { timeout: numericTimeout } : {}), ...(config?.signal ? { signal: config.signal } : {}), // ...onProgress 回调 };这保证了通过 LangChain 标准RunnableConfig设置的超时如tool.withConfig({ timeout: 300000 })或invoke(input, { timeout: 5000 })真正传递到 MCP SDK 的callTool请求而不是只作用于外层 Runnable 包装。四、1.0.x 系列对齐 LangChain v1.0 的三个修复4.1 版本 1.0.0面向 LangChain v1.0 对齐CHANGELOG 中 1.0.0 的说明是该发布将包更新为与 LangChain v1.0 兼容。从 package.json 可确认其 peer 依赖为langchain/core ^1.0.0与langchain/langgraph ^1.4.13均非 optional。对已使用langchainv1 主包提供createAgent等 API的项目langchain/mcp-adapters1.x是与之配套的版本线。4.2 版本 1.0.3解析$defs/$refPydantic v2 兼容1.0.3 的变更是resolve $defs/$ref in JSON schemas for Pydantic v2 compatibility。实现位于 tools.ts 的dereferenceJsonSchema函数将#/$defs/name与#/definitions/name形式的本地引用内联展开到 schema 中展开后移除$defs/definitions段通过visitedRefs集合检测循环引用遇到循环时以{ type: object }占位以避免无限递归注释中说明了动机部分 JSON Schema 校验器如cfworker/json-schema不会自动解析$ref到$defs。调用位置在loadMcpTools中每个工具的inputSchema先经过dereferenceJsonSchema去引用再经过simplifyJsonSchemaForLLM简化最终作为DynamicStructuredTool的 schema。Pydantic v2 生成的 MCP 服务器工具 schema 大量使用$defs此修复正是让这类服务器在 LangChain 侧能正确暴露入参结构的关键。4.3 版本 1.0.2正确传递 cwd1.0.2 修复pass cwd to mcp sdk correctly。对应 connection.ts 中#createStdioTransport方法从解析后的 stdio 连接配置中解构出cwd并透传给StdioClientTransport构造参数同时把用户自定义env与系统PATH合并后传入。此前该参数未正确透传导致 stdio 服务器在错误的工作目录下启动。4.4 版本 1.0.1moduleResolution node 兼容1.0.1 修复moduleResolution: node的兼容性问题。从 package.json 的exports字段可以看到该包同时提供 CJSdist/index.cjs与 ESMdist/index.js两套构建产物及对应类型声明.d.cts/.d.ts以兼容不同 TypeScript 模块解析策略的消费方。五、0.1.x 系列回顾SSE 支持与初始发布5.1 版本 0.1.72024-05-08SSE 传输修复CHANGELOG 对 0.1.7 记录了较详细的 Fixed/Added/Changed 三项内容Fixed修复 SSE headers 支持使自定义 headers如认证头能正确传递给 eventsource改进 SSE 连接的错误处理适配 Node.js 的 eventsource 库修复 agent 集成测试中的类型错误Added测试覆盖率提升至 80% 以上新增错误处理测试新增不同连接类型的集成测试ChangedESLint 配置排除dist目录改进构建流程以避免 lint 报错。其中 SSE headers 支持在现行代码中仍有直接对应connection.ts 的#createSSETransport中headers 同时通过eventSourceInit.fetch初始 EventSource 连接和requestInit.headers后续 POST 请求两处注入并强制设置Accept: text/event-stream头若配置了authProviderfetch 包装器还会读取authProvider.tokens()并自动附加Authorization: Bearer token头——注释明确说明了原因是一旦自定义了eventSourceInit.fetchSDK 就不会自动附加 Authorization 头。5.2 版本 0.1.2 与 0.1.0工程化与初始发布0.1.22023-03-10引入 GitHub Actions 工作流PR 校验、CI、npm 发布、Husky Git hooks、lint-staged、Issue/PR 模板以及 CHANGELOG.md 与 CONTRIBUTING.md0.1.32023-03-11因 npm 发布冲突做版本号递增并在 CI 中自动化版本管理0.1.02023-03-03初始发布即奠定了该包至今的核心形态——支持 stdio 与 SSE 两种传输、MultiServerMCPClient多服务器客户端、配置文件支持、面向不同用例的示例以及与 LangChain.js agent 的集成。从源码结构看0.1.0 确立的MultiServerMCPClientloadMcpTools双入口设计见 index.ts 的导出清单MultiServerMCPClient、loadMcpTools及ClientConfig、Connection、LoadMcpToolsOptions等类型在 1.x 版本中保持不变仅持续叠加能力这也是该包升级兼容性较好的原因。六、版本选择建议与验证方式结合 CHANGELOG 与 package.json 的实际内容升级该包时可以关注以下要点LangChain v1 项目应使用 1.x 版本线peer 依赖要求langchain/core ^1.0.0与langchain/langgraph ^1.4.13若你的 langgraph 版本低于该约束会触发 peer 依赖告警。安全基线需要 MCP SDK 修复CVE-2025-66414时最低版本为 1.1.1若你的 MCP 服务器工具 schema 由 Pydantic v2 生成最低为 1.0.3$defs/$ref解析 1.1.2顶层组合关键字简化才能获得完整的 LLM 兼容 schema 处理管线。多服务器容错需要「部分服务器不可用不影响整体」的部署形态时onConnectionError1.1.0 起是核心开关注意 ignore 模式下失败服务器会被移入失败集合、不再自动重试见 client.ts 中#failedServers的逻辑。环境要求Node.js 20.10.0zod同时接受 3.25.76 与 4.x 大版本源码中通过zod/v3与zod/v4双入口导入以兼容两者。如需在仓库内验证上述行为可直接查看对应测试文件连接与错误处理见 client.test.ts 与 connection.test.ts工具 schema 与输出映射见 tools.test.ts钩子行为见 hooks.test.ts调试时可设置DEBUGlangchain/mcp-adapters:*打开该包的完整调试日志各模块前缀如client、tools、connection在源码getDebugLog调用中可见。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考