Servidor MCP de Sanka

Este repositorio contiene el servicio MCP de Sanka alojado y el cliente de TypeScript que utiliza para llamar a la superficie de la API de Sanka invocable externamente. Ahora se mantiene como un espacio de trabajo de TypeScript normal, no como un repositorio gestionado por Stainless.

El servicio de producción es un endpoint MCP HTTP Streamable remoto:

• POST /mcp como endpoint principal

• POST /sse como alias de compatibilidad para clientes que aún esperan una ruta de estilo SSE

• POST / como alias de compatibilidad

• GET /health para comprobaciones de estado

El endpoint /mcp expone tanto las herramientas generales del SDK como las herramientas de CRM de solo lectura desde una única superficie MCP.

Endpoints en vivo:

• https://mcp.sanka.com/mcp

• https://mcp.sanka.com/sse

Endpoint de staging:

• https://sanka-mcp-staging.fly.dev/mcp

Estructura del repositorio

• src/: Cliente de TypeScript para la superficie de la API de Sanka invocable externamente, utilizado por el servicio MCP

• src/internal/: ayudantes de tiempo de ejecución del SDK privados del paquete, no código de backend privado de Sanka

• packages/mcp-server/: la aplicación del servidor MCP y el punto de entrada de Docker

• .github/workflows/: CI más flujos de trabajo de despliegue en Fly para staging y producción

• fly.toml: configuración de la aplicación Fly de producción

• fly.staging.toml: configuración de la aplicación Fly de staging

• docs/openapi-maintenance.md: guía para mantener la cobertura de la API actualizada sin Stainless

Related MCP server: Isolator MCP Server

Autenticación

sanka-mcp no ejecuta su propia pila OAuth. Utiliza OAuth de Sanka directamente:

• Servidor de autorización: https://app.sanka.com

• Página de autorización: /oauth/authorize

• Endpoint de token: /api/v1/oauth/token

• Endpoint de revocación: /api/v1/oauth/revoke

Para el transporte HTTP alojado o local, los clientes MCP deben usar OAuth nativo contra el servidor de autorización de Sanka expuesto en los metadatos del recurso protegido. El servidor MCP solo acepta tokens de portador (bearer tokens) de OAuth de Sanka y los valida a través de:

• GET /api/v1/oauth/introspect

El mismo token de portador se reenvía luego a la API pública de Sanka.

Los clientes con capacidad OAuth nativa, como Codex y Claude, reciben un desafío OAuth de MCP durante la conexión o las llamadas a herramientas protegidas. Los clientes que no admiten OAuth de MCP nativo aún pueden usar el respaldo de herramienta protegida, que devuelve una URL de Connect Sanka para que el usuario la abra.

Los tokens de API de desarrollador no son compatibles intencionalmente para el acceso MCP. Siguen siendo válidos para el uso directo de la API y el SDK de Sanka fuera de MCP.

Desarrollo local

pnpm install
pnpm build
export MCP_SERVER_AUTHORIZATION_SERVER_URL="http://app.localhost:8000"
export MCP_SERVER_OAUTH_CLIENT_ID="your-public-oauth-client-id"
export SANKA_BASE_URL="http://api.localhost:8000"
node packages/mcp-server/dist/index.js --transport=http --port=8080

MCP_SERVER_OAUTH_CLIENT_ID es opcional. Cuando está presente, el servidor anuncia ese client_id de OAuth en los metadatos de su servidor de autorización.

Prerrequisitos locales de Sanka:

• app.localhost:8000 sirve /oauth/authorize y /api/v1/oauth/token

• api.localhost:8000 sirve /api/v1/public/*

• cree la aplicación/cliente OAuth en Sanka primero:

  • primera parte: /manage/oauth

  • tercera parte: /:wsid/developers/oauth

• registre el URI/origen de redirección de MCP en ese cliente OAuth

Si desea utilizar stdio localmente en lugar del transporte HTTP, OAuth nativo no es parte del protocolo de enlace stdio. En ese caso, pase un token de acceso OAuth de Sanka ya emitido a través de SANKA_API_KEY como una conveniencia de desarrollo local.

Luego verifique:

curl http://127.0.0.1:8080/health
curl -sS -D - http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

Para un cliente MCP con capacidad OAuth nativa, apunte el cliente a http://127.0.0.1:8080/mcp sin encabezados de autenticación estáticos y deje que el cliente siga los metadatos del recurso protegido hacia OAuth de Sanka.

Para pruebas manuales de token de portador:

curl -sS -D - http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'authorization: Bearer soat_your_access_token' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

Despliegue

Este repositorio se despliega en Fly desde packages/mcp-server/Dockerfile.

• Despliegue manual de producción: fly deploy -c fly.toml

• Despliegue manual de staging: fly deploy -c fly.staging.toml

• Despliegue automático de staging: push a staging

• Despliegue automático de producción: publicar un release de GitHub que apunte a main

Flujo de lanzamiento

Utilice la misma forma de promoción que la aplicación principal de Sanka:

1. Abra PRs de características en staging.

2. Fusionar staging después de que pase la CI para desplegar sanka-mcp-staging.

3. Valide el endpoint MCP de staging.

4. Abra staging -> main.

5. Después de que main esté listo, ejecute Create new Sanka MCP Tag and Release.

6. El lanzamiento publicado despliega la producción.

Aplicaciones y secretos de Fly requeridos:

• Aplicación de producción: sanka-mcp

• Aplicación de staging: sanka-mcp-staging

• Establezca los mismos secretos MCP_SERVER_* en ambas aplicaciones a menos que staging utilice intencionalmente una pila de autenticación diferente.

Dirección de mantenimiento

Este repositorio ya no depende del acceso al proyecto Stainless en tiempo de ejecución ni para el desarrollo continuo. La cobertura de la API debe mantenerse directamente en este repositorio.

El siguiente paso recomendado es adoptar herramientas OpenAPI de código abierto para las actualizaciones del cliente de TypeScript, en lugar de reintroducir una dependencia de generador alojado. Consulte openapi-maintenance.md.

El repositorio ahora incluye un comando de generación de tipos inicial:

pnpm generate:openapi-types

Por defecto, lee la especificación de Sanka hermana en ../sanka-sdks/openapi.json.