원격 설정 — yetdapay-mcp-gateway

핵심 요약

원격 Gateway는 판매자용 커머스 도구를 HTTP로 제공하며 기존 REST API에 요청을 전달합니다. 로컬 소스코드를 업로드하는 보호 도구가 아닙니다.

판매자 범위 작업에는 인증 토큰이 필요합니다. 배포 전에 전송 방식과 MCP 호환성 제한을 확인하세요.

게이트웨이(mcp/gateway/worker.js)는 Cloudflare Worker에서 YetdaPay MCP 계약을 Streamable HTTP로 노출합니다 — POST body당 JSON-RPC 2.0 요청 하나, plain application/json 응답. REST API 위의 얇은 어댑터로 자체 비즈니스 로직이 없고, stdio 서버의 계약에서 포팅됐습니다(동일한 도구, 리소스, 프롬프트, merge-before-PUT 의미, receipt, 오류 매핑).

• 프로토콜 버전: 2024-11-05
• serverInfo: yetdapay-mcp-gateway/0.1.0
• capabilities: tools, resources, prompts

라우트

라우트	동작
POST /mcp (및 POST /)	JSON-RPC 2.0 디스패치
GET /health	{"ok":true}
OPTIONS *	CORS preflight
/mcp 또는 /의 비-POST	405 JSON-RPC 오류
그 외	404

클라이언트 설정

{
  "mcpServers": {
    "yetdapay": {
      "url": "https://yetdapay-mcp-staging.<subdomain>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer <seller-token>"
      }
    }
  }
}

Authorization 헤더 자체가 셀러 자격 증명입니다 — 게이트웨이는 이를 업스트림 셀러 엔드포인트로 그대로 전달하고 절대 로깅 또는 저장하지 않습니다. 생략하면 셀러 범위 도구는 {code:"UNAUTHORIZED"}로 fail closed되고, 공개 도구는 없이도 동작합니다. 인증 참조.

설정 (wrangler.toml [vars])

변수	기본값	용도
YETDAPAY_API_BASE	http://127.0.0.1:8080/api/v1	업스트림 REST base URL
YETDAPAY_SITE_ORIGIN	http://127.0.0.1:3000	호스티드 링크 스니펫용 사이트 origin ({origin}/h/{public_id})
YETDAPAY_REQUEST_TIMEOUT_MS	10000	요청당 업스트림 타임아웃
YETDAPAY_CORS_ORIGINS	* (미설정)	쉼표 구분 허용 목록; 요청 Origin이 목록에 있으면 반영, 아니면 *

배포

cd mcp/gateway
npx wrangler deploy --config wrangler.toml

운영자 게이트

배포는 charter 게이트 작업입니다(스테이징 우선; 프로덕션은 명시적 승인 필요). 이 문서를 승인으로 간주하지 마세요.

업스트림 커버리지

모든 20개 도구가 be-cloudflare Worker 와 Axum be/ 백엔드 양쪽에서 동작합니다. d3 패리티 포트가 integration 표면을 be-cloudflare에 추가했으므로(/projects/:id/integration GET/PUT, /public/integrations/:pid, 공개 feedbacks/donations POST), 설정/검증 도구가 배포된 Worker에서 더 이상 막히지 않습니다 — 도구별 업스트림 맵은 도구 레퍼런스를 참조하세요.

리소스 및 프롬프트

• yetdapay://docs/{donation-guide, feedback-guide, sdk-contract, install-checklist, manifest-schema} — 임베드된 마크다운.
• 프롬프트 setup_donation_and_feedback({store_id?}) — 가이드 설치: analyze → inspect → donation + feedback 설정 → 에셋 가져오기 → install → validate → report.

알려진 제한 사항

• POST당 단일 JSON-RPC 요청; 배칭 없음, SSE 없음 — text/event-stream 응답이 필요한 클라이언트는 이 MVP에서 지원되지 않습니다.
• notifications/* 요청은 빈 body와 함께 202를 반환합니다.
• license_get에는 업스트림 단일 GET 라우트가 없습니다(양쪽 백엔드 모두 목록 전용 계약); 도구는 셀러 범위 목록을 가져와서 선택합니다 — 없는 id는 정직한 NOT_FOUND이지 절대 조작된 레코드가 아닙니다.