# Postgres Query MCP

一个面向本地开发的、只读 PostgreSQL MCP Server。它把自然语言转换为 SQL，并在服务端强制执行数据库路由、表列白名单、危险 SQL 拦截、执行前 EXPLAIN、超时和限流。

## 快速开始

```bash
cp .env.example .env
uv sync --all-groups
uv run python -m pgmcp.main
```

默认策略已连接到本机正在运行的 Postgres 15.18：

```text
postgresql://postgres:postgres@127.0.0.1:5432/db_query_demo
```

它包含 `users` 和 `orders` 表。服务层会拦截写操作及 `users.email`；在生产环境应改用独立只读账号。若需要启动仓库自带的隔离演示数据库，执行 `docker compose up -d`，再将连接串改为 `postgresql://pgmcp_reader:pgmcp_reader@127.0.0.1:5433/db_query_demo`。

配置 MCP 客户端时，使用：

```json
{
  "mcpServers": {
    "postgres-query": {
      "command": "uv",
      "args": ["run", "python", "-m", "pgmcp.main"],
      "cwd": "/absolute/path/to/pgmcp"
    }
  }
}
```

未设置 `PGMCP_OPENAI_API_KEY` 时，服务仍可启动和提供 Schema 工具；调用 `query` 会返回明确的配置错误。服务兼容 OpenAI 格式的 API。使用 DeepSeek 时，在 MCP 环境变量中设置：

```text
PGMCP_OPENAI_API_KEY=<你的 DeepSeek API Key>
PGMCP_OPENAI_BASE_URL=https://api.deepseek.com
PGMCP_OPENAI_MODEL=deepseek-v4-flash
```

## MCP 工具

- `list_databases`：可查询数据库列表。
- `describe_table`：读取受允许的表结构。
- `refresh_schema`：刷新目标数据库的内存 Schema 缓存。
- `query`：自然语言查询，`output_mode` 可选 `sql` 或 `result`。

## 验证

```bash
uv run pytest
uv run ruff check .
```

Prometheus 指标默认暴露在 `http://127.0.0.1:9464/metrics`。详细范围和阶段说明见 [项目计划](docs/IMPLEMENTATION_PLAN.md)。

## 多数据库端到端测试

隔离 Docker 环境会创建 `db_query_demo` 和 `reporting_demo` 两个数据库。它们使用同一个只读角色，但策略允许访问的表完全不同。

```bash
docker compose up -d
PGMCP_RUN_INTEGRATION=1 uv run pytest -m integration -q
```

测试会验证两个数据库的正常查询、跨库对象访问被拒绝，以及未知数据库被拒绝；固定 SQL 生成器让这些测试不依赖 OpenAI API Key。