查询CraftMCP
QueryCraftMCP是一个灵活的模型上下文协议（MCP）服务器，旨在弥合大型语言模型（LLM）和各种数据库系统之间的差距。它允许LLM或其他MCP客户端通过标准化协议动态发现数据库模式、执行查询和检索数据。服务器支持多个数据库后端（目前是PostgreSQL和SQLite），可通过配置进行选择。
特性
- 多数据库后端支持：
- PostgreSQL： 异步交互使用 asyncpg，包括通过生命周期管理实现连接池。 - SQLite： 使用内置的同步交互 sqlite3 图书馆。 - 使用易于配置的活动后端 ACTIVE_DB_BACKEND 环境变量。
- 动态工具加载： 工具和数据库连接寿命根据配置的后端动态加载。
- 全面的数据库交互工具：
- 架构发现： 列出可用数据库（PostgreSQL）、数据库对象（表/视图）（PostgreSQL）和对象列（PostgreSQL）的工具。对于SQLite，提供了一个检索全表DDL模式的工具。 - 数据查询： - 结构化搜索能力（例如。， search_data PostgreSQL）。 - 原始SQL查询执行（例如。， execute_raw_sql 对于PostgreSQL， execute_query 对于SQLite），出于安全考虑。
- 寿命管理： 在整个应用程序生命周期中对数据库连接进行稳健管理。
- 传输协议： 利用服务器发送事件（SSE）进行MCP通信。
- 配置： 主要通过
.env文件和环境变量。 - Docker支持： 包括a
Dockerfile（在讨论中建议，未上传），便于容器化和部署。
项目结构
该项目遵循 src/ 布局，特定于数据库的实现按以下方式组织 src/db_backends/:
QueryCraftMCP/
├── src/
│ ├── init.py
│ ├── main.py # Main application entry point
│ │
│ └── db_backends/
│ ├── init.py
│ ├── postgres/ # PostgreSQL specific modules
│ │ ├── init.py
│ │ ├── lifespan.py
│ │ ├── schema_tools.py
│ │ └── query_tools.py
│ └── sqlite/ # SQLite specific modules
│ ├── init.py
│ ├── lifespan.py
│ ├── schema_tools.py
│ └── query_tools.py
│
├── .env # For local environment variables
├── requirements.txt
├── Dockerfile # For building Docker images (example provided in discussion)
└── .dockerignore # Specifies files to ignore in Docker build (example provided in discussion)
└── README.md先决条件
- Python 3.9+
- Docker（如果通过Docker运行）
- 访问PostgreSQL服务器（如果使用PostgreSQL后端）
- SQLite数据库文件的可写目录（如果使用SQLite后端）
设置
- 克隆存储库：
git clone
cd QueryCraftMCP- 创建虚拟环境（推荐）：
python -m venv venv
source venv/bin/activate # On Linux/macOS
# venv\Scripts\activate # On Windows- 安装依赖关系：
pip install -r requirements.txt依赖关系包括 mcp[cli], asyncpg，以及 python-dotenv.
- 配置环境变量：
创建一个 .env 项目根目录中的文件。用必要的配置填充它：
# .env
# --- General Configuration ---
# Choose the active database backend: "postgres" or "sqlite"
ACTIVE_DB_BACKEND="postgres"
# MCP Server Host and Port (used by main.py)
MCP_HOST="0.0.0.0"
MCP_PORT="8888" # The port your MCP server will listen on with SSE/HTTP
# --- PostgreSQL Backend Configuration ---
# Required if ACTIVE_DB_BACKEND is "postgres"
POSTGRES_DATABASE_URL="postgresql://your_user:your_password@your_pg_host:5432/your_database"
# --- SQLite Backend Configuration ---
# Required if ACTIVE_DB_BACKEND is "sqlite"
# This path is relative to where the application runs.
# If running in Docker, this path will be inside the container.
SQLITE_DATABASE_PATH="querycraft_data.db"- 替换占位符值（如 your_user, your_password等）与您的实际凭据和路径。 - 这 MCP_HOST 和 MCP_PORT 被使用 FastMCP 当它在中实例化时 main.py.
运行应用程序
1.本地（直接使用Python）
确保您的 .env 文件配置正确。
python -m src.main服务器将开始使用配置的ACTIVE_DB_BACKEND，并将使用SSE传输在MCP_host和MCP_port（默认为0.0.0.0:8888）指定的主机和端口上进行侦听。
- 使用Docker
首先，构建Docker镜像（假设你有一个像前面讨论中建议的那样的Docker文件）：
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" \
querycraftmcp- 用实际的PostgreSQL凭据替换docker_user、docker_pass、docker_db。
- host.docker.internal可用于从docker容器（适用于Mac/Windows的docker Desktop）连接到主机上运行的PostgreSQL服务器。
-p 8888:8888将主机的端口映射到容器的端口。