Simplepush

@simplepush/mcp

Simplepush 用の MCP サーバーです。エージェントはタスクや通知を人々のスマートフォンに送信して回答を待ち、追加のフォローアップを送り、誤りを取り消し、戻ってきたすべての記録を照会できます。タスク、回答、返信、辞退、臨時の提出内容は引き続き照会できるため、このストリームは作業のナレッジベースとしても機能します。何が依頼され、誰が何に回答し、何がまだ未解決なのかを確認できます。

ツール

ツール	機能
send_notification	アラートやお知らせを送信します。1つのinput（テキスト入力、選択肢、またはアクションボタン）を指定できます。wait_secondsが設定されていない場合は、送信後すぐに戻ります。デフォルトでは受信者ごとに個別のコピーを送信し、結果には各人のnotification_idが1つずつ含まれます。shared: trueを指定すると、全受信者に共通の通知を1つ送信します。
send_task	タスクを送信して、回答を待ちます。入力一式（テキスト、選択肢、アクション、スライダー、写真、音声録音、ファイル、位置情報）、tag、replyモード、expires_at、Markdown、リンクを指定します。デフォルトでは受信者ごとに個別のコピーを送信し、全員の回答を待ちます。期限時点で未回答の受信者がいる場合、その人たちは保留中として報告されます。shared: trueを指定すると、全受信者が一緒に回答するタスクを1つ送信し、最初の回答を採用します。各結果にはappend_tokenが含まれます。
append_subtask	send_taskのappend_tokenを使って、タスクまたはグループに追加の質問やチェックリスト項目を追加します。待機しません。
cancel_task	オプションの理由とメモを指定して、IDでタスク（tsk_）、サブタスク（sub_）、またはグループ全体（grptsk_）を取り下げます。
get_task_answer	以前のsend_taskのtask_id、またはappend_subtaskのsubtask_idに対応する回答を取得します。
get_notification_answer	入力を指定した以前のsend_notificationのnotification_idに対する回答を取得します。
query_tasks	タスクの要約を1ページ分取得します。タグ、トピック、ステータス、受信者、入力の種類、添付ファイルの種類、返信モード、送信時刻、サブタスク数が含まれます。ステータス、期間、トピック、メンバー、グループで絞り込めます。
get_task	1つのタスクと、そのすべてのサブタスクを取得します。質問、回答、返信、辞退、ファイルIDが含まれます。
get_group_status	タスクグループ（grptsk_）の受信者ごとのステータスを取得します。回答した人と、まだ回答していない人を確認できます。
query_events	組織のアクティビティ履歴を取得します。回答、返信、提出、辞退、キャンセル、期限切れの情報と、誰がいつ行ったかが含まれます。デフォルトでは過去7日間が対象です。
query_submissions	現場からの随時報告（テキスト、写真、ファイル、音声、位置情報）を取得します。誰がいつ報告したかが含まれます。デフォルトでは過去7日間が対象です。
search_knowledge	タスクや通知、人々の回答や返信、随時報告など、すべての情報を対象に、全文検索と位置検索を行います。全期間が対象です。単語の完全一致に加え、最大3言語で語幹検索を行えます。または、座標と半径、あるいは角の点で構成されるポリゴンを指定すると、その範囲内で記録された位置を近い順に返します。各検索結果には、全文を取得するためのID（グループへの送信はgrptsk_ IDとして1件のみヒット）と、スニペットまたは距離付きの地点が含まれます。対象はプレーンテキストの記録のみです。
get_activity	メンバー1人または組織全体の進行状況を1回の呼び出しで取得します。未完了／辞退済み／期限切れのタスクに加え、指定期間内の回答、返信、辞退、キャンセル、提出が含まれます。「Xに問題はありますか？」や「最近の状況を教えて」に使うツールです。
download_attachment	scope_id（対象となるtsk_/sub_/sbm_ ID）とfile_id（回答のinputId、返信または提出ファイルのID）を指定して、写真、音声録音、またはファイルを取得します。画像はインラインで返されます。

