LangChain4j 中 MCP 工具传递数量不一致问题解析

问题背景

在使用 LangChain4j 项目与 Model Context Protocol (MCP) 服务器交互时，开发者发现实际传递给模型的工具数量与预期不符。具体表现为：通过 @modelcontextprotocol/server-github 获取的工具列表仅包含 9 个功能，而根据服务器源码和文档，应当提供 16 个工具。

技术细节分析

问题表现

当开发者使用以下代码片段连接 MCP 服务器时：

McpTransport transport = new StdioMcpTransport.Builder()
        .command(List.of("/usr/bin/npm", "exec",
                "@modelcontextprotocol/server-github"
        ))
        .logEvents(true)
        .environment(Map.of("GITHUB_PERSONAL_ACCESS_TOKEN", "notImportantForThisTest"))
        .build();

McpClient mcpClient = new DefaultMcpClient.Builder()
        .transport(transport)
        .build();

mcpClient.listTools().forEach(toolspec -> System.out.println(toolspec.name()));

实际输出仅包含 9 个工具名称，而预期应当包含 16 个 GitHub 相关操作工具。

根本原因

经过深入调查，发现问题根源在于版本差异。MCP 服务器的新增工具是在 0.6.2 版本发布后添加的，尚未包含在正式发布的版本中。具体表现为：

1. 通过 npm 安装的正式版本（0.6.2）不包含最新的工具实现
2. 直接从源码构建的版本则包含完整的 17 个工具

解决方案

开发者可以采用以下两种方式解决此问题：

1. 等待官方发布新版本：待 MCP 服务器发布包含新增工具的新版本后，更新依赖即可

2. 从源码构建运行：

   • 克隆 MCP 服务器源码仓库
   • 执行 npm install 安装依赖
   • 修改 Java 代码中的命令路径，直接指向构建后的服务器入口文件

.command(List.of("node", "path/to/src/github/dist/index.js"))

技术建议

对于类似集成问题，建议开发者：

1. 版本兼容性检查：在集成第三方服务时，始终验证版本兼容性
2. 源码构建验证：当遇到功能差异时，尝试从源码构建以确认是否为版本问题
3. 日志调试：启用详细日志（如示例中的 .logEvents(true)）有助于诊断通信问题

总结

该问题展示了在集成开源组件时常见的版本兼容性挑战。通过深入分析版本差异和构建过程，开发者可以准确识别问题根源并采取相应解决措施。这也提醒我们在技术选型时需要关注组件更新频率和发布周期，以确保获得完整功能支持。