paxaver-mcp

Paxaver MCP 服务

面向 AI 的适配器，基于 Paxaver 学校社区平台。 在 Cloudflare Workers 上实现 Model Context Protocol（MCP），并采用 RS256 JWT 验证、能力优先授权和 Streamable HTTP 传输。

---

这是什么

Paxaver MCP 服务让 AI 助手（ChatGPT、Claude、Perplexity 以及任何兼容 MCP 的 客户端）能够代表 Paxaver 用户执行操作：查看午餐菜单、订购午餐、查看钱包余额和交易记录、报名参加 筹款活动、为学生注册学校项目、参与志愿服务；学校管理员还可以管理餐厅、菜单项、活动、签到、 志愿者班次、项目候补名单和每日订单。

它是一个轻量适配器。其中不包含业务逻辑，也不持有数据库、支付或电子邮件凭据。所有操作都以 已通过身份验证的用户身份调用 Paxaver 后端 API，并在错误传递给客户端之前进行脱敏处理。

---

连接

将兼容 MCP 的客户端指向托管端点，并在提示时使用 Paxaver 账户登录（OAuth 2.1 Authorization Code + PKCE）：

https://mcp.paxaver.com/mcp

服务通过 Streamable HTTP（POST /mcp）使用 MCP 协议 2025-06-18。 所有区域共用一个端点；用户登录时会根据其账户解析所在区域。

---

安装

npm install @paxaver/mcp

该软件包附带 Worker 源码，可用于自托管和开发。大多数用户只需使用上面的托管端点。

本地运行

pnpm install        # Node >= 26.8.2, pnpm >= 10
pnpm dev            # Miniflare on http://localhost:8787 — MCP endpoint: POST /mcp

Docker

docker build -t paxaver-mcp .
docker run -p 8787:8787 paxaver-mcp
# MCP endpoint: http://localhost:8787/mcp

自托管和本地实例不会检查令牌是否已撤销：已撤销的令牌在过期前仍然有效。 但仍会通过签名、过期时间和实时用户上下文加载来验证令牌。

完整的开发环境配置请参阅 CONTRIBUTING.md。

---

工具

服务端公开 37 个工具，分为六类。tools/list 中的可见工具会根据调用方的角色进行筛选；每次调用都会在分发前重新授权，后端还会再次检查数据级访问权限（纵深防御）。

类别	工具
用户 / 钱包	get_my_context、sign_out、get_my_wallet_balance、list_my_wallet_transactions
午餐订购	get_lunch_menu、list_my_lunch_orders、create_lunch_order_draft、update_lunch_order_draft、discard_lunch_order_draft、pay_lunch_order_draft、cancel_my_lunch_order
活动与志愿服务	list_school_events、get_school_event、register_for_event、list_my_event_registrations、cancel_my_event_registration、list_my_volunteer_signups、sign_up_for_volunteer_shift、cancel_my_volunteer_signup
活动管理	create_school_event、update_school_event、cancel_school_event、list_event_attendees、check_in_event_ticket、create_volunteer_shift
项目	list_school_programs、register_for_program、cancel_program_registration、list_program_registrations、admit_program_registration
餐厅 / 菜单管理	list_school_restaurants、create_school_restaurant、list_restaurant_menu_items、create_restaurant_menu_item、update_restaurant_menu_item、archive_restaurant_menu_item、schedule_lunch_menu_item

提示词

服务端注册了四个提示词：daily_lunch_menu、wallet_balance、 upcoming_events 和 lunch_order_helper（可选参数 student_name）。 prompts/list 和 prompts/get 会返回提示词的可用情况及内容。

订购流程为草稿 → 审核 → 付款：使用 create_lunch_order_draft 创建草稿， 使用 update_lunch_order_draft 进行调整，然后使用 pay_lunch_order_draft 付款。

sign_out 会结束调用方在此 MCP 连接中的登录状态：下一次请求会收到常规的登录质询。持有自身 Paxaver 凭据的应用无法通过此方式退出登录；返回结果会指引用户在该应用或 Paxaver 账户设置中断开与 Paxaver 的连接。

2.5 之前的工具名称仍会解析到对应的规范工具，但不再公开；已弃用的 order_lunch 工具已移除。金融类和破坏性工具会标注出来，并要求用户确认。

隐私

通过 MCP 工具返回的唯一联系信息是调用方自己的登录邮箱——get_my_context 会包含该邮箱，以便客户端回答“我当前使用的是哪个账号？”，sign_out 则会注明它要退出登录的账号。不会返回电话号码、地址或其他联系信息字段。学生数据仅限 ID、姓名和学校 slug；读取响应不会暴露过敏信息、备注、生日或其他个人身份信息。MCP 服务不会记录用户数据。

---

文档

文档	主题
CHANGELOG.md	发布历史
SECURITY.md	漏洞报告政策
CONTRIBUTING.md	开发环境搭建和贡献流程

内部文档（架构、身份验证、授权、完整的工具参考、部署、安全模型、测试场景）存放在私有的 Paxaver 单体仓库的 docs/paxaver-mcp/ 中，有意不对外发布。

---

技术栈

• 运行时： Cloudflare Workers
• 框架： Hono v4
• JWT： jose v6（通过 JWKS 使用 RS256）
• 协议： MCP 2025-06-18，Streamable HTTP
• 构建/部署： Wrangler v4
• 测试： Vitest v5（Workers pool + Node pool）

---

支持

• Bug 报告和功能请求： GitHub issues
• 安全报告：参阅 SECURITY.md

许可证

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