MCP Db Server

⚠ 正在进行的工作分叉

此存储库是原始项目的一个正在进行的分支：

原始项目：mcp-db服务器 来源： 许可证：Apache许可证，版本2.0

此分叉正在进行调整，以供内部团队使用。它可能与上游项目存在显著差异，并不打算作为替代品。

⸻

此叉子的用途

此叉子的存在是为了： •扩展和定制内部工作流程的功能 •尝试上游项目中不存在的功能 •为团队特定工具提供基础

目前，它不打算公开分发或向上游捐款。

⸻

与上游的关系

此存储库包含对原始项目的修改。 所有原始代码仍按照Apache许可证2.0版获得许可。

有关完整的许可证详细信息，请参阅LICENSE文件。

在适用的情况下： •保留了原始版权声明。 •在这个分叉中所做的修改可能会在提交历史中被识别出来。

⸻

免责声明

这是一个内部衍生作品，与原始项目维护人员无关或没有得到他们的认可。

⸻

特性

• 多数据库支持：适用于PostgreSQL和MySQL
• 自然语言到SQL：使用HuggingFace转换器将纯英语查询转换为SQL
• RESTful API：为数据库操作清理基于FastAPI的端点
• 安全第一：具有查询验证和结果限制的只读操作
• Docker就绪：使用Docker Compose完成容器化
• 生产就绪：健康检查、日志记录和错误处理
• AI代理友好：专为AI代理集成而设计

API终点

快速开始

选项1:Docker Compose（推荐）

1. 克隆并启动服务：

   git clone https://github.com/Souhar-dya/mcp-db-server.git
   cd mcp-db-server
   docker-compose up --build

1. 测试端点：

   # Health check
   curl http://localhost:8000/health

   # List tables
   curl http://localhost:8000/mcp/list_tables

   # Describe a table
   curl http://localhost:8000/mcp/describe/customers

   # Natural language query
   curl -X POST "http://localhost:8000/mcp/query" \
     -H "Content-Type: application/json" \
     -d '{"nl_query": "show top 5 customers by total orders"}'

方案2：地方发展

1. 先决条件：

- Python 3.11+ - PostgreSQL或MySQL数据库

1. 安装依赖项：

   pip install -r requirements.txt

1. 设置环境变量：

   export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname"
   # or for MySQL:
   # export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname"

1. 运行服务器：

   python -m app.server

示例数据库

该项目包括一个包含真实电子商务数据的示例数据库：

• 客户：客户信息（10个样本客户）
• 订单：订单记录（17个样品订单）
• 订单项目：订单中的单个项目
• 订单_摘要：查看订单和客户数据的组合

自然语言查询示例

服务器可以理解各种类型的自然语言查询：

# Get all customers
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show all customers"}'

# Count orders by status
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "count orders by status"}'

# Top customers by order value
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "top 5 customers by total order amount"}'

# Recent orders
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show recent orders from last week"}'

配置

环境变量

数据库连接示例

# PostgreSQL
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb

# MySQL
DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/mydb

# PostgreSQL with SSL
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb?sslmode=require

### Database Connection Examples

PostgreSQL (local or cloud)

DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname

MySQL (local or cloud)

DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname

PostgreSQL with SSL (cloud, e.g. Neon, Supabase, Aiven)

DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname?sslmode=require

MySQL with SSL (cloud, e.g. Aiven, PlanetScale)

DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname?ssl-mode=REQUIRED

> **注：**
>
> - 对于MySQL云提供商来说 `ssl-mode` 驱动程序会忽略URL中的参数，但MCP服务器中始终为云连接启用SSL。
> - 对于PostgreSQL，使用 `sslmode=require` 对于云数据库。对于MySQL，只需使用标准URL；SSL是自动处理的。
> - 如果您看到以下错误 `ssl-mode` 或 `sslmode`，检查您的URL并确保您使用了正确的驱动程序前缀(`mysql+aiomysql` 或 `postgresql+asyncpg`).

#### 云数据库示例

Neon (PostgreSQL)

DATABASE_URL=postgresql+asyncpg://username:password@ep-xxxxxx-pooler.us-east-2.aws.neon.tech/dbname

Aiven (MySQL)

DATABASE_URL=mysql+aiomysql://avnadmin:yourpassword@mysql-xxxxxx-username-xxxx.aivencloud.com:11079/defaultdb?ssl-mode=REQUIRED

