Conector MCP de Exact Match Site ID

Este servicio expone los datos de Exact Match Site ID a clientes de IA compatibles con MCP, como ChatGPT, Claude, Cursor y otras herramientas que pueden llamar a servidores MCP.

Stack

• TypeScript

• Hono para rutas HTTP

• SDK oficial de MCP para el manejo del protocolo MCP

• Zod para la validación de entradas

• Laravel data como fuente de verdad

Configuración local

1. Copia .env.example a .env.

2. Establece LARAVEL_API_BASE_URL a la URL base de la API de Laravel.

3. Establece LARAVEL_MCP_PROXY_TOKEN al mismo valor configurado en Laravel para services.mcp_proxy.internal_token.

4. Establece OAUTH_TOKEN_SECRET con al menos 32 caracteres aleatorios.

5. Instala las dependencias con npm install.

6. Inicia el desarrollo local con npm run dev.

La URL del servicio local predeterminado es http://localhost:8787.

URLs útiles

• Salud: GET /health

• Endpoint MCP: POST /mcp

• Metadatos de autorización OAuth: GET /.well-known/oauth-authorization-server

• Metadatos MCP: GET /.well-known/mcp-server

• Widget: GET /widgets/site-id

Autenticación de desarrollo

Cuando MCP_DEV_AUTH_ENABLED=true, se puede crear un código de autenticación local llamando a:

GET /oauth/dev/start?clerk_user_id=user_xxx

En producción se debe reemplazar este traspaso de desarrollo con la devolución de llamada (callback) real de inicio de sesión de Exact Match/Clerk.

Flujo de prueba de OAuth local

Utiliza este flujo para probar OAuth localmente antes de conectar el servidor a las aplicaciones de ChatGPT.

1. Asegúrate de que .env contenga una lista blanca de redirección local:

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

2. Inicia el servidor MCP:

npm run dev

3. Abre la URL de autorización de desarrollo con un ID de usuario real de Clerk:

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

El navegador redirige a:

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

4. Copia el valor code de la respuesta de la devolución de llamada.

5. Intercambia el código por un token de acceso 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
  }

Respuesta exitosa:

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

Usa access_token como:

Authorization: Bearer <access_token>

Este token autentica las solicitudes de la aplicación de IA en el servidor MCP. El servidor MCP sigue autenticándose en Laravel por separado con LARAVEL_MCP_PROXY_TOKEN.