Spring Docs

🍃 Spring 文档 MCP 服务

🚀 增强版 v1.4.1： 17 个强大工具，支持 Spring AI、智能缓存、高级教程，并全面访问 Spring 生态系统

🌐 通用 MCP 兼容性： 可与 Claude Code、Gemini CLI、VS Code、JetBrains IDE 和所有兼容 MCP 的客户端配合使用！

🎯 快速开始

🔌 通用 MCP 兼容性

此服务可与所有兼容 MCP 的客户端配合使用：

Claude Desktop/Code

{
  "mcpServers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"],
      "description": "Spring Documentation MCP Server with 17 powerful tools"
    }
  }
}

Gemini CLI

mcp_servers:
  spring-docs:
    command: "npx"
    args: ["@enokdev/springdocs-mcp@latest"]
    description: "Spring Documentation Server"

VS Code MCP 扩展

{
  "mcp.servers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"]
    }
  }
}

任意 MCP 客户端（NPX）

npx @enokdev/springdocs-mcp@latest

全局安装（所有客户端）

npm install -g @enokdev/springdocs-mcp
# Then use: springdocs-mcp

Docker（即将推出 - Docker MCP 目录）

# Via Docker MCP CLI (when available in catalog)
docker mcp add springdocs-mcp

# Via Docker directly
docker pull mcp/springdocs-mcp:latest
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \
  docker run -i mcp/springdocs-mcp:latest

Docker 分发的优势：

• 通过加密签名和 SBOM 增强安全性
• 隔离的执行环境
• 降低 Docker Desktop 中的令牌用量
• 自动安全更新

配置文件位置：

• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）/ %APPDATA%\Claude\claude_desktop_config.json（Windows）
• Claude Code： ~/.claude-code/mcp-config.json
• VS Code： ~/.vscode/mcp-settings.json
• JetBrains IDE： .jetbrains/mcp-config.json

---

✨ 功能与工具

此服务提供 17 个工具。

📚 核心文档（8 个工具）

工具	用途	使用示例
search_spring_docs	搜索 Spring 文档（docType 可选 all、guides、projects、reference、content；可选 version）	“搜索包含 WebClient 的文档”
search_spring_projects	查找 Spring 项目	“查找与安全相关的项目”
get_spring_project	以 Markdown 格式获取项目页面（支持使用 offset 分页）	“显示 Spring Data 项目”
get_all_spring_guides	列出入门指南	“列出这些指南”
get_spring_guide	获取完整指南内容	“获取 rest-service 指南”
get_spring_reference	获取 11 个项目的参考文档（version、offset）	“Boot 参考文档的 web 部分”
get_migration_guide	Spring Boot / Framework / Batch 迁移指南和升级说明	“迁移到 Boot 3.4 的指南”
search_spring_concepts	探索 Spring 概念（可选 version）	“解释自动配置”

🚀 高级功能（6 个工具）

工具	用途	使用示例
search_spring_ecosystem	搜索整个生态系统，包括 Spring AI	“查找 Spring AI 向量存储”
get_spring_tutorial	获取分步教程	“Spring Security 教程”
compare_spring_versions	版本比较和迁移说明	“比较 3.3 和 3.4”
get_release_notes	GitHub 发布说明，支持按重点筛选	“Boot 3.5 的发布说明”
get_spring_best_practices	按类别提供专家指导	“测试最佳实践”
diagnose_spring_issues	离线诊断堆栈跟踪和错误	“诊断此 DataSource 错误”

🧰 工具支持（3 个工具）

工具	用途	使用示例
get_spring_initializr	Spring Initializr 元数据：Boot 版本、依赖项（start.spring.io）	“Initializr 提供哪些 Boot 版本？”
find_spring_dependency	根据需求查找启动器，并提供 Maven 和 Gradle 代码片段（可选 bootVersion，格式为 X.Y.Z）	“Redis 缓存需要哪个依赖项？”
spring_cache_stats	内存缓存统计信息，可选择清除缓存	“显示缓存统计信息”

---

📎 资源

• spring://project/<slug>：Spring 项目页面的完整 Markdown（例如 spring://project/spring-boot）；resources/list 会列出注册表中的 11 个项目，模板接受 spring.io 上的任意项目
• spring://guide/<id>：Spring 入门指南的完整 Markdown（例如 spring://guide/rest-service），可通过资源模板获取

💬 提示词

• migrate-boot-version（to_version，可选 from_version）：通过串联 get_migration_guide、get_release_notes 和 get_spring_reference，规划 Spring Boot 升级
• explain-error（error_message，可选 stack_trace）：通过串联 diagnose_spring_issues 和 get_spring_reference，解释 Spring 错误

📖 使用示例

基本搜索

"Search for REST API documentation in Spring Boot"

search_spring_docs 和 search_spring_concepts 接受可选的 version（3.4 或 3.4.2，补丁版本会被忽略；current 或省略表示最新版本），用于指定对应版本的 Spring Boot 参考文档（未发布的版本会返回专门的错误）。指南和项目不区分版本，会忽略该参数；使用 docType=content 时，其他版本的 Boot 参考页面不会出现在结果中。

