Sanka

Sanka es la empresa de extensiones. Integra IA en tu ciclo de ventas — negocios, cotizaciones, facturación y más de 100 integraciones con CRM/comercio — directamente desde Claude o Codex.

GitHub

Documentación

Servidor MCP de Sanka

Este repositorio contiene el servicio MCP de Sanka alojado y el cliente TypeScript que utiliza para llamar a la superficie de API invocable externamente de Sanka. Ahora se mantiene como un espacio de trabajo 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 salud

El endpoint /mcp expone tanto las herramientas generales del SDK como las herramientas 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 TypeScript para la superficie de API invocable externamente de Sanka, utilizado por el servicio MCP
  • src/internal/: ayudantes de runtime del SDK privados del paquete, no código 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 de 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: orientación para mantener la cobertura de API actualizada sin Stainless

Autenticación

Los clientes HTTP alojados se autentican a través de Connect Sanka. El servidor MCP emite un id de sesión vinculado a recursos, devuelve una URL https://app.sanka.com/oauth/mcp/connect firmada desde connect_sanka o un resultado de herramienta protegido, e intercambia la sesión aprobada internamente por un token de acceso de Sanka de corta duración a través de POST /oauth/internal/mcp-session-token.

El OAuth nativo de MCP está deshabilitado intencionalmente hasta que Sanka V2 implemente el servidor completo de código de autorización. El servicio MCP no publica metadatos de servidor de autorización OAuth ni de recursos protegidos, y rechaza los encabezados Authorization y X-Sanka-API-Key proporcionados por el cliente. El secreto de intercambio de tokens se usa solo entre sanka-mcp y sanka-api; nunca debe enviarse a clientes MCP.

Las lecturas del espacio de trabajo y las llamadas exitosas a switch_workspace actualizan la identidad de espacio de trabajo resuelta que se mantiene para la sesión MCP. El enriquecimiento de URL de registros utiliza por lo tanto el código de espacio de trabajo seleccionado inmediatamente después de un cambio en lugar de retener el código capturado durante la conexión inicial. Las llamadas de vista previa/inicio de flujos de trabajo también releen la sesión MCP actual inmediatamente antes de publicar, vinculan la solicitud a ese espacio de trabajo y fallan de forma cerrada si la API resuelve un espacio de trabajo diferente. Esto mantiene las pruebas de contabilidad y las escrituras de flujos de trabajo en el mismo inquilino que muestra current_workspace.

Todos los clientes alojados, incluidos Codex y Claude, usan el mismo flujo de URL de Connect Sanka. Las solicitudes no autenticadas de inicialización y de listado de herramientas permanecen disponibles para que el cliente pueda cargar connect_sanka y el respaldo de herramientas protegidas.

Los tokens de API para desarrolladores 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_INTERNAL_AUTHORIZATION_SERVER_URL="http://api.localhost:8000"
export MCP_SERVER_TOKEN_EXCHANGE_SHARED_SECRET="local-shared-secret"
export SANKA_BASE_URL="http://api.localhost:8000"
node packages/mcp-server/dist/index.js --transport=http --port=8080

