内容
# springboot-mcp-toolkit
一款用于 Spring Boot 的只读 MCP 诊断服务器 — 将任何 AI 代理指向正在运行的服务，并要求它调试生产问题。
[](https://github.com/baddamsanni/springboot-mcp-toolkit/actions/workflows/ci.yml)
[](https://github.com/baddamsanni/springboot-mcp-toolkit/releases)
[](https://openjdk.org/projects/jdk/21/)
[](https://spring.io/projects/spring-boot)
[](LICENSE)
## 这是什么
您是一名后端工程师。生产环境中出现了问题 — 错误率激增，某个端点响应缓慢，数据库挂起。通常，您需要 SSH 登录，查看日志，运行 jstack，检查 Actuator，查询 pg_stat_activity — 在 5 个工具之间切换，20-40 分钟后才能得出假设。
使用此工具包，您可以打开 Claude Desktop（或 Cursor，或 Claude Code），将其指向正在运行的服务，然后询问：“为什么 /api/orders 目前响应缓慢？”代理会自动调用 get_endpoint_metrics、analyze_thread_dump、analyze_recent_logs 和 get_db_schema，关联结果，并在不到一分钟的时间内给出根本原因假设。
每个工具从设计上都是只读的 — 该项目中没有能够写入、修改或删除任何系统中的数据的代码路径。
## 快速开始（需要 Java 21）
### 1. 下载 jar
```bash
curl -L -o springboot-mcp-toolkit.jar \
https://github.com/baddamsanni/springboot-mcp-toolkit/releases/latest/download/springboot-mcp-toolkit-0.1.0.jar
```
### 2. 添加到您的 MCP 客户端
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"springboot-toolkit": {
"command": "java",
"args": [
"-jar", "/path/to/springboot-mcp-toolkit.jar",
"--spring.datasource.url=jdbc:postgresql://localhost:5432/yourdb",
"--spring.datasource.username=readonly_user",
"--spring.datasource.password=yourpassword"
]
}
}
}
```
**Claude Code / Cursor** (`.cursor/mcp.json` 或 `~/.claude/mcp.json`):
```json
{
"mcpServers": {
"springboot-toolkit": {
"command": "java",
"args": [
"-jar", "/path/to/springboot-mcp-toolkit.jar",
"--spring.datasource.url=jdbc:postgresql://localhost:5432/yourdb",
"--spring.datasource.username=readonly_user",
"--spring.datasource.password=yourpassword"
]
}
}
}
```
### 3. 询问您的代理
```
"为什么 /api/orders 目前响应缓慢？"
"是否有死锁线程？"
"显示我最近 200 行的所有 ERROR 日志。"
"我的数据库有哪些表，它们之间有什么关系？"
```
## 工具
八种只读诊断工具，任何 MCP 兼容代理都可以通过标准 MCP 握手自动发现。
| 工具 | 功能 | 支持 | 安全原因 |
|------|--------|--------|--------|
| `get_db_schema` | 表、列、类型、主键、外键 — 可选表过滤 | JDBC DatabaseMetaData | 零 SQL 执行 — 仅元数据调用 |
| `get_endpoint_metrics` | 每个端点的请求数、错误率、平均/最大延迟 | Micrometer `http.server.requests` | 读取已收集的表数据，绝不发出请求 |
| `run_readonly_query` | 执行调用者提供的 SQL — 仅限 SELECT | JDBC + JSqlParser AST 验证 | 在 AST 级别拒绝 INSERT/UPDATE/DELETE/DDL，而不是字符串匹配 |
| `analyze_recent_logs` | 按级别分组的最后 N 行日志，异常计数 | 日志文件尾部（RandomAccessFile） | 只读文件访问，无写入 |
| `analyze_thread_dump` | 死锁、阻塞线程、CPU 占用最高的线程、线程池耗尽 | JVM ThreadMXBean | 只读 JVM 反射，无法影响正在运行的线程 |
| `analyze_cache_performance` | 缓存命中率、驱逐次数、每个缓存的大小 | Spring CacheManager + 反射 | 只读缓存统计信息，不触发驱逐 |
| `detect_config_drift` | 标记风险运行时属性值 | Spring Environment | 只读属性检查 |
| `run_diagnostic_workflow` | 根据症状描述协调其他工具 | 以上所有 | 仅调用只读工具 |
## 代理如何使用此工具
该服务器支持模型上下文协议（MCP）— Claude、Cursor 和 Claude Code 使用的相同标准用于工具调用。当您将其连接到您的 MCP 客户端时，代理会自动读取所有 8 个工具描述，并根据您的提问决定调用哪些工具。您不需要编写任何胶水代码。
```
您：“为什么 /api/orders 目前响应缓慢？”
↓
代理通过 MCP 握手读取工具描述
↓
代理调用：get_endpoint_metrics → analyze_thread_dump → analyze_recent_logs
↓
代理关联结果并给出根本原因假设
↓
您进行修复
```
## Token 使用跟踪
每个 `@Tool` 调用都被 Spring AOP 切面拦截，并记录到嵌入式 H2 `tool_invocation` 表中：会话 ID、工具名称、估计输入/输出令牌、持续时间和时间戳。
会话 ID 来自 `X-MCP-Session-Id` 请求头（如果存在）；否则，在服务器启动时生成一个 UUID，作为整个进程生命周期的备用方案。
令牌计数是字符长度估计（`1 token ≈ 4 chars`），而不是来自 LLM 提供商的确切标记器输出。记录失败会被记录，但绝不会破坏工具响应。
通过自定义 Actuator 端点公开并检查用法：
| 方法 | 路径 | 返回 |
|--------|------|---------|
| GET | `/actuator/token-usage` | 会话总计（调用次数、输入/输出/总估计、首次/最后调用） |
| GET | `/actuator/token-usage/{sessionId}` | 单个会话的调用明细 |
| GET | `/actuator/token-usage/by-tool` | 按工具名称分组的总计，跨所有会话 |
每个响应都包含：
```text
令牌计数是字符长度估计（1 token ≈ 4 chars），而不是确切的标记器输出。
```
示例：
```bash
curl http://localhost:8081/actuator/token-usage
curl http://localhost:8081/actuator/token-usage/by-tool
```
## 企业安装
企业 Maven 设置通常锁定到内部注册表（JFrog Artifactory，Sonatype Nexus）。此工具包设计用于该工作流程 — 运行时不需要 Maven Central 依赖项。
1. **从 GitHub Releases 下载 jar 并运行安全扫描**
```bash
curl -L -o springboot-mcp-toolkit.jar \
https://github.com/baddamsanni/springboot-mcp-toolkit/releases/latest/download/springboot-mcp-toolkit-0.1.0.jar
# Veracode CLI 示例
veracode package --source springboot-mcp-toolkit.jar
```
2. **推广到内部 Artifactory**
```bash
curl -u "$ARTIFACTORY_USER:$ARTIFACTORY_TOKEN" \
-X PUT "https://artifactory.example.com/artifactory/libs-release-local/ai/toolkit/springboot-mcp-toolkit/0.1.0/springboot-mcp-toolkit-0.1.0.jar" \
-T springboot-mcp-toolkit.jar
```
3. **部署为 sidecar，指向只读数据库副本**，使用 MCP 配置的 HTTP URL 形式：
```json
{
"mcpServers": {
"springboot-toolkit": {
"url": "http://localhost:8081/mcp"
}
}
}
```
**始终使用只读数据库凭证。纵深防御。**
## 支持的数据库
| 数据库 | JDBC URL |
|----------|----------|
| PostgreSQL | `jdbc:postgresql://host:5432/dbname` |
| MySQL / MariaDB | `jdbc:mysql://host:3306/dbname` |
| H2（本地开发） | `jdbc:h2:mem:testdb` |
| Oracle | `jdbc:oracle:thin:@host:1521:SID` |
| SQL Server | `jdbc:sqlserver://host:1433;databaseName=dbname` |
H2 已捆绑。所有其他驱动程序必须添加到类路径中。
## 安全模型
- `get_db_schema` 具有零 SQL 执行 — 仅 DatabaseMetaData 调用。该类中没有 Statement 或 PreparedStatement。
- `run_readonly_query` 使用 JSqlParser 将 SQL 解析为 AST，并拒绝任何非 Select 节点 — 不是字符串检查，而是 AST 检查。SQL 注释技巧和编码绕过无效。
- `analyze_thread_dump` 使用 ThreadMXBean，它是只读 JVM 反射 — 它无法停止、暂停或影响任何线程。
- 推荐：无论如何，都使用只读数据库凭证。该工具包无法写入，但具有无写入权限的凭证是第二道防线。
## 技术栈
- Java 21
- Spring Boot 3.5
- Spring AI 1.1.8（MCP 服务器，可流式 HTTP 传输）
- Micrometer / Spring Boot Actuator（包括自定义 `token-usage` 端点）
- Spring AOP（工具调用记录）
- JSqlParser 4.9
- H2（嵌入式，用于本地开发、CI 和令牌使用持久性）
## 贡献
- 该项目每周发布一个新工具或改进。
- 如果您需要一个尚不存在的工具，请打开问题。
- 欢迎 PR — 在提交前运行 `mvn test`，所有 30 个测试必须通过。
## 许可证
[MIT 许可证](LICENSE)
