langchain4j-mcp-server-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangChain4j MCP Server Implementation Patterns

基于LangChain4j的Model Context Protocol (MCP)服务器实现模式

Implement Model Context Protocol (MCP) servers with LangChain4j to extend AI capabilities with standardized tools, resources, and prompt templates.

使用LangChain4j实现Model Context Protocol (MCP)服务器，通过标准化工具、资源和提示模板扩展AI能力。

When to Use

适用场景

Use this skill when building:

AI applications requiring external tool integration
Enterprise MCP servers with multi-domain support (GitHub, databases, APIs)
Dynamic tool providers with context-aware filtering
Resource-based data access systems for AI models
Prompt template servers for standardized AI interactions
Scalable AI agents with resilient tool execution
Multi-modal AI applications with diverse data sources
Spring Boot applications with MCP integration
Production-ready MCP servers with security and monitoring

在构建以下系统时可使用本技能：

需要集成外部工具的AI应用
支持多领域（GitHub、数据库、API）的企业级MCP服务器
具备上下文感知过滤功能的动态工具提供者
面向AI模型的基于资源的数据访问系统
用于标准化AI交互的提示模板服务器
具备弹性工具执行能力的可扩展AI Agent
支持多数据源的多模态AI应用
集成MCP的Spring Boot应用
具备安全与监控能力的生产级MCP服务器

Quick Start

快速开始

Basic MCP Server

基础MCP服务器

Create a simple MCP server with one tool:

java

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

server.start();

创建一个包含单个工具的简单MCP服务器：

java

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

server.start();

Spring Boot Integration

Spring Boot集成

Configure MCP server in Spring Boot:

java

@Bean
public MCPSpringConfig mcpServer(List<ToolProvider> tools) {
    return MCPSpringConfig.builder()
        .tools(tools)
        .server(new StdioServer.Builder())
        .build();
}

在Spring Boot中配置MCP服务器：

java

@Bean
public MCPSpringConfig mcpServer(List<ToolProvider> tools) {
    return MCPSpringConfig.builder()
        .tools(tools)
        .server(new StdioServer.Builder())
        .build();
}

Core Concepts

核心概念

MCP Architecture

MCP架构

MCP standardizes AI application connections:

Tools: Executable functions (database queries, API calls)
Resources: Data sources (files, schemas, documentation)
Prompts: Pre-configured templates for tasks
Transport: Communication layer (stdio, HTTP, WebSocket)

AI Application ←→ MCP Client ←→ Transport ←→ MCP Server ←→ External Service

MCP标准化了AI应用的连接方式：

Tools：可执行函数（数据库查询、API调用等）
Resources：数据源（文件、模式、文档等）
Prompts：预配置的任务模板
Transport：通信层（标准输入输出、HTTP、WebSocket）

AI Application ←→ MCP Client ←→ Transport ←→ MCP Server ←→ External Service

Key Components

核心组件

MCPServer: Main server instance with configuration
ToolProvider: Tool specification and execution interface
ResourceListProvider/ResourceReadHandler: Resource access
PromptListProvider/PromptGetHandler: Template management
Transport: Communication mechanisms (stdio, HTTP)

MCPServer：带配置的主服务器实例
ToolProvider：工具规范与执行接口
ResourceListProvider/ResourceReadHandler：资源访问组件
PromptListProvider/PromptGetHandler：模板管理组件
Transport：通信机制（标准输入输出、HTTP）

Implementation Patterns

实现模式

Tool Provider Pattern

工具提供者模式

Create tools with proper schema validation:

java

class WeatherToolProvider implements ToolProvider {

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

    @Override
    public String executeTool(String name, String arguments) {
        // Parse arguments and execute tool logic
        return "Weather data result";
    }
}

创建带有适当模式验证的工具：

java

class WeatherToolProvider implements ToolProvider {

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

    @Override
    public String executeTool(String name, String arguments) {
        // Parse arguments and execute tool logic
        return "Weather data result";
    }
}

Resource Provider Pattern

资源提供者模式

