askDB MCP

一个 MCP 服务器，将自然语言数据问题转换为 LLM 编写 SQL 所需的 表结构上下文。它不连接你的数据库，也不自行生成 SQL——它从你的 Pinecone 索引中检索正确的表定义，并将其交给正在提问的模型（Claude Code、Claude Desktop、ChatGPT、Cursor）。

user question
   │
   ▼
Claude Code / ChatGPT ──calls──► askDB MCP ──semantic search──► Pinecone (ask-db)
   │                                  │
   │      relevant DDL + guardrails ◄─┘
   ▼
generated SQL

工具

每个响应都内嵌指令，告诉模型仅使用返回的表和列，因此它不会编造名称。

设置

npm install
npm run setup             # creates .env from the template
#                          → then put your PINECONE_API_KEY in .env
npm run doctor            # verify connection, field mapping and retrieval quality

要分享给其他人？把 SETUP.md 发给他们——它涵盖了本地运行和连接到托管实例两种方式。

npm run doctor 是关键步骤。它会打印索引配置、你的记录实际使用的元数据字段，以及一次示例搜索——这样你可以在将服务器接入客户端之前，确认它读取了正确的字段。

npm run doctor       # connectivity + retrieval sanity check
npm run smoke        # drive the stdio server with a real MCP client
npm run smoke:http   # same over Streamable HTTP, with bearer auth

连接客户端

Claude Code

CLI、桌面应用和 IDE 扩展共享同一个配置，因此这会将服务器注册到所有三种环境中：

# from the repo root — records an absolute path, so it works in any folder
claude mcp add askdb --scope user -- node "$PWD\src\server.js"

用 claude mcp list 检查（askdb: ... ✓ Connected），然后重启桌面应用或 IDE 窗口——MCP 服务器在启动时加载。

使用用户级作用域是刻意为之：目的是在你其他仓库中工作时提出数据库问题。项目级 .mcp.json 只在从本仓库根目录启动 Claude Code 时才会被解析，而在两个作用域中都定义 askdb 会让 Claude Code 警告重复。

Claude Desktop / Cursor

添加到 claude_desktop_config.json（或 Cursor 的 MCP 设置）：

{
  "mcpServers": {
    "askdb": {
      "command": "node",
      "args": ["D:\\working-directory\\AI\\askDB-mcp\\src\\server.js"]
    }
  }
}

凭据来自服务器旁边的 .env，因此客户端配置中不会出现任何密钥。

ChatGPT

ChatGPT 连接器无法生成本地进程——它们只支持 基于 HTTP 的远程 MCP。运行 HTTP 传输并将其暴露：

# set MCP_AUTH_TOKEN first: this endpoint serves your whole schema
MCP_AUTH_TOKEN=some-long-random-string npm run start:http

然后将连接器指向 https://<your-host>/mcp，并带有 Authorization: Bearer <token> 标头。若要快速试用，可以通过隧道暴露（cloudflared tunnel --url http://localhost:3000）；若要长期使用，请妥善托管——DEPLOY.md 完整介绍了 Netlify 部署。GET /health 无需身份验证，供负载均衡器检查；只要设置了 MCP_AUTH_TOKEN，/mcp 就要求携带 Bearer 令牌。

HTTP 传输是无状态的——每个请求一个服务器实例——因此它可以在负载均衡器后面扩展，无需粘性会话。

托管

部署为两个 Netlify Functions——netlify.toml 包含构建设置，因此导入仓库并设置 PINECONE_API_KEY + MCP_AUTH_TOKEN 就是全部工作。逐步说明：DEPLOY.md。

这无需重写传输即可工作，因为 MCP SDK 的 WebStandardStreamableHTTPServerTransport 接收 Request 并返回 Response——正是 Netlify Functions v2 的签名——因此 netlify/functions/mcp.mjs 原样导入了 src/mcp.js。同一个文件也可以部署到 Cloudflare Workers、Deno 或 Bun；src/http.js 适用于容器和虚拟机。

GET /health 不需要令牌，只报告所需环境变量是否已就位（仅存在性，绝不返回值）——这是无服务器环境下读取启动日志的替代方案。/mcp 默认拒绝访问：在未设置 MCP_AUTH_TOKEN 时返回 503，而不是将你的表结构暴露到互联网上。

一旦部署完成，团队成员无需安装任何东西——只需 URL 和令牌（SETUP.md，路线 A）。

配置

除 API 密钥外都是可选的。参见 .env.example。

服务器会自动检测你的记录使用了哪些元数据字段，以及索引是否集成了嵌入功能，因此默认值通常无需修改即可使用。

两件值得了解的事

嵌入模型必须匹配。 如果 EMBED_MODEL 不是上传表结构时所用的模型，所有分数都会骤降到接近零，结果也会变成噪声——这些向量彼此之间实际上是随机的。npm run doctor 会显示为不相关的表以约 0.01 的分数返回，而不是 0.8。此索引是使用 multilingual-e5-large 构建的。

如果你的索引包含多个环境，请设置 DEFAULT_DATABASE。 当同一套表结构同时以 *_live 和 *_test 存在时，不加作用域限定的搜索会返回每张表的两个副本，浪费一半 top_k 槽位在重复项上，并让模型在一次查询中混淆不同环境。

布局