Paxaver MCP Server

面向 AI 的适配器，用于 Paxaver 学校社区平台。 在 Cloudflare Workers 上实现模型上下文协议 (MCP)，支持 RS256 JWT 验证、能力优先授权和 Streamable HTTP 传输。

这是什么

Paxaver MCP 服务器让 AI 助手（ChatGPT、Claude、Perplexity 以及任何兼容 MCP 的客户端）能够代表 Paxaver 用户执行操作：查看午餐菜单、订购午餐、充值钱包、注册筹款活动、向学校捐款、志愿服务，以及——对于学校管理员——管理餐厅、菜单项、活动和每日订单。

它是一个薄适配器。它不包含任何业务逻辑，也从不直接接触数据库、Stripe 或电子邮件。每个操作都通过 Cloudflare 服务绑定（同区域，无公共网络跳转）委托给私有 Paxaver 后端 API。MCP 服务器的唯一职责是：

• MCP 协议处理（JSON-RPC 2.0、Streamable HTTP）

• 通过集中式 Paxaver 认证 worker 的 JWKS 进行 RS256 JWT 验证

• 每个工具的能力策略和角色门控

• 经过清理的、用户安全的错误映射

认证由 Paxaver 认证 worker（auth.paxaver.com）处理，该 worker 充当 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 worker 从不绑定 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 后端 worker，并将 API_BASE_URL 指向它。

部署

两个环境，每个环境都是一个独立的 Worker，具有自己的自定义域名：

生产 worker 通过单个端点（mcp.paxaver.com）同时服务 CA 和 US 用户。用户区域从 JWT 的 tenant_id 声明中解析，worker 通过服务绑定（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（通过 JWKS 的 RS256）

• 协议： MCP 2025-06-18、Streamable HTTP

• 认证： 通过集中式认证 worker（auth.paxaver.com）进行 RS256 JWT 验证

• 构建/部署： Wrangler v4

• 测试： Vitest v2（Workers 池 + Node 池）

许可证

Apache-2.0。版权所有 (c) 2026 Smartoire。请参阅 LICENSE。