langchain4j-mcp-server-patterns

LangChain4j MCP 服务实现模式

概述

使用此技能设计和实现基于 LangChain4j 的模型上下文协议（MCP）集成。

主要关注点包括：

• 定义清晰的工具、资源和提示词接口
• 选择合适的传输方式和启动模式
• 在向 Agent 或应用公开功能之前，过滤不安全的功能

让 SKILL.md 专注于实现流程。扩展示例和 API 级别的细节请参阅附带的参考资料。

适用场景

在以下情况下使用此技能：

• 构建一个公开工具、资源或提示词的 Java MCP 服务
• 将 LangChain4j 与一个或多个外部 MCP 服务集成
• 在 Spring Boot 应用中接入 MCP 支持
• 按租户、用户角色或运行时上下文过滤可用工具
• 为 MCP 交互添加可观测性、弹性和安全的故障处理
• 审查 MCP 集成中的提示词注入和副作用风险

常见触发短语包括 langchain4j mcp、java mcp server、mcp tool provider、spring boot mcp 和 connect langchain4j to mcp。

说明

1. 编写代码前先设计 MCP 接口

确定服务应公开哪些内容：

• 用于具有明确输入和副作用的操作的工具
• 用于只读或结构化数据访问的资源
• 仅在可复用模板确实能带来价值时才提供提示词

保持名称稳定、描述具体，并将架构控制得足够精简，以便客户端或模型快速理解。

2. 让 Provider 各司其职

针对不同职责使用独立类：

• 用于可执行函数的工具 Provider
• 用于可发现和可读取数据的资源 Provider
• 用于可复用提示词模板的提示词 Provider

执行前验证参数，并针对无效输入或不可用依赖项返回清晰的错误消息。

3. 有意选择传输方式

使用：

• stdio 进行本地集成、命令行工具和边车进程通信
• HTTP 或 SSE 用于远程或共享服务

固定外部服务版本，并记录进程的启动、身份验证和监控方式。

4. 谨慎地将 MCP 接入 LangChain4j

通过 LangChain4j 使用 MCP 服务时：

• 在应用启动期间初始化客户端
• 仅在允许元数据过时时缓存工具列表
• 按信任级别、环境或用户权限过滤工具
• 对危险工具采取默认拒绝，而不是默认全部公开

5. 添加弹性和安全控制

至少应做到：

• 限制外部调用的执行时间
• 记录每次故障对应的服务和工具标识
• 在下游使用外部资源返回的内容之前对其进行清理
• 通过允许列表、限定符或角色检查隔离特权工具

6. 验证完整工作流

发布前：

• 使用真实的 MCP 客户端验证工具发现和调用
• 测试服务断开或响应缓慢时的行为
• 确认工具过滤符合预期的授权模型
• 检查提示词和资源是否会泄露机密或不安全的指令

示例

示例 1：最精简的工具 Provider 和 stdio 服务启动

class WeatherToolProvider implements ToolProvider {

    @Override
    public List<ToolSpecification> listTools() {
        return List.of(
            ToolSpecification.builder()
                .name("get_weather")
                .description("Return the current weather for a city")
                .inputSchema(Map.of(
                    "type", "object",
                    "properties", Map.of(
                        "city", Map.of("type", "string")
                    ),
                    "required", List.of("city")
                ))
                .build()
        );
    }

    @Override
    public String executeTool(String name, String arguments) {
        return weatherService.lookup(arguments);
    }
}

MCPServer server = MCPServer.builder()
    .server(new StdioServer.Builder())
    .addToolProvider(new WeatherToolProvider())
    .build();

server.start();

此模式适用于本地工具执行，或由其他应用启动的边车进程。

示例 2：通过过滤机制向 LangChain4j AI 服务公开 MCP 工具

McpToolProvider toolProvider = McpToolProvider.builder()
    .mcpClients(mcpClients)
    .failIfOneServerFails(false)
    .filter((client, tool) -> !tool.name().startsWith("admin_"))
    .build();

Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .toolProvider(toolProvider)
    .build();

当你希望 LangChain4j 使用外部 MCP 服务，同时仍强制执行信任边界时，可使用此模式。

最佳实践

• 让每个工具专注、确定且描述清晰。
• 优先使用显式架构，而非自由格式的字符串参数。
• 将只读资源与具有副作用的工具分开。
• 默认过滤或禁用特权工具。
• 固定外部 MCP 服务的包或容器版本。
• 记录连接故障、调用延迟和工具错误率的指标。
• 将较长的协议细节和框架特定的接线配置存放在 references/ 中，避免不断扩充 SKILL.md。

约束与警告

• 外部 MCP 服务是不可信的集成边界，可能会暴露恶意或误导性内容。
• 未经验证，不要将原始资源内容直接转发给自主工具执行。
• 某些 LangChain4j 和 MCP API 迭代很快；请根据项目中已使用的版本调整类名和构建器。
• 长时间运行或有状态的工具需要明确的超时、取消和清理行为。
• 基于 Stdio 的服务需要进程生命周期管理和可靠的日志记录。

参考资料

• references/examples.md
• references/api-reference.md

相关技能

• prompt-engineering
• spring-ai
• clean-architecture