Mcp Java

MCP Java SDK 🐱

[](https://github.com/jianglai-2000/mcp-java/actions/workflows/ci.yml) [](https://adoptium.net/) [](LICENSE)

> 让 AI 客户端（Claude Desktop、Cursor 等）直接调用你写的 Java 工具！

> A lightweight Java SDK for the Model Context Protocol (MCP) — build servers and expose Java tools to AI clients.

---

这是什么？/ What is this?

中文： MCP（Model Context Protocol）是 AI 工具的标准协议——相当于给 AI 插上 USB-C 接口。

你的 Java 工具通过这个 SDK 暴露出来，Claude Desktop 等 AI 客户端就能直接调用。

English: MCP is the standard protocol for AI tool integration — think of it as a USB-C port for AI. This SDK lets you expose your Java tools so MCP-compatible clients (Claude Desktop, Cursor, etc.) can call them directly.

---

🚀 快速开始 / Quick Start

前提 / Prerequisites

• Java 21+ (recommended)
• Maven 3.8+ (or use the included mvnw wrapper)

1️⃣ 引入依赖 / Add dependency

    io.mcp
    mcp-java
    0.1.0

2️⃣ 写工具 / Write your tools

import io.mcp.server.annotation.*;

@McpToolProvider
public class MyTools {

    @McpTool(name = "get_weather", description = "查询城市天气")
    public String getWeather(@McpParam("city") String city) {
        return "上海 25°C 晴 ☀️";
    }

    @McpTool(name = "calculate", description = "计算两个数之和")
    public int add(@McpParam("a") int a, @McpParam("b") int b) {
        return a + b;
    }
}

3️⃣ 启动 server / Start the server

McpServer.create("my-ai-tools", "1.0.0")
    .registerTools(new MyTools())
    .build()
    .start();

或者用 Maven Wrapper 打包运行：

./mvnw clean package -DskipTests
java -jar target/mcp-java-0.1.0.jar

---

🧩 Resources & Prompts 使用示例

Resources — 向 AI 客户端暴露数据和文件

import io.mcp.server.annotation.*;
import io.mcp.server.registry.ResourceDefinition;
import java.util.List;

public class MyResources {

    @McpResourceProvider
    public List listResources() {
        return List.of(
            new ResourceDefinition(
                "file:///logs/app.log",           // URI 标识
                "Application Log",                 // 名称
                "Server application log file",      // 描述
                "text/plain",                       // MIME 类型
                () -> java.nio.file.Files.readString(
                    java.nio.file.Path.of("/var/log/app.log"))
            )
        );
    }
}

// 注册到 server
McpServer.create("my-server", "1.0.0")
    .registerResources(new MyResources())
    .build()
    .start();

AI 客户端可以：resources/list → resources/read {uri: "file:///logs/app.log"}

Prompts — 预定义提示模板

import io.mcp.server.annotation.*;
import io.mcp.server.registry.PromptDefinition;
import io.mcp.server.protocol.JsonRpcMessage;
import java.util.List;

public class MyPrompts {

    @McpPromptProvider
    public List listPrompts() {
        var messages = JsonRpcMessage.mapper().createObjectNode();
        var arr = messages.putArray("messages");
        var msg = arr.addObject();
        msg.put("role", "assistant");
        msg.put("content", "I'll help you analyze this text.");

        return List.of(
            new PromptDefinition(
                "analyze",                         // 名称
                "Analyze the given text",           // 描述
                List.of(
                    new PromptDefinition.PromptArgument(
                        "text", "The text to analyze", true)
                ),
                messages                            // 返回的消息
            )
        );
    }
}

// 注册到 server
McpServer.create("my-server", "1.0.0")
    .registerPrompts(new MyPrompts())
    .build()
    .start();

AI 客户端可以：prompts/list → prompts/get {name: "analyze"}

三种能力一起注册

McpServer.create("my-server", "1.0.0")
    .registerTools(new MyTools())
    .registerResources(new MyResources())
    .registerPrompts(new MyPrompts())
    .build()
    .start();

---

🔧 通信流程 / Protocol

stdio 模式

sequenceDiagram
    participant AI as AI 客户端
    participant SDK as MCP Java SDK
    participant Tool as 你的工具

    AI->>SDK: initialize
    SDK-->>AI: 服务信息 + 能力声明
    AI->>SDK: tools/list
    SDK-->>AI: [{name, description, inputSchema}, ...]
    AI->>SDK: tools/call {name: "get_weather", arguments: {city: "上海"}}
    SDK->>Tool: 反射调用方法
    Tool-->>SDK: "上海 25°C 晴 ☀️"
    SDK-->>AI: {content: [{type: "text", text: "上海 25°C 晴 ☀️"}]}

SSE/HTTP 模式

Client                    Server (mcp-java)
  |                          |
  |--- GET /sse ------------>|  建立 SSE 连接
  ||  发送 JSON-RPC 请求
  | Made with 🐱 by a Java developer who believes code should be useful, not just a job.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jianglai-2000](https://github.com/jianglai-2000)
- **Source:** [jianglai-2000/mcp-java](https://github.com/jianglai-2000/mcp-java)
- **License:** MIT

Install and usage instructions live in the source repository linked above.