PlainQuery | MCP DB Agent

PlainQuery

用通俗英语提问数据库问题。 PlainQuery 将 PostgreSQL 数据库连接到 Claude、Cursor 或 VS Code，并用真实、结构化的数据作答，而不是猜测。

---

功能介绍

连接一次数据库后，即可从任何 MCP 客户端提出如下问题：

“我们 3 月发出了多少订单？” “去年消费最多的 5 位客户是谁？” “每月的平均订单金额是多少？”

PlainQuery 会检查数据库架构，使用大模型生成 SQL，验证其安全性，执行查询并返回结构化 JSON。如果查询失败，它会读取错误信息并自动重试。

为什么选择 PlainQuery

• 自然语言，真实答案——无需编写 SQL；结果来自你的实际数据，而非幻觉。
• 只读且安全设计——每条查询在执行前都会经过检查：禁止写操作（INSERT/UPDATE/DELETE/DDL），扫描并移除危险函数和模式，并自动添加 LIMIT。
• 自动纠错——生成的查询报错时，Agent 会将错误信息反馈给大模型并重试（次数上限可配置）。
• 了解数据库架构——自动检查并缓存数据库架构，让问题对应到正确的表和列。
• 兼容任何 MCP 客户端——Claude Desktop、Cursor、VS Code Copilot，或任何支持 MCP 的客户端。
• 安全的多租户托管——数据库 URL 和大模型密钥在静态存储时使用 Fernet 加密；用户提供的连接字符串会受到 SSRF 防护；每个请求都限定在对应租户范围内。
• 托管或自托管——使用托管服务，或通过 Docker 自行运行整个技术栈。
• 自带大模型——支持 Anthropic Claude 或 Groq。

工作原理

Your question
   → Schema introspection      (reads tables/columns, cached)
   → SQL generation            (schema + question → LLM → SQL)
   → Safety validation         (blocks writes, scans dangerous patterns, injects LIMIT)
   → Execution                 (runs read-only, with a timeout)
   → Self-correction retry     (on error: feed it back to the LLM, fix, re-run)
   → Structured JSON result

架构

---

快速开始

选项 1 — 使用托管服务（无需安装）

1. 在 https://plainquery.in 注册并验证邮箱。
2. 连接 PostgreSQL 数据库并创建 API 密钥。
3. 将服务添加到 MCP 客户端（参见连接 MCP 客户端）。

就这么简单——现在就可以开始提问。

选项 2 — 自行运行

请参阅下文的自托管和本地开发。

连接 MCP 客户端

PlainQuery 已发布到官方 MCP Registry，名称为 io.github.Jarvis-27/mcp-db-agent，因此支持注册表的客户端可以直接发现它。

如需手动配置客户端，请将其指向 MCP 端点并提供 API 密钥：

{
  "mcpServers": {
    "plainquery": {
      "url": "https://plainquery.in/mcp",
      "headers": { "X-API-Key": "mdbk_your_key_here" }
    }
  }
}

后端还可以为 VS Code、Cursor 和通用 HTTP 客户端生成可直接粘贴的配置——调用 POST /api/v1/account/setup-payloads（参见配置载荷）。根据 MCP_AUTH_MODE 的设置，MCP 客户端可以使用 OAuth 2.1 持有者令牌或 API 密钥进行身份验证。

---

自托管和本地开发

前置条件

• Python 3.12+
• uv
• 前端所需的 Node.js 20+ 和 pnpm
• 至少一个大模型 API 密钥（ANTHROPIC_API_KEY 或 GROQ_API_KEY）

后端

uv sync
cp .env.example .env

编辑 .env，至少包含：

• CREDENTIAL_ENCRYPTION_KEYS
• REGISTRATION_OPEN=true
• 一个 LLM 提供商密钥，以及 LLM_PROVIDER

运行后端：

uv run uvicorn src.app:app --reload --host 0.0.0.0 --port 8000

后端挂载了以下端点：

• REST API：http://localhost:8000/api
• MCP 端点：http://localhost:8000/mcp

前端

cd frontend
pnpm install
pnpm dev

打开 http://localhost:3000，注册并完成设置，然后在账户设置中关联 OAuth 身份，接着连接 MCP 客户端：http://localhost:8000/mcp。客户端会自动完成 OAuth 流程；也可以在 api_key_only / hybrid 模式下使用 API 密钥。

运行时模型

• 后端 API：位于 src.app:app 的 FastAPI/Starlette
• 前端：frontend/ 中的 Next.js 应用
• 身份验证：无密码电子邮件验证和登录链接
• MCP 身份验证：OAuth 2.1 bearer 令牌（oauth_only）、API 密钥（api_key_only）或两者兼用（hybrid）——通过 MCP_AUTH_MODE 设置
• 设置载荷：POST /api/v1/account/setup-payloads
• 计费：Stripe Checkout、Customer Portal，以及通过 Webhook 确认的 Free/Pro 权限

