WoWSQL

WoWSQL MCP（模型上下文协议）

WoWSQL API 上采用 wowsql 风格的 HTTP MCP，使用 OAuth 2.0 授权码 + PKCE。

软件包

软件包	说明
packages/mcp-server-wowsql	@wowsql/mcp-server-wowsql — HTTP MCP 服务，适用于 AI SDK 的 createToolSchemas()

快速开始（可自托管 MCP 进程）

在仓库根目录运行：

cd mcp
npm install
npm run build
npm start

身份验证（OAuth 2.0 + MCP）

MCP 进程是一个受 OAuth 保护的资源（不是授权服务器）：

1. 除非设置了 MCP_ALLOW_UNAUTHENTICATED=true（仅限开发环境），否则 POST /mcp 需要 Authorization: Bearer <access_token>。
2. 缺失或无效的令牌会返回 401，并附带 WWW-Authenticate: Bearer ... resource_metadata="<url>"，以便 MCP 客户端（Cursor 等）启动 OAuth。
3. 令牌验证会调用你的 API：使用相同的 Bearer 令牌请求 GET {WOWSQL_API_BASE}/api/v1/auth/me（必须与 WoWSQL OAuth 或登录签发的 JWT 匹配）。
4. 发现
   • 授权服务器元数据（WoWSQL API）：GET {WOWSQL_API_BASE}/.well-known/oauth-authorization-server
   • 受保护资源元数据（此 MCP 主机）：GET /.well-known/oauth-protected-resource/mcp

Cursor / Electron： OAuth 元数据会经过重写，使 authorization_endpoint、token_endpoint 和 registration_endpoint 指向此 MCP 主机（例如 http://localhost:8787/...）。MCP 进程会将这些请求代理到 WOWSQL_API_BASE，因此 IDE 无需直接成功 fetch localhost:8000 即可完成 OAuth（否则通常会出现 fetch failed）。你仍需在 WOWSQL_API_BASE 上运行 FastAPI，以便代理能够访问它。

如果未设置 MCP_PUBLIC_URL，PRM 和 401 响应中的 resource_metadata 会根据每个请求的 Host（以及 X-Forwarded-Proto）生成，因此 http://localhost:8787/mcp 和 http://127.0.0.1:8787/mcp 各自会获得匹配的元数据。如果 MCP 位于反向代理之后，或生产环境需要唯一固定的源，请设置 MCP_PUBLIC_URL。

变量	默认值	用途
WOWSQL_API_BASE	https://api.wowsql.com	WoWSQL FastAPI 基础 URL（末尾不带斜杠）。
WOWSQL_OAUTH_ISSUER_URL	与 WOWSQL_API_BASE 相同	PRM（authorization_servers）中公布的 issuer。
MCP_PUBLIC_URL	未设置	若设置，则为 OAuth PRM + WWW-Authenticate 指定固定的公共源（不含 /mcp 路径）；优先于基于 Host 的生成方式。
MCP_ALLOW_UNAUTHENTICATED	未设置	若为 true，则跳过 Bearer 检查（不安全；仅用于本地测试）。
PORT / MCP_PORT	8787	MCP HTTP 端口。
MCP_HOST	0.0.0.0	绑定地址。

选项 A — .env / .env.local（推荐）
将 packages/mcp-server-wowsql/.env.example 复制到该文件夹中的 .env 或 .env.local。CLI 会依次加载 .env、.env.local（覆盖前者），然后加载进程 cwd 中的 .env。使用 .env.local 保存机器专属的值（例如 http://localhost:8000），避免将它们提交到版本库。

cd mcp/packages/mcp-server-wowsql
cp .env.example .env
# edit .env — set WOWSQL_API_BASE to your API
npm run build   # from mcp root: npm run build -w @wowsql/mcp-server-wowsql
npm start

选项 B — Shell（不使用文件）

PowerShell：

cd mcp
$env:WOWSQL_API_BASE="http://localhost:8005"
$env:PORT="8787"
npm start

bash / zsh：

cd mcp
export WOWSQL_API_BASE=http://localhost:8005
export PORT=8787
npm start

端点

• MCP（可流式 HTTP）： POST http://localhost:8787/mcp — JSON-RPC 请求体；可追加查询参数以限定范围。MCP 客户端（Cursor 等）会使用此端点。
• MCP（浏览器）： GET http://localhost:8787/mcp 会返回 401，并显示简短的“未授权”页面（不提供公共元数据）。协议使用带 Authorization: Bearer 的 POST JSON-RPC 请求。
• 健康检查： GET http://localhost:8787/health

客户端使用的范围限定 URL 示例：

http://localhost:8787/mcp?project_ref=<uuid-or-slug>&read_only=true&features=database,docs

OAuth（API）

• 元数据：GET https://api.wowsql.com/.well-known/oauth-authorization-server
• 授权（重定向到控制面板）：GET /api/v1/auth/oauth/mcp/authorize
• 批准（已登录用户）：POST /api/v1/auth/oauth/mcp/approve
• 令牌：POST /api/v1/auth/oauth/mcp/token（grant_type=authorization_code 或 refresh_token）

控制面板授权界面：应用中的 /mcp/oauth（参见 dashboard/app/mcp/oauth/page.tsx）。

部署 mcp.wowsql.com

1. 在 TLS 后运行此 Node 服务（可使用反向代理或任意平台）。
2. 将 WOWSQL_API_BASE / WOWSQL_OAUTH_ISSUER_URL 设置为 https://api.wowsql.com（而不是 127.0.0.1:8000/8001）。蓝绿切换会更改后端主机端口；公共主机名始终通过 NPM 指向活动槽位。
3. 设置 MCP_PUBLIC_URL=https://mcp.wowsql.com。
4. 将 DNS mcp.wowsql.com 指向该服务；健康检查：GET /health。
5. 确保 CORS 和 OAuth redirect_uri 值包含 MCP 客户端回调地址（参见 oauth_clients 种子数据和环境变量）。

EC2 蓝绿部署：./deploy/ec2-blue-green.sh mcp 会自动设置这些环境变量。

npm 发布

cd mcp/packages/mcp-server-wowsql
npm version patch
npm publish --access public

需要 npm 组织作用域 @wowsql（或更改 package.json 中的 name）。