MCP Agent Mail

🚀 MCP Agent Mail

コーディングエージェント用のメールのような調整レイヤーで、HTTPのみのFastMCPサーバーとして公開されます。

🚀 クイックスタート

一行でのインストール

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

このコマンドは以下のことを行います。

• uvがない場合はインストールし、このセッションのPATHを更新します。
• Python 3.14の仮想環境を作成し、uvを使用して依存関係をインストールします。
• サポートされているエージェントツールを自動検出して統合します。
• ポート8765でMCP HTTPサーバーを起動し、マスクされたベアラートークンを表示します。
• scripts/以下にヘルパースクリプト（run_server_with_token.shを含む）を作成します。

特定の場所やオプションが必要な場合は、--dir <path>、--project-dir <path>、--no-start、--start-only、--port <number>、--token <hex>などのフラグを追加してください。

ポートが競合する場合：--portを使用して別のポートを指定してください（デフォルト: 8765）。

# カスタムポートでインストール
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

# またはインストール後にCLIコマンドを使用
uv run python -m mcp_agent_mail.cli config set-port 9000

手動で行う場合

リポジトリをクローンし、Python 3.14の仮想環境でuvを使用してセットアップとインストールを行い（uvがない場合はインストールしてください）、その後scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.shを実行します。これにより、インストールされているさまざまなコーディングエージェントツールが自動的に設定され、ポート8765でMCPサーバーが起動します。将来的にMCPサーバーを再度実行する場合は、単にscripts/run_server_with_token.shを実行してください。

# uvをインストールする（まだインストールされていない場合）
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# リポジトリをクローンする
git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail

# Python 3.14の仮想環境を作成し、依存関係をインストールする
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync

# インストールされているコーディングエージェントを検出し、統合して、ポート8765でMCPサーバーを起動する
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

# 後で、同じトークンでMCPサーバーを再度実行する
scripts/run_server_with_token.sh

# これで、他のコンソールでCodex-CLIやClaude Codeなどのエージェントツールを起動するだけです。メールツールが利用可能になっているはずです。既存のAGENTS.mdまたはCLAUDE.mdファイルの末尾に追加できるテキストのサンプルについては、以下を参照してください。

# インストール後にポートを変更する
uv run python -m mcp_agent_mail.cli config set-port 9000

✨ 主な機能

• コーディングエージェントに記憶に残るID、受信箱/送信箱、検索可能なメッセージ履歴、およびファイル予約「リース」を提供し、エージェント同士の衝突を回避します。
• 非同期のメール + ディレクトリ + 変更意図のシグナリングとして機能し、Git（人間が監査可能なアーティファクト用）とSQLite（インデックス作成とクエリ用）をバックエンドに使用します。
• 軽量で相互運用可能なレイヤーを提供し、エージェントがIDを登録し、メッセージを送受信し、会話を検索・要約・スレッド化し、ファイル予約を宣言し、アクティブなエージェントやプログラム/モデル、アクティビティのディレクトリを調査できるようにします。

📦 インストール

上記の「クイックスタート」セクションに記載されている一行でのインストールまたは手動でのインストール手順を参照してください。

💻 使用例

基本的な使用法

# 一行でのインストール
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

# 手動でのインストール
# uvをインストールする（まだインストールされていない場合）
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# リポジトリをクローンする
git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail

# Python 3.14の仮想環境を作成し、依存関係をインストールする
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync

# インストールされているコーディングエージェントを検出し、統合して、ポート8765でMCPサーバーを起動する
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

高度な使用法

# カスタムポートでインストール
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

# インストール後にポートを変更する
uv run python -m mcp_agent_mail.cli config set-port 9000

# 静的メールボックスをエクスポートしてデプロイする
uv run python -m mcp_agent_mail.cli share wizard

📚 詳細ドキュメント

既存のAGENTS.mdまたはCLAUDE.mdファイルに追加するテキスト

## MCP Agent Mail: マルチエージェントワークフローのための調整

概要
- コーディングエージェントがMCPツールとリソースを介して非同期に調整できるメールのようなレイヤーです。
- エージェントにID、受信箱/送信箱、検索可能なスレッド、およびファイル予約を提供し、Gitに人間が監査可能なアーティファクトを保存します。

利点
- 明示的なファイル予約（リース）により、エージェント同士の衝突を防ぎます。
- メッセージをプロジェクトごとのアーカイブに保存することで、トークン予算から通信を除外します。
- クイックリード（`resource://inbox/...`、`resource://thread/...`）と一般的なフローをまとめたマクロを提供します。

