Sanka MCP Server

Этот репозиторий содержит размещенный сервис Sanka MCP и TypeScript-клиент, который он использует для вызова внешне доступной поверхности API Sanka. Теперь он поддерживается как обычное рабочее пространство TypeScript, а не как репозиторий под управлением Stainless.

Продуктовый сервис представляет собой удаленную потоковую HTTP MCP-конечную точку:

• POST /mcp в качестве основной конечной точки

• POST /sse в качестве псевдонима совместимости для клиентов, которые все еще ожидают путь в стиле SSE

• POST / в качестве псевдонима совместимости

• GET /health для проверок работоспособности

Конечная точка /mcp предоставляет как общие инструменты SDK, так и инструменты CRM только для чтения из единой поверхности MCP.

Рабочие конечные точки:

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

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

Конечная точка для стейджинга:

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

Структура репозитория

• src/: TypeScript-клиент для внешне доступной поверхности API Sanka, используемый сервисом MCP

• src/internal/: внутренние вспомогательные средства среды выполнения SDK, не являющиеся закрытым кодом бэкенда Sanka

• packages/mcp-server/: приложение сервера MCP и точка входа Docker

• .github/workflows/: CI, а также рабочие процессы развертывания Fly для стейджинга и продакшена

• fly.toml: конфигурация приложения Fly для продакшена

• fly.staging.toml: конфигурация приложения Fly для стейджинга

• docs/openapi-maintenance.md: руководство по поддержанию актуальности покрытия API без Stainless

Related MCP server: Isolator MCP Server

Аутентификация

sanka-mcp не запускает собственный стек OAuth. Он использует Sanka OAuth напрямую:

• Сервер авторизации: https://app.sanka.com

• Страница авторизации: /oauth/authorize

• Конечная точка токена: /api/v1/oauth/token

• Конечная точка отзыва: /api/v1/oauth/revoke

Для размещенного или локального HTTP-транспорта клиенты MCP должны использовать нативный OAuth против сервера авторизации Sanka, указанного в метаданных защищенного ресурса. Сервер MCP принимает только токены носителя (bearer tokens) Sanka OAuth и проверяет их через:

• GET /api/v1/oauth/introspect

Тот же токен носителя затем пересылается в публичный API Sanka.

Клиенты с поддержкой нативного OAuth, такие как Codex и Claude, получают запрос MCP OAuth во время подключения или вызовов защищенных инструментов. Клиенты, которые не поддерживают нативный MCP OAuth, все еще могут использовать резервный вариант с защищенным инструментом, который возвращает URL-адрес Connect Sanka для открытия пользователем.

Токены API разработчика намеренно не поддерживаются для доступа через MCP. Они остаются действительными для прямого использования API и SDK Sanka вне MCP.

Локальная разработка

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 является необязательным. При наличии сервер объявляет этот client_id OAuth в метаданных своего сервера авторизации.

Локальные предварительные требования Sanka:

• app.localhost:8000 обслуживает /oauth/authorize и /api/v1/oauth/token

• api.localhost:8000 обслуживает /api/v1/public/*

• сначала создайте приложение/клиент OAuth в Sanka:

  • для первого лица: /manage/oauth

  • для третьих лиц: /:wsid/developers/oauth

• зарегистрируйте URI перенаправления/источник MCP на этом клиенте OAuth

Если вы хотите использовать stdio локально вместо HTTP-транспорта, нативный OAuth не является частью рукопожатия stdio. В этом случае передайте уже выданный токен доступа Sanka OAuth через SANKA_API_KEY в качестве удобства для локальной разработки.

Затем проверьте:

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

Для MCP-клиента с поддержкой нативного OAuth направьте клиент на http://127.0.0.1:8080/mcp без статических заголовков аутентификации и позвольте клиенту следовать метаданным защищенного ресурса к Sanka OAuth.

Для ручного тестирования токена носителя:

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

Развертывание

Этот репозиторий развертывается на Fly из packages/mcp-server/Dockerfile.

• Ручное развертывание в продакшен: fly deploy -c fly.toml

• Ручное развертывание в стейджинг: fly deploy -c fly.staging.toml

• Автоматическое развертывание в стейджинг: push в staging

• Автоматическое развертывание в продакшен: публикация релиза GitHub, нацеленного на main

Процесс выпуска

Используйте ту же схему продвижения, что и в основном приложении Sanka:

1. Откройте PR с функциями в staging.

2. Объедините staging после прохождения CI для развертывания sanka-mcp-staging.

3. Проверьте конечную точку MCP стейджинга.

4. Откройте staging -> main.

5. После того как main будет готов, запустите Create new Sanka MCP Tag and Release.

6. Опубликованный релиз развертывает продакшен.

Необходимые приложения и секреты Fly:

• Приложение для продакшена: sanka-mcp

• Приложение для стейджинга: sanka-mcp-staging

• Установите одни и те же секреты MCP_SERVER_* на обоих приложениях, если только стейджинг намеренно не использует другой стек аутентификации.

Направление поддержки

Этот репозиторий больше не зависит от доступа к проекту Stainless во время выполнения или для текущей разработки. Покрытие API должно поддерживаться непосредственно в этом репозитории.

Рекомендуемый следующий шаг — принять инструменты OpenAPI с открытым исходным кодом для обновлений TypeScript-клиента, вместо повторного внедрения зависимости от размещенного генератора. См. openapi-maintenance.md.

Репозиторий теперь включает стартовую команду typegen:

pnpm generate:openapi-types

По умолчанию она считывает сопутствующую спецификацию Sanka в ../sanka-sdks/openapi.json.