dlmpx/mcp-java-demo

下面我给你从架构 completeness、模块划分、Server/Client 技术点、协议设计、测试方案、运行方式等角度，给出一个 适用于 MCP（Model Context Protocol）Demo 的完善建议清单。 你可以按此结构逐步搭建，避免后期返工。

✅ 整体结构分析与建议补充

你的基础结构已经很合理：父 POM + server/client + shared-protocol。 为了让 Demo 真正具备 MCP 的典型功能，可以补充以下模块/要素。

📌 一、建议补充后的最终项目结构

mcp-java-demo/
├── pom.xml
├── shared-protocol/                   # 协议 & DTO & 公用工具
│   ├── pom.xml
│   └── src/main/java/com/example/mcp/protocol/
├── mcp-server/                        # MCP Server 实现（Spring Boot）
│   ├── pom.xml
│   └── src/main/java/com/example/mcp/server/
│       ├── config/
│       ├── controller/
│       ├── service/
│       ├── websocket/                 # 强烈建议：MCP 默认走 WebSocket
│       ├── registry/                  # 工具/资源的注册表
│       └── handler/                   # 消息处理器
├── mcp-client/                        # MCP Client（Spring Boot）
│   ├── pom.xml
│   └── src/main/java/com/example/mcp/client/
│       ├── websocket/
│       ├── runner/
│       ├── service/
│       └── workflow/                  # 可选：封装调用链
└── docs/                              # 强烈建议
    ├── protocol.md
    ├── server-design.md
    ├── client-usage.md
    └── messages-examples.md

📌 二、关键补充要点（重要！）

① shared-protocol 模块中应包含的内容

MCP 强制要求的基本协议字段：

• MCPMessage（基础消息）

  • id
  • type ("call" | "response" | "error")
  • method
  • params

• MCPRequest

• MCPResponse

• MCPError

• 可扩展字段（如 resource, sampling, tool 等）

🔧 建议增加：

• JsonRpcSupport 或简单的 message wrapper（方便序列化）
• 全局常量
• MessageType enum

② Server 端应补充的内容

1. WebSocket 端点

MCP 规范基本默认使用 WebSocket，如：

ws://localhost:8080/mcp

需要实现：

• 握手
• 接收消息
• 分发到 handler
• 响应消息

你需要一个：

@ServerEndpoint("/mcp")

或使用 Spring WebSocket：

@EnableWebSocket

2. “工具注册表”或“资源注册表”

MCP 服务器通常提供工具/功能，需要注册：

{
  "tools": ["echo", "calculator", "file_reader"]
}

因此需要：

interface McpTool {
    String getName();
    McpResponse execute(McpRequest req);
}

并建立 registry：

Map<String, McpTool> toolRegistry

3. Request Handler 分发器

Server 端需要支持：

• "ping"
• "list_tools"
• "call_tool"
• "sampling"（可选）

因此需要：

class MessageDispatcher {
    McpResponse handle(McpMessage msg);
}

③ Client 端应补充的内容

1. WebSocket 客户端

Spring Boot 可使用：

• WebSocketClient（Reactor Netty）
• 或 Java 21 的 java.net.http.WebSocket

需要自动重连能力：

connect -> send identify -> list_tools -> call echo

2. Client workflow 示例

例如启动后自动：

• 连接 server
• 发送 list_tools
• 调用 echo 工具
• 输出响应

让整个 Demo 有明显效果。

3. Client 统一 MessageHandler

建议建立：

class ClientMessageHandler { 
    void onMessage(McpMessage msg);
}

④ 父 POM 应补充内容

推荐加入：

🔧 依赖管理（BOM）

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.3.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

🔧 Java 21 设置

<properties>
    <java.version>21</java.version>
</properties>

🔧 版本对齐（Lombok / Jackson）

optional but recommended。

📌 三、建议补充一些使用案例（便于调试）

可以在 docs/ 中加入几组样例消息：

1. 客户端 identify

{
  "type": "call",
  "method": "identify",
  "params": {
    "client_name": "mcp-java-demo-client",
    "version": "0.1.0"
  }
}

2. 服务端 list_tools 响应

{
  "type": "response",
  "result": {
    "tools": ["echo", "calculator"]
  }
}

📌 四、Demo 的最小功能清单（必备）

这是实现最小可运行 MCP Demo 的 必备清单。

📌 五、你可以先从 Server 开始

我建议先按以下顺序搭建：

1. 建 shared-protocol（DTO）
2. 建 mcp-server（WebSocket + MessageHandler）
3. 实现一个 demo 工具（EchoTool）
4. 完成 list_tools
5. 构建 mcp-client WebSocket
6. 实现 client 调用 echo

如你需要：

✅ 我可以直接给出 三个模块的完整 Maven POM 模板 ✅ 我可以给你 Server 端 WebSocket 完整代码（Spring Boot 3.3 + Java 21） ✅ 我可以给你 Client 的 async WebSocket 客户端模板 ✅ 或者根据你想做的 MCP 功能（tools / sampling / resource）进一步设计协议

需要哪个我马上生成？