MCP 全面解析 —— 类型、原理与使用方式

// CalculatorServer.java
import java.util.List;
import java.util.Map;

import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.server.McpServer;
import io.modelcontextprotocol.server.McpServerFeatures.SyncPromptSpecification;
import io.modelcontextprotocol.server.McpServerFeatures.SyncResourceSpecification;
import io.modelcontextprotocol.server.McpServerFeatures.SyncToolSpecification;
import io.modelcontextprotocol.server.McpSyncServer;
import io.modelcontextprotocol.server.transport.StdioServerTransportProvider;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
import io.modelcontextprotocol.spec.McpSchema.Prompt;
import io.modelcontextprotocol.spec.McpSchema.PromptArgument;
import io.modelcontextprotocol.spec.McpSchema.PromptMessage;
import io.modelcontextprotocol.spec.McpSchema.ReadResourceResult;
import io.modelcontextprotocol.spec.McpSchema.Resource;
import io.modelcontextprotocol.spec.McpSchema.Role;
import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
import io.modelcontextprotocol.spec.McpSchema.TextContent;
import io.modelcontextprotocol.spec.McpSchema.TextResourceContents;
import io.modelcontextprotocol.spec.McpSchema.Tool;

public class CalculatorServer {

    public static void main(String[] args) {
        // 1. 选择 stdio 传输：本地进程，由客户端以子进程方式拉起
        var transport = new StdioServerTransportProvider(McpJsonDefaults.getMapper());

        // 2. 构建服务器：声明标识与能力（tools / resources / prompts）
        McpSyncServer server = McpServer.sync(transport)
            .serverInfo("calculator-demo", "1.0.0")
            .capabilities(ServerCapabilities.builder()
                .tools(true)              // 工具能力
                .resources(false, false)  // 资源能力（subscribe=false, listChanged=false）
                .prompts(true)            // 提示词能力
                .build())
            .build();

        // 3. 注册工具 / 资源 / 提示词
        server.addTool(addTool());
        server.addTool(fibTool());
        server.addResource(noteResource());
        server.addPrompt(codeReviewPrompt());

        // 4. 优雅关闭；stdio 传输的非守护线程会保持进程存活，等待客户端调用
        Runtime.getRuntime().addShutdownHook(new Thread(server::closeGracefully));
    }

    // ---- Tool：加法（JSON Schema 声明入参 + 处理器）----
    static SyncToolSpecification addTool() {
        Map<String, Object> schema = Map.of(
            "type", "object",
            "properties", Map.of(
                "a", Map.of("type", "integer"),
                "b", Map.of("type", "integer")),
            "required", List.of("a", "b"));

        return SyncToolSpecification.builder()
            .tool(Tool.builder("add", schema)
                .description("求两个整数之和")
                .build())
            .callHandler((exchange, request) -> {
                int a = ((Number) request.arguments().get("a")).intValue();
                int b = ((Number) request.arguments().get("b")).intValue();
                return CallToolResult.builder()
                    .content(List.of(new TextContent(String.valueOf(a + b))))
                    .isError(false)
                    .build();
            })
            .build();
    }

    // ---- Tool：斐波那契 ----
    static SyncToolSpecification fibTool() {
        Map<String, Object> schema = Map.of(
            "type", "object",
            "properties", Map.of("n", Map.of("type", "integer")),
            "required", List.of("n"));

        return SyncToolSpecification.builder()
            .tool(Tool.builder("fib", schema)
                .description("计算斐波那契数列的第 n 项（n >= 0）")
                .build())
            .callHandler((exchange, request) -> {
                int n = ((Number) request.arguments().get("n")).intValue();
                if (n < 0) {
                    return CallToolResult.builder()
                        .content(List.of(new TextContent("n 必须 >= 0")))
                        .isError(true)
                        .build();
                }
                int a = 0, b = 1;
                for (int i = 0; i < n; i++) {
                    int next = a + b;
                    a = b;
                    b = next;
                }
                return CallToolResult.builder()
                    .content(List.of(new TextContent(String.valueOf(a))))
                    .isError(false)
                    .build();
            })
            .build();
    }

