AI MCP Demo

自定义MCP工具系统演示

一个基于 Spring Boot 的 Model Context Protocol (MCP) 服务端演示项目，完全符合 MCP 官方协议规范，展示了如何使用自定义注解系统创建高质量的 MCP 服务端。

🚀 项目概述

本项目实现了一个完整的 MCP 服务端，提供标准的工具调用、资源管理和协议通信功能。项目经过全面测试，确保与 MCP 协议的完全兼容性。

核心功能

• 🔧 工具系统: 提供计算器、时间获取、消息回显等实用工具
• 📡 协议兼容: 完全符合 MCP 1.0 协议规范
• 🌐 HTTP 传输: 支持 Streamable HTTP 传输机制
• 🔒 安全验证: Origin 头验证和本地地址安全检查
• 📊 健康监控: 内置健康检查和服务状态监控
• 🧪 完整测试: 包含客户端演示和协议兼容性测试

🛠 技术栈

📁 项目结构

src/
├── main/java/com/example/mcpdemo/
│   ├── McpDemoApplication.java           # 🚀 主应用程序
│   ├── controller/
│   │   ├── StandardMcpController.java    # 🎯 MCP 协议控制器
│   │   └── HealthController.java         # 💊 健康检查控制器
│   ├── service/
│   │   └── McpMessageHandler.java        # 📨 消息处理服务
│   ├── tools/
│   │   ├── CalculatorTool.java          # 🧮 计算器工具
│   │   ├── CurrentTimeTool.java         # ⏰ 时间工具
│   │   └── EchoTool.java                # 🔊 回显工具
│   ├── client/
│   │   ├── McpClient.java               # 📱 MCP 客户端
│   │   └── McpClientDemo.java           # 🎮 客户端演示
│   ├── model/
│   │   ├── JsonRpcRequest.java          # 📤 请求模型
│   │   └── JsonRpcResponse.java         # 📥 响应模型
│   └── resources/
│       └── SystemInfoResource.java      # 💻 系统信息资源
└── test/java/com/example/mcpdemo/
    └── McpClientTest.java               # 🧪 客户端测试

🎯 可用工具

1. 计算器工具 (calculator)

• 功能: 执行数学表达式计算
• 参数: expression (string) - 数学表达式
• 示例: 2+3*4 → 14.0

2. 当前时间工具 (current_time)

• 功能: 获取当前系统时间
• 参数: format (可选) - 时间格式
• 示例: yyyy-MM-dd HH:mm:ss → 2025-09-29 14:28:30

3. 回显工具 (echo)

• 功能: 回显输入消息并添加时间戳
• 参数: message (string) - 要回显的消息
• 示例: Hello → Echo: Hello (timestamp: 1759127310490)

🚀 快速开始

环境要求

• Java 17 或更高版本
• Maven 3.6 或更高版本

1. 克隆项目

git clone 
cd MCP_demo

2. 启动服务器

# 使用 Maven 启动
mvn spring-boot:run

# 或者编译后运行
mvn clean package
java -jar target/mcp-demo-1.0.0.jar

3. 验证服务

# 健康检查
curl http://localhost:8080/actuator/health

# 测试 MCP 端点
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

🧪 测试

运行协议兼容性测试

# 运行完整的 MCP 协议测试
./test.sh

运行客户端演示

# 启动交互式客户端演示
mvn compile exec:java -Dexec.mainClass="com.example.mcpdemo.client.McpClientDemo"

运行单元测试

mvn test

🔌 API 端点

MCP 协议端点

• POST /mcp - 发送 JSON-RPC 消息
• GET /mcp - 开启 SSE 流接收服务器消息

健康检查端点

• GET /actuator/health - Spring Boot Actuator 健康检查
• GET /api/health - 自定义健康检查
• GET /api/info - 服务信息

🔒 安全特性

Origin 验证

• 自动验证请求的 Origin 头
• 允许本地地址 (localhost, 127.0.0.1, ::1)
• 支持预配置的允许域名列表

本地地址检测

• 智能识别 IPv4 和 IPv6 本地地址
• 支持多种本地地址格式
• 详细的安全日志记录

📊 协议兼容性

本项目完全符合 MCP 1.0 协议规范：

• ✅ JSON-RPC 2.0: 标准的请求/响应格式
• ✅ Streamable HTTP: POST 和 GET 方法支持
• ✅ 工具发现: 自动工具注册和列表
• ✅ 工具调用: 标准的工具执行机制
• ✅ 资源管理: 资源列表和访问
• ✅ 通知机制: 单向通知消息支持
• ✅ 错误处理: 标准 JSON-RPC 错误响应
• ✅ 安全验证: Origin 头和本地地址验证

🎮 使用示例

初始化连接

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

获取工具列表

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

调用计算器工具

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {
      "expression": "2+3*4"
    }
  }
}

🔧 配置

应用配置 (application.yml)

server:
  port: 8080

spring:
  application:
    name: mcp-demo

management:
  endpoints:
    web:
      exposure:
        include: health,info

📈 扩展开发

添加新工具

1. 创建新的工具类并继承适当的基类
2. 使用 @Tool 注解标记工具方法
3. 在 McpMessageHandler 中注册新工具
4. 添加相应的测试用例

添加新资源

1. 在 resources 包中创建资源类
2. 实现资源访问逻辑
3. 在消息处理器中注册资源
4. 更新资源列表处理逻辑

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🆘 支持

如果您在使用过程中遇到问题，请：

1. 查看项目文档和示例
2. 运行测试脚本验证环境
3. 提交 Issue 描述问题
4. 查看日志获取详细错误信息

🎉 现在您的 MCP 服务已经可以与任何符合 MCP 协议的 AI 客户端进行交互了！