产品采用单账户、用户级作用域模型： signup → verify email → connect database → link OAuth identity → use /mcp → upgrade with Stripe

安全性

• 用户提供的数据库 URL 会在尝试连接前经过验证，以防范 SSRF、路径遍历、私有 IP 和 DNS 重绑定。
• 数据库 URL 和 LLM 密钥在静态存储时使用 Fernet 加密，并支持密钥轮换。
• 生成的 SQL 在执行前会经过验证：单语句检查、禁用函数扫描、危险模式扫描、写入/DDL 阻止、表存在性检查，以及自动注入 LIMIT。
• 按请求限定上下文范围，防止跨租户数据泄漏。
• 按用户设置的速率限制和备用 LLM 配额可限制成本滥用。

重要环境变量

变量	说明
AUTH_DATABASE_URL	托管产品使用的身份验证/账户数据库
CREDENTIAL_ENCRYPTION_KEYS	加密存储的数据库 URL 和其他机密信息
REGISTRATION_OPEN	启用或禁用公开注册
ANTHROPIC_API_KEY / GROQ_API_KEY	用于生成 SQL 的 LLM 凭据
LLM_PROVIDER	当前使用的提供商名称
APP_BASE_URL	设置载荷中使用的基础 URL
FRONTEND_BASE_URL	电子邮件链接中使用的基础 URL
STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET	Stripe API 和 Webhook 凭据
STRIPE_PRO_PRICE_ID	对应 Pro 计划的 Stripe Price ID
STRIPE_CHECKOUT_SUCCESS_URL / STRIPE_CHECKOUT_CANCEL_URL	可选的 Checkout 重定向覆盖值
STRIPE_CUSTOMER_PORTAL_RETURN_URL	可选的 Customer Portal 返回 URL 覆盖值

当前完整变量列表请参阅 .env.example。

API 概览

身份验证

• POST /api/v1/auth/signup
• GET /api/v1/auth/verify-email
• POST /api/v1/auth/request-login-link
• GET /api/v1/auth/exchange-login-link
• POST /api/v1/auth/logout

账户（通过会话进行身份验证）

所有账户路由均使用会话令牌进行身份验证（x-session-token: <session-token> 或 Authorization: Bearer <session-token>）：

• GET /api/v1/account
• GET /api/v1/account/status
• PUT /api/v1/account/database
• GET /api/v1/account/api-keys
• POST /api/v1/account/api-keys
• DELETE /api/v1/account/api-keys/{id}
• POST /api/v1/account/api-keys/{id}/rotate
• POST /api/v1/account/setup-payloads
• GET /api/v1/account/dashboard
• GET /api/v1/account/usage/recent

计费

• GET /api/v1/account/billing
• POST /api/v1/account/billing/checkout-session
• POST /api/v1/account/billing/portal-session
• POST /api/v1/billing/webhook

Stripe webhook 是方案变更的事实来源。结账或订阅激活会将用户切换为 plan_code=pro；已取消、未付款或逾期状态会限制付费权益，但不会删除数据库配置。

OAuth MCP 账户关联（会话认证）

• GET /api/v1/account/mcp-oauth/status
• POST /api/v1/account/mcp-oauth/start
• GET /api/v1/account/mcp-oauth/callback
• DELETE /api/v1/account/mcp-oauth/link

MCP

• POST /mcp
• 认证：OAuth 2.1 bearer 令牌、API 密钥，或两者兼用——由 MCP_AUTH_MODE 控制

配置载荷

POST /api/v1/account/setup-payloads 会返回适用于 VS Code、Cursor、通用 HTTP MCP 客户端以及当前 ChatGPT 占位项的客户端配置材料。

curl -X POST http://localhost:8000/api/v1/account/setup-payloads \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"raw_api_key":"mdbk_..."}'

创建后，后端绝不会存储原始 API 密钥。只有在请求中明确发送原始密钥时，它才会嵌入配置载荷。

测试

uv run pytest tests/ -m "not integration"
uv run pytest tests/ -m integration
uv run ruff check .
uv run mypy src --ignore-missing-imports

部署冒烟测试

每次托管部署后，请验证公共 MCP OAuth 发现端点：

uv run python scripts/smoke_mcp_deployment.py \
  --mcp-url https://mcp.example.com/mcp \
  --issuer-url https://YOUR_DOMAIN.auth0.com/

冒烟测试会检查未经认证的 /mcp 挑战、受保护资源元数据、ChatGPT/Claude well-known 发现路由以及颁发者元数据。若要同时验证经过认证的 MCP initialize、tools/list 和 resources/list，请使用 --access-token 或 MCP_SMOKE_ACCESS_TOKEN 传入已关联用户的访问令牌。

Docker

运行托管 HTTP 堆栈：

docker compose up --build

容器镜像仅提供托管 HTTP 运行时。MCP 端点仍为 http://localhost:8000/mcp。

许可证

MIT © 2026 PlainQuery