LangChain.js MCP 适配器版本演进：@langchain/mcp-adapters 从 0.1 到 1.1.4 的变更全解

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 Protocol（MCP）服务器工具桥接为 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.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.3：resource_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 Schema

1.1.2 的变更是fix(mcp-adapters): simplify complex JSON schemas for LLM compatibility。其实现是 tools.ts 中的simplifyJsonSchemaForLLM函数，用于移除 OpenAI 等 LLM 工具调用 API 在顶层不支持的 JSON Schema 模式：

• allOf：被深合并（deepMergeSchemas）进主 schema；
• anyOf/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-66414

1.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.0：onConnectionError与 timeout 传递

1.1.0 是 1.x 中唯一的 Minor 版本，包含一个新增选项和一个行为修复。

3.1 新增onConnectionError选项

该选项控制MultiServerMCPClient中某个服务器连接失败时的行为，取值为"throw"（默认）、"ignore"或自定义函数。从 client.ts 的initializeConnections方法可以完整看到这一逻辑的实现：

• 构造函数中通过 Zod schema（clientConfigSchema，定义于 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 的RequestOptions：

const 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-adapters@1.x是与之配套的版本线。

4.2 版本 1.0.3：解析$defs/$ref（Pydantic 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：正确传递 cwd

1.0.2 修复pass cwd to mcp sdk correctly。对应 connection.ts 中#createStdioTransport方法：从解析后的 stdio 连接配置中解构出cwd并透传给StdioClientTransport构造参数，同时把用户自定义env与系统PATH合并后传入。此前该参数未正确透传，导致 stdio 服务器在错误的工作目录下启动。

4.4 版本 1.0.1：moduleResolution "node" 兼容

1.0.1 修复moduleResolution: "node"的兼容性问题。从 package.json 的exports字段可以看到，该包同时提供 CJS（dist/index.cjs）与 ESM（dist/index.js）两套构建产物及对应类型声明（.d.cts/.d.ts），以兼容不同 TypeScript 模块解析策略的消费方。

五、0.1.x 系列回顾：SSE 支持与初始发布

5.1 版本 0.1.7（2024-05-08）：SSE 传输修复

CHANGELOG 对 0.1.7 记录了较详细的 Fixed/Added/Changed 三项内容：

• Fixed：修复 SSE headers 支持，使自定义 headers（如认证头）能正确传递给 eventsource；改进 SSE 连接的错误处理；适配 Node.js 的 eventsource 库；修复 agent 集成测试中的类型错误；
• Added：测试覆盖率提升至 80% 以上；新增错误处理测试；新增不同连接类型的集成测试；
• Changed：ESLint 配置排除dist目录；改进构建流程以避免 lint 报错。

其中 SSE headers 支持在现行代码中仍有直接对应：connection.ts 的#createSSETransport中，headers 同时通过eventSourceInit.fetch（初始 EventSource 连接）和requestInit.headers（后续 POST 请求）两处注入，并强制设置Accept: text/event-stream头；若配置了authProvider，fetch 包装器还会读取authProvider.tokens()并自动附加Authorization: Bearer <token>头——注释明确说明了原因是：一旦自定义了eventSourceInit.fetch，SDK 就不会自动附加 Authorization 头。

5.2 版本 0.1.2 与 0.1.0：工程化与初始发布

• 0.1.2（2023-03-10）：引入 GitHub Actions 工作流（PR 校验、CI、npm 发布）、Husky Git hooks、lint-staged、Issue/PR 模板，以及 CHANGELOG.md 与 CONTRIBUTING.md；
• 0.1.3（2023-03-11）：因 npm 发布冲突做版本号递增，并在 CI 中自动化版本管理；
• 0.1.0（2023-03-03）：初始发布，即奠定了该包至今的核心形态——支持 stdio 与 SSE 两种传输、MultiServerMCPClient多服务器客户端、配置文件支持、面向不同用例的示例，以及与 LangChain.js agent 的集成。

从源码结构看，0.1.0 确立的MultiServerMCPClient+loadMcpTools双入口设计（见 index.ts 的导出清单：MultiServerMCPClient、loadMcpTools及ClientConfig、Connection、LoadMcpToolsOptions等类型）在 1.x 版本中保持不变，仅持续叠加能力，这也是该包升级兼容性较好的原因。

六、版本选择建议与验证方式

结合 CHANGELOG 与 package.json 的实际内容，升级该包时可以关注以下要点：

1. LangChain v1 项目：应使用 1.x 版本线，peer 依赖要求@langchain/core ^1.0.0与@langchain/langgraph ^1.4.13；若你的 langgraph 版本低于该约束，会触发 peer 依赖告警。
2. 安全基线：需要 MCP SDK 修复（CVE-2025-66414）时，最低版本为 1.1.1；若你的 MCP 服务器工具 schema 由 Pydantic v2 生成，最低为 1.0.3（$defs/$ref解析）+ 1.1.2（顶层组合关键字简化）才能获得完整的 LLM 兼容 schema 处理管线。
3. 多服务器容错：需要「部分服务器不可用不影响整体」的部署形态时，onConnectionError（1.1.0 起）是核心开关，注意 ignore 模式下失败服务器会被移入失败集合、不再自动重试（见 client.ts 中#failedServers的逻辑）。
4. 环境要求：Node.js >= 20.10.0；zod同时接受 3.25.76+ 与 4.x 大版本，源码中通过zod/v3与zod/v4双入口导入以兼容两者。

如需在仓库内验证上述行为，可直接查看对应测试文件：连接与错误处理见 client.test.ts 与 connection.test.ts，工具 schema 与输出映射见 tools.test.ts，钩子行为见 hooks.test.ts；调试时可设置DEBUG='@langchain/mcp-adapters:*'打开该包的完整调试日志（各模块前缀如client、tools、connection在源码getDebugLog调用中可见）。

【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs