Sanka MCP 서버

이 저장소는 호스팅된 Sanka MCP 서비스와 Sanka의 외부 호출 가능 API 표면을 호출하는 데 사용되는 TypeScript 클라이언트를 포함합니다. 이제 Stainless 관리 저장소가 아닌 일반적인 TypeScript 워크스페이스로 유지 관리됩니다.

프로덕션 서비스는 원격 Streamable HTTP MCP 엔드포인트입니다:

• POST /mcp: 기본 엔드포인트

• POST /sse: SSE 스타일 경로를 여전히 기대하는 클라이언트를 위한 호환성 별칭

• POST /: 호환성 별칭

• GET /health: 상태 확인용

/mcp 엔드포인트는 단일 MCP 표면에서 일반 SDK 도구와 읽기 전용 CRM 도구를 모두 노출합니다.

라이브 엔드포인트:

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

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

스테이징 엔드포인트:

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

저장소 레이아웃

• src/: MCP 서비스에서 사용하는 Sanka의 외부 호출 가능 API 표면용 TypeScript 클라이언트

• src/internal/: 패키지 비공개 SDK 런타임 도우미 (Sanka 비공개 백엔드 코드가 아님)

• packages/mcp-server/: MCP 서버 애플리케이션 및 Docker 진입점

• .github/workflows/: CI 및 스테이징/프로덕션 Fly 배포 워크플로우

• fly.toml: 프로덕션 Fly 앱 구성

• fly.staging.toml: 스테이징 Fly 앱 구성

• docs/openapi-maintenance.md: Stainless 없이 API 커버리지를 최신 상태로 유지하기 위한 지침

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 클라이언트는 보호된 리소스 메타데이터에 노출된 Sanka 인증 서버에 대해 네이티브 OAuth를 사용해야 합니다. MCP 서버는 Sanka OAuth 베어러 토큰만 허용하며 다음을 통해 유효성을 검사합니다:

• GET /api/v1/oauth/introspect

동일한 베어러 토큰이 Sanka 공개 API로 전달됩니다.

Codex 및 Claude와 같은 네이티브 OAuth 지원 클라이언트는 연결 또는 보호된 도구 호출 중에 MCP OAuth 챌린지를 받습니다. 네이티브 MCP OAuth를 지원하지 않는 클라이언트는 사용자가 열 수 있는 Connect Sanka URL을 반환하는 보호된 도구 대체 방식을 계속 사용할 수 있습니다.

개발자 API 토큰은 MCP 액세스에 대해 의도적으로 지원되지 않습니다. 이는 MCP 외부의 직접적인 Sanka API 및 SDK 사용에 대해서는 유효하게 유지됩니다.

로컬 개발

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는 선택 사항입니다. 존재할 경우, 서버는 해당 OAuth client_id를 인증 서버 메타데이터에 광고합니다.

로컬 Sanka 필수 구성 요소:

• app.localhost:8000은 /oauth/authorize 및 /api/v1/oauth/token을 제공합니다.

• api.localhost:8000은 /api/v1/public/*을 제공합니다.

• 먼저 Sanka에서 OAuth 앱/클라이언트를 생성합니다:

  • 퍼스트 파티: /manage/oauth

  • 서드 파티: /:wsid/developers/oauth

• 해당 OAuth 클라이언트에 MCP 리디렉션 URI/오리진을 등록합니다.

HTTP 전송 대신 로컬에서 stdio를 사용하려는 경우, 네이티브 OAuth는 stdio 핸드셰이크의 일부가 아닙니다. 이 경우 로컬 개발 편의를 위해 SANKA_API_KEY를 통해 이미 발급된 Sanka OAuth 액세스 토큰을 전달하십시오.

그런 다음 확인:

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

네이티브 OAuth 지원 MCP 클라이언트의 경우, 정적 인증 헤더 없이 클라이언트를 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"}}}'

배포

이 저장소는 packages/mcp-server/Dockerfile에서 Fly로 배포됩니다.

• 수동 프로덕션 배포: fly deploy -c fly.toml

• 수동 스테이징 배포: fly deploy -c fly.staging.toml

• 자동 스테이징 배포: staging으로 푸시

• 자동 프로덕션 배포: main을 대상으로 하는 GitHub 릴리스 게시

릴리스 흐름

메인 Sanka 앱과 동일한 프로모션 형태를 사용합니다:

1. staging으로 기능 PR을 엽니다.

2. CI 통과 후 staging을 병합하여 sanka-mcp-staging을 배포합니다.

3. 스테이징 MCP 엔드포인트를 검증합니다.

4. staging -> main PR을 엽니다.

5. main이 준비되면 Create new Sanka MCP Tag and Release를 실행합니다.

6. 게시된 릴리스가 프로덕션을 배포합니다.

필수 Fly 앱 및 보안 비밀:

• 프로덕션 앱: sanka-mcp

• 스테이징 앱: sanka-mcp-staging

• 스테이징이 의도적으로 다른 인증 스택을 사용하지 않는 한 두 앱 모두에 동일한 MCP_SERVER_* 보안 비밀을 설정하십시오.

유지 관리 방향

이 저장소는 더 이상 런타임이나 지속적인 개발을 위해 Stainless 프로젝트 액세스에 의존하지 않습니다. API 커버리지는 이 저장소에서 직접 유지 관리되어야 합니다.

권장되는 다음 단계는 호스팅된 생성기 종속성을 다시 도입하는 대신 TypeScript 클라이언트 업데이트를 위해 오픈 소스 OpenAPI 도구를 채택하는 것입니다. openapi-maintenance.md를 참조하십시오.

저장소에는 이제 시작용 typegen 명령이 포함되어 있습니다:

pnpm generate:openapi-types

기본적으로 ../sanka-sdks/openapi.json에 있는 형제 Sanka 사양을 읽습니다.