効果的な使用方法
1) 同じリポジトリ内
   - IDを登録する：`ensure_project`を呼び出し、その後このリポジトリの絶対パスを`project_key`として`register_agent`を使用します。
   - 編集する前にファイルを予約する：`file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)`を使用して意図をシグナルし、衝突を回避します。
   - スレッドで通信する：`send_message(..., thread_id="FEAT-123")`を使用し、`fetch_inbox`で受信箱を確認し、`acknowledge_message`でメッセージを承認します。
   - 高速に読む：`resource://inbox/{Agent}?project=<abs-path>&limit=20`または`resource://thread/{id}?project=<abs-path>&include_bodies=true`を使用します。
   - ヒント：環境変数に`AGENT_NAME`を設定すると、プリコミットガードが他のエージェントのアクティブな排他的ファイル予約と衝突するコミットをブロックできます。

2) 1つのプロジェクト内の異なるリポジトリ間（例：Next.jsフロントエンド + FastAPIバックエンド）
   - オプションA（単一のプロジェクトバス）：両方を同じ`project_key`（共有キー/パス）の下に登録します。予約パターンを具体的に保ちます（例：`frontend/**`対`backend/**`）。
   - オプションB（別々のプロジェクト）：各リポジトリに独自の`project_key`を持たせ、`macro_contact_handshake`または`request_contact`/`respond_contact`を使用してエージェントをリンクし、その後直接メッセージを送ります。リポジトリ間で共有の`thread_id`（例：チケットキー）を保持して、クリーンな要約/監査を行います。

マクロと細粒度のツール
- 速度が必要な場合や小さいモデルを使用する場合は、マクロを優先します：`macro_start_session`、`macro_prepare_thread`、`macro_file_reservation_cycle`、`macro_contact_handshake`。
- 制御が必要な場合は、細粒度のツールを使用します：`register_agent`、`file_reservation_paths`、`send_message`、`fetch_inbox`、`acknowledge_message`。

一般的な落とし穴
- "from_agent not registered"：常に正しい`project_key`で`register_agent`を最初に呼び出してください。
- "FILE_RESERVATION_CONFLICT"：パターンを調整し、期限が切れるのを待つか、適切な場合は非排他的な予約を使用してください。
- 認証エラー：JWT+JWKSが有効になっている場合は、サーバーJWKSと一致する`kid`を持つベアラートークンを含めてください。静的なベアラートークンはJWTが無効になっている場合のみ使用されます。

Beads（依存関係を考慮したタスク計画）との統合

Beadsは軽量なタスクプランナー（bd CLI）で、Agent Mailのメッセージング、ファイル予約、および監査トレイルを補完します。プロジェクト：steveyegge/beads

特長

• Beadsはタスクの優先順位付けを担当し、Agent Mailは会話とアーティファクトを処理します。
• 共有ID（例：bd-123）により、Beadsの問題、Mailのスレッド、およびコミットが一致します。
• bd CLIは事前ビルドされたリリースまたはGoビルドを介してインストールできます。プラットフォーム固有の詳細については、リポジトリを参照してください。

エージェント向けドキュメントにコピー&ペーストできるテキスト

## Beads（依存関係を考慮したタスク計画）との統合

Beadsは軽量で依存関係を考慮した問題データベースと、「準備ができた作業」を選択し、優先順位を設定し、ステータスを追跡するためのCLI（`bd`）を提供します。これはMCP Agent Mailのメッセージング、監査トレイル、およびファイル予約シグナルを補完します。プロジェクト：[steveyegge/beads](https://github.com/steveyegge/beads)

推奨される規則
- **単一の信頼できる情報源**：タスクのステータス/優先順位/依存関係には**Beads**を使用し、会話、決定、および添付ファイル（監査）には**Agent Mail**を使用します。
- **共有ID**：Beadsの問題ID（例：`bd-123`）をMailの`thread_id`として使用し、メッセージの件名に`[bd-123]`を付けます。
- **予約**：`bd-###`タスクを開始するときは、影響を受けるパスに対して`file_reservation_paths(...)`を呼び出し、理由に問題IDを含め、完了時に解放します。

典型的なフロー（エージェント）
1) **準備ができた作業を選択する**（Beads）
   - `bd ready --json` → 1つの項目を選択する（最も優先度が高く、ブロッカーがないもの）
