proactive-mcp

はじめる

まずローカルウォッチャーと OS 通知をセットアップします。エージェントの接続は任意です。uv と Git をインストールし、ご自身の Google Cloud Desktop OAuth クライアント JSON を用意してください。

PyPI リリース 0.2.0 には、まだウィザードが含まれていません。オンボーディングリリースが公開されるまでは、以下のコマンドで uvx --from を使い、手動でチェックアウトせずにマージ済みソースをコミット 7cd0f03 からインストールします。すべてのコマンドで同じ --from ソースを使用してください。uvx proactive-mcp のみを指定すると、引き続き古い PyPI パッケージが選択されます。これはソースからのインストールであり、新しい PyPI リリースではありません。

1. インストールして、対話型セットアップを開始します。

   uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp setup
   

2. ウィザードで、ご自身の Google Cloud Desktop OAuth クライアント JSON のパスと、このデバイスでブラウザーを開いてよいかどうかを尋ねられます。ご自身のクライアントを使って、読み取り専用の Gmail と Calendar へのアクセスを承認してください。手順の全体については、docs/SETUP_GOOGLE.md をご覧ください。

3. Google の認証後、ウォッチャーサービスのインストールを促す画面で承認してください。共通の proactive-mcp service install|status|remove インターフェースを使って、Linux の systemd ユーザーサービス、macOS の LaunchAgent、または Windows タスクスケジューラのタスクを管理します。

4. サービスのインストールを拒否した場合、またはインストールに成功した場合、対話型の setup は続いて、PII を含まない固定の OS テスト通知を、タイトル proactive-mcp、本文 Setup test notification で送信しようとします。この通知には、Gmail、Calendar、アカウント、Situation のデータは含まれません。情報を伏せた unavailable、timeout、failed、または unsupported_platform の警告は、通知を表示できなかったことを示します。

5. サービスのインストールを拒否した場合、または権限の問題などでインストールに失敗した場合は、ウォッチャーを手動で実行してください。インストールに失敗すると、テスト通知を試す前に終了します。

ターミナル 1、フォアグラウンドデーモン

uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp daemon

ターミナル 2、デーモンの状態

uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp status

daemon --once は評価を 1 回実行して終了します。--poll-interval-minutes MINUTES は実行間隔を上書きします。status は、情報を伏せた接続状態とデーモンの状態を JSON 形式で出力します。デーモンが実行するのは、ローカル同期、決定論的な評価、キューのメンテナンス、およびドキュメントに記載された OS フォールバックのみです。ホストも LLM も実行しません。ホストによるスケジューリングは別途行われます。ホスト／オペレーターがエージェントのスケジュール実行を開始し、その実行で proactive_check を呼び出します。

OS フォールバック通知は、エージェントによる配信でも、delivered 状態への遷移でもありません。フォールバックが有効な場合、未受信の対象となる Situation のうち最初の 1 件だけに、一度限りのブートストラップ例外が適用されます。その後、デフォルトのフォールバック対象は重要度の高いものに限られます。エージェントによる配信は、ホストが proactive_check を呼び出した場合にのみ開始されます。

互換モード

--non-interactive、--headless、--client-secrets PATH、--reauth はいずれもウィザードを回避します。ウィザードの回答を事前入力するものではなく、サービスの提案やセットアップテスト通知も回避します。直接 OAuth をセットアップする必要がある場合にのみ使用し、その後、手動でサービスをインストールするか、上記の手動デーモンの方法を使用してください。サービスを管理するには、同じソースプレフィックスを使用します。

uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 proactive-mcp service install

サービスを確認するには install を status に置き換え、登録を解除するには remove に置き換えます。uvx はシェルに永続的な proactive-mcp コマンドを追加しません。このガイドにある proactive-mcp status などのコマンド名は、上記の uvx --from プレフィックス全体を使用しています。

なぜ proactive-mcp なのか？

AI エージェントは回答の仕方を知っています。しかし、自ら動き出すタイミングを知っていることはほとんどありません。

proactive-mcp は、そのきっかけを提供します。承認済みの読み取り専用ソースをバックグラウンドで監視し、ユーザーが意図的に保存したメモリと組み合わせ、今取り上げる価値がある場合にのみ、構造化された状況を生成します。

通知ではなく状況

