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：从源代码构建
先决条件
- Java 21+ 安装
- Maven 3.6+ 安装
- 数据库 用户配置为只读
配置
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实施的好处
- 动态代理：LLM超越静态知识，访问实时数据
- 标准化：LLM数据库交互的通用协议
- 幻觉减少：访问受信任的外部数据源
- 可扩展性：可以部署到Cloud Run、GKE或其他平台
- 多数据库：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实例。
📊 测试和覆盖范围
该项目保持 全面测试覆盖率 随着 无强制性最低要求。我们专注于跟踪不同版本的覆盖范围演变：
在本地运行测试
# Run all tests
mvn clean test
# Generate coverage report
mvn jacoco:report
# View report
firefox target/site/jacoco/index.htmlCI/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