agent-mail

MCP Agent Mail

HTTP 専用の FastMCP サーバーとして提供される、メールのようなコーディングエージェント向け調整レイヤーです。覚えやすい ID、受信トレイ／送信トレイ、ファイル予約リース、連絡ポリシー、検索可能なメッセージ履歴、人間の監督者とのメッセージ機能を備えています。Git（人間が監査できる成果物）と SQLite（FTS5 による高速なクエリ）を使用します。

これが必要な理由

調整の仕組みがないと、複数のエージェントは次のような問題に直面します。

• お互いの編集を上書きしたり、予期しない差分に慌てたりします
• 並行する作業の重要なコンテキストを見落とします
• ツール間のメッセージの伝達を人間に頼る必要があります

Agent Mail は、次の機能でこれらの問題を解決します。

• 覚えやすい ID（「GreenCastle」のような形容詞＋名詞の名前）
• 編集の意図を示すファイルのアドバイザリー予約
• 重要度レベルと確認応答に対応したスレッド形式のメッセージ
• コミット時に予約を強制するプレコミットガード
• 人間からエージェントへ直接連絡できる人間の監督者

サーバーの起動

# Quickest way (alias added during install)
am

# Or manually
cd ~/projects/mcp_agent_mail
./scripts/run_server_with_token.sh

デフォルト：http://127.0.0.1:8765 人間向けの Web UI：http://127.0.0.1:8765/mail

主な概念

プロジェクト

各作業ディレクトリ（絶対パス）がプロジェクトです。同じディレクトリにいるエージェントは、プロジェクトの名前空間を共有します。連携が必要なエージェントには、同じ project_key を使用してください。

エージェントの ID

エージェントは形容詞＋名詞の名前（GreenCastle、BlueLake）で登録します。名前はプロジェクトごとに一意で、覚えやすく、受信トレイ、コミットログ、Web UI に表示されます。

ファイル予約（リース）

ファイルパスまたは glob に対するアドバイザリーロックです。ファイルを編集する前に予約し、作業の意図を示します。他のエージェントは予約を確認し、別の作業を選べます。任意のプレコミットガードを有効にすると、他のエージェントの排他的予約と競合するコミットをブロックできます。

連絡ポリシー

エージェントごとのポリシーで、誰が誰にメッセージを送れるかを制御します。

ポリシー	動作
open	プロジェクト内のすべてのメッセージを受け入れます
auto（デフォルト）	共通のコンテキストがある場合（同じスレッド、重複する予約、最近の連絡）に許可します
contacts_only	事前に明示的な連絡承認を要求します
block_all	すべての新しい連絡を拒否します

メッセージ

スレッド機能、重要度レベル（low、normal、high、urgent）、任意の確認応答要件に対応した GitHub Flavored Markdown です。画像は自動的に WebP に変換されます。

基本的なワークフロー

1. セッションを開始する（1 回の呼び出しで初期設定）

macro_start_session(
  human_key="/abs/path/to/project",
  program="claude-code",
  model="opus-4.5",
  task_description="Implementing auth module"
)

返される内容：{project, agent, file_reservations, inbox}

この 1 回の呼び出しで、プロジェクトの存在確認、ID の登録、任意のファイル予約、受信トレイの取得を行います。

2. 編集前にファイルを予約する

file_reservation_paths(
  project_key="/abs/path/to/project",
  agent_name="GreenCastle",
  paths=["src/auth/**/*.ts", "src/middleware/auth.ts"],
  ttl_seconds=3600,
  exclusive=true,
  reason="br-123"
)

返される内容：{granted: [...], conflicts: [...]}

競合が報告されても、予約は許可されます。競合を確認し、必要に応じて調整してください。

3. 作業内容を知らせる

send_message(
  project_key="/abs/path/to/project",
  sender_name="GreenCastle",
  to=["BlueLake"],
  subject="[br-123] Starting auth refactor",
  body_md="Reserving src/auth/**. Will update session handling.",
  thread_id="br-123",
  importance="normal",
  ack_required=true
)

4. 定期的に受信トレイを確認する

fetch_inbox(
  project_key="/abs/path/to/project",
  agent_name="GreenCastle",
  limit=20,
  urgent_only=false,
  include_bodies=true
)

または、リソースを使ってすばやく読み取れます。

resource://inbox/GreenCastle?project=/abs/path&limit=20&include_bodies=true

5. 作業が終わったら予約を解除する

release_file_reservations(
  project_key="/abs/path/to/project",
  agent_name="GreenCastle"
)

4 つのマクロ

速度と小規模モデルでの利用を優先する場合は、マクロを使用してください。細かく制御する必要がある場合は、個別のツールを使用してください。