get_migration_guide 接受 project（默认为 spring-boot，也可以是 spring-framework、spring-batch）：Framework 提供其次要版本的发行说明（6.2，章节为“Upgrading From ...”），Batch 提供其迁移指南（5.0、6.0），两者均从项目 wiki 读取原始 Markdown；section 和 offset 的用法与 Boot 相同。Spring Security 和 Spring AI（docs.spring.io 页面）目前尚未涵盖。

search_spring_docs 接受 docType=content：对服务已读取的页面（get_spring_project、get_spring_reference、get_spring_guide）进行全文搜索（BM25 排名）。它包含在 docType=all 中，并且在读取页面之前结果为空。

🆕 Spring AI 支持

"Get Spring AI ChatClient reference documentation"
"Search for RAG and embeddings in Spring AI"
"Show me Spring AI vector store documentation"
"Find Spring AI LLM integration examples"

生态系统探索

"Search the Spring ecosystem for microservices patterns"

学习路径

"Get a beginner tutorial for REST API development"

问题解决

"Diagnose 'Failed to configure DataSource' error"

迁移规划

"Compare Spring Boot 2.7.0 and 3.0.0 breaking changes"

最佳实践

"Get architecture best practices for expert developers"

---

🔧 高级配置

性能优化

{
  "mcpServers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"],
      "env": {
        "NODE_OPTIONS": "--max-old-space-size=4096",
        "REQUEST_TIMEOUT": "15000",
        "MAX_RETRIES": "3"
      }
    }
  }
}

企业／代理环境

{
  "mcpServers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"],
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

---

HTTP 传输（可选）

默认情况下，服务通过 stdio 通信。若要在本地或容器中托管：

npx @enokdev/springdocs-mcp --transport http --port 3000   # écoute sur 127.0.0.1

选项	变量	默认值
--transport stdio|http	MCP_TRANSPORT	stdio
--port	MCP_PORT	3000
--host	MCP_HOST	127.0.0.1
（无）	MCP_ALLOWED_HOSTS	空：额外 Host 列表，以逗号分隔

MCP 端点：POST /mcp（无状态模式）；健康检查：GET /healthz。无身份验证：默认仅监听 loopback 地址，并检查 Host／Origin 标头以防止 DNS 重绑定。对于容器，使用 MCP_TRANSPORT=http MCP_HOST=0.0.0.0，并发布端口（-p 127.0.0.1:3000:3000）；如果发布端口与内部端口不同，则声明客户端使用的 Host，例如 MCP_ALLOWED_HOSTS=localhost:8080。

Host 必须采用 名称:端口 的形式：不带端口的 Host（例如客户端通过反向代理使用端口 80 或 443，且标头为 Host: mcp.example.com）会被拒绝并返回 403。此时需通过 MCP_ALLOWED_HOSTS=mcp.example.com 声明代理传递的值（列表以逗号分隔，并与收到的标头进行精确匹配）。

GitHub 令牌（可选）

get_release_notes 和 compare_spring_versions 会查询 GitHub API，未经身份验证时每小时限制为 60 次请求。设置 GITHUB_TOKEN（无需特定权限范围的令牌即可）可将此限制提高到每小时 5000 次；令牌只会发送到 api.github.com（绝不会发送到其他主机，也不会在重定向后发送），并且绝不会被记录。达到速率限制时，工具会立即失败并显示清晰的消息（包含可重试时间），而不是等待。get_release_notes 接受格式为 X.Y 的 version（例如 3.5），以获取该次要版本的最新稳定版；compare_spring_versions 会应用 focus（breaking-changes、new-features、deprecations）。

{ "mcpServers": { "springdocs": { "command": "npx", "args": ["@enokdev/springdocs-mcp@latest"], "env": { "GITHUB_TOKEN": "ghp_..." } } } }

🧪 测试与开发

快速测试

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx @enokdev/springdocs-mcp@latest

开发环境设置

git clone https://github.com/tky0065/springdocs-mcp.git
cd springdocs-mcp
npm install
npm run build
npm test

负载测试

# Test multiple tools quickly
for tool in "search_spring_docs" "search_spring_projects" "search_spring_ecosystem"; do
  echo "Testing $tool..."
  echo "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"$tool\", \"arguments\": {\"query\": \"test\", \"limit\": 2}}}" | npx @enokdev/springdocs-mcp@latest > /dev/null
done

---

🆘 故障排除

常见问题与解决方案

“服务器启动失败”

# Check Node.js version (requires 20.18.1+)
node --version

# Update to latest
npm update -g @enokdev/springdocs-mcp

# Clear cache
npm cache clean --force

“工具无响应”

# Test connectivity
curl -I https://spring.io

# Check Claude Desktop config syntax
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

“性能缓慢”

• 启用缓存（v1.2.3+ 中自动启用）
• 使用具体查询，而不是宽泛搜索
• 增加内存：NODE_OPTIONS="--max-old-space-size=4096"

“端口 8080 已被占用”（Spring Boot 错误）