2) **編集領域を予約する**（Mail）
   - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`
3) **開始を宣言する**（Mail）
   - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`
4) **作業と更新**
   - 進捗状況をスレッド内で返信し、アーティファクト/画像を添付します。各問題IDについて会話を1つのスレッドにまとめます。
5) **完了と解放**
   - `bd close bd-123 --reason "Completed"`（Beadsがステータスの権限を持つ）
   - `release_file_reservations(project_key, agent_name, paths=["src/**"])`
   - 最後のMail返信：`[bd-123] Completed`と要約とリンクを付ける

マッピングチートシート
- **Mailの`thread_id`** ↔ `bd-###`
- **Mailの件名**：`[bd-###] …`
- **ファイル予約の理由**：`bd-###`
- **コミットメッセージ（オプション）**：追跡可能性のために`bd-###`を含める

イベントミラーリング（オプションの自動化）
- `bd update --status blocked`で、`bd-###`スレッドに重要度の高いMailメッセージを送信してブロッカーを説明します。
- 重要な決定に対するMailの「ACK期限切れ」で、Beadsのラベル（例：`needs-ack`）を追加するか、優先順位を上げて`bd ready`で表示されるようにします。

避けるべき落とし穴
- Mailでタスクを作成または管理しないでください。Beadsを単一のタスクキューとして扱ってください。
- メッセージの`thread_id`に常に`bd-###`を含めて、ツール間のIDのずれを避けてください。

コアアイデア

• HTTPのみのFastMCPサーバー（Streamable HTTP）。SSEやSTDIOは使用しません。
• 二重永続化モデル：
  • 各プロジェクトのGitリポジトリに人間が読めるMarkdown形式で、すべての正式なメッセージと受信者ごとの受信箱/送信箱のコピーを保存します。
  • FTS5を備えたSQLiteを使用して、高速な検索、ディレクトリクエリ、およびファイル予約/リースを行います。
• エージェント用の「ディレクトリ/LDAP」スタイルのクエリ。記憶に残る形容詞+名詞の名前を使用します。
• 編集領域のためのアドバイザリファイル予約。オプションのプリコミットガードがあります。
• 便利な読み取りのためのリソースレイヤー（例：resource://inbox/{agent}）。

典型的なユースケース

• 複数のエージェントが大規模なリファクタリングをサービス間で分割しながら同期を維持する。
• フロントエンドとバックエンドのエージェントチームがスレッドごとに調整する。
• 排他的なファイル予約とプリコミットガードで重要なマイグレーションを保護する。
• 長い技術的な会話をスレッドが進むにつれて検索し、要約する。
• AIによる提案を通じて関連するプロジェクト（例：フロントエンド/バックエンド）を発見し、リンクする。

アーキテクチャ

graph LR
  A[Agents]
  S[Server]
  G[Git repo]
  Q[SQLite FTS5]

  A -->|HTTP tools/resources| S
  S -->|writes/reads| G
  S -->|indexes/queries| Q

  subgraph GitTree["Git tree"]
    GI1[agents/profile.json]
    GI2[agents/mailboxes/...]
    GI3[messages/YYYY/\nMM/\nid.md]
    GI4[file_reservations/\nsha1.json]
    GA[attachments/xx/\nsha1.webp]
  end

  G --- GI1
  G --- GI2
  G --- GI3
  G --- GI4
  G --- GA

Web UI（人間向けのメールビューア）

サーバーには人間向けの軽量なサーバーレンダリングのWeb UIが搭載されています。これにより、プロジェクト、エージェント、受信箱、単一のメッセージ、添付ファイル、ファイル予約を閲覧し、FTS5を使用した全文検索を行うことができます（利用可能な場合は自動的にLIKEにフォールバックします）。

• 場所：mcp_agent_mail.httpのHTTPサーバーに組み込まれており、/mailパスでアクセスできます。
• 対象ユーザー：アクティビティをレビューする人間。エージェントは引き続きMCPツール/リソースAPIを使用する必要があります。

Web UIの起動

推奨（簡単）：

scripts/run_server_with_token.sh
# 次にhttp://127.0.0.1:8765/mailを開く

高度（手動コマンド）：

uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765
# または:
uv run uvicorn mcp_agent_mail.http:build_http_app --factory --host 127.0.0.1 --port 8765

認証に関する注意事項：

