AI To SQL

PromptToSql-MCP服务器

描述

MCP服务器（模型上下文协议） 是一个Spring Boot 3+应用程序，它实现了LLM代理通过JDBC与数据库系统交互的标准化协议。该服务器充当桥梁，将静态AI知识转换为能够检索当前信息并执行操作的动态代理。

主要特点

• 数据库不可知：支持Oracle、MySQL、PostgreSQL和MSSQL
• 🎯 驾驶员自动检测：从URL模式解析智能JDBC驱动程序
• JSON-RPC 2.0传输：MCP的标准通信协议
• 图式反思：完成数据库元数据发现
• 安全查询：具有只读强制的SQL注入预防
• 触发器发现：数据库触发自检
• 缓存：元数据操作的性能优化
• 性能指标：详细的标记化和性能跟踪
• 成本估算：自动LLM API成本计算

技术

• Java 21
• 弹簧靴3.2.1
• Spring JDBC （JdbcTemplate-无JPA）
• JSON-RPC 2.0
• 梅文

建筑

com.magacho.aiToSql
├── AiToSqlApplication.java          # Main application
├── config/
│   ├── CachingConfig.java           # Cache configuration
│   └── McpServerConfig.java         # MCP server settings
├── controller/
│   └── McpController.java           # JSON-RPC 2.0 endpoint
├── service/
│   ├── SchemaIntrospectionService.java
│   ├── TableDetailsService.java
│   ├── TriggerService.java
│   └── SecureQueryService.java
├── tools/
│   └── McpToolsRegistry.java        # MCP tools registry
├── jsonrpc/
│   ├── JsonRpcRequest.java
│   ├── JsonRpcResponse.java
│   └── JsonRpcError.java
└── dto/
    ├── SchemaStructure.java
    ├── TableDetails.java
    ├── TriggerList.java
    └── QueryResult.java

🚀 快速开始

选项1:Docker（推荐）🐳

运行MCP服务器最简单的方法是使用Docker：

# Pull the image from Docker Hub
docker pull flaviomagacho/aitosql:latest

# Run with PostgreSQL
docker run -d \
  --name aitosql-mcp \
  -e DB_URL="jdbc:postgresql://your-host:5432/your_db" \
  -e DB_USERNAME="readonly_user" \
  -e DB_PASSWORD="your_password" \
  -p 8080:8080 \
  flaviomagacho/aitosql:latest

# Test the server
curl http://localhost:8080/actuator/health
curl http://localhost:8080/mcp/tools/list

✨ 新功能：无需指定 DB_TYPE 或 DB_DRIVER -它们会被自动检测到！看 JDBC驱动程序自动检测

或者使用Docker Compose进行本地开发:

# Clone the repository
git clone https://github.com/magacho/aiToSql.git
cd aiToSql

# Start with PostgreSQL (or mysql, sqlserver)
docker-compose -f docker-compose-postgres.yml up -d

# View logs
docker-compose -f docker-compose-postgres.yml logs -f mcp-server

# Stop
docker-compose -f docker-compose-postgres.yml down

📖 全部文件:

• **** -完整的部署说明
• **** -如何构建和发布
• 快速入门指南 -分步教程

______________________________________________________________________

选项2：从源代码构建

先决条件

1. Java 21+ 安装
2. Maven 3.6+ 安装
3. 数据库 用户配置为只读

配置

1.添加JDBC驱动程序

编辑 pom.xml 并取消对相应驾驶员的注释：

    org.postgresql
    postgresql
    runtime

2.配置数据库连接

编辑 src/main/resources/application.properties:

# PostgreSQL Example
spring.datasource.url=jdbc:postgresql://localhost:5432/production_db
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.username=mcp_readonly_user
spring.datasource.password=secure_password

关键安全性：数据库用户必须具有只读权限（仅限SELECT）。这是针对SQL注入的主要防御措施。

构建并运行

# Compile
mvn clean install

# Run
mvn spring-boot:run

服务器将在以下时间启动 http://localhost:8080

MCP工具

服务器通过JSON-RPC 2.0公开了4个工具：

1.getSchemaStructure

获取包含表和列的完整数据库架构。