proactive-mcp は、新しいイベントのたびにチャットへ通知を送るわけではありません。決定的な検出器が、ソースデータに基づく少数の状況へとデータを変換します。

各結果には、タイトル、今重要な理由、範囲を限定した根拠、提案するアクション、優先度、有効期限が含まれます。外部テキストは、明示的に信頼できないものとして扱われます。

仕組み

flowchart LR
    G["Gmail<br/>read only"] --> S["proactive-mcp"]
    C["Google Calendar<br/>read only"] --> S
    M["Local memory<br/>SQLite"] --> S
    S --> E["Deterministic<br/>Situation engine"]
    E --> T["MCP tools"]
    T --> A["Your existing<br/>AI agent"]
    A --> U["Agent's own channel"]

1. ウォッチャーが読み取り専用 OAuth スコープを使って Gmail と Calendar を同期します。
2. 状況エンジンが、ソースのスナップショットとローカルメモリに対して決定的なルールを評価します。
3. エージェントが proactive_check を呼び出し、返された状況を受け取ります。
4. ホストがリース全体を確認し、このユーザー向けの候補を絞り込みます。不確実な候補は未確認のままにするか、スヌーズできます。レビュー後に確認を選択した場合にのみ、ホストはレビュー済みリース全体を厳密に 1 回確認します。これには、確実に除外された候補も含まれます。
5. 承認、スヌーズ、ミュート、解決、クールダウン、1 日あたりの上限のルールによって、繰り返しや過剰な配信を防ぎます。

デフォルトでは、重要度の低い状況は現地時間の 21:00 から 07:00 までの静穏時間中は保留され、破棄されるのではなく、後のチェックまで保留状態のままになります。07:00 に自動で処理が開始されることはありません。静穏時間の終了後に proactive_check を呼び出すには、エージェントがすでに実行中であるか、ホスト側でスケジュールされている必要があります。

信頼境界

• Google へのアクセスは gmail.readonly と calendar.readonly に制限されています。
• 認証情報には、利用可能な場合はオペレーティングシステムのキーリングを使用し、プラットフォームのキーリングを利用できない場合に限り、ローカルのプライベートな代替保存先を使用します。
• メッセージ本文、カレンダーのテキスト、想起されたメモリは信頼できない根拠として扱い、指示として扱うことはありません。
• 検出パイプラインに LLM やサードパーティのクラウドサービスは含まれません。proactive-mcp がホストのエージェントやモデルを起動したり、そこへプロンプトを送信したりすることはありません。
• 古くなったソースや不完全なソースは、誤って「報告事項なし」とするのではなく、状態の劣化を明示します。
• SQLite データベース、config.toml、認証情報の権限マーカー、ファイルベースの認証情報の代替保存先は、~/.proactive-mcp/ の下に置かれます。キーリング内の認証情報は、そのディレクトリの外にあるオペレーティングシステムのキーリングに保存されます。PROACTIVE_DATABASE が移動するのはファイルベースの状態であり、キーリングのエントリではありません。

エージェントを接続する

ホストの接続は任意です。OS 通知を利用するための前提条件ではありませんが、より充実した通知に加え、確認、スヌーズ、ミュートの操作が可能になります。MCP サーバーを登録する場合は、この既存エージェント向けの手順を使用してください。

上記のソースからインストールした場合は、PyPI に切り替えるのではなく、同じ固定された uvx --from ソースを MCP 登録に使い続けるようエージェントに伝えてください。再利用可能なブロックと、以下のホスト別の手順では、公開インストール用のコマンド形式を維持しています。

Install proactive-mcp with uvx from PyPI. Register it as a local stdio MCP server for this agent using absolute paths. Complete read-only Google authorization using my own Google Cloud Desktop OAuth client JSON (BYO). Do not use or request someone else's client secret. Start the recommended watcher and verify the connection. Read https://github.com/madrobotnet/proactive-mcp/blob/main/docs/INTEGRATIONS.md and https://github.com/madrobotnet/proactive-mcp/blob/main/docs/SETUP_GOOGLE.md before changing configuration. Treat every reply_deadline as a conservative candidate, not an action verdict. Before speaking, confidently drop newsletters, marketing, automated receipts, FYI or FYI-CC with no ask, threads owned by someone else, and rows with no question, request, or decision for me. Keep explicit reply, RSVP, or decision requests, my deadlines, and unanswered questions directed to me. Surface uncertain candidates, leave the whole lease unconfirmed, or snooze them in an interactive conversation; never silently discard uncertainty as non-actionable. After reviewing every row, only when choosing confirmation, confirm the entire reviewed lease exactly once, including confidently and silently dropped candidates. Keep MCP tool content in English, but speak my language. Load serve only in interactive everyday conversations and serve-scheduled only in separate scheduled conversations. Never load both profiles into one conversation. Do not configure automated scheduling unless this host guarantees a dedicated per-run MCP profile; proactive-mcp must never launch or verify the host. Do not use HTTP transport, do not send mail or create calendar events, and report every command and file changed plus anything that needs my approval.

