# mcp-server-springBoot-example **Repository Path**: feng-kailong/mcp-server-spring-boot-example ## Basic Information - **Project Name**: mcp-server-springBoot-example - **Description**: 自定义mcp服务的springBoot实例项目 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-06-06 - **Last Updated**: 2026-06-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MCP Server 示例项目 这是一个基于 **Spring Boot** 实现的 **MCP(Model Context Protocol)Server 示例项目**,用于演示如何通过 HTTP 接口对外暴露 MCP 工具,供 Cursor、Claude Desktop 等支持 MCP 的客户端调用。 项目将 MCP 协议封装为统一的 JSON-RPC 网关,客户端只需配置服务地址即可接入,无需额外安装进程或命令行工具。 ## 技术栈 | 类别 | 技术 | |------|------| | 语言 | Java 17 | | 框架 | Spring Boot 3.2 | | 协议 | MCP over HTTP(JSON-RPC 2.0 风格) | | 其他 | Lombok、Fastjson2、Spring Mail | ## 项目结构 ``` src/main/java/org/example/ ├── Application.java # 启动入口 ├── controller/ │ └── McpController.java # MCP 协议网关(/mcp) ├── service/ │ └── ToolsService.java # 工具注册与执行逻辑 ├── req/ # 请求体模型 └── resp/ # 响应体模型 ``` 核心流程: 1. 客户端向 `POST /mcp` 发送 JSON-RPC 请求 2. `McpController` 根据 `method` 字段路由到对应处理逻辑 3. `ToolsService` 负责列出工具、执行具体工具并返回结果 ## 内置工具 | 工具名 | 说明 | 参数 | |--------|------|------| | `get_current_day` | 获取今天的日期 | 无 | | `get_weather` | 获取今天的天气 | 无 | | `send_email` | 发送邮件 | `email`(收件人)、`title`(标题)、`content`(内容) | > `send_email` 依赖 `application.yml` 中的邮件配置,使用前请填写真实的 SMTP 账号与授权码。 ## 本地运行 ### 环境要求 - JDK 17+ - Maven 3.6+ ### 配置邮件(可选) 编辑 `src/main/resources/application.yml`,将发件邮箱信息改为你的实际配置: ```yaml spring: mail: username: your_email@163.com password: your_password ``` ### 启动服务 ```bash mvn spring-boot:run ``` 服务默认监听 **8000** 端口,MCP 入口地址为: ``` http://localhost:8000/mcp ``` ## MCP 客户端注册方式 在 Cursor 或其他支持 MCP 的客户端中,添加如下配置即可连接本服务: ```json { "mcpServers": { "fkl-project": { "url": "http://localhost:8000/mcp" } } } ``` ### Cursor 配置路径 - **全局配置**:`~/.cursor/mcp.json` - **项目级配置**:项目根目录下的 `.cursor/mcp.json` 配置完成后重启 Cursor,或在 MCP 设置中刷新服务列表,即可看到 `fkl-project` 及其提供的工具。 ## 协议说明 所有请求统一发往 `POST /mcp`,请求体为 JSON-RPC 格式: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` ### 支持的方法 | method | 说明 | |--------|------| | `ping` | 健康检查 | | `initialize` | 初始化握手,返回协议版本与服务器信息 | | `tools/list` / `list_tools` | 列出所有可用工具 | | `tools/call` / `call_tool` | 调用指定工具 | | `notifications/initialized` | 初始化完成通知(返回 202) | ### 调用工具示例 ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "send_email", "arguments": { "email": "example@qq.com", "title": "mcp-test", "content": "这是一封 mcp-test 邮件" } } } ``` ## 扩展新工具 1. 在 `ToolsService.listTools()` 中注册新工具的名称、描述和参数 schema 2. 在 `ToolsService.callTool()` 的 `switch` 分支中实现对应逻辑 完成以上两步后,客户端刷新工具列表即可使用新工具,无需修改 `McpController`。 ## 注意事项 - 本项目为 **学习与演示用途** 的 MCP Server 实现,生产环境需补充鉴权、限流、错误处理等能力 - 确保本地服务已启动且端口 `8000` 未被占用,否则客户端无法连接 - 邮件发送功能需使用支持 SMTP 的邮箱,并开启授权码(非登录密码)