弹簧文档MCP服务器

Name: 弹簧文档MCP服务器
Author: andrlange

作者：andrlange24 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

Spring Documentation MCP Server

这是一个全面的Spring Boot应用程序，作为模型上下文协议（MCP）服务器，通过服务器发送事件（SSE）提供对Spring生态系统文档的全文搜索访问。

这是什么？

这个MCP服务器使AI助手（如Claude）能够搜索、浏览并检索Spring框架文档、代码示例和API参考。它包括：

MCP服务器：使用Spring AI实现的基于SSE的协议
文档同步：从spring.io自动同步
全文搜索：使用PostgreSQL在整个Spring文档中进行搜索
Web管理界面：使用Thymeleaf的界面，用于管理项目、版本和文档
代码示例：可搜索的Spring代码片段库

截图

<table> <tr> <td width="50%"> <img src="assets/screen-00.png" alt="登录" /> 登录 - 使用Spring Security的安全认证 </td> <td width="50%"> <img src="assets/screen-01.png" alt="仪表盘" /> 仪表盘 - 概览统计信息和快速操作 </td> </tr> <tr> <td width="50%"> <img src="assets/screen-02.png" alt="Spring Boot" /> Spring Boot - Spring Boot项目的管理 </td> <td width="50%"> <img src="assets/screen-03.png" alt="项目" /> 项目 - 所有Spring项目的概览 </td> </tr> <tr> <td width="50%"> <img src="assets/screen-04.png" alt="项目详情" /> 项目详情 - Spring Batch项目的详细信息 </td> <td width="50%"> <img src="assets/screen-05.png" alt="版本" /> 版本 - 版本管理和追踪 </td> </tr> <tr> <td width="50%"> <img src="assets/screen-06.png" alt="文档" /> 文档 - 全文搜索和浏览 </td> <td width="50%"> <img src="assets/screen-10.png" alt="代码示例" /> 代码示例 - 可搜索的代码片段库，带有语言和标签过滤器 </td> </tr> <tr> <td width="50%"> <img src="assets/screen-07.png" alt="设置" /> 设置 - 应用配置、调度器和同步控制 </td> <td width="50%"> <img src="assets/screen-11.png" alt="文档Markdown扩展" /> 文档Markdown - 扩展的Spring Batch文档内容 </td> </tr> <tr> <td width="50%"> <img src="assets/screen-12.png" alt="MCP Inspector连接" /> MCP Inspector - 连接到Spring文档MCP服务器的MCP Inspector </td> <td width="50%"> <img src="assets/screen-13.png" alt="Claude代码控制台" /> Claude代码集成 - 通过MCP列出所有Spring Boot版本的Claude代码控制台 </td> </tr> <tr> <td width="50%"> <img src="assets/screen-14.png" alt="Spring AI版本查询" /> Spring AI兼容性 - Claude使用MCP查找与Spring Boot 3.5.7兼容的Spring AI版本 </td> <td width="50%"> </td> </tr> </table>

当前状态

✅ 已完全实现的功能

MCP工具（10个可用工具）

searchSpringDocs - 在所有Spring文档中进行全文搜索，并带有过滤器
getSpringVersions - 列出任何Spring项目的可用版本
listSpringProjects - 浏览所有可用的Spring项目
getDocumentationByVersion - 获取特定版本的所有文档
getCodeExamples - 搜索代码示例，并带有语言/项目/版本过滤器
listSpringBootVersions - 列出Spring Boot版本，并带有状态过滤器
getLatestSpringBootVersion - 获取主要.次要版本的最新补丁
filterSpringBootVersionsBySupport - 根据支持状态（OSS/企业版）进行过滤
listProjectsBySpringBootVersion - 列出与Spring Boot版本兼容的项目
findProjectsByUseCase - 根据用例关键词搜索项目

Web管理界面

仪表盘 - 概览统计信息和最近更新
项目 - 管理Spring项目（Spring Boot、框架、数据、安全、云等）
版本 - 带有最新/默认标记的版本管理
文档 - 浏览和搜索文档链接，并带有全文搜索
代码示例 - 带有标签的代码片段库
用户 - 基于角色的访问用户管理
设置 - 应用配置、功能切换和API密钥管理
身份验证 - 带会话管理的Spring Security
API密钥管理 - 用于MCP端点的安全令牌认证