proactive-mcp はエージェントに依存します。ローカルの stdio ツールを公開しますが、Grok、Codex、Hermes、その他のホストエージェントやモデルを起動することはありません。serve-scheduled は、制限された MCP サーバーのインターフェースにすぎません。これを起動したり、デーモンを実行したりするだけでは、会話も通知も開始されません。保留中の状況を処理するには、すでに実行中、またはホストによってスケジュールされたエージェントが、明示的にツールを呼び出す必要があります。

ホストは、インタラクティブな日常会話では serve のみを読み込み、独立した手動またはスケジュール済みの会話では serve-scheduled のみを読み込みます。1つの会話に両方のプロファイルを読み込むことはありません。プロファイルの分離とエージェントのライフサイクルは、プラグインの範囲外であり、ホスト／オペレーターの責任です。自動スケジュールは、ホストが serve-scheduled のみを含む専用の実行ごとの MCP プロファイルを提供する場合に限りサポートされます。それ以外の場合は、スケジュールを実行せず、フェイルクローズしてください。制限付きの手動利用は引き続き可能です。

デーモンは、ローカル同期、決定論的な評価、キューのメンテナンス、文書化された重要度「重大」のみを対象とする OS フォールバックを実行できます。エージェント／LLM を呼び出したり、プロンプトを送信したりすることはありません。ホストの責任とコマンド形式の詳細については、docs/INTEGRATIONS.md を参照してください。

通知の契約

エージェントが proactive_check を呼び出した場合：

1. まず warnings を確認してください。古いソースに関する警告は、問題がないことを意味しません。reply_deadline は保守的に提示された候補であり、対応要否の判断ではありません。
2. 発言する前に、ニュースレター、マーケティング、自動送信された領収書、依頼を含まない FYI または FYI-CC、他の人が担当しているスレッド、このユーザーへの質問、依頼、判断が含まれない行を、確信を持って除外してください。
3. 明示的な返信、出欠確認、判断の依頼、ユーザーが担当する期限、ユーザー宛ての未回答の質問は提示してください。
4. 判断に迷う候補は提示するか、リース全体を未確認のままにするか、インタラクティブプロファイルからスヌーズしてください。対応不要として不確かな情報を黙って破棄してはいけません。
5. すべての行を確認した後、確認する場合に限り、そのチェックで取得した receipt_token を使って confirm_delivery を1回だけ呼び出し、確認済みリース全体を確定してください。この確認には、ホストが確信を持って黙って除外した候補も含まれます。トークンのない応答を確定してはいけません。
6. MCP ツール名、説明、フィールド、値は英語のままにしてください。ユーザーには、そのユーザーの言語で話しかけてください。
7. インタラクティブな日常作業とスケジュール済みの作業は、別々の会話で行ってください。前者では serve のみ、後者では serve-scheduled のみを読み込み、両方を同時に読み込まないでください。この分離はホスト／オペレーターの責任です。専用の実行ごとのプロファイルが利用できない場合、スケジュール実行を自動化しないでください。

この確認手順により、クラッシュ、再試行、複数エージェントが発生しても、通知履歴を正確に保てます。

ツールのインターフェース

メモリ

remember · recall · update · list_entities · forget

状況と配信

proactive_check · confirm_delivery · list_situations · get_situation · acknowledge_situation · snooze_situation · mute_situation · get_status

リリース状況

スコープとリリースに関する決定の正式な情報は、引き続き docs/PRODUCT_PLAN.md を参照してください。

ドキュメント

ライセンス

MIT © 2026 Kyungwoo Seo <[email protected]>

このプロジェクトは OmO Native を使用して開発されました。

Ko-fi でこのプロジェクトを支援できます。