LangChain4j 中 MCP 工具与本地工具的集成实践

在 LangChain4j 项目中，开发者经常需要将 MCP（Model Control Plane）提供的远程工具与本地自定义工具结合使用。本文深入探讨了这一技术场景的解决方案，并提供了最佳实践建议。

背景与挑战

LangChain4j 作为 Java 生态中的 AI 应用开发框架，提供了强大的工具集成能力。在实际应用中，开发者可能面临以下需求：

1. 使用 MCP 提供的远程工具服务
2. 同时使用本地自定义的工具方法
3. 保持代码的简洁性和可维护性

解决方案演进

初始方案：手动映射工具

在早期版本中，开发者需要手动将 MCP 工具和本地工具映射为统一的工具规范：

// 创建 MCP 客户端
McpClient mcpClient = new DefaultMcpClient.Builder()
    .transport(transport)
    .build();

// 手动构建工具映射
Map<ToolSpecification, ToolExecutor> toolMap = new HashMap<>();
mcpClient.listTools().forEach(
    tool -> toolMap.put(tool, (req, mem) -> mcpClient.executeTool(req))
);

// 添加本地工具
ToolSpecification toolSpecification = ToolSpecification.builder()
    .name("query")
    .description("xxx")
    .parameters(JsonObjectSchema.builder()
        .addStringProperty("xxxP1", "xxxDesc")
        .addStringProperty("xxxP2", "xxxDesc")
        .build())
    .build();

ToolExecutor toolExecutor = (toolExecutionRequest, memoryId) -> {
    // 本地工具实现
    return customedToolService.query(xxxP1, xxxP2);
};
toolMap.put(toolSpecification, toolExecutor);

// 构建 AI 服务
return DefaultAiServices.builder(xxx.class)
    .tools(toolMap)
    .build();

这种方式虽然可行，但存在以下问题：

• 代码冗长，维护成本高
• 需要手动处理工具参数映射
• 不利于工具的扩展和复用

改进方案：注解式工具定义

对于纯本地工具，LangChain4j 提供了更简洁的注解式定义方式：

@Component
public class XxxAgentTools {
    @Tool("xxx tool")
    public String query(
        @P(value = "p1 xxxDesc") String xxxP1, 
        @P(value = "p2 xxxDesc") Long xxxP2) {
        return xxxToolService.execute(xxxP1, xxxP2);
    }
}

这种方式明显更加简洁和易于维护，但无法直接与 MCP 工具集成。

最新解决方案：McpToolProvider

从 LangChain4j 1.0.0-beta4 版本开始，框架提供了 McpToolProvider 来简化 MCP 工具与本地工具的集成：

// 创建 MCP 工具提供者
ToolProvider mcpToolProvider = McpToolProvider.builder()
    .mcpClients(List.of(mcpClient))
    .build();

// 构建 AI 服务，同时使用 MCP 工具和本地工具
AiServices.builder(Assistant.class)
    .chatModel(...)
    .toolProvider(mcpToolProvider)
    .tools(new XxxAgentTools(...))
    .build();

这一方案具有以下优势：

1. 简洁性：无需手动映射工具
2. 可维护性：保持注解式工具定义的优雅
3. 扩展性：轻松添加新工具
4. 版本兼容性：确保使用最新版本（1.0.0-rc1）可获得最佳体验

最佳实践建议

1. 版本管理：确保使用 langchain4j-core、langchain4j、langchain4j-http-client 等核心模块的 1.0.0-rc1 版本，其他模块使用 1.0.0-beta4 版本。

2. 工具组织：

   • 将相关工具逻辑组织在同一个工具类中
   • 使用有意义的工具名称和参数描述
   • 保持工具方法的单一职责

3. 错误处理：在工具方法中加入适当的异常处理逻辑，确保健壮性。

4. 文档注释：为工具方法添加详细的 JavaDoc 注释，说明工具的用途、参数和返回值。

总结

LangChain4j 框架不断演进，为开发者提供了越来越便捷的工具集成方式。通过 McpToolProvider 与注解式工具定义的结合，开发者可以轻松实现远程 MCP 工具与本地工具的无缝集成，同时保持代码的简洁性和可维护性。随着框架的持续发展，我们期待看到更多简化 AI 应用开发的创新特性。