文档同步服务

自动从spring.io/projects同步
版本检测和追踪
Spring Boot版本同步
项目关系映射
支持Spring世代
定时更新（可配置的cron）
启动数据加载

数据库功能

PostgreSQL 18带全文搜索（tsvector）
使用Flyway迁移进行版本控制
优化索引以提高搜索性能
支持关系和元数据

先决条件

重要：此项目需要Java 25（长期支持）。

安装Java 25

选项1：SDKMAN（推荐）

# 安装SDKMAN
curl -s "https://get.sdkman.io" | bash

# 安装Java 25
sdk install java 25.0.1-tem

# 使用Java 25
sdk use java 25.0.1-tem

选项2：从Adoptium下载

下载地址：https://adoptium.net/temurin/releases/?version=25
安装并设置JAVA_HOME

选项3：Homebrew（macOS）

brew install openjdk@25

验证安装

java -version
# 应显示：openjdk version "25"

快速开始

1. 启动PostgreSQL数据库

docker-compose up -d postgres

2. 验证数据库是否运行

docker-compose ps
# 应看到spring-mcp-db的状态为"Up"和"健康"

3. 构建应用

./gradlew clean build

4. 运行应用

java -jar build/libs/spring-mcp-server-1.0.0.jar

或者使用Gradle：

./gradlew bootRun

5. 访问应用

Web UI：http://localhost:8080
登录：用户名：admin，密码：admin
MCP SSE端点：http://localhost:8080/mcp/spring/sse
MCP消息端点：http://localhost:8080/mcp/spring/messages

API密钥认证

创建API密钥

API密钥管理界面，带有安全密钥生成、激活/停用控制和确认模态框

MCP端点受安全API密钥认证保护。要创建API密钥：

登录到Web UI，网址为http://localhost:8080（用户名：`admin`，密码：`admin`）
导航到设置（/settings）
**滚动到“API密钥管理”**部分
**点击“创建新API密钥”**按钮
输入详细信息：
- 名称：此密钥的唯一标识符（至少3个字符）
- 描述：可选用途描述
点击“创建API密钥”
⚠️ 重要：立即复制API密钥 - 它只会显示一次！

API密钥格式：smcp_<安全随机字符串>（256位加密安全）

安全特性：

密钥使用BCrypt（成本因子12）哈希 - 从未以明文形式存储
支持激活/停用（软删除）
跟踪最后使用时间戳以供审核

使用API密钥

API密钥可以通过三种方式提供（按优先级顺序）：

X-API-Key头（推荐）：

curl -H "X-API-Key: smcp_your_key_here" http://localhost:8080/mcp/spring/sse

Authorization Bearer头：

curl -H "Authorization: Bearer smcp_your_key_here" http://localhost:8080/mcp/spring/sse

查询参数（仅限测试 - 不够安全）：

curl "http://localhost:8080/mcp/spring/sse?api_key=smcp_your_key_here"

测试MCP服务器

选项1：MCP Inspector（推荐用于测试）

MCP Inspector是一款优秀的测试和调试MCP服务器的工具。它提供了可视界面来测试所有MCP功能。

安装并运行MCP Inspector

npx @modelcontextprotocol/inspector

这将启动MCP Inspector并输出类似以下内容：

正在启动MCP Inspector...
代理服务器在localhost:6277监听
会话令牌：3c672c3389d66786f32ffe2f90d6d2116634bef316a09198fb6e933a5eeefe2b

MCP Inspector正在运行于：
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3c672c3389d66786f32ffe2f90d6d2116634bef316a09198fb6e933a5eeefe2b

配置MCP Inspector

在浏览器中打开MCP Inspector URL
选择**“SSE”**作为传输类型
输入URL：http://localhost:8080/mcp/spring/sse
添加头（点击“添加头”）：
- 头名：X-API-Key
- 头值：smcp_your_api_key_here（你的实际API密钥）
点击**“连接”**

一旦连接成功，你可以：