Requisitos locales de Sanka:

  • app.localhost:8000 sirve /oauth/mcp/connect
  • api.localhost:8000 sirve /api/v2/public/*
  • api.localhost:8000 sirve /oauth/internal/mcp-session-token
  • el servidor MCP y la API usan el mismo secreto local de intercambio de tokens

Stdio sigue siendo un transporte de desarrollo local. SANKA_API_KEY allí es configuración de proceso, no un modo de portador proporcionado por el cliente; los clientes alojados deben usar Connect Sanka.

Luego verifica:

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"}}}'

Apunta los clientes HTTP MCP a http://127.0.0.1:8080/mcp sin encabezados de autenticación estáticos. Llama a connect_sanka o a una herramienta protegida, abre la URL de Connect Sanka devuelta y reintenta con el id de sesión MCP emitido por el servidor.

Worker de Browser Use

La herramienta MCP browser_use envía flujos de trabajo de navegador en lista blanca a un worker separado. El servidor MCP mantiene la autenticación de sesión, los metadatos de auditoría, el enrutamiento de flujos de trabajo y las puertas de confirmación; el worker posee el estado del navegador y la interacción con la interfaz de terceros. El primer flujo de trabajo registrado es:

  • demo.hubspot.company_avatar: actualizar los avatares de la empresa de demostración de HubSpot a través de la interfaz de HubSpot cuando las API de CRM no pueden establecer el avatar visible.

Ejecuta un worker local con agent-browser:

npm install -g agent-browser
agent-browser install

export SANKA_BROWSER_USE_WORKER_TOKEN="local-worker-token"
export SANKA_BROWSER_USE_PROFILE_ROOT=".browser-use-profiles"
export SANKA_BROWSER_USE_ARTIFACT_DIR=".browser-use-artifacts"
pnpm --dir packages/mcp-server browser-use-worker

Apunta el servidor MCP a él:

export SANKA_BROWSER_USE_WORKER_URL="http://127.0.0.1:8787/run"
export SANKA_BROWSER_USE_WORKER_TOKEN="local-worker-token"

Para producción, despliega el worker como un servicio separado, por ejemplo en Fly, con un volumen persistente montado en SANKA_BROWSER_USE_PROFILE_ROOT para que las cookies de inicio de sesión de HubSpot sobrevivan a los reinicios. Mantén el worker privado o protegido por token y expón solo /run al servicio MCP.

Consulta docs/browser-use-worker-fly.md para el runbook de la aplicación worker de Fly, volumen persistente, configuración de secretos y siembra de perfiles.

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 una release de GitHub que apunte a main

Flujo de releases

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

  1. Abre PRs de características en staging.
  2. Fusiona staging después de que CI pase para desplegar sanka-mcp-staging.
  3. Valida el endpoint MCP de staging.
  4. Abre staging -> main.
  5. Después de que main esté listo, ejecuta Create new Sanka MCP Tag and Release.
  6. La release publicada despliega producción.

Aplicaciones y secretos de Fly requeridos:

  • Aplicación de producción: sanka-mcp
  • Aplicación de staging: sanka-mcp-staging
  • Establece los mismos secretos MCP_SERVER_* en ambas aplicaciones a menos que staging use intencionalmente una pila de autenticación diferente.

Política de reintentos

El cliente TypeScript reintenta 408, 409, 429, 5xx y errores de conexión dos veces por defecto. Solo las herramientas con metadata.operation: 'read' mantienen esos reintentos automáticos. Cada herramienta de escritura llama a la API una vez y devuelve cualquier error al agente: una escritura puede fallar después de que su efecto secundario haya ocurrido, como un correo que Gmail aceptó antes de que Sanka lo registrara, y un reintento lo repetiría. La API también marca errores de rutas de entrega con x-should-retry: false. Las herramientas de respuesta informan DELIVERY_UNKNOWN como un error de no reenviar.

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 API debe mantenerse directamente en este repositorio.

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

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

pnpm generate:openapi-types

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

Developer Cloud (candidato a release)

Las herramientas alojadas exponen los mismos contratos V2 de fuente, ejecución, recibo, certificado y Fleet que la CLI y los SDK. Este cambio de fuente no habilita la ejecución en producción. Lee get_developer_cloud_availability primero y obedece la bandera de disponibilidad de cada capacidad. La migración local gratuita y el registro de evidencia del cliente no cambian.

Cada llamada toma un workspace_id fijado. Las creaciones de pago y los reintentos selectivos requieren una solicitud explícita, un límite aprobado, confirm: true y un idempotency_key estable. La autorización de usuario existente es suficiente. Una respuesta perdida no debe crear una nueva intención: lee de nuevo o reproduce la clave y la solicitud idénticas. Ninguna herramienta compra créditos, crea PRs de repositorio, fusiona o despliega.

  • Fuente/ejecución: upload_developer_cloud_source, create_developer_cloud_run, list_developer_cloud_runs, get_developer_cloud_run, cancel_developer_cloud_run.
  • Evidencia: list_developer_cloud_events, get_developer_cloud_receipt, list_developer_cloud_artifacts, download_developer_cloud_artifact.
  • Certificados: list_developer_cloud_certificate_keys, get_developer_cloud_certificate, revoke_developer_cloud_certificate.
  • Fleet: create_developer_cloud_fleet, list_developer_cloud_fleets, get_developer_cloud_fleet, cancel_developer_cloud_fleet, retry_developer_cloud_fleet.

La reparación y la emisión de certificados usan create_developer_cloud_run.request.repair y .certification, respectivamente. El cómputo es de 100 créditos por minuto de worker, redondeado una vez por ejecución. La reparación exitosa agrega 1,000 créditos; la emisión independiente de certificados agrega 2,000. Todo el cómputo y las primas permanecen dentro del límite aprobado. Las puertas fallidas no tienen prima. Fleet no agrega recargo: su límite es la suma de los límites hijos explícitos, reservados atómicamente, con un máximo de cinco workers activos por espacio de trabajo. El reintento selecciona solo los hijos fallidos después de que el Fleet original se asiente; crea un nuevo Fleet y conserva los recibos de los hijos completados.

Sube el digest ZIP exacto y la revisión completa declarada; el servicio fija los bytes subidos pero no prueba de forma independiente su procedencia de Git. Inspecciona el alcance del certificado, los escenarios, las limitaciones y la revocación. Descargar un certificado no verifica su firma: usa la verificación offline de la CLI con la clave publicada. Las descargas de artefactos verifican los bytes contra los metadatos SHA-256 registrados. MCP admite hasta 64 MiB; los artefactos más grandes usan la CLI/API. Las descargas grandes usan la URL vinculada a sesión existente o el flujo read_binary_download_chunk.

La regeneración del esquema de solicitud usa la entrada compartida del SDK V2:

python3 scripts/sync-developer-cloud-contract.py ../sanka-sdks/openapi.json
pnpm exec prettier --write packages/mcp-server/src/generated/developer-cloud-schemas.ts

Espacio de trabajo integrado

La aplicación de Sanka abre el espacio de trabajo Flow completo conectado: su barra lateral, paneles, tablas de registros, flujos de trabajo e informes. El acceso completo al espacio de trabajo requiere autorización explícita de Sanka. Las conexiones con acceso más restringido muestran los controles de autorización; la pantalla anterior del piloto del asistente de facturas ya no se ofrece.

Las herramientas MCP de facturas alojadas permanecen disponibles bajo sus alcances existentes y requisitos de confirmación. Eliminar la pantalla del piloto no cambia los registros de facturas ni el contrato de API.