Exact Match Site ID MCP 连接器

此服务将 Exact Match Site ID 数据暴露给兼容 MCP 的 AI 客户端，例如 ChatGPT、Claude、Cursor 以及其他可以调用 MCP 服务器的工具。

技术栈

• TypeScript

• 用于 HTTP 路由的 Hono

• 用于处理 MCP 协议的官方 MCP SDK

• 用于输入验证的 Zod

• 作为事实来源的 Laravel data

本地设置

1. 将 .env.example 复制为 .env。

2. 将 LARAVEL_API_BASE_URL 设置为 Laravel API 的基础 URL。

3. 将 LARAVEL_MCP_PROXY_TOKEN 设置为与 Laravel 中 services.mcp_proxy.internal_token 配置的值相同。

4. 将 OAUTH_TOKEN_SECRET 设置为至少 32 个随机字符。

5. 使用 npm install 安装依赖。

6. 使用 npm run dev 启动本地开发。

默认的本地服务 URL 为 http://localhost:8787。

有用链接

• 健康检查: GET /health

• MCP 端点: POST /mcp

• OAuth 授权元数据: GET /.well-known/oauth-authorization-server

• MCP 元数据: GET /.well-known/mcp-server

• 小部件: GET /widgets/site-id

开发环境身份验证

当 MCP_DEV_AUTH_ENABLED=true 时，可以通过调用以下内容创建本地授权码：

GET /oauth/dev/start?clerk_user_id=user_xxx

生产环境应将此开发环境的移交方式替换为真实的 Exact Match/Clerk 登录回调。

本地 OAuth 测试流程

在将服务器连接到 ChatGPT 应用之前，请使用此流程在本地测试 OAuth。

1. 确保 .env 包含本地重定向允许列表：

OAUTH_ALLOWED_REDIRECT_URIS=http://localhost:8787/oauth/dev/callback
MCP_DEV_AUTH_ENABLED=true

2. 启动 MCP 服务器：

npm run dev

3. 使用真实的 Clerk 用户 ID 打开开发授权 URL：

http://localhost:8787/oauth/dev/start?clerk_user_id=user_xxx

浏览器将重定向至：

http://localhost:8787/oauth/dev/callback?code=...&state=...

4. 从回调响应中复制 code 值。

5. 使用该代码交换 MCP 访问令牌：

$code = "paste-code-here"

Invoke-RestMethod `
  -Method Post `
  -Uri "http://localhost:8787/oauth/token" `
  -ContentType "application/x-www-form-urlencoded" `
  -Body @{
    grant_type = "authorization_code"
    client_id = "local-dev"
    redirect_uri = "http://localhost:8787/oauth/dev/callback"
    code = $code
  }

成功响应：

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "site_id:read"
}

将 access_token 用作：

Authorization: Bearer <access_token>

此令牌用于验证 AI 应用对 MCP 服务器的请求。MCP 服务器仍会使用 LARAVEL_MCP_PROXY_TOKEN 单独向 Laravel 进行身份验证。