参数：

• databaseName （可选）：数据库名称

退货： 完整的架构结构

2.获取表格详细信息

获取特定表格的详细信息。

参数：

• tableName （必填）：表名

退货： 表详细信息，包括索引、外键和约束

3.列表触发器

列出特定表的所有触发器。

参数：

• tableName （必填）：表名

退货： 触发器及其定义列表

4.安全数据库查询

执行安全的SELECT查询。

参数：

• queryDescription （必填）：SQL SELECT查询
• maxRows （可选）：要返回的最大行数

退货： 带元数据的查询结果

安全： 只允许使用SELECT语句。自动验证并防止危险操作。

JSON-RPC 2.0示例

初始化会话

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

列出可用工具

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 2
  }'

获取架构结构

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

执行查询

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "secureDatabaseQuery",
      "arguments": {
        "queryDescription": "SELECT * FROM customers WHERE age > 50",
        "maxRows": 100
      }
    },
    "id": 4
  }'

安全特性

• ✅ 只读数据库用户 （主要防御）
• ✅ 仅选择验证 （拒绝插入/更新/删除/删除）
• ✅ 危险关键字过滤
• ✅ 查询结果限制 （防止资源枯竭）
• ✅ 综合录井 用于审计跟踪

MCP实施的好处

1. 动态代理：LLM超越静态知识，访问实时数据
2. 标准化：LLM数据库交互的通用协议
3. 幻觉减少：访问受信任的外部数据源
4. 可扩展性：可以部署到Cloud Run、GKE或其他平台
5. 多数据库：Oracle、MySQL、PostgreSQL、MSSQL的单一接口

部署

Docker（可选）

FROM eclipse-temurin:21-jre
COPY target/aiToSql-0.0.1-SNAPSHOT.jar app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

云运行/GKE

该服务器是无状态的，可以轻松部署到Google Cloud Run或GKE等托管平台，连接到Cloud SQL实例。

📊 测试和覆盖范围

该项目保持 全面测试覆盖率 随着 无强制性最低要求。我们专注于跟踪不同版本的覆盖范围演变：

• 当前覆盖范围：检查 封面_报告.md
• 覆盖历史：参见 发布_圣诞节.md
• 测试指导：阅读 测试指南.md
• 追踪详情: 封面_确认.md

在本地运行测试

# Run all tests
mvn clean test

# Generate coverage report
mvn jacoco:report

# View report
firefox target/site/jacoco/index.html

CI/CD

• ✅ 自动化测试 每一次承诺
• ✅ 覆盖率报告 自动生成
• ✅ 发布工作流程 有报道历史
• ✅ 无阻塞 关于覆盖率

哲学：跟踪，不要阻拦。持续改进。 📈

📈 绩效和指标

MCP服务器包括全面的性能跟踪和标记化指标：

指标端点

# Get all metrics
curl http://localhost:8080/mcp/metrics

# Reset metrics
curl -X POST http://localhost:8080/mcp/metrics/reset

测量什么

• 执行时间：处理每个工具需要多长时间
• 令牌估计：近似令牌计数（1个令牌≈4个字符）
• 成本估算：估计LLM API成本（GPT-4定价）
• 高速缓存性能：每个工具的缓存命中率
• 响应大小：每个响应的字符和估计令牌

文档

• 性能指标: PERFORMANCE_METRICS.md
• 代币化指南: 代币化\_ GIDE.md
• 令牌化架构: 代币化_代币结构.md

示例指标响应

{
  "tools": {
    "getSchemaStructure": {
      "totalCalls": 150,
      "avgExecutionTimeMs": 45,
      "avgTokens": 3125,
      "totalCostUSD": 0.001875,
      "cacheHitRate": 80.0
    }
  },
  "summary": {
    "totalCalls": 1880,
    "totalCostUSD": 0.3483,
    "averageCostPerCall": 0.00019
  }
}

备注：实际的标记化发生在LLM主机（Claude、GPT-4等）中，而不是在MCP服务器中。服务器提供 *估计* 用于分析和优化。

许可证

开源项目。

组ID/工件ID

• 组ID: com.magacho
• 工件ID: aiToSql