数据库架构MCP服务器
一个模型上下文协议（MCP）服务器，使用OpenAI的LLM和向量嵌入来提取、丰富和索引数据库模式。该服务器提供跨多种数据库类型（MySQL、PostgreSQL、SQL server）的自然语言查询功能。
特性
- 多数据库支持：连接到MySQL、PostgreSQL和SQL Server数据库
- 模式提取：自动提取表和列元数据
- LLM强化：使用OpenAI生成描述、示例和提示
- 矢量索引：使用pgvector在PostgreSQL中存储模式元数据以进行语义搜索
- 自然语言查询：用简单的英语提问并获得SQL结果
- MCP集成：通过模型上下文协议公开工具
- API身份验证：使用API密钥身份验证保护所有端点
- 增量更新：基于CRC的智能更改检测，避免不必要的LLM调用
先决条件
- Node.js 18+
- 带pgvector扩展的PostgreSQL
- OpenAI API密钥
- 用于身份验证的API密钥
- 至少一个源数据库（MySQL、PostgreSQL或SQL Server）
安装
- 克隆存储库：
git clone
cd hubeet-mysql-llmasisted-mcpserver- 安装依赖项：
npm install- 使用pgvector设置PostgreSQL：
选项A：使用Docker Compose（推荐）
# Start all required databases
docker-compose up -d
# Wait for databases to be ready
docker-compose ps选项B：手动设置
# Run the setup script
./scripts/setup.sh
# Or manually run the SQL script
psql -U postgres -f scripts/setup-database.sql- 配置环境变量：
cp env.example .env编辑 .env 根据您的配置：
认证
除了运行状况检查之外，服务器要求对所有终结点进行API密钥身份验证。看 API_授权.md 有关详细的身份验证说明。
快速开始身份验证
- 在中设置API密钥
.env文件：
API_KEY=your_secure_api_key_here- 使用带有身份验证的API：
# Using Authorization header
curl -X POST http://localhost:3002/api/query \
-H "Authorization: Bearer your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"question": "show me all countries"}'
# Using X-API-Key header
curl -X POST http://localhost:3002/api/query \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"question": "show me all countries"}'如果使用Docker Compose：
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
# Database URLs (using Docker Compose defaults)
POSTGRES_URL=postgres://postgres:postgres123@localhost:5433/source_db
MYSQL_URL=mysql://mysql_user:mysql123@localhost:3306/source_db
SQLSERVER_URL=mssql://sa:SqlServer123!@localhost:1433/source_db
# Vector Database (PostgreSQL with pgvector)
VECTOR_DB_URL=postgres://postgres:postgres123@localhost:5432/vector_db
# Server Configuration
PORT=3000
NODE_ENV=development如果使用手动设置：
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
# Database URLs (configure at least one source database)
POSTGRES_URL=postgres://user:password@localhost:5432/source_db
MYSQL_URL=mysql://user:password@localhost:3306/source_db
SQLSERVER_URL=mssql://user:password@localhost:1433/source_db
# Vector Database (PostgreSQL with pgvector)
VECTOR_DB_URL=postgres://user:password@localhost:5432/vector_db
# Server Configuration
PORT=3000
NODE_ENV=development用法
启动服务器
# Development mode
npm run dev
# Production mode
npm run build
npm start可用的MCP工具
1.extractSchema
从所有连接的数据库中提取并丰富数据库模式。
输入：无
输出：JSON包含带有描述、示例和提示的丰富模式。
示例:
{
"tables": [
{
"name": "users",
"description": "Table storing user information and authentication data",
"columns": [
{
"name": "id",
"type": "int",
"description": "Unique identifier for each user",
"isPrimaryKey": true,
"isForeignKey": false
},
{
"name": "email",
"type": "varchar",
"description": "User's email address, must be unique",
"isPrimaryKey": false,
"isForeignKey": false
}
],
"examples": [
{"id": 1, "email": "john@example.com"},
{"id": 2, "email": "jane@example.com"}
],
"hints": "Contains user profile data and authentication information"
}
],
"extractedAt": "2024-01-15T10:30:00.000Z",
"version": "1.0.0"
}2. reindex方案
将当前模式重新索引到向量数据库中。
输入：无
输出：成功消息，其中包含索引的表数。
3.重新索引所有
清除向量数据库中的所有模式数据并重新建立索引。
输入：无
输出：成功消息，其中包含重新索引的表数。
4.查询自然语言
处理一个自然语言问题，并返回相关的模式元素、建议的SQL和执行结果。
输入:
{
"question": "Show me all users with their email addresses"
}输出:
{
"relevantElements": {
"tables": [
{
"name": "users",
"description": "Table storing user information",
"columnCount": 3,
"hints": "Contains user profile data"
}
],
"columns": [
{
"name": "email",
"description": "User's email address",
"type": "varchar",
"hints": "Must be unique"
}
]
},
"proposedSQL": "SELECT id, email FROM users",
"executionResults": [
{"id": 1, "email": "john@example.com"},
{"id": 2, "email": "jane@example.com"}
],
"executionTime": 150
}测试
运行测试套件：
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverageAPI示例
使用curl与MCP服务器交互
# Extract schema
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "extractSchema",
"arguments": {}
}
}'
# Query natural language
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "queryNaturalLanguage",
"arguments": {
"question": "What tables contain user information?"
}
}
}'
# Reindex all data
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "reindexAll",
"arguments": {}
}
}'建筑
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Source DBs │ │ OpenAI API │ │ Vector DB │
│ │ │ │ │ (PostgreSQL │
│ • PostgreSQL │ │ • GPT-4 │ │ + pgvector) │
│ • MySQL │ │ • Embeddings │ │ │
│ • SQL Server │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ MCP Server │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Schema │ │ LLM │ │ Vector │ │
│ │ Service │ │ Service │ │ Service │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Query │ │ MCP │ │
│ │ Service │ │ Server │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘安全考虑
- SQL注入保护：所有生成的SQL都经过危险操作验证
- 输入验证：所有输入都经过验证和消毒
- 错误处理：全面的错误处理可防止系统崩溃
- 连接安全性：数据库连接在配置时使用SSL
- API密钥安全：OpenAI API密钥是从环境变量加载的
性能优化
- 连接池：数据库连接被池化以提高效率
- 矢量索引：创建pgvector索引以进行快速相似性搜索
- 缓存：模式元数据缓存在矢量数据库中
- 并行处理：并行处理多个数据库连接
故障排除
常见问题
- 未找到pgvector扩展名
CREATE EXTENSION IF NOT EXISTS vector;- 数据库连接失败
- 检查中的数据库URL .env - 验证数据库凭据 - 确保数据库正在运行且可访问
- OpenAI API错误
- 验证API密钥是否正确 - 检查API配额和账单 - 确保网络连接
- 矢量索引失败
- 检查矢量数据库权限 - 验证是否安装了pgvector扩展 - 检查可用磁盘空间
日志
服务器记录重要事件和错误。检查控制台输出：
- 数据库连接状态
- 架构提取进度
- LLM富集结果
- 矢量索引状态
- 查询处理结果
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持
对于问题和疑问：
- 检查故障排除部分
- 查看测试文件以获取使用示例
- 在GitHub上打开一个问题
- 联系开发团队