Spring Boot MCP网关库
一个Spring Boot库，自动将REST和GraphQL端点公开为MCP（模型上下文协议）工具，使LLM引擎能够动态发现和执行API端点。
特性
- 🔍 自动端点发现：扫描并发现Spring Boot应用程序中的所有REST和GraphQL端点
- 🛠️ MCP工具生成：使用JSON模式自动将REST和GraphQL端点转换为MCP工具定义
- 🚀 运行时执行：通过MCP接口执行任何发现的端点
- 📊 GraphQL支持：完全支持GraphQL查询和突变
- 🔒 结构化错误有效载荷：使用错误代码、请求ID和结构化详细信息增强错误响应
- 📋 增强元数据：丰富的参数元数据，包括javaType、graphqlType和可空字段
- ⚡ 发现缓存：每端点TTL缓存，可配置刷新以实现最佳性能
- 🔐 线程安全：具有适当内存管理和生命周期挂钩的无锁并发缓存
- 📝 全部文件：适用于所有公共API的全面Javadoc
- 🐛 调试日志记录：用于故障排除的详细调试级别日志记录
- ✅ 已测试：包括单元测试和集成测试
什么是MCP？
模型上下文协议（MCP）是一种标准化的方式，用于公开大型语言模型（LLM）可以与之交互的工具和资源。此库为Spring Boot REST和GraphQL端点实现了MCP，允许LLM：
- 发现可用的API端点作为工具
- 通过JSON模式理解端点参数
- 使用适当的参数映射执行端点
建造和测试
- 使用以下命令运行库测试
mvn test从存储库根目录。 - Maven必须到达Maven Central才能下载Spring Boot BOM和相关依赖项。如果你看到
403 Forbidden错误，删除或更新中的任何代理配置~/.m2/settings.xml并在启用网络访问的情况下重试。
安装
梅文
将以下依赖项添加到您的 pom.xml:
com.shaibachar
spring-boot-mcp-lib
1.0.0-SNAPSHOT
Gradle
implementation 'com.shaibachar:spring-boot-mcp-lib:1.0.0-SNAPSHOT'用法
基本设置
- 将依赖项添加到Spring Boot项目中
- 库会自动配置自己，不需要额外的配置！
- 您的REST和GraphQL端点会自动作为MCP工具公开
REST示例
@SpringBootApplication
public class MyApplication {
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
@RestController
@RequestMapping("/api")
public class UserController {
@GetMapping("/users/{id}")
public User getUser(@PathVariable String id) {
return userService.findById(id);
}
@PostMapping("/users")
public User createUser(@RequestBody User user) {
return userService.create(user);
}
}GraphQL示例
@Controller
public class UserGraphQLController {
@QueryMapping
public User getUserById(@Argument Long id) {
return userService.getUserById(id).orElse(null);
}
@MutationMapping
public User createUser(@Argument String name, @Argument String email) {
User user = new User();
user.setName(name);
user.setEmail(email);
return userService.createUser(user);
}
}要启用GraphQL支持，请添加Spring for GraphQL依赖关系：
org.springframework.boot
spring-boot-starter-graphql
MCP端点
添加库后，以下MCP端点将自动可用：
列出可用工具
GET /mcp/tools将所有发现的REST和GraphQL端点作为MCP工具及其模式返回。
响应示例：
{
"tools": [
{
"name": "get_api_users_id_getUser",
"description": "Calls GET /api/users/{id} (Controller: UserController, Method: getUser)",
"inputSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"javaType": "java.lang.String",
"nullable": false
}
},
"required": ["id"]
}
},
{
"name": "graphql_query_getUserById",
"description": "Calls GraphQL QUERY 'getUserById' (Controller: UserGraphQLController, Method: getUserById)",
"inputSchema": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"graphqlType": "Long",
"javaType": "java.lang.Long",
"nullable": true
}
}
}
}
]
}执行工具
POST /mcp/tools/execute
Content-Type: application/json
{
"name": "get_api_users_id_getUser",
"arguments": {
"id": "123"
}
}响应示例：
{
"content": [
{
"type": "text",
"text": "{\"id\":\"123\",\"name\":\"John Doe\"}"
}
],
"isError": false,
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}错误响应示例：
{
"content": [
{
"type": "text",
"text": "Tool not found: invalid_tool_name"
}
],
"isError": true,
"errorCode": "tool_not_found",
"requestId": "550e8400-e29b-41d4-a716-446655440001",
"details": null
}错误代码：
validation_error：请求参数无效tool_not_found：请求的工具不存在execution_error：执行工具时出错serialization_error：序列化结果时出错internal_error：内部服务器错误
刷新工具缓存
POST /mcp/tools/refresh强制刷新发现的端点（如果控制器是动态注册的，则很有用）。
螺纹安全和性能
该库专为高并发生产环境而设计：
线程安全
- 无锁缓存：发现服务使用
ConcurrentHashMap用于无锁的线程安全缓存 - 双重检查锁定：工具映射服务使用优化的延迟初始化
- 不可变数据：所有端点元数据类在构造后都是不可变的
- 防御性复制：公共API返回副本以防止外部突变
内存管理
- 有界缓存：缓存自然受到端点数量的限制
- 基于TTL的驱逐：可配置的TTL（默认5分钟）可防止无限增长
- 生命周期挂钩:
@PreDestroy确保停机时进行适当清理的方法 - 无内存泄漏：没有线程池、计划任务或无限制集合
性能特征
- 温缓存：使用O（1）查找的亚毫秒响应时间
- 冷缓存：通过反思，初步发现需要几秒钟的时间
- 刷新：已同步以防止并发重建
看 spec/implementation_parallel.md 用于详细的螺纹安全分析和符合并行性规范。
配置
缓存配置
在中配置发现缓存TTL application.properties:
# Cache TTL in milliseconds (default: 300000 = 5 minutes)
mcp.cache.ttl-millis=600000或在 application.yml:
mcp:
cache:
ttl-millis: 600000 # 10 minutes日志记录
默认情况下，该库使用SLF4J进行DEBUG级别的日志记录。要配置日志记录，请添加到 application.properties:
# Set to DEBUG to see detailed endpoint discovery and execution logs
logging.level.com.shaibachar.springbootmcplib=DEBUG
# Set to INFO for production
logging.level.com.shaibachar.springbootmcplib=INFO参数名称
为了确保在编译后的代码中保留参数名称（对于正确的参数映射很重要），请将此添加到您的 pom.xml:
org.apache.maven.plugins
maven-compiler-plugin
true
运作原理
- 端点发现：应用程序启动时，库会扫描：
- 春天 RequestMappingHandlerMapping 发现所有已注册的REST端点 - Spring GraphQL控制器用于发现所有GraphQL查询和突变
- 工具生成：每个端点都转换为MCP工具，具有：
- 基于HTTP方法/GraphQL操作类型、路径/字段名和处理程序方法名的唯一名称 - 端点功能的描述 - 描述输入参数的JSON模式
- 运行时执行：执行工具时：
- 库找到相应的端点 - 将提供的参数映射到方法参数 - 调用实际控制器方法 - 以JSON格式返回结果
建筑
┌─────────────────────────────────────────┐
│ LLM / MCP Client │
└────────────┬────────────────────────────┘
│
│ HTTP Requests
│
┌────────────▼────────────────────────────┐
│ McpController │
│ - GET /mcp/tools │
│ - POST /mcp/tools/execute │
└────────────┬────────────────────────────┘
│
┌────┴─────┐
│ │
┌───────▼──────┐ ┌▼─────────────────────┐
│ToolMapping │ │ToolExecution │
│Service │ │Service │
└───────┬──────┘ └┬────────────────────┘
│ │
│ ┌────▼──────┐
│ │Endpoint │
└────►Discovery │
│Service │
└───────────┘
│
┌─────────▼──────────┐
│ Spring MVC │
│ Controllers │
└────────────────────┘规格
详细规格请参见 spec 目录并直接映射到实现的行为：
api参考
模型
McpTool：表示MCP工具定义McpToolsResponse：包含可用工具列表的响应McpToolExecutionRequest：请求执行工具McpToolExecutionResponse：工具执行的响应EndpointMetadata：REST端点的内部表示GraphQLEndpointMetadata：GraphQL端点的内部表示
服务
EndpointDiscoveryService：从Spring MVC中发现REST端点GraphQLDiscoveryService：发现GraphQL查询和突变McpToolMappingService：将端点映射到MCP工具McpToolExecutionService：通过调用端点来执行工具
配置
McpAutoConfiguration：库的自动配置
发展
建筑
mvn clean install运行测试
mvn test测试覆盖率
图书馆包括：
- 所有核心部件的单元测试
- 使用测试Spring Boot应用程序进行集成测试
- 端点发现、工具映射和执行测试
需求
- Java 17或更高版本
- 弹簧靴3.2.0或更高版本
- Maven 3.6+（用于构建）
许可证
该项目根据MIT许可证获得许可。
贡献
欢迎投稿！请随时提交拉取请求。
支持
有关问题和疑问，请在GitHub上打开问题。