{
  "markdown": "# Paxaver MCP Server\n\n> AI-facing adapter over the [Paxaver](https://paxaver.com) school community platform.\n> Implements the Model Context Protocol (MCP) on Cloudflare Workers with RS256 JWT\n> validation, capability-first authorization, and Streamable HTTP transport.\n\n[![npm version](https://img.shields.io/npm/v/@paxaver/mcp.svg)](https://www.npmjs.com/package/@paxaver/mcp)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)\n[![MCP Badge](https://lobehub.com/badge/mcp/paxaver)](https://lobehub.com/mcp/paxaver)\n\n---\n\n## What this is\n\nThe Paxaver MCP server lets AI assistants (ChatGPT, Claude, Perplexity, and any\nMCP-compatible client) act on behalf of a Paxaver user: check a lunch menu, order\nlunch, register for fundraising events, volunteer, and — for school administrators\n— manage restaurants, menu items,\nevents, and daily orders.\n\nIt is a **thin adapter**. It contains no business logic and never touches the\ndatabase, Stripe, or email directly. Every action is delegated to the private\nPaxaver backend API over a Cloudflare **service binding** (same region, no public\nnetwork hop). The MCP server's only responsibilities are:\n\n- MCP protocol handling (JSON-RPC 2.0, Streamable HTTP)\n- RS256 JWT validation via JWKS from the centralized Paxaver auth worker\n- Per-tool capability policy and role gating\n- Sanitized, user-safe error mapping\n\nAuthentication is handled by the Paxaver auth worker (`auth.paxaver.com`), which\nserves as the OAuth 2.0 / OIDC authorization server. The MCP server validates\nthe resulting RS256 JWTs and forwards them to the backend. The MCP server itself\nis not an authorization server.\n\n---\n\n## Architecture\n\n```text\n┌───────────────┐     MCP (Streamable HTTP)      ┌──────────────────────┐\n│   AI Client   │ ─────────────────────────────▶ │   Paxaver MCP Worker │\n│ ChatGPT/Claude│ ◀───────────────────────────── │  (this repo)         │\n│  /Perplexity  │     RS256 JWT + JSON-RPC 2.0   │  Hono + jose         │\n└───────────────┘                                └──────────┬───────────┘\n                                                            │\n                                          Cloudflare service binding\n                                          (PAXAVER_API, same region)\n                                                            │\n                                                            ▼\n                                                 ┌──────────────────────┐\n                                                 │  Paxaver API Worker  │\n                                                 │  (private backend)   │\n                                                 │  D1 · Stripe · SES   │\n                                                 └──────────────────────┘\n```\n\nThe MCP worker **never** binds D1, Stripe, or SES. The service binding carries a\nshort-lived JWT (120s TTL, audience `paxaver-internal`) that the backend trusts as\nan internal call while still attributing the action to the authenticated Paxaver\nuser. See [`docs/architecture.md`](./docs/architecture.md) for the full picture.\n\n---\n\n## Quick start\n\n### Install\n\n```bash\nnpm install @paxaver/mcp\n```\n\n### Develop locally\n\n```bash\n# 1. Install dependencies (Node >= 22)\nnpm install\n\n# 2. Configure local secrets\ncp .dev.vars.example .dev.vars   # then fill in OAUTH_STATE_SECRET, ...\n\n# 3. Run the worker locally (Miniflare)\nnpm run dev\n\n# 4. Typecheck, lint, and test\nnpm run typecheck\nnpm run lint\nnpm test\n```\n\nThe local dev server starts on `http://localhost:8787`. Discovery endpoints live\nunder `/.well-known/`; the MCP endpoint is `POST /mcp`.\n\n> **Note:** Local development without the `PAXAVER_API` service binding falls back\n> to authenticated HTTPS against `API_BASE_URL` (default `http://localhost:8787`).\n> For full integration testing, run the Paxaver backend worker locally and point\n> `API_BASE_URL` at it.\n\n---\n\n## Deployment\n\nTwo environments, each a separate Worker with its own custom domain:\n\n| Environment  | Worker name           | Domain            |\n| ------------ | --------------------- | ----------------- |\n| `staging`    | `paxaver-mcp-staging` | `mcp.paxaver.dev` |\n| `production` | `paxaver-mcp`         | `mcp.paxaver.com` |\n\nThe production worker serves both CA and US users through a single endpoint\n(`mcp.paxaver.com`). User region is resolved from the JWT `tenant_id` claim,\nand the worker routes to the correct regional backend via service bindings\n(`PAXAVER_API_CA`, `PAXAVER_API_US`). Currency is determined by the user's\nschool, not by the MCP endpoint.\n\n```bash\nnpm run deploy:staging   # wrangler deploy --env staging\nnpm run deploy:prod      # wrangler deploy --env production\n```\n\nSecrets must be set with `wrangler secret put --env production`:\n`OAUTH_STATE_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`,\n`CHATGPT_VERIFY_TOKEN`. See [`docs/deployment.md`](./docs/deployment.md).\n\n---\n\n## Tools\n\nThe server exposes 26 tools grouped into six categories. Visibility in\n`tools/list` is filtered by the caller's roles; every call is re-authorized\nbefore dispatch, and the backend re-checks data-level access (defense-in-depth).\n\n| Category           | Tools                                                                                                                                                                  |\n| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| User / account     | `get_user_info`                                                                                                                                                        |\n| Wallet             | `get_wallet_balance`, `get_wallet_status`                                                                                                                              |\n| Orders & menu      | `order_lunch`, `get_orders`, `get_daily_menu`, `get_daily_orders`, `get_monthly_orders`, `create_draft_order`, `finalize_order`, `cancel_order`                        |\n| Events             | `get_upcoming_events`, `create_event`, `update_event`, `cancel_event`, `register_event`, `sign_up_to_volunteer`                                                        |\n| Admin / restaurant | `list_school_restaurants`, `create_restaurant`, `list_menu_items`, `create_menu_item`, `update_menu_item`, `set_menu_item_price`, `delete_menu_item`, `set_daily_menu` |\n\nFinancial and destructive tools are labeled and require user confirmation. Full\nreference: [`docs/tools.md`](./docs/tools.md). Authorization policy:\n[`docs/authorization.md`](./docs/authorization.md).\n\n### Privacy\n\nNo personal contact information (email, phone, address) is collected or\nreturned through MCP tools. The `get_user_info` tool returns only the user's\nname, school, students, and roles. Student data is limited to IDs, names, and\nschool slugs. Allergies, notes, birthday, and other PII are not exposed in\nread responses. The MCP server does not log user data.\n\n---\n\n## Documentation\n\n| Document                                           | Topic                                                             |\n| -------------------------------------------------- | ----------------------------------------------------------------- |\n| [docs/architecture.md](./docs/architecture.md)     | System architecture, service binding boundary, regional isolation |\n| [docs/authentication.md](./docs/authentication.md) | JWT validation, JWKS, auth worker delegation, token format        |\n| [docs/authorization.md](./docs/authorization.md)   | Capability policy table, role gating, defense-in-depth            |\n| [docs/tools.md](./docs/tools.md)                   | Full tool reference with input schemas and classifications        |\n| [docs/deployment.md](./docs/deployment.md)         | Wrangler config, environments, secrets, custom domains            |\n| [docs/security.md](./docs/security.md)             | Security model, CORS, CSRF, error sanitization, headers           |\n| [docs/compatibility.md](./docs/compatibility.md)   | MCP protocol version, transports, supported AI clients            |\n| [docs/migration.md](./docs/migration.md)           | Migration from the legacy `mcp-server/` in the private monorepo   |\n| [CHANGELOG.md](./CHANGELOG.md)                     | Release history                                                   |\n| [SECURITY.md](./SECURITY.md)                       | Vulnerability reporting policy                                    |\n| [CONTRIBUTING.md](./CONTRIBUTING.md)               | Development setup and contribution process                        |\n\n---\n\n## Tech stack\n\n- **Runtime:** Cloudflare Workers (`compatibility_date: 2026-08-01`, `nodejs_compat`)\n- **Framework:** [Hono](https://hono.dev) v4\n- **JWT:** [jose](https://github.com/panva/jose) v6 (RS256 via JWKS)\n- **Protocol:** MCP `2025-06-18`, Streamable HTTP\n- **Auth:** RS256 JWT validation via centralized auth worker (`auth.paxaver.com`)\n- **Build/deploy:** [Wrangler](https://developers.cloudflare.com/workers/wrangler/) v4\n- **Test:** [Vitest](https://vitest.dev) v2 (Workers pool + Node pool)\n\n---\n\n## License\n\nApache-2.0. Copyright (c) 2026 Smartoire. See [`LICENSE`](./LICENSE).\n",
  "bytes": 9282,
  "sha": "74e817f99a1d71f642e25c2d5cee0f156289dd857cf13216093042cefacdf8f4",
  "repo_slug": "smartoire/paxaver-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_smartoire_paxaver_mcp_633194c9/readme"
}