マクロ	目的
macro_start_session	初期設定：プロジェクトを確認 → エージェントを登録 → 任意のファイル予約 → 受信トレイを取得
macro_prepare_thread	既存の会話に参加：登録 → スレッドを要約 → 受信トレイのコンテキストを取得
macro_file_reservation_cycle	ファイルを予約して作業し、任意で完了時に自動解除
macro_contact_handshake	連絡許可を要求し、任意で自動承認して、ウェルカムメッセージを送信

Beads 連携（br-### ワークフロー）

タスク管理に Beads を使用する場合は、識別子を一致させてください。

1. Pick ready work:     br ready --json → choose br-123
2. Reserve files:       file_reservation_paths(..., reason="br-123")
3. Announce start:      send_message(..., thread_id="br-123", subject="[br-123] Starting...")
4. Work and update:     Reply in thread with progress
5. Complete:            br close br-123
                        release_file_reservations(...)
                        send_message(..., subject="[br-123] Completed")

br-### を次の用途に使用します。

• メールの thread_id
• メッセージの件名プレフィックス [br-###]
• ファイル予約の reason
• コミットメッセージの参照

Beads Viewer（bv）との連携

bv のロボットフラグを使って、タスクをインテリジェントに選択します。

フラグ	出力	用途
bv --robot-insights	PageRank、クリティカルパス、サイクル	「最も影響が大きいのは何ですか？」
bv --robot-plan	並列トラック、ブロック解除	「並行して進められるのは何ですか？」
bv --robot-priority	信頼度付きの推奨事項	「次に取り組むべきことは何ですか？」
bv --robot-diff --diff-since <ref>	コミット／日付以降の変更	「何が変わりましたか？」

目安： タスク操作には br を使い、タスクの分析には bv を使います。

プロジェクト間の調整

フロントエンド／バックエンド、または複数のリポジトリにまたがるプロジェクトの場合：

オプション A：共有 project_key 両方のリポジトリで同じ project_key を使います。エージェントは自動的に連携します。

オプション B：連絡リンクを使った個別プロジェクト

# Backend agent requests contact with frontend agent
request_contact(
  project_key="/abs/path/backend",
  from_agent="GreenCastle",
  to_agent="BlueLake",
  to_project="/abs/path/frontend",
  reason="API contract coordination"
)

# Frontend agent accepts
respond_contact(
  project_key="/abs/path/frontend",
  to_agent="BlueLake",
  from_agent="GreenCastle",
  accept=true
)

コミット前のガード

他のエージェントの排他的な予約と競合するコミットをブロックするには、ガードをインストールします。

install_precommit_guard(
  project_key="/abs/path/to/project",
  code_repo_path="/abs/path/to/project"
)

ガードの機能

• 既存フックを維持：チェーンランナーは hooks.d/ 内の既存フックを保持します
• 名前変更に対応：名前変更／移動の前後の両方のパスを確認します
• NUL セーフ：特殊文字を含むパスを処理します
• Git ネイティブの照合：Git の wildmatch pathspec セマンティクスを使用します

ガードがユーザーを識別できるよう、AGENT_NAME 環境変数を設定します。

緊急時のバイパス：AGENT_MAIL_BYPASS=1 git commit ...

ツールのリファレンス

プロジェクトと ID

ツール	目的
ensure_project(human_key)	プロジェクトを作成／存在確認します
register_agent(project_key, program, model, name?, task_description?)	ID を登録します
whois(project_key, agent_name)	最近のコミットを含むエージェントのプロフィールを取得します
create_agent_identity(project_key, program, model)	常に新しい一意のエージェントを作成します

メッセージ

ツール	目的
send_message(project_key, sender, to, subject, body_md, ...)	メッセージを送信します
reply_message(project_key, message_id, sender, body_md)	返信します（スレッドを維持します）
fetch_inbox(project_key, agent, limit?, since_ts?, urgent_only?)	メッセージを取得します
mark_message_read(project_key, agent, message_id)	既読にします
acknowledge_message(project_key, agent, message_id)	受信を確認します
search_messages(project_key, query)	FTS5 検索
summarize_thread(project_key, thread_id)	要点とアクションを抽出します

ファイル予約

ツール	目的
file_reservation_paths(project_key, agent, paths, ttl?, exclusive?)	ファイルを予約します
release_file_reservations(project_key, agent, paths?)	予約を解除します
renew_file_reservations(project_key, agent, extend_seconds?)	TTL を延長します
force_release_file_reservation(project_key, agent, reservation_id)	古い予約を解除します

連絡先の管理

ツール	目的
request_contact(project_key, from_agent, to_agent, reason?)	メッセージを送る許可をリクエストします
respond_contact(project_key, to_agent, from_agent, accept)	連絡リクエストを承認／拒否します
list_contacts(project_key, agent_name)	連絡リンクを一覧表示します
set_contact_policy(project_key, agent_name, policy)	open／auto／contacts_only／block_all を設定します

リソース（すばやく読み取る場合）

変更を伴わない読み取りをすばやく行うには、リソースを使用します。

resource://inbox/{agent}?project=<path>&limit=20&include_bodies=true
resource://thread/{thread_id}?project=<path>&include_bodies=true
resource://message/{id}?project=<path>
resource://file_reservations/{slug}?active_only=true
resource://project/{slug}
resource://projects
resource://agents/{project_key}

検索構文（FTS5）

"exact phrase"
prefix*
term1 AND term2
term1 OR term2
subject:login
body:"api key"
(auth OR login) AND NOT admin

例：search_messages(project_key, '"auth module" AND error NOT legacy')

Web UI の機能

http://127.0.0.1:8765/mail で閲覧できます。

• すべてのプロジェクトを横断する統合受信トレイ
• FTS5 を使ったプロジェクトごとの検索
• Markdown 表示に対応したスレッドビューア
• ファイル予約ブラウザー
• Human Overseer：Web UI からエージェントに優先度の高いメッセージを送信します
• 関連プロジェクトの検出：リポジトリのリンク候補を AI で提案します

Human Overseer

自動の前置き付きで、エージェントにダイレクトメッセージを送信します。

• メッセージの重要度は high に設定されます
• 連絡ポリシーをバイパスします
• エージェントには、現在の作業を一時停止し、リクエストを完了してから作業を再開するよう指示されます

静的メールボックスエクスポート

監査担当者、関係者、またはアーカイブ向けに、プロジェクトを移植可能な読み取り専用バンドルとしてエクスポートします。

# Interactive wizard (recommended)
uv run python -m mcp_agent_mail.cli share wizard

# Manual export
uv run python -m mcp_agent_mail.cli share export --output ./bundle

# With signing
uv run python -m mcp_agent_mail.cli share export \
  --output ./bundle \
  --signing-key ./keys/signing.key

# Preview locally
uv run python -m mcp_agent_mail.cli share preview ./bundle

エクスポート機能

• Ed25519 による暗号署名
• 機密情報の配布に使う Age 暗号化
• サニタイズのプリセット：standard（シークレットを削除）または strict（本文をマスキング）
• ウィザードを使って GitHub Pages または Cloudflare Pages にデプロイ

災害復旧

# Save current state
uv run python -m mcp_agent_mail.cli archive save --label nightly

# List restore points
uv run python -m mcp_agent_mail.cli archive list --json

# Restore after disaster
uv run python -m mcp_agent_mail.cli archive restore <file>.zip --force

メールボックスの健全性（Doctor）

# Run diagnostics
uv run python -m mcp_agent_mail.cli doctor check

# Preview repairs
uv run python -m mcp_agent_mail.cli doctor repair --dry-run

# Apply repairs (creates backup first)
uv run python -m mcp_agent_mail.cli doctor repair

チェック項目：古いロック、データベースの整合性、孤立したレコード、FTS の同期、期限切れの予約。

よくある落とし穴

エラー	解決方法
"sender_name not registered"	最初に register_agent または macro_start_session を呼び出します
"FILE_RESERVATION_CONFLICT"	期限切れを待つか、調整するか、排他的でない方法を使用します
"CONTACT_BLOCKED"	request_contact を使用し、承認を待ちます
受信トレイが空	since_ts と urgent_only を確認し、エージェント名が完全に一致することを確認します

インストール

# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

# Custom port
curl -fsSL ... | bash -s -- --port 9000 --yes

# Change port after installation
uv run python -m mcp_agent_mail.cli config set-port 9000

主な環境変数

変数	デフォルト値	説明
STORAGE_ROOT	~/.mcp_agent_mail_git_mailbox_repo	リポジトリと SQLite DB のルート
HTTP_PORT	8765	サーバーポート
HTTP_BEARER_TOKEN	—	認証用の静的ベアラートークン
LLM_ENABLED	true	要約／検出に LLM を有効化
CONTACT_ENFORCEMENT_ENABLED	true	連絡ポリシーを適用

Docker

docker build -t mcp-agent-mail .
docker run --rm -p 8765:8765 \
  -e HTTP_HOST=0.0.0.0 \
  -v agent_mail_data:/data \
  mcp-agent-mail

Flywheel との連携

ツール	連携方法
NTM	エージェントのペインがメールで連携し、ダッシュボードに受信トレイを表示します
BV	タスク ID がスレッド ID になり、ロボットフラグがタスク選択に反映されます
CASS	セッションをまたいでメールスレッドを検索します
CM	メールアーカイブから手順に関するメモリを抽出します
DCG	ブロックされたコマンドをエージェントにメールで通知します
RU	プロジェクト間メールを使って複数リポジトリの更新を調整します