    // ---- Resource：只读数据，用 URI 标识 ----
    static SyncResourceSpecification noteResource() {
        Resource resource = Resource.builder("notes://todo", "Todo 便签")
            .description("按名字读取便签内容")
            .mimeType("text/plain")
            .build();

        return new SyncResourceSpecification(resource, (exchange, request) -> {
            String content = switch (request.uri()) {
                case "notes://todo" -> "1. 写 MCP 博客\n2. 本地构建验证";
                case "notes://idea" -> "下一篇写 Agent 编排";
                default -> "未找到该便签";
            };
            return ReadResourceResult.builder(List.of(
                    TextResourceContents.builder(request.uri(), content)
                        .mimeType("text/plain")
                        .build()))
                .build();
        });
    }

    // ---- Prompt：可复用提示词模板 ----
    static SyncPromptSpecification codeReviewPrompt() {
        Prompt prompt = Prompt.builder("code_review")
            .description("生成一段代码评审提示词")
            .arguments(List.of(
                PromptArgument.builder("language")
                    .description("编程语言")
                    .required(false)
                    .build()))
            .build();

        return new SyncPromptSpecification(prompt, (exchange, request) -> {
            Object lang = request.arguments() == null ? null : request.arguments().get("language");
            String language = lang == null ? "Java" : lang.toString();
            String text = "请以资深 " + language + " 工程师的视角，从正确性、性能、可读性三个维度审查以下代码：";
            return GetPromptResult.builder(List.of(
                    PromptMessage.builder(Role.USER, new TextContent(text)).build()))
                .description("代码评审提示词")
                .build();
        });
    }
}

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.context.annotation.Configuration;

@Configuration
public class CalculatorTools {

    @Tool(description = "求两个整数之和")
    public int add(@ToolParam(description = "第一个整数") int a,
                   @ToolParam(description = "第二个整数") int b) {
        return a + b;
    }

    @Tool(description = "计算斐波那契数列的第 n 项（n >= 0）")
    public int fib(@ToolParam(description = "项数 n") int n) {
        if (n < 0) {
            throw new IllegalArgumentException("n 必须 >= 0");
        }
        int a = 0, b = 1;
        for (int i = 0; i < n; i++) {
            int next = a + b;
            a = b;
            b = next;
        }
        return a;
    }
}

// McpClientDemo.java
import java.time.Duration;
import java.util.Map;

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.json.McpJsonDefaults;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.GetPromptRequest;
import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
import io.modelcontextprotocol.spec.McpSchema.ListToolsResult;
import io.modelcontextprotocol.spec.McpSchema.ReadResourceRequest;
import io.modelcontextprotocol.spec.McpSchema.ReadResourceResult;
import io.modelcontextprotocol.spec.McpSchema.TextContent;
import io.modelcontextprotocol.spec.McpSchema.TextResourceContents;
import io.modelcontextprotocol.spec.McpSchema.Tool;

public class McpClientDemo {

    public static void main(String[] args) {
        // 1. 声明要拉起的服务器进程（stdio）
        ServerParameters params = ServerParameters.builder("java")
            .args("-jar", "target/calculator-server-1.0.0.jar")
            .build();

        // 2. 创建 stdio 传输 + 同步客户端
        McpSyncClient client = McpClient.sync(
                new StdioClientTransport(params, McpJsonDefaults.getMapper()))
            .requestTimeout(Duration.ofSeconds(10))
            .build();

        try {
            // 3. 初始化握手（SDK 自动协商协议版本与能力）
            client.initialize();

            // 4. 发现工具
            ListToolsResult tools = client.listTools();
            System.out.println("可用工具: " + tools.tools().stream().map(Tool::name).toList());

            // 5. 调用工具
            CallToolResult result = client.callTool(CallToolRequest.builder("add")
                .arguments(Map.of("a", 40, "b", 2))
                .build());
            System.out.println("add(40, 2) = " + ((TextContent) result.content().get(0)).text());

            // 6. 读取资源
            ReadResourceResult note = client.readResource(
                ReadResourceRequest.builder("notes://todo").build());
            System.out.println("便签内容:\n" + ((TextResourceContents) note.contents().get(0)).text());

            // 7. 获取提示词模板
            GetPromptResult prompt = client.getPrompt(GetPromptRequest.builder("code_review")
                .arguments(Map.of("language", "Java"))
                .build());
            System.out.println("提示词: " + ((TextContent) prompt.messages().get(0).content()).text());
        } finally {
            client.closeGracefully();
        }
    }
}

var transport = HttpClientStreamableHttpTransport.builder("http://localhost:8080")
    .endpoint("/mcp")
    .build();
McpSyncClient client = McpClient.sync(transport).build();