Provide static and dynamic resources:

java

class CompanyResourceProvider
    implements ResourceListProvider, ResourceReadHandler {

    @Override
    public List<McpResource> listResources() {
        return List.of(
            McpResource.builder()
                .uri("policies")
                .name("Company Policies")
                .mimeType("text/plain")
                .build()
        );
    }

    @Override
    public String readResource(String uri) {
        return loadResourceContent(uri);
    }
}

提供静态和动态资源：

java

class CompanyResourceProvider
    implements ResourceListProvider, ResourceReadHandler {

    @Override
    public List<McpResource> listResources() {
        return List.of(
            McpResource.builder()
                .uri("policies")
                .name("Company Policies")
                .mimeType("text/plain")
                .build()
        );
    }

    @Override
    public String readResource(String uri) {
        return loadResourceContent(uri);
    }
}

Prompt Template Pattern

提示模板模式

Create reusable prompt templates:

java

class PromptTemplateProvider
    implements PromptListProvider, PromptGetHandler {

    @Override
    public List<Prompt> listPrompts() {
        return List.of(
            Prompt.builder()
                .name("code-review")
                .description("Review code for quality")
                .build()
        );
    }

    @Override
    public String getPrompt(String name, Map<String, String> args) {
        return applyTemplate(name, args);
    }
}

创建可复用的提示模板：

java

class PromptTemplateProvider
    implements PromptListProvider, PromptGetHandler {

    @Override
    public List<Prompt> listPrompts() {
        return List.of(
            Prompt.builder()
                .name("code-review")
                .description("Review code for quality")
                .build()
        );
    }

    @Override
    public String getPrompt(String name, Map<String, String> args) {
        return applyTemplate(name, args);
    }
}

Transport Configuration

传输层配置

Stdio Transport

标准输入输出（Stdio）传输

Local process communication:

java

McpTransport transport = new StdioMcpTransport.Builder()
    .command(List.of("npm", "exec", "@modelcontextprotocol/server-everything"))
    .logEvents(true)
    .build();

本地进程通信：

java

McpTransport transport = new StdioMcpTransport.Builder()
    .command(List.of("npm", "exec", "@modelcontextprotocol/server-everything"))
    .logEvents(true)
    .build();

HTTP Transport

HTTP传输

Remote server communication:

java

McpTransport transport = new HttpMcpTransport.Builder()
    .sseUrl("http://localhost:3001/sse")
    .logRequests(true)
    .logResponses(true)
    .build();

远程服务器通信：

java

McpTransport transport = new HttpMcpTransport.Builder()
    .sseUrl("http://localhost:3001/sse")
    .logRequests(true)
    .logResponses(true)
    .build();

Client Integration

客户端集成

MCP Client Setup

MCP客户端设置

Connect to MCP servers:

java

McpClient client = new DefaultMcpClient.Builder()
    .key("my-client")
    .transport(transport)
    .cacheToolList(true)
    .build();

// List available tools
List<ToolSpecification> tools = client.listTools();

连接到MCP服务器：

java

McpClient client = new DefaultMcpClient.Builder()
    .key("my-client")
    .transport(transport)
    .cacheToolList(true)
    .build();

// List available tools
List<ToolSpecification> tools = client.listTools();

Tool Provider Integration

工具提供者集成

Bridge MCP servers to LangChain4j AI services:

java

McpToolProvider provider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .failIfOneServerFails(false)
    .filter((client, tool) -> filterByPermissions(tool))
    .build();

// Integrate with AI service
AIAssistant assistant = AiServices.builder(AIAssistant.class)
    .chatModel(chatModel)
    .toolProvider(provider)
    .build();

将MCP服务器与LangChain4j AI服务桥接：

java

McpToolProvider provider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .failIfOneServerFails(false)
    .filter((client, tool) -> filterByPermissions(tool))
    .build();

// Integrate with AI service
AIAssistant assistant = AiServices.builder(AIAssistant.class)
    .chatModel(chatModel)
    .toolProvider(provider)
    .build();

