streamable-http

Streamable HTTP MCP Server 提供一个基于传统 HTTP REST API 的 MCP（Model Controller Protocol）实现，支持通过注解快速集成到 Spring Boot 项目中。该服务器采用 JSON-RPC 2.0 风格的通信，允许客户端通过初始化、工具列表、工具调用和心跳等方法与工具链交互。使用时，开发者在 Spring Boot 应用中加入 starter 依赖并通过 @McpServerEndpoint 注解定义 MCP 服务端点及 @McpFunction、@McpParam 等注解描述可暴露的函数和参数，即可实现一个可通过 MCP 调用的服务。客户端可以向服务端发送初始化请求，获取可用工具，并调用具体工具来执行任务，适配了流式能力较弱的场景，因此不支持 SSE 流式传输。该实现与 Spring Boot 2.1.x 及以上版本兼容。

在实践中，您会：

• 使用 Maven 构建并运行示例项目，如 streamable-http-mcp-demo，通过 mvn spring-boot:run 启动演示应用。
• 通过工具注册与调用机制，使用 tools/list 获取可用工具列表，使用 tools/call 调用指定工具。
• 使用 initialize 进行初始化并管理会话，保持与客户端的协作状态。
• 使用简单的 JSON-RPC 风格请求与响应进行通信，便于前后端集成。

请按照以下步骤在本地或 CI 环境中安装并运行 Streamable HTTP MCP Server。

prerequisites:

• 安装 Java (JDK 8+，推荐 11+) 和 Maven
• 具备 Docker（若使用 Docker 启动镜像）

步骤：

1. 下载源代码并进入项目根目录。
2. 构建项目（使用 Maven）：

mvn clean install

3. 运行演示应用（演示子模块 streamable-http-mcp-demo）：

mvn spring-boot:run -pl streamable-http-mcp-demo

4. 如需通过 Docker 运行，请确保镜像可用或已从仓库拉取，然后以如下方式启动：

docker run -i daydayup-zyn-streamable-http-mcp-server

5. 根据需要在 Spring Boot 应用中引入 starter，并实现 MCP 服务控制器，示例中提供了示例注解使用方式与 Controller 结构。将以下依赖添加到您的项目中（示例为 Maven 依赖）：

<dependency>
  <groupId>cn.daydayup.dev</groupId>
  <artifactId>streamable-http-mcp-starter</artifactId>
  <version>1.0</version>
</dependency>

6. 创建 MCP 服务：在您的 Spring 控制器中使用 @McpServerEndpoint、@McpFunction、@McpParam 等注解来暴露功能，完成后即可通过 MCP 客户端进行初始化、工具查询和调用。

小贴士与常见问题：

• 本实现不支持 SSE 流式传输，适用于传统 HTTP REST 架构场景。
• 与 Spring Boot 2.1.x 兼容，确保项目采用兼容版本。
• JSON-RPC 2.0 作为通信协议，注意请求/响应格式及参数命名规范。
• 如遇初始化失败，请检查工具注册是否正确，以及 initialize、tools/list、tools/call 的调用顺序。
• 若使用 Docker 运行，请确保镜像名称与版本与您的部署计划一致，必要时构建自定义镜像。
• 环境变量可在容器启动时通过 -e 选项注入，例如配置端口、日志级别等（根据镜像的实际实现支持情况）。