クエリツールはどちらのモードでも動作します。組織の認証情報（統合トークン、または組織管理者としてサインインしたホスト型コネクター）を使うと、組織全体の情報を読み取ります。個人用の認証情報（APIトークン、または個人用APIトークンを使うホスト型コネクター）では、個人のストリームを読み取ります（個人アカウントでの利用にはサブスクリプションが必要です）。ホスト型トランスポートではreadスコープが必要です。download_attachmentには、さらにfiles:readが必要です。暗号化されたコンテンツはサーバーが保持するキーで復号されます。復号できないものは暗号文のまま残され、その旨が報告されます。

send_taskのタイムアウトはキャンセルではありません。質問は引き続きスマートフォン上で有効で、回答は後からget_task_answerまたはget_group_statusで取得できます。inputsはタスクの回答方法を示します。テキスト、単一または複数選択、アクションボタン、スライダー、写真、音声録音、ファイル、位置情報を指定できます。send_taskのデフォルトの待機時間は90秒です。呼び出しごとのwait_secondsで、SP_MAX_WAIT_SECONDSまで延長できます。

セットアップ

サーバーは、設定する認証情報によって2つのモードのいずれかで動作します。

個人モード

Simplepush アプリの API Token 画面で API トークンを取得し、次を実行します。

{
  "mcpServers": {
    "simplepush": {
      "command": "npx",
      "args": ["-y", "@simplepush/mcp"],
      "env": { "SP_API_TOKEN": "your-token" }
    }
  }
}

または、Claude Code を使用する場合：

claude mcp add simplepush --env SP_API_TOKEN=your-token -- npx -y @simplepush/mcp

メッセージは自分のデバイスに送信されます。代わりに topic を渡すと、そのトピックの登録者に送信されます。1つの共有タスクとして送信され、最初の回答が採用されます。

組織モード

CLI を使用してインテグレーショントークンを作成します（管理者の Vault のロックを解除してください）。

sp integration create

claude mcp add simplepush --env SP_INTEGRATION_TOKEN=spi_... -- npx -y @simplepush/mcp

組織モードでは、完全な送信先指定が可能になります。各送信には topic、member（名前または usr_ ID）、broadcast のいずれか1つを必ず指定します。トークンのスコープで許可されたツールのみが一覧に表示されます。たとえば、read files:read で作成したトークンでは、クエリとダウンロードのツールが公開され、送信ツールは表示されません。これにより、読み取り専用のエージェントがリクエストごとに保持するツールスキーマを最小限に抑えられます。組織で暗号化が有効になっている場合、トークンの後半部分を使って起動時に組織のマスターキーを復号し、すべての送信をエンドツーエンドで暗号化します。回答も同じ方法で復号されます。

両方の認証情報が設定されている場合は、インテグレーショントークンが優先され、stderr に注意書きが出力されます。MCP クライアントはシェル環境を引き継いで stdio サーバーを起動するため、別の CLI 作業でエクスポートした SP_API_TOKEN もそのまま引き継がれます。一方、SP_INTEGRATION_TOKEN の設定は常に意図的なものです。

環境変数（stdio）

変数	デフォルト値	意味
SP_API_TOKEN	認証情報が1つ必要	アプリから取得した個人用 API トークンです。
SP_INTEGRATION_TOKEN	認証情報が1つ必要	sp integration create で作成した組織インテグレーショントークンです。
SP_KEYS	未設定	個人用暗号化キー。下記を参照してください。
SP_BASE_URL	https://api.simplepu.sh	API のオリジンです。ローカル開発では http://localhost:8000 を指定します。
SP_MAX_WAIT_SECONDS	900	send_task がブロックする最大時間です。呼び出しごとの wait_seconds はこの値を上限として調整されます。
SP_POLL_INTERVAL_MS	2000	ブロック中に回答をポーリングする間隔です。
SP_SCOPES	未設定	スコープコード（send、read、files:read）をスペースまたはカンマで区切って指定します。該当するツールのみが一覧に表示されます。インテグレーショントークン自体のスコープをさらに絞り込むために使用します。また、バックエンドが常にフルアクセスとして扱う個人用 API トークンで、一覧に表示するツールを絞り込む唯一の方法です。

