使用说明

Spring MCP工具包

基于Spring Boot的模型上下文协议（MCP）服务器，为MCP客户端提供数据库模式和SQL生成模板，用于智能SQL查询生成。

概述

此MCP服务器通过模型上下文协议公开数据库模式信息和SQL查询模板，使AI助手和其他MCP客户端能够生成关于数据库结构的正确上下文的准确SQL查询。

特性

MCP协议支持：全面实施MCP（模型上下文协议）以实现上下文共享
数据库架构上下文：提供详细的数据库架构信息，包括：
- 表结构
- 具有类型和约束的列定义
- 主键和外键关系
- 表和列说明
SQL模板：用于常见操作的预构建SQL查询模板：
- SELECT查询
- 联接操作
- 插入语句
- 更新语句
- DELETE语句
- 使用GROUP BY聚合查询
RESTful API：用于MCP通信的基于HTTP的JSON-RPC 2.0端点
易于集成：易于与任何MCP客户端集成

建筑

服务器通过以下方式实现MCP规范：

JSON-RPC 2.0协议用于请求/响应
用于可执行操作的工具API
用于静态上下文的资源API
正确的错误处理和记录

先决条件

Java 17或更高版本
Maven 3.6+或Gradle 7+
弹簧靴3.2.0

安装和设置

1.克隆存储库

git clone https://github.com/satyavenik/spring-mcp-toolkit.git
cd spring-mcp-toolkit

2.建设项目

mvn clean install

3.运行服务器

mvn spring-boot:run

服务器将于启动 http://localhost:8080

配置

应用程序属性

服务器可以通过以下方式配置 src/main/resources/application.yml:

server:
  port: 8080  # Change port if needed

spring:
  application:
    name: spring-mcp-toolkit

自定义架构

要提供自己的数据库架构，请修改 SchemaService.java 类或扩展它以从以下位置加载模式：

数据库元数据
配置文件
外部服务

API 参考

MCP端点

基础URL: http://localhost:8080/mcp

健康检查

GET http://localhost:8080/mcp/health

MCP方法

所有MCP请求都使用POST /mcp JSON-RPC 2.0格式：

1.初始化

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "Spring MCP Toolkit",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {},
      "resources": {}
    }
  }
}

2.列出工具

请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

答复：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_schema",
        "description": "Get database schema for SQL generation context",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      {
        "name": "get_templates",
        "description": "Get SQL generation templates",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      {
        "name": "get_template",
        "description": "Get specific SQL template by name",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Template name"
            }
          },
          "required": ["name"]
        }
      }
    ]
  }
}

3.调用工具-获取架构

请求：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_schema",
    "arguments": {}
  }
}

响应：返回包含表、列和关系的完整数据库架构。

4.调用工具-获取模板

请求：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_templates",
    "arguments": {}
  }
}

响应：返回所有可用的SQL模板。

5.调用工具-获取特定模板

请求：

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_template",
    "arguments": {
      "name": "basic_select"
    }
  }
}

响应：返回带有参数和示例的指定SQL模板。

6.列出资源

请求：

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "resources/list",
  "params": {}
}

答复：

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "resources": [
      {
        "uri": "schema://database/ecommerce",
        "name": "E-commerce Database Schema",
        "description": "Complete schema for e-commerce database",
        "mimeType": "application/json"
      },
      {
        "uri": "templates://sql/all",
        "name": "SQL Templates",
        "description": "All available SQL generation templates",
        "mimeType": "application/json"
      }
    ]
  }
}

7.阅读资源

请求：

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "resources/read",
  "params": {
    "uri": "schema://database/ecommerce"
  }
}

响应：返回指定资源的内容。

数据库架构示例

服务器包括一个示例电子商务数据库模式，其中包含：

用户：具有id、用户名、电子邮件、created_at的用户帐户
产品：产品目录，包括id、名称、描述、价格、库存
订单：带有id、user_id、总计、状态、created_at的客户订单
订单项目：具有id、Order_id、product_id、数量、价格的订单行项目

关系：

orders.user_id→ users.id
order_items.order_id→ orders.id
order_items.product_id→ products.id

SQL模板

可用模板

基本选择：带WHERE子句的基本SELECT查询
inner_join：INNER JOIN查询
基本插入：INSERT语句
基本更新：带WHERE子句的UPDATE语句
基本删除：带WHERE子句的DELETE语句
合计：使用GROUP BY聚合查询

每个模板包括：

带有占位符的模板结构
参数定义
查询示例

与MCP客户端一起使用

卷曲示例

# Initialize
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

# Get schema
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_schema",
      "arguments": {}
    }
  }'

# Get templates
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_templates",
      "arguments": {}
    }
  }'

与AI助手集成

MCP客户端（如Claude Desktop或其他AI助手）可以连接到此服务器以：

发现可用的数据库表和列
了解表之间的关系
访问SQL查询模板
基于模式上下文生成准确的SQL查询

发展

项目结构

spring-mcp-toolkit/
├── src/
│   ├── main/
│   │   ├── java/com/satyavenik/mcpserver/
│   │   │   ├── McpServerApplication.java
│   │   │   ├── config/
│   │   │   ├── controller/
│   │   │   │   └── McpController.java
│   │   │   ├── model/
│   │   │   │   ├── ColumnSchema.java
│   │   │   │   ├── DatabaseSchema.java
│   │   │   │   ├── ForeignKey.java
│   │   │   │   ├── SqlTemplate.java
│   │   │   │   ├── TableSchema.java
│   │   │   │   └── TemplateParameter.java
│   │   │   ├── protocol/
│   │   │   │   ├── McpError.java
│   │   │   │   ├── McpRequest.java
│   │   │   │   └── McpResponse.java
│   │   │   └── service/
│   │   │       ├── McpService.java
│   │   │       ├── SchemaService.java
│   │   │       └── TemplateService.java
│   │   └── resources/
│   │       └── application.yml
│   └── test/
│       └── java/
├── pom.xml
└── README.md

添加自定义架构

扩展 SchemaService 添加您自己的数据库模式：

@Service
public class CustomSchemaService extends SchemaService {
    
    @Override
    public DatabaseSchema getExampleSchema() {
        // Return your custom schema
    }
}

添加自定义模板

扩展 TemplateService 要添加自定义SQL模板，请执行以下操作：

@Service
public class CustomTemplateService extends TemplateService {
    
    @Override
    public List<SqlTemplate> getAllTemplates() {
        List<SqlTemplate> templates = super.getAllTemplates();
        // Add your custom templates
        return templates;
    }
}

测试

使用以下工具运行测试：

mvn test

故障排除

服务器无法启动

检查端口8080是否可用
验证是否安装了Java 17+： java -version
检查应用程序日志是否有错误

MCP客户端无法连接

验证服务器是否正在运行： curl http://localhost:8080/mcp/health
检查防火墙设置
确保客户端配置了正确的URL

架构未加载

检查SchemaService实现
验证JSON序列化是否正常工作
检查应用程序日志

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
进行更改
添加测试
提交拉取请求

许可证

这个项目是开源的，可以在MIT许可证下使用。

支持

对于问题、疑问或贡献：

在GitHub上创建问题
提交拉取请求
联系维护人员

路线图

[]支持多种数据库模式
[]来自实时数据库的模式自检
[]MCP的WebSocket传输
[]架构版本控制
[]查询验证
[]性能指标
[]Docker支持
[]Kubernetes部署配置