pickuppatrol-mcp

pickuppatrol-mcp

PickUp Patrol の MCP サーバーです。学校の下校アプリである PickUp Patrol の情報を扱います。お子様が学校を出る方法について、週ごとのデフォルト設定、特定の日付のみの変更、学校の下校方法と締め切り時刻を確認・変更できます。

AI（Claude Code）が開発・保守しています。ご自身の判断でご利用ください。

接続先

app.pickuppatrol.net は、Ionic/Vue SPA の背後で ServiceStack の JSON API を実行しています。公開 API はありませんが、通常の HTTPS リクエストを使ってサーバー側からアクセスできます。ブラウザー拡張機能やボット対策、CAPTCHA は不要です。サーバーはご自身のメールアドレスとパスワードでサインインし、取得したセッションをメモリ内に保持します。

すべてのリクエスト形式は、推測ではなく配布済みクライアントから読み取ったうえで、実際のアカウントに対して読み取り、書き込み、および復元を実行して確認し、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	1 人の児童の全情報
pup_get_default_plans	児童の週ごとのデフォルト設定（日ごと）
pup_list_plans	指定した日付範囲の日ごとの設定
pup_get_plan	1 人の児童、1 日分の設定（ロックされているかどうかを含む）
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	1 日以上の指定日の下校設定を変更するか、デフォルトに戻すために設定を解除します
pup_set_default_plans	週ごとのデフォルト設定を変更するか、すべてのデフォルト設定を解除します
pup_mark_defaults_reviewed	学校の「デフォルト設定を確認してください」という通知を処理します

確認

変数	デフォルト
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で、書き込みがどのように処理されるかを指定します。ask-user：2段階で処理します。1回目の呼び出しでは何も実行されず、プレビューとトークンが返されます。モデルは、トークンを付けて再度呼び出す前に、チャットでユーザーの承認を得る必要があります。auto：同じく2段階で処理しますが、プレビューを確認したモデルはトークンを使用できます。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 に記録されるため、アイドル状態での再起動後も承認が有効です。

トークンは1回のみ使用でき、特定のペイロードに紐付けられます。2回目の呼び出しでは、生徒情報を再取得してペイロードを再構築します。そのため、プレビューから承認までの間に何かが変わった場合（別の日付やオプションが指定された場合、またはデフォルトプランで生徒レコード全体を往復させる場合に、その間にレコードが変更された場合）、何も送信されず、新しいプレビューとともに DRAFT_CHANGED が返されます。

API にはない、ツールの2つの機能

送信前にルールを適用します。 各欠席オプションには、メモ、車両番号、早退時刻、特定の生徒のみへの制限など、それぞれ独自の要件があります。pup_set_plan は学校独自のリストと照合して要件を確認し、学校側の文言で拒否するため、書き込みが拒否された場合は不透明な400エラーではなく、検証メッセージが返されます。

書き込み後に再取得して検証します。 PickUp Patrol からの2xx応答は、成功の証明にはなりません。学校の締め切り後に変更を行うと、受け付けられても黙って無視されることがあります。すべての書き込み後に、影響を受ける日付を再取得し、交通手段のID とメモを比較します。ModifiedDate は独自に更新されてすべての書き込みが成功したように見えてしまうため、比較には決して使用しません。これまでに確認された欠席オプションはすべてメモを必須としているため、メモだけの編集も通常の操作です。IDだけを比較すると、変更する必要のなかったフィールドをもとに成功と報告してしまいます。結果には verified: true/false が示され、変更が反映されなかった日付が列挙されます。

MCP サーバーを使わない場合

skills/pickuppatrol-api/ は、サーバーがインストールされていないスクリプトやマシン向けに、curl と jq で同じAPIを利用するシェル呼び出し型のスキルです。

開発

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

テストではネットワークに接続しません。トランスポートは注入され、MCP ツールは実際のインメモリのクライアント／サーバーのペアを介して実行されます。

知っておくとよいAPIの2つの点

GetPlanEdit が返すのは、日付ごとの上書きであり、有効なプランではありません。 特定のプランが設定されていない日付では、その曜日に対する生徒の週間デフォルトが設定されていても、TransportationId: null が返されます。pup_get_plan はこれをそのまま返します。週間デフォルトは pup_list_students で確認できます。

サインインではJWTではなく、セッションCookieを使います。 このデプロイ環境では、Authenticate は BearerToken: null を返し、ss-id／ss-pid／ss-opt を設定します。クライアントはサーバーから返されたものを保持して両方を送信するため、将来JWTに切り替えても、ここを変更する必要はありません。

安全に関する注意事項

• サインインが拒否された場合、再試行されることはありません。PickUp Patrol はアカウントに対する失敗回数をカウントし、ロックアウトはサポート窓口を通じてのみ解除されるため、エラーはキャッシュされ、その後の呼び出しはすべて同じメッセージですぐに失敗します。
• 週次のデフォルト設定の書き込みでは、API にデフォルトプラン用のエンドポイントがないため、学生レコード全体を読み取り、変更してから書き込みます。サーバーは書き込みの直前に必ず学生情報を読み取り、DefaultPlans のみを変更します。
• 認証情報は .env（gitignore 対象）または MCP ホストの設定に保存され、結果やログに書き込まれることはありません。

ライセンス

MIT