Paxaver MCP Server

ИИ-ориентированный адаптер для школьной платформы сообщества Paxaver. Реализует Model Context Protocol (MCP) на Cloudflare Workers с проверкой RS256 JWT, авторизацией на основе возможностей и транспортом Streamable HTTP.

Что это такое

Сервер Paxaver MCP позволяет ИИ-ассистентам (ChatGPT, Claude, Perplexity и любому MCP-совместимому клиенту) действовать от имени пользователя Paxaver: просматривать меню обеда, заказывать обед, пополнять кошелёк, регистрироваться на благотворительные мероприятия, жертвовать школе, участвовать в волонтёрстве и — для администраторов школ — управлять ресторанами, пунктами меню, событиями и ежедневными заказами.

Это тонкий адаптер. Он не содержит бизнес-логики и никогда напрямую не обращается к базе данных, Stripe или электронной почте. Каждое действие делегируется частному внутреннему API Paxaver через сервисную привязку Cloudflare (тот же регион, без перехода через публичную сеть). Единственные обязанности MCP-сервера:

• Обработка протокола MCP (JSON-RPC 2.0, Streamable HTTP)

• Проверка RS256 JWT через JWKS из централизованного auth-воркера Paxaver

• Политика возможностей и ограничение по ролям для каждого инструмента

• Санитизированное, безопасное для пользователя сопоставление ошибок

Аутентификация обрабатывается auth-воркером Paxaver (auth.paxaver.com), который служит сервером авторизации OAuth 2.0 / OIDC. 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 (TTL 120 секунд, аудитория 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

Локальный dev-сервер запускается на http://localhost:8787. Эндпоинты обнаружения находятся в /.well-known/; MCP-эндпоинт — POST /mcp.

Примечание: Локальная разработка без сервисной привязки PAXAVER_API использует аутентифицированный HTTPS к API_BASE_URL (по умолчанию http://localhost:8787). Для полного интеграционного тестирования запустите бэкенд-воркер Paxaver локально и укажите API_BASE_URL на него.

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

Две среды, каждая — отдельный Worker со своим собственным доменом:

Продакшн-воркер обслуживает пользователей из CA и US через единый эндпоинт (mcp.paxaver.com). Регион пользователя определяется из утверждения tenant_id в JWT, и воркер маршрутизирует запросы в правильный региональный бэкенд через сервисные привязки (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.

Инструменты

Сервер предоставляет 31 инструмент, сгруппированных в шесть категорий. Видимость в tools/list фильтруется по ролям вызывающего; каждый вызов повторно авторизуется перед отправкой, а бэкенд дополнительно проверяет доступ на уровне данных (защита в глубину).

Финансовые и деструктивные инструменты помечены и требуют подтверждения пользователя. Полная справка: docs/tools.md. Политика авторизации: docs/authorization.md.

Документация

Технологический стек

• Среда выполнения: Cloudflare Workers (compatibility_date: 2026-08-01, nodejs_compat)

• Фреймворк: Hono v4

• JWT: jose v6 (RS256 через JWKS)

• Протокол: MCP 2025-06-18, Streamable HTTP

• Аутентификация: проверка RS256 JWT через централизованный auth-воркер (auth.paxaver.com)

• Сборка/развёртывание: Wrangler v4

• Тестирование: Vitest v2 (пул Workers + пул Node)

Лицензия

Apache-2.0. Авторские права (c) 2026 Smartoire. См. LICENSE.