暗号化

上記のとおり、組織で暗号化が有効になっている場合、組織モードでは自動的に暗号化されます。

キーを指定しない場合、個人用の送信は平文になります。アプリでは、暗号化されたタスクと平文のタスクをひと目で見分けられます。暗号化されたタスクにはロックアイコンが表示されます。

キーは Simplepush アプリからエクスポートします。個人用パスワードキーは Encryption 画面の Copy Key for Integrations から、トピックキーは Topics 画面で対象トピックの横にあるコピー操作から取得します。

SP_KEYS はカンマ区切りのリストです。キーを単独で Base64 形式で指定すると、セルフ送信に使う個人用パスワードキーになります。topic=key の形式で、キーを1つのトピックに紐付けます。

SP_KEYS="AbC...="                        # default key only
SP_KEYS="alerts=AbC...=,deploys=XyZ...="  # two topic keys
SP_KEYS="AbC...=,alerts=XyZ...="          # both

対応するキーがある場合、その宛先への送信は暗号化され、回答は復号されます。サーバーがキーを持たない回答は、誤った内容として返されることなく、undecryptable: true として返されます。

キーのみです。SP_PASSWORD はありません。

ホスト型 HTTP トランスポート

simplepush-mcp-http は、OAuth リソースサーバーとして Streamable HTTP 経由で同じツールを提供します。環境から暗黙に引き継がれる認証情報はありません。各リクエストに独自のアクセストークンが含まれ、認可サーバーへのイントロスペクションによって検証され、SP_CANONICAL_URI に対するオーディエンスチェックが行われます。ディスカバリーメタデータは /.well-known/oauth-protected-resource で提供され、MCP エンドポイントは /mcp です。GET /status は稼働時間監視用の公開サマリーです。認可サーバーと API の両方が応答した場合は 200、それ以外の場合は 503 を返します。形式はバックエンドの /v1/status と同じです。ツールはスコープで制限されています。send は send_notification、send_task、append_subtask、cancel_task に、read は回答ツールとクエリツールに、files:read は download_attachment に必要です。付与されたスコープで利用できるツールのみが一覧表示されます。それ以外のツールを直接呼び出すと、不足しているスコープを示すチャレンジが返され、拒否されます。

ホスト型モードでは、個人用 OAuth グラントのみを使用できます。設計上、インテグレーショントークンは受け付けません。また、ホスト型の送信は平文です。復号できるサーバーがあなたの代わりに復号する仕組みでは、エンドツーエンドにはなりません。

変数	デフォルト	説明
SP_INTROSPECTION_SECRET	必須	AS イントロスペクションエンドポイント用のベアラー。バックエンドの oauth.introspectionSecret と一致する必要があります。
SP_CANONICAL_URI	必須	クライアントがこのサーバーにアクセスする公開 URL。例：https://mcp.simplepu.sh/mcp。トークンのオーディエンスはこの URL に紐付けられます。
SP_OAUTH_ISSUER	https://api.simplepu.sh	クライアントから見た認可サーバーのオリジン。
SP_AUTH_SERVER_URL	SP_OAUTH_ISSUER	このサーバーがトークンのイントロスペクションで認可サーバーに接続する URL。バックエンドに内部アドレスでより近くから接続する場合に設定してください。
SP_BASE_URL	https://api.simplepu.sh	このサーバーが呼び出す API のオリジン。
SP_MCP_PORT	8787	リッスンするポート。

開発

npm install
npm run build
npm run typecheck

MCP クライアントを使わずに、ローカルバックエンドに対してスモークテストを実行します。

npx @modelcontextprotocol/inspector --cli node dist/index.mjs \
  -e SP_API_TOKEN=testtoken5678 -e SP_BASE_URL=http://localhost:8000 \
  --method tools/list

Inspector は、起動したサーバーにシェル環境を引き継がないことに注意してください。認証情報はエクスポートするのではなく、-e で渡してください。