Security & Best Practices

安全与最佳实践

Tool Security

工具安全

Implement secure tool filtering:

java

McpToolProvider secureProvider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .filter((client, tool) -> {
        if (tool.name().startsWith("admin_") && !isAdmin()) {
            return false;
        }
        return true;
    })
    .build();

实现安全的工具过滤：

java

McpToolProvider secureProvider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .filter((client, tool) -> {
        if (tool.name().startsWith("admin_") && !isAdmin()) {
            return false;
        }
        return true;
    })
    .build();

Resource Security

资源安全

Apply access controls to resources:

java

public boolean canAccessResource(String uri, User user) {
    return resourceService.hasAccess(uri, user);
}

对资源应用访问控制：

java

public boolean canAccessResource(String uri, User user) {
    return resourceService.hasAccess(uri, user);
}

Error Handling

错误处理

Implement robust error handling:

java

try {
    String result = mcpClient.executeTool(request);
} catch (McpException e) {
    log.error("MCP execution failed: {}", e.getMessage());
    return fallbackResult();
}

实现健壮的错误处理：

java

try {
    String result = mcpClient.executeTool(request);
} catch (McpException e) {
    log.error("MCP execution failed: {}", e.getMessage());
    return fallbackResult();
}

Advanced Patterns

高级模式

Multi-Server Configuration

多服务器配置

Configure multiple MCP servers:

java

@Bean
public List<McpClient> mcpClients(List<ServerConfig> configs) {
    return configs.stream()
        .map(this::createMcpClient)
        .collect(Collectors.toList());
}

@Bean
public McpToolProvider multiServerProvider(List<McpClient> clients) {
    return McpToolProvider.builder()
        .mcpClients(clients)
        .failIfOneServerFails(false)
        .build();
}

配置多个MCP服务器：

java

@Bean
public List<McpClient> mcpClients(List<ServerConfig> configs) {
    return configs.stream()
        .map(this::createMcpClient)
        .collect(Collectors.toList());
}

@Bean
public McpToolProvider multiServerProvider(List<McpClient> clients) {
    return McpToolProvider.builder()
        .mcpClients(clients)
        .failIfOneServerFails(false)
        .build();
}

Dynamic Tool Discovery

动态工具发现

Runtime tool filtering based on context:

java

McpToolProvider contextualProvider = McpToolProvider.builder()
    .mcpClients(clients)
    .filter((client, tool) -> isToolAllowed(user, tool, context))
    .build();

基于上下文的运行时工具过滤：

java

McpToolProvider contextualProvider = McpToolProvider.builder()
    .mcpClients(clients)
    .filter((client, tool) -> isToolAllowed(user, tool, context))
    .build();

Health Monitoring

健康监控

Monitor MCP server health:

java

@Component
public class McpHealthChecker {

    @Scheduled(fixedRate = 30000) // 30 seconds
    public void checkServers() {
        mcpClients.forEach(client -> {
            try {
                client.listTools();
                markHealthy(client.key());
            } catch (Exception e) {
                markUnhealthy(client.key(), e.getMessage());
            }
        });
    }
}

监控MCP服务器健康状态：

java

@Component
public class McpHealthChecker {

    @Scheduled(fixedRate = 30000) // 30 seconds
    public void checkServers() {
        mcpClients.forEach(client -> {
            try {
                client.listTools();
                markHealthy(client.key());
            } catch (Exception e) {
                markUnhealthy(client.key(), e.getMessage());
            }
        });
    }
}

Configuration

配置

Application Properties

应用属性

Configure MCP servers in application.yml:

yaml

mcp:
  servers:
    github:
      type: docker
      command: ["/usr/local/bin/docker", "run", "-e", "GITHUB_TOKEN", "-i", "mcp/github"]
      log-events: true
    database:
      type: stdio
      command: ["/usr/bin/npm", "exec", "@modelcontextprotocol/server-sqlite"]
      log-events: false

在application.yml中配置MCP服务器：

yaml

