ModelContextProtocol (MCP) Java SDK v0.8.0 Specification

基本能力

产品定位

MCP Java SDK 是一个用于AI模型与外部工具或资源通信的标准协议实现，旨在通过Java应用程序提供高效的通信能力。

核心功能

1. 客户端实现：提供同步和异步客户端，用于与MCP服务器通信。
2. 服务器实现：支持同步和异步服务器，用于暴露资源和工具。
3. 传输层：支持多种传输机制，包括标准I/O流和自定义传输。
4. 协议层：实现MCP协议规范，确保通信的标准化。
5. 资源管理：支持静态和动态资源的访问和管理。
6. 工具调用：提供工具的执行功能，支持参数传递和结果返回。
7. 错误处理：标准化的错误处理机制，支持多种错误码和自定义错误消息。

适用场景

1. AI模型集成：将AI模型与外部工具或资源集成，扩展模型功能。
2. 动态资源访问：通过动态资源模板生成和访问数据。
3. 工具调用：执行外部工具并获取结果，适用于需要扩展功能的场景。
4. 跨进程通信：通过标准I/O流实现子进程间的通信。

工具列表

1. 同步客户端：支持同步调用工具和访问资源。
2. 异步客户端：支持异步调用工具和访问资源，提高性能。
3. 同步服务器：支持同步处理客户端请求。
4. 异步服务器：支持异步处理客户端请求，提高吞吐量。
5. 标准I/O传输：通过标准输入/输出流进行通信。
6. 自定义传输：支持自定义传输机制，适应不同通信需求。

常见问题解答

1. 错误处理：使用McpError类处理标准错误码和自定义错误消息。
2. 资源未找到：返回RESOURCE_NOT_FOUND错误码。
3. 工具未找到：返回METHOD_NOT_FOUND错误码。
4. 参数无效：返回INVALID_PARAMS错误码。

使用教程

使用依赖

1. 添加MCP BOM（材料清单）以确保所有组件的兼容版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.modelcontextprotocol.sdk</groupId>
            <artifactId>mcp-bom</artifactId>
            <version>0.8.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

1. 添加具体依赖：

<dependencies>
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp</artifactId>
    </dependency>
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp-test</artifactId>
    </dependency>
    <dependency>
        <groupId>jakarta.servlet</groupId>
        <artifactId>jakarta.servlet-api</artifactId>
        <version>5.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

安装教程

1. 同步客户端示例：

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.spec.McpSchema;

public class SyncClientStdioToolsExample {
    public static void main(String[] args) throws Exception {
        McpSchema.Implementation clientInfo = new McpSchema.Implementation("example-client", "1.0.0");
        ServerParameters serverParams = ServerParameters.builder("example-server-command").build();
        StdioClientTransport transport = new StdioClientTransport(serverParams);
        McpSyncClient client = McpClient.sync(transport).clientInfo(clientInfo).build();
        try {
            McpSchema.ReadResourceRequest request = new McpSchema.ReadResourceRequest("example://resource");
            McpSchema.ReadResourceResult result = client.readResource(request);
            if (result.contents() != null && !result.contents().isEmpty()) {
                McpSchema.ResourceContents contents = result.contents().get(0);
                if (contents instanceof McpSchema.TextResourceContents textContents) {
                    System.out.println("Resource content: " + textContents.text());
                }
            }
        } finally {
            client.close();
        }
    }
}

调试方式

1. 错误调试：使用McpError捕获和处理错误。
2. 日志输出：在服务器和客户端中添加日志输出，便于跟踪通信过程。
3. 测试工具：使用mcp-test依赖进行单元测试和集成测试。

许可证

None