• UIのGETページはRBACミドルウェアによってゲートされていません（POSTされたMCP呼び出しのみを分類します）。ただし、ベアラートークンを設定すると、別のBearerAuthミドルウェアがデフォルトですべてのルートを保護します。
• ローカル開発の場合は、HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=true（およびオプションでHTTP_BEARER_TOKEN）を設定すると、ローカルホストがヘッダーなしでUIをロードできます。
• ヘルスエンドポイントは常に/health/*で開かれています。

ルートと機能

• /mail（統合受信箱 + プロジェクト + 関連プロジェクトの発見）

  • すべてのプロジェクトの最近のメッセージを逆時系列で表示する統合受信箱を表示します。抜粋、相対的なタイムスタンプ、送信者/受信者、およびプロジェクトバッジが表示されます。
  • 受信箱の下には、すべてのプロジェクト（スラッグ、人間用の名前、作成時間）が表示され、兄弟プロジェクトの提案が表示されます。
  • 2つのスラッグが同じ製品の一部であると思われる場合（例：バックエンド対フロントエンド）、可能性のある兄弟プロジェクトを提案します。提案はヒューリスティックスでランク付けされ、LLM_ENABLED=trueの場合は主要なドキュメント（README.md、AGENTS.mdなど）に対してLLMが実行されます。
  • 人間はダッシュボードから提案をリンクを確認または却下することができます。確認された兄弟プロジェクトは強調表示されたバッジになりますが、自動的にクロスプロジェクトのメッセージングが許可されるわけではありません。エージェントは依然としてrequest_contact/respond_contactを介してAgentLinkの承認を取得する必要があります。

• /mail/projects（プロジェクトインデックス）

  • 専用のプロジェクトリストビュー。プロジェクトをクリックすると詳細を表示します。

• /mail/{project}（プロジェクト概要 + 検索 + エージェント）

  • フィルター付きの高度な検索フォーム：
    • スコープ：件名/本文/両方、順序：関連性または時間、オプションの「件名を強調」。
    • クエリトークン：subject:foo、body:"multi word"、引用句、および単語をサポートします。
    • 利用可能な場合はFTS5のbm25スコアリングを使用します。それ以外の場合は、選択したスコープで件名/本文に対するSQL LIKEにフォールバックします。
  • 結果には件名、送信者、作成時間、スレッドID、およびFTSを使用する場合はハイライトされたスニペットが表示されます。
  • エージェントパネルには、プロジェクトに登録されているエージェントが表示され、各受信箱へのリンクがあります。
  • プロジェクトヘッダーにはファイル予約と添付ファイルへのクイックリンクがあります。

• /mail/{project}/inbox/{agent}（1つのエージェントの受信箱）

  • 逆時系列のリストで、件名、送信者、作成時間、重要度バッジ、スレッドIDが表示されます。
  • ページネーション（?page=N&limit=M）。

• /mail/{project}/message/{id}（メッセージ詳細）

  • 件名、送信者、作成時間、重要度、受信者（To/Cc/Bcc）、スレッドメッセージが表示されます。
  • 本文のレンダリング：
    • サーバーがMarkdownをHTMLに事前変換した場合は、Bleachでサニタイズされ（制限されたタグ/属性、CSSSanitizerを使用した安全なCSS）、表示されます。
    • それ以外の場合は、Marked + Prismを使用してクライアントサイドでMarkdownがレンダリングされ、コードがハイライトされます。
  • 添付ファイルはメッセージのフロントマターから参照されます（WebPファイルまたはインラインデータURI）。

• /mail/{project}/search?q=...（専用の検索ページ）

  • プロジェクト概要の検索と同じクエリ構文を使用し、フィルターを組み立て/削除するためのトークン「ピル」UIがあります。

• /mail/{project}/file_reservations（ファイル予約リスト）

  • アクティブなファイル予約と履歴のファイル予約が表示されます（排他的/共有、パスパターン、タイムスタンプ、解放/期限切れの状態）。

• /mail/{project}/attachments（添付ファイル付きのメッセージ）

  • 添付ファイルを含むメッセージが一覧表示され、件名と作成時間が表示されます。

• /mail/unified-inbox（クロスプロジェクトのアクティビティ）

  • すべてのプロジェクトの最近のメッセージが表示され、スレッド数と送信者/受信者が表示されます。

人間オーバーシーヤー：エージェントへのメッセージ送信

時には、人間のオペレーターが緊急の問題を処理したり、説明を提供したり、優先順位を調整したりするために、エージェントを直接ガイドまたはリダイレクトする必要があります。人間オーバーシーヤー機能は、人間がプロジェクト内の任意のエージェントの組み合わせに高優先度のメッセージを送信できるWebベースのメッセージコンポーザーを提供します。

アクセス方法：任意のプロジェクトビュー（/mail/{project}）のヘッダーにある目立つ**「メッセージを送信」**ボタン（オーバーシーヤーバッジ付き）をクリックするか、直接/mail/{project}/overseer/composeに移動します。

オーバーシーヤーメッセージの特徴

1. 自動的なプリアンブル：すべてのメッセージには、人間のオペレーターからのメッセージであることを明確に示し、エージェントに以下のことを指示するフォーマットされたプリアンブルが含まれています。
   • 現在の作業を一時的に中断する。
   • 人間の要求を既存のタスクよりも優先する。
   • その後、元の計画を再開する（指示によって変更されない限り）。
2. 高優先度：すべてのオーバーシーヤーメッセージは自動的に高重要度としてマークされ、エージェントの受信箱で目立つようになります。
3. ポリシーバイパス：オーバーシーヤーメッセージは通常の連絡先ポリシーをバイパスするため、人間は常に連絡先設定に関係なく任意のエージェントに到達できます。
4. 特別な送信者ID：メッセージは特別なエージェント名**"HumanOverseer"**（プロジェクトごとに自動的に作成される）から送信され、以下の情報が含まれています。
   • プログラム：WebUI
   • モデル：Human
   • 連絡先ポリシー：open

メッセージのプリアンブル

すべてのオーバーシーヤーメッセージは、このプリアンブルで始まります（自動的に追加されます）。

---

🚨 MESSAGE FROM HUMAN OVERSEER 🚨

This message is from a human operator overseeing this project. Please prioritize
the instructions below over your current tasks.

You should:
1. Temporarily pause your current work
2. Complete the request described below
3. Resume your original plans afterward (unless modified by these instructions)

The human's guidance supersedes all other priorities.

---

[Your message body follows here]

コンポーザーの使用方法

コンポーザーインターフェースは以下を提供します。

• 受信者選択：すべての登録されたエージェントのチェックボックスグリッド（「すべて選択」/「クリア」ショートカット付き）
• 件名：必須項目で、エージェントの受信箱に表示されます。
• メッセージ本文：GitHubフレーバーのMarkdownエディターとプレビュー。
• スレッドID（オプション）：既存の会話を続けるか、新しい会話を開始します。
• プリアンブルプレビュー：エージェントに表示されるメッセージの正確な表示を確認できます。

ユースケースの例

緊急の問題：

Subject: Urgent: Stop migration and revert changes

The database migration in PR #453 is causing data corruption in staging.

Please:
1. Immediately stop any migration-related work
2. Revert commits from the last 2 hours
3. Wait for my review before resuming

I'm investigating the root cause now.

優先順位の調整：

Subject: New Priority: Security Vulnerability

A critical security vulnerability was just disclosed in our auth library.

Drop your current tasks and:
1. Update `auth-lib` to version 2.4.1 immediately
2. Review all usages in src/auth/
3. Run the full security test suite
4. Report status in thread #892

This takes precedence over the refactoring work.

説明の提供：

Subject: Clarification on API design approach

I see you're debating REST vs. GraphQL in thread #234.

Go with REST for now because:
- Our frontend team has more REST experience
- GraphQL adds complexity we don't need yet
- We can always add GraphQL later if needed

Resume the API implementation with REST.

エージェントがオーバーシーヤーメッセージを見る方法

エージェントが受信箱を確認するとき（fetch_inboxまたはresource://inbox/{name}を介して）、オーバーシーヤーメッセージは他のメッセージと同じように表示されますが、以下の点が異なります。

• 送信者：HumanOverseer
• 重要度：high（目立つように表示されます）
• 本文：オーバーシーヤーのプリアンブルで始まり、人間のメッセージが続きます。
• 視覚的な手がかり：Web UIでは、これらのメッセージに特別なハイライトが付く場合があります（将来的な機能強化）。

エージェントは他のメッセージと同じようにオーバーシーヤーメッセージに返信でき、会話スレッドを続けることができます。

技術的な詳細

• 保存方法：オーバーシーヤーメッセージはエージェント間のメッセージと同じように保存されます（Git + SQLite）。
• Git履歴：完全に監査可能で、メッセージはmessages/YYYY/MM/{id}.mdにコミット履歴とともに表示されます。
• スレッドの継続性：既存のスレッドの一部になることも、新しいスレッドを開始することもできます。
• 認証バイパスなし：オーバーシーヤーのコンポーズフォームは、HTTPサーバーの適切な認証が有効になっている場合でも、依然として必要です。

設計哲学

人間オーバーシーヤー機能は以下のように設計されています。

• 明示的：エージェントはガイダンスが人間から来たか他のエージェントから来たかを明確に知ることができます。
• 礼儀正しい：指示はエージェントが既存の作業を持っていることを認識しており、「すべてを捨てる」ことを永久的に要求することはありません。
• 一時的：エージェントは人間の要求が完了したら元の計画を再開するように指示されます。
• 柔軟性：人間はメッセージ本文でこのガイダンスを直接上書きすることができます。

これにより、明確な階層（人間 → エージェント）が作成されると同時に、エージェント通信システムの協調的で礼儀正しい雰囲気が維持されます。

関連プロジェクトの発見

プロジェクトインデックス（/mail）には、AIによる発見システムが搭載されており、フロントエンド + バックエンドや関連するマイクロサービスなど、どのプロジェクトをリンクすべきかをインテリジェントに提案します。

発見の仕組み

1. スマートな分析 システムは複数のシグナルを使用して関係を識別します。

• パターンマッチング：プロジェクト名とパスを比較します（例："my-app-frontend" ↔ "my-app-backend"）。
• AI理解（LLM_ENABLED=trueの場合）：README.md、AGENTS.md、および他のドキュメントを読み取り、各プロジェクトの目的を理解し、自然な関係を検出します。
• 信頼度スコアリング：提案を0-100%でランク付けし、明確な根拠を示します。

2. 美しい提案 関連するプロジェクトは、ダッシュボード上に洗練されたカードとして表示され、以下の情報が含まれています。

• 🎯 マッチの強さを示す視覚的な信頼度インジケーター
• 💬 AIによって生成された関係を説明する根拠
• ✅ リンクを確認 - 提案を受け入れる
• ✖️ 却下 - 関係のないマッチを非表示にする

3. クイックナビゲーション 確認されると、両方のプロジェクトには関連するコードベース間をすぐに移動できるインタラクティブなバッジが表示されます。

なぜ提案をするのか、自動リンクをしないのか

TL;DR：あなたにコントロールを持たせます。発見は関係を見つけるのに役立ち、明示的な承認によって実際に通信できる相手が決まります。

Agent Mailはエージェント中心のメッセージングを使用しています。すべてのメッセージは明示的な許可チェーンに従います。

Send Message → Find Recipient → Check AgentLink Approval → Deliver

この設計により、以下のことが保証されます。

• セキュリティ：誤ったクロスプロジェクトのメッセージ配信が防止されます。
• 透明性：誰が誰と話せるかを常に知ることができます。
• 監査トレイル：すべての通信パスは明示的に承認されます。

なぜAIによる自動リンクをしないのか LLMが自動的にプロジェクト間のメッセージングを許可すると、以下の問題が発生します。

• ❌ 人間の監視なしで連絡先ポリシーをバイパスする。
• ❌ 意図しない受信者にメッセージが誤配信されるリスクがある。
• ❌ 監査が困難な不可視のルーティングパスが作成される。
• ❌ 曖昧な名前のプロジェクトが誤ってリンクされる可能性がある。

代わりに、私たちは発見 + コントロールを提供します。

• ✅ AIが可能性のある関係を提案する（安全で読み取り専用の分析）
• ✅ あなたが適切なものを確認する（1クリックで）
• ✅ エージェントは依然としてrequest_contact / respond_contactを使用して実際のメッセージング権限を取得する
• ✅ 明確な分離：発見 ≠ 承認

完全なワークフロー

1. System suggests: "These projects look related" (AI analysis)
           ↓
2. You confirm: "Yes, link them" (updates UI badges)
           ↓
3. Agents request: request_contact(from_agent, to_agent, to_project)
           ↓
4. You approve: respond_contact(accept=true)
           ↓
5. Messages flow: Agents can now communicate across projects

これはLinkedInのようなものです。システムが接続を提案しますが、実際にメッセージを送信できるのはあなたが決めることです。

検索構文（UI）

UIはAPIの_parse_fts_queryと同じパースを共有します。

• フィールドフィルター：subject:login、body:"api key"
• フレーズ検索："build plan"
• 条件の組み合わせ：login AND security（FTS）
• フォールバックLIKE：スコープによって、件名、本文、または両方が検索されます。

データを表示するための前提条件

UIはMCPツールと同じSQLite + Gitアーティファクトを読み取ります。コンテンツを表示するには、以下のことを行ってください。

1. プロジェクトが存在することを確認する（ツール呼び出しまたはCLIを介して）
   • プロジェクトを確認/作成する：ensure_project(human_key)
2. 1つ以上のエージェントを登録する：register_agent(project_key, program, model, name?)
3. メッセージを送信する：send_message(...)（添付ファイルとインライン画像がサポートされています。画像はWebPに変換される場合があります）。

メッセージが存在するようになったら、/mailにアクセスし、プロジェクトをクリックしてから、エージェントの受信箱を開くか検索してください。

実装と依存関係

• テンプレートはsrc/mcp_agent_mail/templates/にあり、Jinja2によってレンダリングされます。
• Markdownは可能な限りサーバー上でmarkdown2を使用して変換され、HTMLはBleachでサニタイズされます（利用可能な場合はCSSサニタイザーも使用されます）。
• Tailwind CSS、Lucideアイコン、Alpine.js、Marked、およびPrismはbase.htmlでCDNを介して読み込まれ、フロントエンドのビルドステップなしで最新の外観を実現します。
• すべてのレンダリングはサーバーサイドで行われ、SPAルーターはありません。ページはJavaScriptなしでも適切に動作します。

セキュリティに関する考慮事項

• HTMLサニタイズ：保守的なタグ/属性のみが許可され、CSSはフィルタリングされます。リンクはhttp/https/mailto/dataに制限されます。
• 認証：ローカルホスト以外に公開する場合は、ベアラートークンまたはJWTを使用してください。ローカル開発の場合は、上記のようにローカルホストのバイパスを有効にしてください。
• レート制限（オプション）：トークンバケット制限器を有効にすることができます。UIのGETリクエストは軽量で、POST制限の影響を受けません。

UIのトラブルシューティング

• ローカルホストで空白ページまたは401エラーが表示される：HTTP_BEARER_TOKENを設定解除するか、HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=trueを設定してください。
• プロジェクトが表示されない：ensure_projectでプロジェクトを作成してください。
• 受信箱が空の場合：受信者名が正確に一致することを確認し、メッセージがそのエージェントに送信されていることを確認してください。
• 検索結果が表示されない：より単純な条件を試すか、LIKEフォールバックを使用してください（スコープ/本文を切り替えます）。

静的メールボックスエクスポート（共有と配布アーカイブ）

shareコマンドグループは、プロジェクトのメールボックスをポータブルな読み取り専用バンドルにエクスポートします。これにより、監査担当者、利害関係者、またはチームメイトがMCP Agent Mailスタック全体を起動することなく、スレッドを閲覧し、履歴を検索し、配信タイムラインを証明することができます。

なぜ静的バンドルにエクスポートするのか

• コンプライアンスと監査トレイル：プロジェクトの通信の不変のスナップショットを監査担当者またはコンプライアンス担当者に提供します。静的バンドルには改ざん検知用の暗号化署名が含まれています。
• 利害関係者のレビュー：書き込みアクセスが必要ない製品マネージャー、幹部、または外部コンサルタントと会話履歴を共有します。彼らは認証なしでブラウザーでメッセージを閲覧し、スレッドを検索し、添付ファイルを表示することができます。
• オフラインアクセス：エアギャップ環境、災害復旧バックアップ、またはインターネット接続が不安定な状況でポータブルなアーカイブを作成します。
• 長期アーカイブ：数十年後も読み取り可能な形式でプロジェクトの通信を保存します。静的HTMLはデータベースサーバーやランタイム依存関係を必要とせず、独自形式よりもソフトウェアの廃止に耐えます。
• 安全な配布：機密プロジェクトの場合は、バンドルをageで暗号化します。秘密鍵を持つ受信者のみが内容を復号化して表示できます。

エクスポートに含まれる内容

各バンドルには以下が含まれています。

• 自己完結型：すべてが単一のディレクトリ（HTML、CSS/JS、SQLiteスナップショット、添付ファイル）に収められています。静的ホストに配置するか、ローカルで開くことができます。
• 充実したリーダーUI：Gmailスタイルの受信箱で、プロジェクトフィルター、検索、および完全なスレッドレンダリングが可能です。各メッセージはメタデータとMarkdown本文とともに表示され、ライブウェブUIと同じようになります。
• 高速な検索とフィルター：FTSによる検索と事前計算されたメッセージごとの要約により、大規模なアーカイブでもスクロールとフィルタリングが応答性良く行えます。
• 検証可能な整合性：すべてのアセットにSHA-256ハッシュが付けられ、オプションのEd25519署名により、信頼性と改ざんチェックが簡単に行えます。
• チャンク対応のアーカイブ：大規模なデータベースはhttpvfsストリーミング用にチャンク化できます。chunks.sha256ファイルには各チャンクのダイジェストがリストされており、クライアントはハッシュを再計算することなくストリーミングされたブロブを信頼できます。
• ワンクリックホスティング：インタラクティブウィザードにより、GitHub PagesまたはCloudflare Pagesに直接公開できます。または、CLIプレビューコマンドでバンドルをローカルで提供することもできます。

クイックスタート：インタラクティブデプロイメントウィザード

エクスポートとデプロイを行う最も簡単な方法は、GitHub PagesとCloudflare Pagesの両方をサポートするインタラクティブウィザードです。

# CLIを介して（推奨）
uv run python -m mcp_agent_mail.cli share wizard

# またはスクリプトを直接実行
./scripts/share_to_github_pages.py

ウィザードの機能

ウィザードは完全自動のエンドツーエンドのデプロイメントエクスペリエンスを提供します。

1. セッションの再開：中断されたセッションを検出し、中断した場所から再開するオプションを提供し、再エクスポートを回避します。
2. 設定管理：最後の設定を記憶し、再利用するオプションを提供し、繰り返しのエクスポートで時間を節約します。
3. デプロイメントターゲットの選択：GitHub Pages、Cloudflare Pages、またはローカルエクスポートから選択します。
4. 自動CLIインストール：不足しているツール（GitHub用のgh、Cloudflare用のwrangler）を検出してインストールします。
5. ガイド付き認証：GitHubとCloudflareのブラウザーログインフローを段階的に案内します。
6. スマートなプロジェクト選択：
   • すべての利用可能なプロジェクトを整形されたテーブルで表示します。
   • 複数の選択モードをサポートします：all、単一の番号（1）、リスト（1,3,5）、または範囲（1-3、2-5,8）。
   • 前回の選択を記憶し、迅速な再エクスポートを可能にします。
7. レダクション設定：standard（APIキー/トークンなどのシークレットをスクラブし、エージェント名を保持）またはstrict（すべてのメッセージ本文をレダクト）から選択します。
8. 暗号化署名：オプションのEd25519署名を自動キー生成または既存のキーの再利用で行います。
9. 事前検証：エクスポートを開始する前に、GitHubリポジトリ名が利用可能かを確認します。
10. デプロイメント概要：デプロイされる内容（プロジェクト数、バンドルサイズ、ターゲット、署名ステータス）を表示し、確認を求めます。
11. エクスポートとプレビュー：バンドルをエクスポートし、自動ポート検出でインタラクティブなプレビューサーバーを起動します（9000-9100を試します）。
12. インタラクティブなプレビューコントロール：
    • 'r' を押すと、ブラウザーを強制的に更新します（手動でキャッシュを削除し、ビューアーをリフレッシュします）。
    • 'd' を押すと、デプロイを要求します（コード42で終了し、ウィザードが検出してデプロイを続行します）。
    • 'q' を押すと、プレビューサーバーを終了します。
    • Ctrl+C を押すと、プレビューサーバーを停止します。
13. 自動ビューアーアセットのリフレッシュ：バンドルを再利用する場合でも、常にソースツリーから最新のHTML/JS/CSSが使用されるようにします。
14. リアルタイムデプロイメント：gitとデプロイメントの出力をリアルタイムでストリーミングし、進捗状況を追跡できるようにします。
15. 自動デプロイメント：リポジトリを作成し、Pagesを有効にし、コードをプッシュし、ライブURLを提供します。

セッションの再開（最新バージョンの新機能）

ウィザードを中断した場合（ターミナルを閉じる、プレビュー中にCtrl+Cを押すなど）、進捗状況が~/.mcp-agent-mail/wizard-session/に保存されます。ウィザードを再度実行すると、以下のように表示されます。