Paxaver MCP 서버

Paxaver 학교 커뮤니티 플랫폼을 위한 AI 지향 어댑터. RS256 JWT 검증, 기능 우선(capability-first) 권한 부여, Streamable HTTP 전송을 갖춘 Cloudflare Workers에서 Model Context Protocol(MCP)을 구현합니다.

이게 무엇인가

Paxaver MCP 서버는 AI 어시스턴트(ChatGPT, Claude, Perplexity 및 모든 MCP 호환 클라이언트)가 Paxaver 사용자를 대신하여 작업을 수행할 수 있게 합니다: 점심 메뉴 확인, 점심 주문, 지갑 충전, 기금 모금 이벤트 등록, 학교 기부, 자원봉사, 그리고 학교 관리자의 경우 레스토랑, 메뉴 항목, 이벤트 및 일일 주문 관리.

이는 얇은 어댑터입니다. 비즈니스 로직을 포함하지 않으며 데이터베이스, Stripe 또는 이메일에 직접 접근하지 않습니다. 모든 작업은 Cloudflare 서비스 바인딩(동일 리전, 공용 네트워크 홉 없음)을 통해 비공개 Paxaver 백엔드 API에 위임됩니다. MCP 서버의 유일한 책임은 다음과 같습니다:

• MCP 프로토콜 처리(JSON-RPC 2.0, Streamable HTTP)

• 중앙 집중식 Paxaver 인증 워커의 JWKS를 통한 RS256 JWT 검증

• 도구별 기능 정책 및 역할 게이팅

• 정화된 사용자 안전 오류 매핑

인증은 OAuth 2.0 / OIDC 권한 부여 서버 역할을 하는 Paxaver 인증 워커(auth.paxaver.com)에서 처리됩니다. MCP 서버는 결과로 생성된 RS256 JWT를 검증하고 백엔드로 전달합니다. MCP 서버 자체는 권한 부여 서버가 아닙니다.

Related MCP server: IIITH Mess MCP

아키텍처

┌───────────────┐     MCP (Streamable HTTP)      ┌──────────────────────┐
│   AI Client   │ ─────────────────────────────▶ │   Paxaver MCP Worker │
│ ChatGPT/Claude│ ◀───────────────────────────── │  (this repo)         │
│  /Perplexity  │     RS256 JWT + JSON-RPC 2.0   │  Hono + jose         │
└───────────────┘                                └──────────┬───────────┘
                                                            │
                                          Cloudflare service binding
                                          (PAXAVER_API, same region)
                                                            │
                                                            ▼
                                                 ┌──────────────────────┐
                                                 │  Paxaver API Worker  │
                                                 │  (private backend)   │
                                                 │  D1 · Stripe · SES   │
                                                 └──────────────────────┘

MCP 워커는 D1, Stripe 또는 SES에 절대 바인딩하지 않습니다. 서비스 바인딩은 수명이 짧은 JWT(120초 TTL, 대상 paxaver-internal)를 전달하며, 백엔드는 이를 내부 호출로 신뢰하면서도 인증된 Paxaver 사용자에게 작업을 귀속시킵니다. 전체 내용은 docs/architecture.md를 참조하세요.

빠른 시작

설치

npm install @paxaver/mcp

로컬 개발

# 1. Install dependencies (Node >= 22)
npm install

# 2. Configure local secrets
cp .dev.vars.example .dev.vars   # then fill in JWT_SECRET, OAUTH_STATE_SECRET, ...

# 3. Run the worker locally (Miniflare)
npm run dev

# 4. Typecheck, lint, and test
npm run typecheck
npm run lint
npm test

로컬 개발 서버는 http://localhost:8787에서 시작됩니다. 검색 엔드포인트는 /.well-known/ 아래에 있으며, MCP 엔드포인트는 POST /mcp입니다.

참고: PAXAVER_API 서비스 바인딩이 없는 로컬 개발은 API_BASE_URL(기본값 http://localhost:8787)에 대한 인증된 HTTPS로 대체됩니다. 전체 통합 테스트를 위해 Paxaver 백엔드 워커를 로컬에서 실행하고 API_BASE_URL을 해당 주소로 지정하세요.

배포

두 개의 환경, 각각 고유한 사용자 정의 도메인을 가진 별도의 Worker:

프로덕션 워커는 단일 엔드포인트(mcp.paxaver.com)를 통해 CA 및 US 사용자 모두에게 서비스를 제공합니다. 사용자 리전은 JWT tenant_id 클레임에서 확인되며, 워커는 서비스 바인딩(PAXAVER_API_CA, PAXAVER_API_US)을 통해 올바른 리전 백엔드로 라우팅합니다. 통화는 MCP 엔드포인트가 아닌 사용자의 학교에 따라 결정됩니다.

npm run deploy:staging   # wrangler deploy --env staging
npm run deploy:prod      # wrangler deploy --env production

시크릿은 wrangler secret put --env production으로 설정해야 합니다: JWT_SECRET, OAUTH_STATE_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, CHATGPT_VERIFY_TOKEN. docs/deployment.md를 참조하세요.

도구

서버는 6개 범주로 그룹화된 31개의 도구를 제공합니다. tools/list에서의 가시성은 호출자의 역할에 따라 필터링되며, 모든 호출은 디스패치 전에 다시 권한이 부여되고 백엔드는 데이터 수준 접근을 다시 확인합니다(심층 방어).

금전 및 파괴적 도구는 라벨이 지정되며 사용자 확인이 필요합니다. 전체 참조: docs/tools.md. 권한 부여 정책: docs/authorization.md.

문서

기술 스택

• 런타임: Cloudflare Workers (compatibility_date: 2026-08-01, nodejs_compat)

• 프레임워크: Hono v4

• JWT: jose v6 (JWKS를 통한 RS256)

• 프로토콜: MCP 2025-06-18, Streamable HTTP

• 인증: 중앙 집중식 인증 워커(auth.paxaver.com)를 통한 RS256 JWT 검증

• 빌드/배포: Wrangler v4

• 테스트: Vitest v2 (Workers 풀 + Node 풀)

라이선스

Apache-2.0. Copyright (c) 2026 Smartoire. LICENSE를 참조하세요.