Spring Demo MCP Server SSE

带用户服务的MCP Spring Boot示例

该项目演示了如何构建一个简单的Spring Boot API，并使用Spring Boot和Spring AI MCP Server将其公开为REST端点和模型上下文协议（MCP）工具。该应用程序现在包括 UserService 其作为MCP工具公开。

______________________________________________________________________

目录

• 特性
• 需求
• 设置
• 运行应用程序
• REST API使用
• MCP服务器使用情况（SSE+JSON-RPC）
• 测试
• 开发说明
• 故障排除

______________________________________________________________________

特性

• UserService工具：通过用户ID获取用户详细信息（REST和MCP）
• 用户详细信息的REST API端点
• MCP服务器将用户服务作为AI工具公开（可由VS Code Copilot等使用）
• 集成测试的全面测试覆盖

______________________________________________________________________

需求

• Java 17+
• Maven 3.8+
• VS代码（可选，用于MCP客户端测试）
• REST客户端扩展 （可选，用于 .http 文件）

______________________________________________________________________

设置

1. 克隆存储库：

   git clone 
   cd mcpdemo

1. 配置Git（可选）：

   git config user.name ""
   git config user.email ""

1. 构建项目：

   ./mvnw clean install

______________________________________________________________________

运行应用程序

启动Spring Boot应用程序：

./mvnw spring-boot:run

服务器将于启动 http://localhost:8080.

______________________________________________________________________

REST API使用

您可以使用curl、Postman或提供的 .http 文件。

UserService示例请求：

• 获取用户详细信息：

  GET http://localhost:8080/api/users/123

答复：

  "User: 123, Name: John Doe"

______________________________________________________________________

MCP服务器使用情况（SSE+JSON-RPC）

MCP服务器使用服务器发送事件（SSE）进行基于会话的通信，使用JSON-RPC通过HTTP发送消息。这允许您在通过POST发送请求时在浏览器或SSE客户端中接收异步响应。

1.使用SSE端点创建会话

打开浏览器并导航到：

http://localhost:8080/mcp/sse

将创建一个新会话，您将收到如下响应：

id:8a09a074-ad2d-434d-a768-8e30f25a186b
event:endpoint
data:/mcp/messages?sessionId=8a09a074-ad2d-434d-a768-8e30f25a186b

• 这 id 是您的会话ID。
• 这 data 字段为您提供此会话的正确消息端点。

2.使用消息端点发送JSON-RPC消息

使用Bruno、Postman或curl等工具将POST请求发送到：

http://localhost:8080/mcp/messages?sessionId=

使用JSON正文。例如，要初始化：

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "warp",
      "version": "1.0.0"
    }
  }
}

然后发送：

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

现在，您可以发送工具/列表或工具/调用请求，如下所示。所有响应都将显示在您在步骤1中打开的浏览器窗口（SSE会话）中。

示例：列出可用工具

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/list",
  "params": {}
}

示例：调用工具

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "getUserDetailsMcp",
    "arguments": {
      "userId": "123"
    }
  }
}

示例响应（将出现在SSE会话中）

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": "User: 123, Name: John Doe"
}

______________________________________________________________________

VS代码集成

1. 打开VS Code并安装MCP兼容的扩展（例如，Copilot Chat）。
2. 将MCP服务器URL设置为 http://localhost:8080/mcp/sse 在扩展设置中。
3. 使用扩展程序的聊天或工具功能调用您的用户工具。

______________________________________________________________________

测试

使用以下命令运行所有测试：

./mvnw test

集成测试涵盖了所有端点和MCP工具。

______________________________________________________________________

开发说明

• 用户逻辑在 UserService.
• REST端点位于 UserController.
• MCP工具注册已在 McpConfig.
• MCP服务器配置在 src/main/resources/application.yaml.

______________________________________________________________________

故障排除

• 会话ID错误： 始终包括a sessionId 在MCP工具/完成请求中。
• 工具在VS代码中不可见： 确保MCP服务器正在运行，并且扩展指向正确的URL。
• 端口冲突： 更改端口 application.yaml 如果需要的话。
• 日志： 启用TRACE登录 application.yaml 了解详细的MCP服务器日志。

______________________________________________________________________

许可证

Apache 2.0