mcp:
  servers:
    github:
      type: docker
      command: ["/usr/local/bin/docker", "run", "-e", "GITHUB_TOKEN", "-i", "mcp/github"]
      log-events: true
    database:
      type: stdio
      command: ["/usr/bin/npm", "exec", "@modelcontextprotocol/server-sqlite"]
      log-events: false

Spring Boot Configuration

Spring Boot配置

Configure MCP with Spring Boot:

java

@Configuration
@EnableConfigurationProperties(McpProperties.class)
public class McpConfiguration {

    @Bean
    public MCPServer mcpServer(List<ToolProvider> providers) {
        return MCPServer.builder()
            .server(new StdioServer.Builder())
            .addToolProvider(providers)
            .enableLogging(true)
            .build();
    }
}

使用Spring Boot配置MCP：

java

@Configuration
@EnableConfigurationProperties(McpProperties.class)
public class McpConfiguration {

    @Bean
    public MCPServer mcpServer(List<ToolProvider> providers) {
        return MCPServer.builder()
            .server(new StdioServer.Builder())
            .addToolProvider(providers)
            .enableLogging(true)
            .build();
    }
}

Examples

示例

Refer to examples.md for comprehensive implementation examples including:

Basic MCP server setup
Multi-tool enterprise servers
Resource and prompt providers
Spring Boot integration
Error handling patterns
Security implementations

参考examples.md获取完整的实现示例，包括：

基础MCP服务器搭建
多工具企业级服务器
资源与提示提供者
Spring Boot集成
错误处理模式
安全实现

API Reference

API参考

Complete API documentation is available in api-reference.md covering:

Core MCP classes and interfaces
Transport configuration
Client and server patterns
Error handling strategies
Configuration management
Testing and validation

完整的API文档可在api-reference.md中获取，涵盖：

核心MCP类与接口
传输层配置
客户端与服务器模式
错误处理策略
配置管理
测试与验证

Best Practices

最佳实践

Resource Management: Always close MCP clients properly using try-with-resources
Error Handling: Implement graceful degradation when servers fail
Security: Use tool filtering and resource access controls
Performance: Enable caching and optimize tool execution
Monitoring: Implement health checks and observability
Testing: Create comprehensive test suites with mocks
Documentation: Document tools, resources, and prompts clearly
Configuration: Use structured configuration for maintainability

资源管理：始终使用try-with-resources正确关闭MCP客户端
错误处理：在服务器故障时实现优雅降级
安全：使用工具过滤和资源访问控制
性能：启用缓存并优化工具执行
监控：实现健康检查与可观测性
测试：使用Mock创建全面的测试套件
文档：清晰记录工具、资源和提示
配置：使用结构化配置提升可维护性

langchain4j-mcp-server-patterns

Original

Translation

LangChain4j MCP Server Implementation Patterns

基于LangChain4j的Model Context Protocol (MCP)服务器实现模式

When to Use

适用场景

Quick Start

快速开始

Basic MCP Server

基础MCP服务器

Spring Boot Integration

Spring Boot集成

Core Concepts

核心概念

MCP Architecture

MCP架构

Key Components

核心组件

Implementation Patterns

实现模式

Tool Provider Pattern

工具提供者模式

Resource Provider Pattern

资源提供者模式

Prompt Template Pattern

提示模板模式

Transport Configuration

传输层配置

Stdio Transport

标准输入输出（Stdio）传输

HTTP Transport

HTTP传输

Client Integration

客户端集成

MCP Client Setup

MCP客户端设置

Tool Provider Integration

工具提供者集成

Security & Best Practices

安全与最佳实践

Tool Security

工具安全

Resource Security

资源安全

Error Handling

错误处理

Advanced Patterns

高级模式

Multi-Server Configuration

多服务器配置

Dynamic Tool Discovery

动态工具发现

Health Monitoring

健康监控

Configuration

配置

Application Properties

应用属性

Spring Boot Configuration

Spring Boot配置

Examples

示例

API Reference

API参考

Best Practices

最佳实践

References

参考资料