QueryCraftMCP

QueryCraftMCP 是一个灵活的模型上下文协议（MCP）服务器，旨在弥合大型语言模型（LLMs）与各种数据库系统之间的差距。它允许 LLMs 或其他 MCP 客户端通过标准化协议动态发现数据库模式、执行查询并检索数据。该服务器支持多种数据库后端（目前支持 PostgreSQL 和 SQLite），可通过配置进行选择。

功能

• 多数据库后端支持：
  • PostgreSQL： 使用 asyncpg 进行异步交互，包括通过生命周期管理实现连接池。
  • SQLite： 使用内置的 sqlite3 库进行同步交互。
  • 可通过环境变量 ACTIVE_DB_BACKEND 灵活配置活动后端。
• 动态工具加载： 工具和数据库连接生命周期根据配置的后端动态加载。
• 全面的数据库交互工具：
  • 模式发现： 提供列出可用数据库（PostgreSQL）、数据库对象（表/视图）（PostgreSQL）和对象列（PostgreSQL）的工具。对于 SQLite，提供获取完整表 DDL 模式的工具。
  • 数据查询：
    • 结构化搜索能力（例如，PostgreSQL 的 search_data）。
    • 原始 SQL 查询执行（例如，PostgreSQL 的 execute_raw_sql，SQLite 的 execute_query），考虑安全性。
• 生命周期管理： 在应用程序生命周期中对数据库连接进行强大的管理。
• 传输协议： 使用服务器发送事件（SSE）进行 MCP 通信。
• 配置： 主要通过 .env 文件和环境变量进行配置。
• Docker 支持： 包含 Dockerfile（讨论中建议，未上传），便于容器化和部署。

项目结构

项目遵循 src/ 布局，数据库特定的实现组织在 src/db_backends/ 下：

QueryCraftMCP/
├── src/
│   ├── init.py
│   ├── main.py                 # 主应用入口点
│   │
│   └── db_backends/
│       ├── init.py
│       ├── postgres/           # PostgreSQL 特定模块
│       │   ├── init.py
│       │   ├── lifespan.py
│       │   ├── schema_tools.py
│       │   └── query_tools.py
│       └── sqlite/             # SQLite 特定模块
│           ├── init.py
│           ├── lifespan.py
│           ├── schema_tools.py
│           └── query_tools.py
│
├── .env                        # 本地环境变量文件
├── requirements.txt
├── Dockerfile                  # 构建 Docker 镜像（讨论中提供的示例）
└── .dockerignore               # 指定在 Docker 构建中忽略的文件（讨论中提供的示例）
└── README.md

先决条件

• Python 3.9+
• Docker（如果通过 Docker 运行）
• 访问 PostgreSQL 服务器（如果使用 PostgreSQL 后端）
• SQLite 数据库文件的可写目录（如果使用 SQLite 后端）

设置

1. 克隆仓库：

   git clone <your-repository-url>
   cd QueryCraftMCP
   

2. 创建虚拟环境（推荐）：

   python -m venv venv
   source venv/bin/activate  # 在 Linux/macOS 上
   # venv\Scripts\activate    # 在 Windows 上
   

3. 安装依赖项：

   pip install -r requirements.txt
   

   依赖项包括 mcp[cli]、asyncpg 和 python-dotenv。

4. 配置环境变量： 在项目根目录下创建一个 .env 文件，并填充必要的配置：

   # .env
   
   # --- 通用配置 ---
   # 选择活动数据库后端："postgres" 或 "sqlite"
   ACTIVE_DB_BACKEND="postgres"
   
   # MCP 服务器主机和端口（由 main.py 使用）
   MCP_HOST="0.0.0.0"
   MCP_PORT="8888" # MCP 服务器监听的端口，使用 SSE/HTTP
   
   # --- PostgreSQL 后端配置 ---
   # 如果 ACTIVE_DB_BACKEND 是 "postgres" 则需要此配置
   POSTGRES_DATABASE_URL="postgresql://your_user:your_password@your_pg_host:5432/your_database"
   
   # --- SQLite 后端配置 ---
   # 如果 ACTIVE_DB_BACKEND 是 "sqlite" 则需要此配置
   # 此路径相对于应用程序运行的位置。
   # 如果在 Docker 中运行，则此路径位于容器内。
   SQLITE_DATABASE_PATH="querycraft_data.db"
   

   • 替换占位符值（如 your_user、your_password 等）为实际凭据和路径。
   • MCP_HOST 和 MCP_PORT 在 main.py 中实例化 FastMCP 时使用。

运行应用程序

1. 本地（直接使用 Python）

确保你的 .env 文件配置正确。

python -m src.main

服务器将使用配置的 ACTIVE_DB_BACKEND 启动，并监听由 MCP_HOST 和 MCP_PORT 指定的主机和端口（默认为 0.0.0.0:8888），使用 SSE 传输。

2. 使用 Docker 首先，构建 Docker 镜像（假设你有一个类似于先前讨论中建议的 Dockerfile）：

docker build -t querycraftmcp .

然后，运行 Docker 容器。你需要传递环境变量。

示例（PostgreSQL 后端）：

docker run -it --rm \
  -p 8888:8888 \
  -e ACTIVE_DB_BACKEND="postgres" \
  -e POSTGRES_DATABASE_URL="postgresql://docker_user:docker_pass@host.docker.internal:5432/docker_db" \
  -e MCP_HOST="0.0.0.0" \
  -e MCP_PORT="8888" \
  querycraftm

• 替换 docker_user、docker_pass、docker_db 为实际的 PostgreSQL 凭据。
• host.docker.internal 可用于从 Docker 容器内部连接到主机上的 PostgreSQL 服务器（适用于 Mac/Windows 上的 Docker Desktop）。
• -p 8888:8888 将主机端口映射到容器端口。