#### Docker与Cloud DB的使用

docker run -d \ -p 8000:8000 \ -e DATABASE_URL="" \ souhardyak/mcp-db-server:latest

#### 故障排除

- 如果你得到 `connect() got an unexpected keyword argument 'ssl-mode'`，忽略它：SSL仍处于启用状态。
- 对于网络错误，请检查防火墙和数据库凭据。
- 对于MySQL，始终使用 `mysql+aiomysql` 在URL中提供异步支持。

Security Features

• Read-Only Operations: Only SELECT queries are allowed
• Query Validation: Automatic detection and blocking of dangerous SQL operations
• Result Limiting: Maximum 50 rows per query (configurable)
• Input Sanitization: Protection against SQL injection
• Safe Defaults: Secure configuration out of the box

Architecture

mcp数据库服务器/
├── app/
│   ├── __初始化__.py#包初始化
│   ├── server.py#FastAPI应用程序和端点
│   ├── db.py#数据库连接和操作
│   └── nl_to_sql.py#自然语言到sql的转换
├── .github/工作流/
│   └── docker-publish.yml#CI/CD管道
├── docker-compose.yml#docker compose配置
├── Dockerfile#容器定义
├── init_db.sql#示例数据库模式和数据
├── requirements.txt#Python依赖项
└── README.md#此文件

Model Context Protocol (MCP) Integration

This server is designed to work seamlessly with MCP-compatible AI agents:

1. Standardized Endpoints: RESTful API following MCP conventions
2. Structured Responses: JSON responses optimized for AI consumption
3. Error Handling: Consistent error messages and status codes
4. Documentation: OpenAPI/Swagger documentation available at /docs

Deployment

Docker Hub

# Pull the latest image
docker pull souhardyak/mcp-db-server:latest

# Run with your database
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="your_database_url_here" \
  souhardyak/mcp-db-server:latest

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-db-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-db-server
  template:
    metadata:
      labels:
        app: mcp-db-server
    spec:
      containers:
        - name: mcp-db-server
          image: souhardyak/mcp-db-server:latest
          ports:
            - containerPort: 8000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-db-server-service
spec:
  selector:
    app: mcp-db-server
  ports:
    - port: 80
      targetPort: 8000
  type: LoadBalancer

测试

在本地运行测试

# Start test database
docker-compose up postgres -d

# Wait for database to be ready
sleep 10

# Run tests
python -m pytest tests/ -v

手动测试

# Test health endpoint
curl http://localhost:8000/health

# Test table listing
curl http://localhost:8000/mcp/list_tables

# Test natural language query
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show me all customers from California"}'

贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。

📝 更新日志

v1.3.0（2025-12-24）-Docker路径修复

• 固定的：解决了Docker容器中的导入路径问题，导致 from db import DatabaseManager 失败
• 固定的：在Dockerfile和docker-compose.yml健康检查中将相对路径更改为绝对路径
• 改进的: mcp_server.py 现在使用强大的路径解析，既适用于本地，也适用于Docker容器
• 更新：Docker镜像重建并推送所有路径修复

v1.2.0（2025-11-03）-MySQL列访问修复

• 固定的：已解决 Could not locate column in row for column 'column_name' MySQL数据库出错
• 固定的：已更改 describe_table 使用基于索引的行访问以获得更好的SQLAlchemy兼容性的方法
• 改进的：增强了模式自检的跨数据库兼容性
• 已解决：GitHub问题 #1

V1.0（2025-09-28）-异步错误修复

• 固定的：已解决 str can't be used in 'await' expression MCP服务器出错
• 改进的：NLP查询处理现在可以与Claude Desktop集成正常工作
• 增强：添加了全面的测试数据库设置脚本
• 更新：使用错误修复和更新的依赖关系重建Docker映像

v1.0.0（2025-09-25）-初始版本

• 初始：完整的MCP数据库服务器实现
• 添加：带FastAPI的RESTful API
• 添加：自然语言到SQL的转换
• 添加：Docker容器化和部署
• 添加：多数据库支持（PostgreSQL、MySQL、SQLite）

致谢

• 快速API 优秀的web框架
• 拥抱面部变压器 用于NL到SQL的功能
• SQLAlchemy 用于数据库抽象
• 模型上下文协议（MCP）社区

支持

• 报告问题
• 讨论
• 文档

______________________________________________________________________

⭐ 如果这个项目对你有帮助，请考虑给它一颗星！