pickuppatrol-mcp

pickuppatrol-mcp

适用于 PickUp Patrol 的 MCP 服务——这款应用用于管理学生离校。查看和更改孩子离校的安排：每周默认计划、特定日期的一次性更改，以及学校的离校选项和截止时间。

由 AI（Claude Code）开发并维护。请自行斟酌使用。

对接的服务

app.pickuppatrol.net 通过 Ionic/Vue SPA 提供 ServiceStack JSON API。该 API 未公开发布，但可通过普通 HTTPS 请求从服务端访问——无需浏览器扩展、无需应对机器人拦截，也无需验证码。服务使用你自己的电子邮件和密码登录，并将生成的会话保存在内存中。

每种请求格式都记录在 docs/PICKUPPATROL-API.md 中；这些格式是从已发布的客户端读取而来，并非猜测，并且已针对真实账户进行测试——包括读取、一次写入及其还原。

安装

// .mcp.json
{
  "mcpServers": {
    "pickuppatrol": {
      "command": "npx",
      "args": ["-y", "@chrischall/pickuppatrol-mcp"],
      "env": {
        "PICKUPPATROL_USERNAME": "[email protected]",
        "PICKUPPATROL_PASSWORD": "…"
      }
    }
  }
}

进行本地开发时，将 .env.example 复制为 .env 并填写内容。

服务无需凭据即可启动——它会响应主机安装时的探测请求，并且仅在首次调用工具时报告配置错误。

工具

读取

工具	提供的信息
pup_get_session	已登录的账户及与该账户关联的学生
pup_list_students	所有学生及其每周默认安排和审核标记
pup_get_student	某位学生的完整信息
pup_get_default_plans	某位学生每周的默认计划，按日期列出
pup_list_plans	某个日期范围内按日期列出的计划
pup_get_plan	某位学生在某个日期的计划——包括该计划是否已锁定
pup_list_transportations	学校的离校选项及每个选项所附带的规则
pup_get_school	学校资料、通知时间、截止时间和设置
pup_list_non_school_days	无法设置计划的日期，以及已更改计划的日期
pup_list_car_numbers	学校分配给该账户的车辆编号
pup_healthcheck	凭据可以登录且 API 有响应；失败时，error.kind 会指出出错的环节（edge_blocked、credential_rejected、……）

读取内容仅包含已知字段。账户中的任何监护人都可以填写计划备注，学校工作人员也可以填写选项提示和学校设置，因此，所有包含这些内容的读取结果都会标记为 untrusted_content，并附上说明，提醒模型将文本视为数据而非指令。pup_list_plans、pup_get_plan、pup_get_school 和 pup_get_student 可使用 raw: true 获取未经修改的 API 记录（仍会标记为不可信）——这是查看 SASId 或 SafetyFlag 等字段的唯一方式。

写入——每次写入都需要先确认。支持显示确认提示的客户端（Claude Code）会显示确认提示，除非 MCP_CONFIRM_ELICITATION=off。否则，首次调用不会进行任何更改，而是返回即将发送的确切负载预览以及 confirmToken；只有使用该令牌再次调用才会执行更改——请参阅确认。

工具	更改内容
pup_set_plan	一个或多个特定日期的离校安排，或清除这些安排并恢复为默认计划
pup_set_default_plans	每周默认计划，或清除所有默认计划
pup_mark_defaults_reviewed	学校显示的“默认计划需要审核”提示

确认

变量	默认值
MCP_CONFIRM_MODE	ask-user	在无法显示确认提示词的客户端（claude.ai、Claude Desktop）上，写入操作会如何处理。ask-user：分两步——第一次调用不执行任何操作，而是返回预览和令牌；模型必须先在聊天中获得你的批准，再携带令牌再次调用。auto：同样分两步，但模型自行检查预览后即可使用令牌。refuse：此类客户端上的写入操作会被拒绝。能够显示提示词的客户端（Claude Code）始终会显示实际提示词，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示永不显示确认提示词，因此所有客户端都会走 MCP_CONFIRM_MODE 指定的流程。对于声称支持提示词却从不显示提示词的客户端，请设置此项（写入操作会一直挂起——opencode 2.0.x）。任何其他值都会保持 on，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；只有在令牌必须跨服务重启保留时才设置。在 mcp-host 上，主机会为每个子进程提供稳定的密钥（MCP_HOST_CONFIRM_SECRET），并将已使用的令牌记录在 MCP_DATA_DIR 下，因此即使空闲重启，批准仍会保留。

令牌只能使用一次，并且绑定到确切的负载。第二次调用会重新读取学生信息并重建负载，因此，如果预览和批准之间有任何内容发生变化——日期或选项不同，或者（对于默认计划，会往返传递整条学生记录）记录在此期间被修改——都不会发送任何内容，并且你会收到 DRAFT_CHANGED 和一份新的预览。

这些工具具备而 API 不具备的两项功能

发送任何内容之前都会执行规则检查。 每个离校选项都有自己的要求——备注、车辆号码、提前离校时间，或仅限特定学生。pup_set_plan 会根据学校自己的选项列表检查这些要求，并使用学校的措辞拒绝不符合要求的操作，因此，被拒绝的写入操作会返回验证消息，而不是含糊不清的 400 错误。

写入操作会通过重新读取进行验证。 PickUp Patrol 返回 2xx 并不能证明操作成功：学校截止时间之后进行的更改会被接受，但悄然忽略。每次写入操作都会重新读取受影响的日期，并比较交通方式 ID 和备注——绝不比较 ModifiedDate，因为它会自行更新，导致每次写入看起来都成功。备注是验证依据的一部分，因为迄今为止见过的每个离校选项都要求填写备注，因此只修改备注也是常规操作：如果只比较 ID，就会根据一个实际上无需变动的字段报告成功。结果会显示 verified: true/false，并列出未发生变化的日期。

不使用 MCP 服务

skills/pickuppatrol-api/ 是一个 shell-out 技能，通过 curl 和 jq 调用同一 API，适用于脚本或未安装服务的机器。

开发

npm install
npm run build
npm test              # fast
npm run test:coverage # coverage-enforced at 100%

测试绝不会访问网络：传输层通过注入提供，MCP 工具则通过真实的内存客户端／服务端对运行。

关于 API 值得了解的两件事

GetPlanEdit 返回的是某个日期的覆盖值，而非生效计划。 如果某日期没有专属计划，即使该星期几有学生的每周默认计划，读取结果仍会是 TransportationId: null。pup_get_plan 会原样传递该值；每周默认计划则保存在 pup_list_students 中。

登录使用的是会话 Cookie，而非 JWT。 在此部署中，Authenticate 返回的 BearerToken: null，并设置 ss-id/ss-pid/ss-opt。客户端会保留服务器返回的内容并同时发送两者，因此，今后切换到 JWT 无需在此处做任何更改。

安全说明

• 登录遭拒后绝不会重试。PickUp Patrol 会将失败尝试计入账户，只有通过其支持服务台才能解除锁定，因此错误会被缓存，后续每次调用都会立即失败并返回相同的消息。
• 设置每周默认值时，会对整个学生记录执行读取-修改-写入操作，因为 API 没有默认计划端点。服务端始终会在写入前立即读取学生记录，并且只修改 DefaultPlans。
• 凭据保存在 .env（已加入 gitignore）或 MCP 主机的配置中，绝不会写入结果或日志。

许可证

MIT