Pure Java 21 MCP Server

纯 Java 21 MCP 服务

本项目使用纯 Java 21 实现了一个 Model Context Protocol（MCP）服务，严格遵循（概念上的）2025-03-26 MCP 规范。本项目从零开始构建，未使用外部 MCP 专用 SDK。

前置条件

• Java 21 SDK： 确保已安装并配置 Java 21（或更高版本）。
• Gson 库： 此服务使用 Gson 库解析和序列化 JSON。你需要下载 Gson JAR 文件。
  • 通常可以从 Maven Central 下载。搜索“Gson”或 com.google.code.gson:gson，然后下载 JAR（例如，gson-2.10.1.jar 或更高版本）。
  • 将下载的 Gson JAR（例如，gson-2.10.1.jar）放在已知位置，例如本项目中的 lib 目录（lib/gson-2.10.1.jar）。以下编译和运行命令假设 JAR 位于此位置。

项目结构

• src/：包含 Java 源代码。
  • main/java/io/modelcontextprotocol/server/：根包。
    • jsonrpc/：用于 JSON-RPC 消息结构、解析和错误处理的类。
    • messages/：用于 MCP 专用消息负载的类（初始化、工具定义等）。
    • tools/：工具的实现（例如，EchoTool）。
    • transport/：传输层处理（例如，StdioTransport）。
    • McpServer.java：服务的核心逻辑。
    • Main.java：应用程序入口点。
• lib/：（推荐）创建此目录以存放 Gson JAR。
• mcp-server.log：服务运行期间生成的日志文件。
• .gitignore：指定 Git 应忽略的未跟踪文件。
• README.md：本文件。

编译

1. 创建目录：

   • 确保项目根目录中有一个 lib 目录，并将 Gson JAR 文件（例如，gson-2.10.1.jar）放在其中。
   • 在项目根目录中创建一个 bin 目录，用于存放编译后的类文件：

     mkdir lib
     mkdir bin
     # Download Gson JAR and place it in lib/
     # For example: wget https://repo1.maven.org/maven2/com/google/code/gson/gson/2.10.1/gson-2.10.1.jar -P lib/
     

2. 编译服务： 在项目根目录中打开终端或命令提示符。 如果使用不同版本的 Gson 或不同的路径，请调整 lib/gson-2.10.1.jar。

   Nix（Linux/macOS）：

   javac -d bin -cp "lib/gson-2.10.1.jar:src/main/java" $(find src/main/java -name "*.java")
   

   Windows（命令提示符）：

   javac -d bin -cp "lib\gson-2.10.1.jar;src\main\java" $(powershell -Command "(Get-ChildItem -Recurse -Filter *.java src\main\java | Select-Object -ExpandProperty FullName) -join ';' ")
   

   如果 $(powershell ...) 命令无法直接在 cmd.exe 中运行，你可能需要手动列出文件，或采用其他方法：

   javac -d bin -cp "lib\gson-2.10.1.jar;src\main\java" src\main\java\io\modelcontextprotocol\server\*.java src\main\java\io\modelcontextprotocol\server\jsonrpc\*.java src\main\java\io\modelcontextprotocol\server\messages\*.java src\main\java\io\modelcontextprotocol\server	ools\*.java src\main\java\io\modelcontextprotocol\server	ransport\*.java
   

   （手动列出文件时，请确保包含所有包路径。）

运行服务

成功编译后，在项目根目录中运行服务：

Nix（Linux/macOS）：

java -cp "bin:lib/gson-2.10.1.jar" io.modelcontextprotocol.server.Main

Windows（命令提示符）：

java -cp "bin;lib\gson-2.10.1.jar" io.modelcontextprotocol.server.Main

服务将启动，并在标准输入（STDIO）上监听 JSON-RPC 消息。

已实现的功能

• 传输方式： STDIO（使用 Content-Length 标头对消息进行帧封装）。
• JSON-RPC： 解析和序列化 Version 2.0 消息。
• MCP 核心：
  • initialize 请求：服务端响应其功能。
  • initialized 通知：客户端确认初始化。
  • shutdown 请求：服务端确认并准备退出。
  • exit 通知：服务端终止。
• 工具：
  • 基本的“工具”功能。
  • 对 echoTool 的 tool/call 请求。
  • echoTool：一个回显消息的简单工具。
    • 输入架构：{ "type": "object", "properties": { "message": { "type": "string" } } }
    • 输出架构：{ "type": "object", "properties": { "response": { "type": "string" } } }
• 日志记录： 服务端活动会记录到 mcp-server.log（FINE 级别及以上）和控制台（INFO 级别及以上）。

交互示例（通过 STDIO）

消息以 Content-Length 和 \r\n\r\n 为帧头，后接 JSON 正文。

1. 客户端 -> 服务端：initialize 请求

Content-Length: 123

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"processId":1234,"capabilities":{}}}

（注意：params 中的 processId 和 capabilities 等内容仅为 initialize 的示例，目前会被此服务端忽略。）

2. 服务端 -> 客户端：initialize 响应

Content-Length: 297

{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":[{"name":"echoTool","description":"A simple tool that takes a 'message' string and returns it prefixed with 'Echo: '.","inputSchema":{"type":"object","properties":{"message":"string"}},"outputSchema":{"type":"object","properties":{"response":"string"}}}]}}}

（实际的 Content-Length 会根据具体格式而变化。服务端会计算该值。）

3. 客户端 -> 服务端：initialized 通知

Content-Length: 40

{"jsonrpc":"2.0","method":"initialized"}

（通知没有 id。服务端不会响应。）

4. 客户端 -> 服务端：针对 echoTool 的 tool/call 请求

Content-Length: 107

{"jsonrpc":"2.0","id":2,"method":"tool/call","params":{"toolName":"echoTool","params":{"message":"Hello MCP!"}}}

5. 服务端 -> 客户端：tool/result 响应

Content-Length: 74

{"jsonrpc":"2.0","id":2,"result":{"response":"Echo: Hello MCP!"}}

6. 客户端 -> 服务端：shutdown 请求

Content-Length: 49

{"jsonrpc":"2.0","id":3,"method":"shutdown","params":{}}

7. 服务端 -> 客户端：shutdown 响应

Content-Length: 34

{"jsonrpc":"2.0","id":3,"result":null}

8. 客户端 -> 服务端：exit 通知

Content-Length: 36

{"jsonrpc":"2.0","method":"exit","params":{}}

（随后服务端终止，不会响应。）