🚀 MCP 协议 Java SDK 全面指南

MCP（Model Context Protocol）协议是用于连接和管理模型上下文的开放标准，在人工智能和分布式系统开发中应用广泛。本指南将详细介绍如何使用 MCP 协议的 Java SDK 进行开发。

🚀 快速开始

创建客户端

使用 McpClient 工厂创建一个 MCP 客户端：

import io.modelcontextprotocol.client.McpClient;

public class McpExample {
    public static void main(String[] args) {
        // 创建默认的 MCP 客户端实例
        try (var client = McpClient.createDefault()) {
            // 使用客户端进行操作
            System.out.println("MCP 客户端已创建");
        }
    }
}

创建服务器

使用 McpServer 工厂创建一个 MCP 服务器：

import io.modelcontextprotocol.server.McpServer;

public class McpExample {
    public static void main(String[] args) {
        // 创建默认的 MCP 服务器实例
        try (var server = McpServer.createDefault()) {
            // 使用服务器进行操作
            System.out.println("MCP 服务器已创建");
        }
    }
}

✨ 主要特性

• 开放标准：MCP 协议是开放标准，便于在不同系统中集成和使用。
• 请求 - 响应模式：所有 MCP 操作都基于请求 - 响应模式，保证数据交互的有序性。
• 资源与工具管理：支持资源模板动态生成资源内容，以及自定义工具的定义和执行。

📦 安装指南

下载 SDK

访问 MCP 官方网站 下载适用于您项目的 MCP Java SDK 版本。

环境配置

1. 添加依赖
   在您的项目构建文件中（如 pom.xml 或 build.gradle）添加 MCP SDK 依赖：

   <dependency>
       <groupId>io.modelcontextprotocol</groupId>
       <artifactId>mcp-java-sdk</artifactId>
       <version>${mcp.sdk.version}</version>
   </dependency>
   

2. 配置环境变量
   确保 JDK 和 MCP SDK 已正确安装，并将 MCP 工具添加到系统路径中。

💻 使用示例

基础用法

客户端与服务端交互

所有 MCP 操作都基于请求 - 响应模式。以下是一个简单的交互示例：

// 发起请求
var request = createRequest();
client.sendRequest(request);

// 处理响应
client.receiveResponse().thenAccept(response -> {
    System.out.println("收到响应: " + response.toString());
});

高级用法

资源与工具管理

资源模板

使用资源模板动态生成资源内容：

import io.modelcontextprotocol.schema.McpSchema;

public class McpExample {
    public static void main(String[] args) {
        // 创建一个简单的资源模板
        var resourceTemplate = new Template() {
            @Override
            public String getResourceId() {
                return "example_resource";
            }

            @Override
            public Map<String, Object> getParameters() {
                return Collections.emptyMap();
            }
        };

        // 应用资源模板生成内容
        McpSchema.applyTemplate(resourceTemplate);
    }
}

工具执行

定义并执行自定义工具：

import io.modelcontextprotocol.tool.McpTool;

public class McpExample {
    public static void main(String[] args) {
        // 定义一个简单的工具
        var tool = new Tool() {
            @Override
            public String getName() {
                return "example_tool";
            }

            @Override
            public void execute(List<String> arguments, Callback<String> callback) {
                callback.onResult("执行完成: " + arguments);
            }
        };

        // 执行工具并获取结果
        var result = McpTool.execute(tool, List.of("arg1", "arg2"));
        System.out.println(result);
    }
}

📚 详细文档

核心概念

客户端与服务端

• 客户端：负责发起请求和接收响应。
• 服务端：负责处理客户端的请求并返回响应。

请求与响应

所有 MCP 操作都基于请求 - 响应模式，确保数据在客户端和服务端之间的有序交互。

🔧 技术细节

MCP 协议 Java SDK 基于开放标准 MCP 协议，采用请求 - 响应模式进行数据交互。客户端通过 McpClient 发起请求，服务端通过 McpServer 处理请求。在资源与工具管理方面，支持使用资源模板动态生成资源内容，以及自定义工具的定义和执行，提高了系统的灵活性和可扩展性。

📄 最佳实践

一般规范

1. 使用 BOM - 总是使用 MCP BOM 确保所有组件的兼容版本。
2. 关闭连接 - 处理完毕后，总是关闭客户端和服务器实例。
3. 处理错误 - 实现所有 MCP 操作的适当错误处理。
4. 验证输入 - 在处理之前验证所有输入数据。
5. 选择合适的传输机制 - 根据使用场景选择适当的传输方式。

客户端侧

1. 重用客户端 - 创建一个单独的客户端实例并多次使用。