**解决方案：**在 application.properties 中更改端口：

server.port=8081

“DataSource 配置失败”

解决方案：

1. 在 pom.xml 中添加数据库依赖
2. 在 application.properties 中配置数据源
3. 排除自动配置：@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})

健康检查脚本

#!/bin/bash
echo "🔍 Testing Spring MCP Server..."

# Test server startup
timeout 10s echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx @enokdev/springdocs-mcp@latest > /dev/null
echo $? -eq 0 && echo "✅ Server: OK" || echo "❌ Server: FAILED"

# Test network
curl -s --max-time 5 https://spring.io > /dev/null
echo $? -eq 0 && echo "✅ Network: OK" || echo "❌ Network: FAILED"

---

📊 v1.2.3 新功能

🆕 重大增强

• 新增 5 个高级工具，全面访问 Spring 生态系统
• 内存缓存重复请求（TTL 为 30 分钟，稳定内容为 24 小时）
• 自动重试，采用指数退避机制，并限制响应大小为 5 MiB
• 整洁的架构，采用模块化服务和优化后的代码

🎯 新功能

• 跨生态系统搜索，覆盖项目、指南、文档和 API
• 渐进式教程，分为初级、中级和高级
• 智能版本比较，提供详细的迁移指导
• 专家最佳实践，按领域和经验级别分类
• 针对常见 Spring Boot 问题的 智能诊断

⚡ 性能与弹性

• 重复请求由内存缓存提供（TTL 为 30 分钟，稳定内容为 24 小时），无需发起新的网络调用
• 缓存受估算内存预算限制（默认 64 MiB，使用 LRU 淘汰；超出预算的单个值不会被缓存）；可通过 MCP_CACHE_MAX_MB 覆盖（例如 MCP_CACHE_MAX_MB=32）。spring_cache_stats 会报告条目数以及估算的已用内存／预算
• 所有外部 HTTP 调用均采用指数退避重试和请求超时
• 拒绝超过 5 MiB 的响应

---

🔮 路线图

v1.5.0（下一版本）

• 交互式 Spring Boot 项目生成器（已支持 Initializr 元数据和依赖查询）
• 自定义教程创建

v1.6.0（未来版本）

• AI 驱动的代码建议
• 性能瓶颈检测
• 安全漏洞扫描
• 自动化测试建议

---

🤝 贡献与支持

快速链接

• **问题：**https://github.com/tky0065/springdocs-mcp/issues
• **讨论：**https://github.com/tky0065/springdocs-mcp/discussions
• **NPM 包：**https://www.npmjs.com/package/@enokdev/springdocs-mcp

获取帮助

1. 在 GitHub 上搜索现有问题
2. 创建详细的问题报告，附上错误消息和复现步骤
3. 参与社区讨论，提出问题和功能请求

开发

# Setup development environment
git clone https://github.com/tky0065/springdocs-mcp.git
cd springdocs-mcp
npm install
npm run build

# Run tests
npm test
./test-enhanced.sh

# Submit PR
git checkout -b feature/your-feature
# Make changes
git commit -m "feat: add your feature"
git push origin feature/your-feature

🌐 CLI 集成示例

Claude Code

# Direct usage
claude-code --mcp-server "npx @enokdev/springdocs-mcp@latest"

# With config file
claude-code --mcp-config claude-mcp-config.json

Gemini CLI

# Direct integration
gemini --mcp-server "npx @enokdev/springdocs-mcp@latest"

# With YAML config
gemini --mcp-config gemini-config.yaml

# Environment variable
export GEMINI_MCP_SERVERS='[{"name":"spring-docs","command":"npx","args":["@enokdev/springdocs-mcp@latest"]}]'
gemini "Search for Spring Boot security documentation"

自定义 API 集成

// Express.js API Gateway example
const { spawn } = require('child_process');

app.post('/spring-docs/:tool', async (req, res) => {
    const mcp = spawn('npx', ['@enokdev/springdocs-mcp@latest']);
    const request = {
        jsonrpc: "2.0",
        id: Date.now(),
        method: "tools/call",
        params: {
            name: req.params.tool,
            arguments: req.body
        }
    };
    mcp.stdin.write(JSON.stringify(request));
    // Handle response...
});

兼容性测试

# Test MCP protocol handshake
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | npx @enokdev/springdocs-mcp@latest

# Test tools listing
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | npx @enokdev/springdocs-mcp@latest

# Test tool execution
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search_spring_projects", "arguments": {"query": "boot", "limit": 1}}}' | npx @enokdev/springdocs-mcp@latest

---

📄 许可证与致谢

许可证： MIT - 请参阅 LICENSE 文件

感谢：

• Spring Framework Team 提供出色的文档
• Anthropic 推出 Model Context Protocol
• Spring Community 提供持续支持

---

🚀 准备好以更强的智能和性能探索 Spring 生态系统了吗！

🌐 通用 MCP 兼容性： 可与 Claude Code、Gemini CLI、VS Code、JetBrains IDE 以及任何兼容 MCP 的客户端无缝协作！

由 EnokDev ❤️ 打造