列出工具：查看所有10个可用的MCP工具
测试工具：执行带有参数的工具并查看响应
查看日志：查看客户端和服务器之间的实时通信
调试问题：检查请求/响应负载

示例：测试searchSpringDocs工具

在MCP Inspector中：

导航到**“工具”**标签页
选择**“searchSpringDocs”**工具

填写参数：

{
  "query": "autoconfiguration",
  "project": "spring-boot",
  "version": "3.5.7"
}

点击**“执行”**
查看带有所有文档结果的响应

选项2：Claude Desktop/Claude Code

在你的Claude Desktop或Claude Code MCP配置（.mcp.json）中添加：

{
  "mcpServers": {
    "spring-documentation": {
      "type": "sse",
      "url": "http://localhost:8080/mcp/spring/sse",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}

配置步骤：

在项目根目录或Claude Code配置目录中创建或编辑.mcp.json
将YOUR_API_KEY_HERE替换为你从设置页面获取的实际API密钥
重启Claude Code以加载新的MCP服务器
Spring文档工具将在你的Claude Code会话中可用

注意：API密钥格式是smcp_<随机字符串>。从Web UI设置页面获取你的密钥。

可用的MCP工具

一旦连接，以下10个工具可供AI助手使用：

文档工具

1. searchSpringDocs

跨所有Spring文档搜索，可选过滤器。

参数：

query（必需）：搜索词
project（可选）：项目别名（例如，spring-boot）
version（可选）：版本字符串（例如，3.5.7）
docType（可选）：文档类型（例如，reference，api）

示例：

{
  "query": "autoconfiguration",
  "project": "spring-boot",
  "version": "3.5.7"
}

2. getSpringVersions

列出Spring项目的可用版本。

参数：

project（必需）：项目别名

示例：

{
  "project": "spring-boot"
}

3. listSpringProjects

列出所有可用的Spring项目。

无需参数。

4. getDocumentationByVersion

获取特定项目版本的所有文档。

参数：

project（必需）：项目别名
version（必需）：版本字符串

示例：

{
  项目： "spring-framework",
  版本： "6.2.1"
}

5. getCodeExamples

带有过滤器的代码示例搜索。

参数：

query（可选）：标题/描述中的搜索
project（可选）：项目别名
version（可选）：版本字符串
language（可选）：编程语言
limit（可选）：最大结果数（默认：110，最大：50）

示例：

{
  "query": "REST控制器",
  "project": "spring-boot",
  "language": "java",
  "limit": 20
}

Spring Boot版本工具

6. listSpringBootVersions

列出所有Spring Boot版本，可选过滤器。

参数：

state（可选）：根据状态过滤（'GA'，'RC'，'快照'，'里程碑'）
limit（可选）：最大结果数（默认：20，最大：100）

示例：

{
  "state": "GA",
  "limit": 10
}

7. getLatestSpringBootVersion

获取特定Spring Boot主.次版本的最新补丁版本。

参数：

majorVersion（必需）：主版本（例如，3）
minorVersion（必需）：次版本（例如，5）

示例：

{
  "majorVersion": 3,
  "minorVersion":  5
}

8. filterSpringBootVersionsBySupport

根据支持状态过滤Spring Boot版本。

参数：

supportActive（可选）：true表示支持，false表示生命周期结束
limit（可选）：最大结果数（默认：20，最大：100）

示例：

{
  "supportActive": true,
  "limit": 20
}

9. listProjectsBySpringBootVersion

列出与特定Spring Boot版本兼容的所有Spring项目。

参数：

majorVersion（必需）：Spring Boot主版本
minorVersion（必需）：Spring Boot次版本

示例：

{
  "majorVersion": 3,
  "minorVersion": 5
}

10. findProjectsByUseCase

根据用例关键词搜索Spring项目。

参数：

useCase（必需）：用例关键词（例如，'数据访问'，'安全'，'消息传递'）

示例：

{
  "useCase": "安全"
}

配置

环境变量

# 数据库配置
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=spring_mcp
export DB_USER=postgres
export DB_PASSWORD=postgres

# 安全
export ADMIN_USER=admin
export ADMIN_PASSWORD=changeme

# 服务器
export SERVER_PORT=8080

# 文档引导
export BOOTSTRAP_DOCS=false