Skip to content
Back to search

mcp_agent_mail

Asynchronous coordination layer for AI coding agents: identities, inboxes, searchable threads, and advisory file leases over FastMCP + Git + SQLite

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Dicklesworthstone/mcp_agent_mail with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Dicklesworthstone/mcp_agent_mail'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dicklesworthstone--mcp-agent-mail/badge.svg)](/listings/dicklesworthstone--mcp-agent-mail)

HTML

<a href="/listings/dicklesworthstone--mcp-agent-mail"><img src="/api/listings/dicklesworthstone--mcp-agent-mail/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

One-line installer

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

What this does:

- Installs uv if missing and updates your PATH for this session - Installs jq if missing (needed for safe config merging; auto-detects your package manager) - Creates a Python 3.14 virtual environment and installs dependencies with uv - Runs the auto-detect integration to wire up supported agent tools - Starts the MCP HTTP server on port 8765 and prints a masked bearer token - Creates helper scripts under `scripts/` (including `run_server_with_token.sh`) - Adds an `am` shell alias to your `.zshrc` or `.bashrc` for quick server startup (just type `am` in a new terminal!) - Installs **Beads Rust (`br`)**, a Rust reimplementation of the Beads task tracker, and creates a `bd` shell alias pointing to `br` for backwards compatibility. This replaces any existing `bd` (Go) installation. Pass `--skip-beads` to opt out. See [beads_rust](https://github.com/Dicklesworthstone/beads_rust) for details on CLI differences. - Installs/updates the Beads Viewer `bv` TUI for interactive task browsing and AI-friendly robot commands (pass `--skip-bv` to opt out) - Prints a short on-exit summary of each setup step so you immediately know what changed

Prefer a specific location or options? Add flags like `--dir <path>`, `--project-dir <path>`, `--no-start`, `--start-only`, `--port <number>`, or `--token <hex>`.

Already have Beads or Beads Viewer installed? Append `--skip-beads` and/or `--skip-bv` to bypass automatic installation.

Important: Beads Rust (br) Replaces Beads Go (bd)

The installer automatically replaces `bd` (the original Go-based Beads CLI) with `br` (Beads Rust):

1. **`br` is the actively maintained version.** Beads Rust is a complete reimplementation with ongoing development, while the original Go version is no longer actively maintained.

2. **Existing `bd` users get automatic aliasing.** The installer creates a shell alias so that `bd` commands continue to work by redirecting to `br`. Your existing workflows and muscle memory are preserved.

3. **A migration skill is installed for agents.** AI coding agents receive a `bd-br-migration` skill that helps them adapt to any CLI differences between the two implementations.

4. **Same data format, compatible workflows.** Both implementations use the same `.beads/issues.jsonl` format, so your existing Beads data remains fully compatible.

To opt out of this replacement, pass `--skip-beads` to the installer. See the [beads_rust repository](https://github.com/Dicklesworthstone/beads_rust) for detailed documentation on CLI differences.

Starting the server in the future

After installation, you can start the MCP Agent Mail server from **anywhere** by simply typing:

am

That's it! The `am` alias (added to your `.zshrc` or `.bashrc` during installation) automatically: 1. Changes to the MCP Agent Mail directory 2. Runs the server startup script (which uses `uv run` to handle the virtual environment) 3. Loads your saved bearer token from `.env` and starts the HTTP server

**Note:** If you just ran the installer, open a new terminal or run `source ~/.zshrc` (or `source ~/.bashrc`) to load the alias.

**Port conflicts?** Use `--port` to specify a different port (default: 8765):

Install with custom port:

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

Or use the CLI command after installation: uv run python -m mcp_agent_mail.cli config set-port 9000


### If you want to do it yourself

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 421 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: agent-mail
  3. description: "MCP Agent Mail - Mail-like coordination layer for multi-agent workflows. Identities, inbox/outbox, file reservations, contact policies, threaded messaging, pre-commit guard, Human Overseer, static exports, disaster recovery. Git+SQLite backed. Python/FastMCP."
  4. ---
  5. # MCP Agent Mail
  6. A mail-like coordination layer for coding agents exposed as an HTTP-only FastMCP server. Provides memorable identities, inbox/outbox, file reservation leases, contact policies, searchable message history, and Human Overseer messaging. Backed by Git (human-auditable artifacts) and SQLite (fast queries with FTS5).
  7. ## Why This Exists
  8. Without coordination, multiple agents:
  9. - Overwrite each other's edits or panic on unexpected diffs
  10. - Miss critical context from parallel workstreams
  11. - Require humans to relay messages between tools
  12. Agent Mail solves this with:
  13. - Memorable identities (adjective+noun names like "GreenCastle")
  14. - Advisory file reservations to signal editing intent
  15. - Threaded messaging with importance levels and acknowledgments
  16. - Pre-commit guard to enforce reservations at commit time
  17. - Human Overseer for direct human-to-agent communication
  18. ## Starting the Server
  19. ```bash
  20. # Quickest way (alias added during install)
  21. am
  22. # Or manually
  23. cd ~/projects/mcp_agent_mail
  24. ./scripts/run_server_with_token.sh
  25. ```
  26. Default: `http://127.0.0.1:8765`
  27. Web UI for humans: `http://127.0.0.1:8765/mail`
  28. ## Core Concepts
  29. ### Projects
  30. Each working directory (absolute path) is a project. Agents in the same directory share a project namespace. Use the same `project_key` for agents that need to coordinate.
  31. ### Agent Identity
  32. Agents register with adjective+noun names (GreenCastle, BlueLake). Names are unique per project, memorable, and appear in inboxes, commit logs, and the web UI.
  33. ### File Reservations (Leases)
  34. Advisory locks on file paths or globs. Before editing files, reserve them to signal intent. Other agents see the reservation and can choose different work. The optional pre-commit guard blocks commits that conflict with others' exclusive reservations.
  35. ### Contact Policies
  36. Per-agent policies control who can message whom:
  37. | Policy | Behavior |
  38. |--------|----------|
  39. | `open` | Accept any message in the project |
  40. | `auto` (default) | Allow if shared context exists (same thread, overlapping reservations, recent contact) |
  41. | `contacts_only` | Require explicit contact approval first |
  42. | `block_all` | Reject all new contacts |
  43. ### Messages
  44. GitHub-Flavored Markdown with threading, importance levels (`low`, `normal`, `high`, `urgent`), and optional acknowledgment requirements. Images are auto-converted to WebP.
  45. ## Essential Workflow
  46. ### 1. Start Session (One-Call Bootstrap)
  47. ```
  48. macro_start_session(
  49. human_key="/abs/path/to/project",
  50. program="claude-code",
  51. model="opus-4.5",
  52. task_description="Implementing auth module"
  53. )
  54. ```
  55. Returns: `{project, agent, file_reservations, inbox}`
  56. This single call: ensures project exists, registers your identity, optionally reserves files, fetches your inbox.
  57. ### 2. Reserve Files Before Editing
  58. ```
  59. file_reservation_paths(
  60. project_key="/abs/path/to/project",
  61. agent_name="GreenCastle",
  62. paths=["src/auth/**/*.ts", "src/middleware/auth.ts"],
  63. ttl_seconds=3600,
  64. exclusive=true,
  65. reason="bd-123"
  66. )
  67. ```
  68. Returns: `{granted: [...], conflicts: [...]}`
  69. Conflicts are reported but reservations are still granted. Check conflicts and coordinate if needed.
  70. ### 3. Announce Your Work
  71. ```
  72. send_message(
  73. project_key="/abs/path/to/project",
  74. sender_name="GreenCastle",
  75. to=["BlueLake"],
  76. subject="[bd-123] Starting auth refactor",
  77. body_md="Reserving src/auth/**. Will update session handling.",
  78. thread_id="bd-123",
  79. importance="normal",
  80. ack_required=true
  81. )
  82. ```
  83. ### 4. Check Inbox Periodically
  84. ```
  85. fetch_inbox(
  86. project_key="/abs/path/to/project",
  87. agent_name="GreenCastle",
  88. limit=20,
  89. urgent_only=false,
  90. include_bodies=true
  91. )
  92. ```
  93. Or use resources for fast reads:
  94. ```
  95. resource://inbox/GreenCastle?project=/abs/path&limit=20&include_bodies=true
  96. ```
  97. ### 5. Release Reservations When Done
  98. ```
  99. release_file_reservations(
  100. project_key="/abs/path/to/project",
  101. agent_name="GreenCastle"
  102. )
  103. ```
  104. ## The Four Macros
  105. Prefer macros for speed and smaller models. Use granular tools when you need fine control.
  106. | Macro | Purpose |
  107. |-------|---------|
  108. | `macro_start_session` | Bootstrap: ensure project → register agent → optional file reservations → fetch inbox |
  109. | `macro_prepare_thread` | Join existing conversation: register → summarize thread → fetch inbox context |
  110. | `macro_file_reservation_cycle` | Reserve files, do work, optionally auto-release when done |
  111. | `macro_contact_handshake` | Request contact permission, optionally auto-accept, send welcome message |
  112. ## Beads Integration (bd-### Workflow)
  113. When using Beads for task management, keep identifiers aligned:
  114. ```
  115. 1. Pick ready work: bd ready --json → choose bd-123
  116. 2. Reserve files: file_reservation_paths(..., reason="bd-123")
  117. 3. Announce start: send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")
  118. 4. Work and update: Reply in thread with progress
  119. 5. Complete: bd close bd-123
  120. release_file_reservations(...)
  121. send_message(..., subject="[bd-123] Completed")
  122. ```
  123. Use `bd-###` as:
  124. - Mail `thread_id`
  125. - Message subject prefix `[bd-###]`
  126. - File reservation `reason`
  127. - Commit message reference
  128. ## Beads Viewer (bv) Integration
  129. Use bv's robot flags for intelligent task selection:
  130. | Flag | Output | Use Case |
  131. |------|--------|----------|
  132. | `bv --robot-insights` | PageRank, critical path, cycles | "What's most impactful?" |
  133. | `bv --robot-plan` | Parallel tracks, unblocks | "What can run in parallel?" |
  134. | `bv --robot-priority` | Recommendations with confidence | "What should I work on next?" |
  135. | `bv --robot-diff --diff-since <ref>` | Changes since commit/date | "What changed?" |
  136. **Rule of thumb:** Use `bd` for task operations, use `bv` for task intelligence.
  137. ## Cross-Project Coordination
  138. For frontend/backend or multi-repo projects:
  139. **Option A: Shared project_key**
  140. Both repos use the same `project_key`. Agents coordinate automatically.
  141. **Option B: Separate projects with contact links**
  142. ```
  143. # Backend agent requests contact with frontend agent
  144. request_contact(
  145. project_key="/abs/path/backend",
  146. from_agent="GreenCastle",
  147. to_agent="BlueLake",
  148. to_project="/abs/path/frontend",
  149. reason="API contract coordination"
  150. )
  151. # Frontend agent accepts
  152. respond_contact(
  153. project_key="/abs/path/frontend",
  154. to_agent="BlueLake",
  155. from_agent="GreenCastle",
  156. accept=true
  157. )
  158. ```
  159. ## Pre-Commit Guard
  160. Install the guard to block commits that conflict with others' exclusive reservations:
  161. ```
  162. install_precommit_guard(
  163. project_key="/abs/path/to/project",
  164. code_repo_path="/abs/path/to/project"
  165. )
  166. ```
  167. ### Guard Features
  168. - **Composition-safe**: Chain-runner preserves existing hooks in `hooks.d/`
  169. - **Rename-aware**: Checks both old and new paths for renames/moves
  170. - **NUL-safe**: Handles paths with special characters
  171. - **Git-native matching**: Uses Git wildmatch pathspec semantics
  172. Set `AGENT_NAME` environment variable so the guard knows who you are.
  173. Bypass in emergencies: `AGENT_MAIL_BYPASS=1 git commit ...`
  174. ## Tools Reference
  175. ### Project & Identity
  176. | Tool | Purpose |
  177. |------|---------|
  178. | `ensure_project(human_key)` | Create/ensure project exists |
  179. | `register_agent(project_key, program, model, name?, task_description?)` | Register identity |
  180. | `whois(project_key, agent_name)` | Get agent profile with recent commits |
  181. | `create_agent_identity(project_key, program, model)` | Always create new unique agent |
  182. ### Messaging
  183. | Tool | Purpose |
  184. |------|---------|
  185. | `send_message(project_key, sender, to, subject, body_md, ...)` | Send message |
  186. | `reply_message(project_key, message_id, sender, body_md)` | Reply (preserves thread) |
  187. | `fetch_inbox(project_key, agent, limit?, since_ts?, urgent_only?)` | Get messages |
  188. | `mark_message_read(project_key, agent, message_id)` | Mark as read |
  189. | `acknowledge_message(project_key, agent, message_id)` | Acknowledge receipt |
  190. | `search_messages(project_key, query)` | FTS5 search |
  191. | `summarize_thread(project_key, thread_id)` | Extract key points and actions |
  192. ### File Reservations
  193. | Tool | Purpose |
  194. |------|---------|
  195. | `file_reservation_paths(project_key, agent, paths, ttl?, exclusive?)` | Reserve files |
  196. | `release_file_reservations(project_key, agent, paths?)` | Release reservations |
  197. | `renew_file_reservations(project_key, agent, extend_seconds?)` | Extend TTL |
  198. | `force_release_file_reservation(project_key, agent, reservation_id)` | Clear stale reservation |
  199. ### Contact Management
  200. | Tool | Purpose |
  201. |------|---------|
  202. | `request_contact(project_key, from_agent, to_agent, reason?)` | Request permission to message |
  203. | `respond_contact(project_key, to_agent, from_agent, accept)` | Accept/deny contact request |
  204. | `list_contacts(project_key, agent_name)` | List contact links |
  205. | `set_contact_policy(project_key, agent_name, policy)` | Set open/auto/contacts_only/block_all |
  206. ## Resources (Fast Reads)
  207. Use resources for quick, non-mutating reads:
  208. ```
  209. resource://inbox/{agent}?project=<path>&limit=20&include_bodies=true
  210. resource://thread/{thread_id}?project=<path>&include_bodies=true
  211. resource://message/{id}?project=<path>
  212. resource://file_reservations/{slug}?active_only=true
  213. resource://project/{slug}
  214. resource://projects
  215. resource://agents/{project_key}
  216. ```
  217. ## Search Syntax (FTS5)
  218. ```
  219. "exact phrase"
  220. prefix*
  221. term1 AND term2
  222. term1 OR term2
  223. subject:login
  224. body:"api key"
  225. (auth OR login) AND NOT admin
  226. ```
  227. Example: `search_messages(project_key, '"auth module" AND error NOT legacy')`
  228. ## Web UI Features
  229. Browse at `http://127.0.0.1:8765/mail`:
  230. - **Unified inbox** across all projects
  231. - **Per-project search** with FTS5
  232. - **Thread viewer** with markdown rendering
  233. - **File reservations** browser
  234. - **Human Overseer**: Send high-priority messages to agents from the web UI
  235. - **Related Projects Discovery**: AI-powered suggestions for linking repos
  236. ### Human Overseer
  237. Send direct messages to agents with automatic preamble:
  238. - Messages marked as `high` importance
  239. - Bypasses contact policies
  240. - Agents are instructed to pause current work, complete request, then resume
  241. ## Static Mailbox Export
  242. Export projects to portable, read-only bundles for auditors, stakeholders, or archives:
  243. ```bash
  244. # Interactive wizard (recommended)
  245. uv run python -m mcp_agent_mail.cli share wizard
  246. # Manual export
  247. uv run python -m mcp_agent_mail.cli share export --output ./bundle
  248. # With signing
  249. uv run python -m mcp_agent_mail.cli share export \
  250. --output ./bundle \
  251. --signing-key ./keys/signing.key
  252. # Preview locally
  253. uv run python -m mcp_agent_mail.cli share preview ./bundle
  254. ```
  255. ### Export Features
  256. - Ed25519 cryptographic signing
  257. - Age encryption for confidential distribution
  258. - Scrub presets: `standard` (removes secrets) or `strict` (redacts bodies)
  259. - Deploy to GitHub Pages or Cloudflare Pages via wizard
  260. ## Disaster Recovery
  261. ```bash
  262. # Save current state
  263. uv run python -m mcp_agent_mail.cli archive save --label nightly
  264. # List restore points
  265. uv run python -m mcp_agent_mail.cli archive list --json
  266. # Restore after disaster
  267. uv run python -m mcp_agent_mail.cli archive restore <file>.zip --force
  268. ```
  269. ## Mailbox Health (Doctor)
  270. ```bash
  271. # Run diagnostics
  272. uv run python -m mcp_agent_mail.cli doctor check
  273. # Preview repairs
  274. uv run python -m mcp_agent_mail.cli doctor repair --dry-run
  275. # Apply repairs (creates backup first)
  276. uv run python -m mcp_agent_mail.cli doctor repair
  277. ```
  278. Checks: stale locks, database integrity, orphaned records, FTS sync, expired reservations.
  279. ## Common Pitfalls
  280. | Error | Fix |
  281. |-------|-----|
  282. | "sender_name not registered" | Call `register_agent` or `macro_start_session` first |
  283. | "FILE_RESERVATION_CONFLICT" | Wait for expiry, coordinate, or use non-exclusive |
  284. | "CONTACT_BLOCKED" | Use `request_contact` and wait for approval |
  285. | Empty inbox | Check `since_ts`, `urgent_only`, verify agent name matches exactly |
  286. ## Installation
  287. ```bash
  288. # One-liner (recommended)
  289. curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes
  290. # Custom port
  291. curl -fsSL ... | bash -s -- --port 9000 --yes
  292. # Change port after installation
  293. uv run python -m mcp_agent_mail.cli config set-port 9000
  294. ```
  295. ## Key Environment Variables
  296. | Variable | Default | Description |
  297. |----------|---------|-------------|
  298. | `STORAGE_ROOT` | `~/.mcp_agent_mail_git_mailbox_repo` | Root for repos and SQLite DB |
  299. | `HTTP_PORT` | `8765` | Server port |
  300. | `HTTP_BEARER_TOKEN` | — | Static bearer token for auth |
  301. | `LLM_ENABLED` | `true` | Enable LLM for summaries/discovery |
  302. | `CONTACT_ENFORCEMENT_ENABLED` | `true` | Enforce contact policy (when `false`, explicit cross-project sends skip the approved-link requirement; `block_all` still honored) |
  303. ## Docker
  304. ```bash
  305. docker build -t mcp-agent-mail .
  306. docker run --rm -p 8765:8765 \
  307. -e HTTP_HOST=0.0.0.0 \
  308. -v agent_mail_data:/data \
  309. mcp-agent-mail
  310. ```
  311. ## Integration with Flywheel
  312. | Tool | Integration |
  313. |------|-------------|
  314. | **NTM** | Agent panes coordinate via mail, dashboard shows inbox |
  315. | **BV** | Task IDs become thread IDs, robot flags inform task selection |
  316. | **CASS** | Search mail threads across sessions |
  317. | **CM** | Extract procedural memory from mail archives |
  318. | **DCG** | Mail notifies agents of blocked commands |
  319. | **RU** | Coordinate multi-repo updates via cross-project mail |
README.md · README · 2,624 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Agent Mail
  2. > **Superseded by [mcp_agent_mail_rust](https://github.com/Dicklesworthstone/mcp_agent_mail_rust).** This Python version is no longer maintained; use the Rust version for new installs.
  3. ![Agent Mail Showcase](screenshots/output/agent_mail_showcase.gif)
  4. > "It's like gmail for your coding agents!"
  5. A mail-like coordination layer for coding agents, exposed as an HTTP-only FastMCP server. It gives agents memorable identities, an inbox/outbox, searchable message history, and voluntary file reservation "leases" to avoid stepping on each other.
  6. Think of it as asynchronous email + directory + change-intent signaling for your agents, backed by Git (for human-auditable artifacts) and SQLite (for indexing and queries).
  7. Status: Maintenance mode. This Python implementation is superseded by the Rust rewrite and is no longer actively developed; new installs should use [mcp_agent_mail_rust](https://github.com/Dicklesworthstone/mcp_agent_mail_rust). The original design is captured in detail in `docs/planning/project_idea_and_guide.md` (start with the original prompt at the top of that file).
  8. ## Why this exists
  9. Modern projects often run multiple coding agents at once (backend, frontend, scripts, infra). Without a shared coordination fabric, agents:
  10. - Overwrite each other's edits or panic on unexpected diffs
  11. - Miss critical context from parallel workstreams
  12. - Require humans to "liaison" messages across tools and teams
  13. This project provides a lightweight, interoperable layer so agents can:
  14. - Register a temporary-but-persistent identity (e.g., GreenCastle)
  15. - Send/receive GitHub-Flavored Markdown messages with images
  16. - Search, summarize, and thread conversations
  17. - Declare advisory file reservations (leases) on files/globs to signal intent
  18. - Inspect a directory of active agents, programs/models, and activity
  19. It's designed for: FastMCP clients and CLI tools (Claude Code, Codex, Gemini CLI, Factory Droid, etc.) coordinating across one or more codebases.
  20. ## From Idea Spark to Shipping Swarm
  21. If a blank repo feels daunting, follow the field-tested workflow we documented in `docs/planning/project_idea_and_guide.md` (“Appendix: From Blank Repo to Coordinated Swarm”):
  22. - **Ideate fast:** Write a scrappy email-style blurb about the problem, desired UX, and any must-have stack picks (≈15 minutes).
  23. - **Promote it to a plan:** Feed that blurb to GPT-5 Pro (and optionally Grok4 Heavy / Opus 4.1) until you get a granular Markdown plan, then iterate on the plan file while it’s still cheap to change. The Markdown Web Browser sample plan shows the level of detail to aim for.
  24. - **Codify the rules:** Clone a tuned `AGENTS.md`, add any tech-specific best-practice guides, and let Codex scaffold the repo plus Beads tasks straight from the plan.
  25. - **Spin up the swarm:** Launch multiple Codex panes (or any agent mix), register each identity with Agent Mail, and have them acknowledge `AGENTS.md`, the plan document, and the Beads backlog before touching code.
  26. - **Keep everyone fed:** Reuse the canned instruction cadence from the tweet thread or, better yet, let the commercial Companion app’s Message Stacks broadcast those prompts automatically so you never hand-feed panes again.
  27. Watch the full 23-minute walkthrough (https://youtu.be/68VVcqMEDrs?si=pCm6AiJAndtZ6u7q) to see the loop in action.
  28. ## Productivity Math & Automation Loop
  29. One disciplined hour of GPT-5 Codex—when it isn’t waiting on human prompts—often produces 10–20 “human hours” of work because the agents reason and type at machine speed. Agent Mail multiplies that advantage in two layers:
  30. 1. **Base OSS server:** Git-backed mailboxes, advisory file reservations, Typer CLI helpers, and searchable archives keep independent agents aligned without babysitting. Every instruction, lease, and attachment is auditable.
  31. 2. **Companion stack (commercial):** The iOS app + host automation can provision, pair, and steer heterogeneous fleets (Claude Code, Codex, Gemini CLI, Factory Droid, etc.) from your phone using customizable Message Stacks, Human Overseer broadcasts, Beads awareness, and plan editing tools—no manual tmux choreography required. The automation closes the loop by scheduling prompts, honoring Limited Mode, and enforcing Double-Arm confirmations for destructive work.
  32. Result: you invest 1–2 hours of human supervision, but dozens of agent-hours execute in parallel with clear audit trails and conflict-avoidance baked in.
  33. ## TLDR Quickstart
  34. ### One-line installer
  35. ```bash
  36. curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes
  37. ```
  38. What this does:
  39. - Installs uv if missing and updates your PATH for this session
  40. - Installs jq if missing (needed for safe config merging; auto-detects your package manager)
  41. - Creates a Python 3.14 virtual environment and installs dependencies with uv
  42. - Runs the auto-detect integration to wire up supported agent tools
  43. - Starts the MCP HTTP server on port 8765 and prints a masked bearer token
  44. - Creates helper scripts under `scripts/` (including `run_server_with_token.sh`)
  45. - Adds an `am` shell alias to your `.zshrc` or `.bashrc` for quick server startup (just type `am` in a new terminal!)
  46. - Installs **Beads Rust (`br`)**, a Rust reimplementation of the Beads task tracker, and creates a `bd` shell alias pointing to `br` for backwards compatibility. This replaces any existing `bd` (Go) installation. Pass `--skip-beads` to opt out. See [beads_rust](https://github.com/Dicklesworthstone/beads_rust) for details on CLI differences.
  47. - Installs/updates the Beads Viewer `bv` TUI for interactive task browsing and AI-friendly robot commands (pass `--skip-bv` to opt out)
  48. - Prints a short on-exit summary of each setup step so you immediately know what changed
  49. Prefer a specific location or options? Add flags like `--dir <path>`, `--project-dir <path>`, `--no-start`, `--start-only`, `--port <number>`, or `--token <hex>`.
  50. Already have Beads or Beads Viewer installed? Append `--skip-beads` and/or `--skip-bv` to bypass automatic installation.
  51. ### Important: Beads Rust (br) Replaces Beads Go (bd)
  52. The installer automatically replaces `bd` (the original Go-based Beads CLI) with `br` (Beads Rust):
  53. 1. **`br` is the actively maintained version.** Beads Rust is a complete reimplementation with ongoing development, while the original Go version is no longer actively maintained.
  54. 2. **Existing `bd` users get automatic aliasing.** The installer creates a shell alias so that `bd` commands continue to work by redirecting to `br`. Your existing workflows and muscle memory are preserved.
  55. 3. **A migration skill is installed for agents.** AI coding agents receive a `bd-br-migration` skill that helps them adapt to any CLI differences between the two implementations.
  56. 4. **Same data format, compatible workflows.** Both implementations use the same `.beads/issues.jsonl` format, so your existing Beads data remains fully compatible.
  57. To opt out of this replacement, pass `--skip-beads` to the installer. See the [beads_rust repository](https://github.com/Dicklesworthstone/beads_rust) for detailed documentation on CLI differences.
  58. ### Starting the server in the future
  59. After installation, you can start the MCP Agent Mail server from **anywhere** by simply typing:
  60. ```bash
  61. am
  62. ```
  63. That's it! The `am` alias (added to your `.zshrc` or `.bashrc` during installation) automatically:
  64. 1. Changes to the MCP Agent Mail directory
  65. 2. Runs the server startup script (which uses `uv run` to handle the virtual environment)
  66. 3. Loads your saved bearer token from `.env` and starts the HTTP server
  67. **Note:** If you just ran the installer, open a new terminal or run `source ~/.zshrc` (or `source ~/.bashrc`) to load the alias.
  68. **Port conflicts?** Use `--port` to specify a different port (default: 8765):
  69. Install with custom port:
  70. ```bash
  71. curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --port 9000 --yes
  72. ```
  73. Or use the CLI command after installation:
  74. uv run python -m mcp_agent_mail.cli config set-port 9000
  75. ```
  76. ### If you want to do it yourself
  77. Clone the repo, set up and install with uv in a python 3.14 venv (install uv if you don't have it already), and then run `scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh`. This will automatically set things up for your various installed coding agent tools and start the MCP server on port 8765. If you want to run the MCP server again in the future, simply run `scripts/run_server_with_token.sh`:
  78. Install uv (if you don't have it already):
  79. ```bash
  80. curl -LsSf https://astral.sh/uv/install.sh | sh
  81. export PATH="$HOME/.local/bin:$PATH"
  82. # Clone the repo
  83. git clone https://github.com/Dicklesworthstone/mcp_agent_mail
  84. cd mcp_agent_mail
  85. # Create a Python 3.14 virtual environment and install dependencies
  86. # Note: If you have an older uv version, run `uv self update` first
  87. uv python install 3.14
  88. uv venv -p 3.14
  89. source .venv/bin/activate
  90. uv sync
  91. # Detect installed coding agents, integrate, and start the MCP server on port 8765
  92. scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh
  93. # Later, to run the MCP server again with the same token
  94. scripts/run_server_with_token.sh
  95. # Now, simply launch Codex-CLI or Claude Code or other agent tools in other consoles; they should have the mail tool available. See below for a ready-made chunk of text you can add to the end of your existing AGENTS.md or CLAUDE.md files to help your agents better utilize the new tools.
  96. # Change port after installation
  97. uv run python -m mcp_agent_mail.cli config set-port 9000
  98. ```
  99. ## Ready-Made Blurb to Add to Your AGENTS.md or CLAUDE.md Files:
  100. <!-- BEGIN_AGENT_MAIL_SNIPPET -->
  101. ```
  102. ## MCP Agent Mail: coordination for multi-agent workflows
  103. What it is
  104. - A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.
  105. - Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.
  106. Why it's useful
  107. - Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.
  108. - Keeps communication out of your token budget by storing messages in a per-project archive.
  109. - Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.
  110. How to use effectively
  111. 1) Same repository
  112. - Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.
  113. - Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.
  114. - Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.
  115. - Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20&agent_token=<registration_token>` or `resource://thread/{id}?project=<abs-path>&agent=<Agent>&agent_token=<registration_token>&include_bodies=true` unless the current MCP session already authenticated as that agent.
  116. - Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.
  117. 2) Across different repos in one project (e.g., Next.js frontend + FastAPI backend)
  118. - Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).
  119. - Option B (separate projects): each repo has its own `project_key`; use `macro_contact_handshake` or `request_contact`/`respond_contact` to link agents, then message directly. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.
  120. Macros vs granular tools
  121. - Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.
  122. - Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.
  123. Common pitfalls
  124. - "from_agent not registered": always `register_agent` in the correct `project_key` first.
  125. - "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.
  126. - Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.
  127. ```
  128. <!-- END_AGENT_MAIL_SNIPPET -->
  129. ## Integrating with Beads (dependency-aware task planning)
  130. Beads is a lightweight task planner that complements Agent Mail by keeping status and dependencies in one place while Mail handles messaging, file reservations, and audit trails.
  131. **Note on implementations:** The MCP Agent Mail installer installs [Beads Rust (`br`)](https://github.com/Dicklesworthstone/beads_rust), a Rust reimplementation, and creates a `bd` alias for backwards compatibility. The original Go implementation is at [steveyegge/beads](https://github.com/steveyegge/beads). Both share the same data format (`.beads/issues.jsonl`) but have some CLI differences. Use `--skip-beads` during installation if you prefer to manage this yourself.
  132. Highlights:
  133. - Beads owns task prioritization; Agent Mail carries the conversations and artifacts.
  134. - Shared identifiers (e.g., `bd-123`) keep Beads issues, Mail threads, and commits aligned.
  135. - The `br` CLI (aliased as `bd`) provides similar functionality to the original with some enhancements.
  136. Copy/paste blurb for agent-facing docs (leave as-is for reuse):
  137. <!-- BEGIN_BEADS_SNIPPET -->
  138. ```
  139. ## Integrating with Beads (dependency-aware task planning)
  140. Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: [steveyegge/beads](https://github.com/steveyegge/beads)
  141. Recommended conventions
  142. - **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).
  143. - **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.
  144. - **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.
  145. Typical flow (agents)
  146. 1) **Pick ready work** (Beads)
  147. - `bd ready --json` → choose one item (highest priority, no blockers)
  148. 2) **Reserve edit surface** (Mail)
  149. - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`
  150. 3) **Announce start** (Mail)
  151. - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`
  152. 4) **Work and update**
  153. - Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id
  154. 5) **Complete and release**
  155. - `bd close bd-123 --reason "Completed"` (Beads is status authority)
  156. - `release_file_reservations(project_key, agent_name, paths=["src/**"])`
  157. - Final Mail reply: `[bd-123] Completed` with summary and links
  158. Mapping cheat-sheet
  159. - **Mail `thread_id`** ↔ `bd-###`
  160. - **Mail subject**: `[bd-###] …`
  161. - **File reservation `reason`**: `bd-###`
  162. - **Commit messages (optional)**: include `bd-###` for traceability
  163. Event mirroring (optional automation)
  164. - On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.
  165. - On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.
  166. Pitfalls to avoid
  167. - Don't create or manage tasks in Mail; treat Beads as the single task queue.
  168. - Always include `bd-###` in message `thread_id` to avoid ID drift across tools.
  169. ```
  170. <!-- END_BEADS_SNIPPET -->
  171. Prefer automation? Run `uv run python -m mcp_agent_mail.cli docs insert-blurbs` to scan your code directories for `AGENTS.md`/`CLAUDE.md` files and append the latest Agent Mail + Beads snippets with per-project confirmation. The installer also offers to launch this helper right after setup so you can take care of onboarding docs immediately.
  172. ## Beads Viewer (bv) — AI-Friendly Task Analysis
  173. The Beads Viewer (`bv`) is a fast terminal UI for Beads projects that also provides **robot flags** designed specifically for AI agent integration. Project: [Dicklesworthstone/beads_viewer](https://github.com/Dicklesworthstone/beads_viewer)
  174. ### Why bv for Agents?
  175. While `bd` (Beads CLI) handles task CRUD operations, `bv` provides **precomputed graph analytics** that help agents make intelligent prioritization decisions:
  176. - **PageRank scores**: Identify high-impact tasks that unblock the most downstream work
  177. - **Critical path analysis**: Find the longest dependency chain to completion
  178. - **Cycle detection**: Spot circular dependencies before they cause deadlocks
  179. - **Parallel track planning**: Determine which tasks can run concurrently
  180. Instead of agents parsing `.beads/issues.jsonl` directly or attempting to compute graph metrics (risking hallucinated results), they can call bv's deterministic robot flags and get JSON output they can trust. Legacy `.beads/beads.jsonl` is deprecated in this repo.
  181. ### Robot Flags for AI Integration
  182. | Flag | Output | Agent Use Case |
  183. |------|--------|----------------|
  184. | `bv --robot-help` | All AI-facing commands | Discovery / capability check |
  185. | `bv --robot-insights` | PageRank, betweenness, HITS, critical path, cycles | Quick triage: "What's most impactful?" |
  186. | `bv --robot-plan` | Parallel tracks, items per track, unblocks lists | Execution planning: "What can run in parallel?" |
  187. | `bv --robot-priority` | Priority recommendations with reasoning + confidence | Task selection: "What should I work on next?" |
  188. | `bv --robot-recipes` | Available filter presets (actionable, blocked, etc.) | Workflow setup: "Show me ready work" |
  189. | `bv --robot-diff --diff-since <ref>` | Changes since commit/date, new/closed items, cycles | Progress tracking: "What changed?" |
  190. ### Example: Agent Task Selection Workflow
  191. ```bash
  192. # 1. Get priority recommendations with reasoning
  193. bv --robot-priority
  194. # Returns JSON with ranked tasks, impact scores, and confidence levels
  195. # 2. Check what completing a task would unblock
  196. bv --robot-plan
  197. # Returns parallel tracks showing dependency chains
  198. # 3. After completing work, check what changed
  199. bv --robot-diff --diff-since "1 hour ago"
  200. # Returns new items, closed items, cycle changes
  201. ```
  202. ### When to Use bv vs bd
  203. | Tool | Best For |
  204. |------|----------|
  205. | `bd` | Creating, updating, closing tasks; `bd ready` for simple "what's next" |
  206. | `bv` | Graph analysis, impact assessment, parallel planning, change tracking |
  207. **Rule of thumb**: Use `bd` for task operations, use `bv` for task intelligence.
  208. ### Integration with Agent Mail
  209. Combine bv insights with Agent Mail coordination:
  210. 1. **Agent A** runs `bv --robot-priority` → identifies `bd-42` as highest-impact
  211. 2. **Agent A** reserves files: `file_reservation_paths(..., reason="bd-42")`
  212. 3. **Agent A** announces: `send_message(..., thread_id="bd-42", subject="[bd-42] Starting high-impact refactor")`
  213. 4. **Other agents** see the reservation and Mail announcement, pick different tasks
  214. 5. **Agent A** completes, runs `bv --robot-diff` to report downstream unblocks
  215. This creates a feedback loop where graph intelligence drives coordination.
  216. ## Core ideas (at a glance)
  217. - FastMCP server over Streamable HTTP (primary transport; no SSE). A STDIO transport (`serve-stdio`) is also available for direct CLI integration.
  218. - Dual persistence model:
  219. - Human-readable markdown in a per-project Git repo for every canonical message and per-recipient inbox/outbox copy
  220. - SQLite with FTS5 for fast search, directory queries, and file reservations/leases
  221. - "Directory/LDAP" style queries for agents; memorable adjective+noun names
  222. - Advisory file reservations for editing surfaces; optional pre-commit guard
  223. - Resource layer for convenient reads (e.g., `resource://inbox/{agent}`)
  224. ## Typical use cases
  225. - Multiple agents splitting a large refactor across services while staying in sync
  226. - Frontend and backend teams of agents coordinating thread-by-thread
  227. - Protecting critical migrations with exclusive file reservations and a pre-commit guard
  228. - Searching and summarizing long technical discussions as threads evolve
  229. - Discovering and linking related projects (e.g., frontend/backend) through AI-powered suggestions
  230. ## Workflow FAQ
  231. **Do I still need the tmux broadcast script to “feed” every Codex pane?**
  232. No. The historical zsh loop from the tweet thread is still handy if you are running the OSS stack by itself, but the AgentMail Companion system now automates that cadence with Message Stacks. Once the companion host services are installed, you queue presets (builder loop, reviewer sweep, test focus, etc.) from the iOS app or CLI and the automation fans those instructions out to every enrolled agent—without touching tmux.
  233. ## Architecture
  234. ```mermaid
  235. graph LR
  236. A[Agents]
  237. S[Server]
  238. G[Git repo]
  239. Q[SQLite FTS5]
  240. A -->|HTTP tools/resources| S
  241. S -->|writes/reads| G
  242. S -->|indexes/queries| Q
  243. subgraph GitTree["Git tree"]
  244. GI1[agents/profile.json]
  245. GI2[agents/mailboxes/...]
  246. GI3[messages/YYYY/\nMM/\nid.md]
  247. GI4[file_reservations/\nsha1.json]
  248. GA[attachments/xx/\nsha1.webp]
  249. end
  250. G --- GI1
  251. G --- GI2
  252. G --- GI3
  253. G --- GI4
  254. G --- GA
  255. ```
  256. ## Web UI (human-facing mail viewer)
  257. The server ships a lightweight, server-rendered Web UI for humans. It lets you browse projects, agents, inboxes, single messages, attachments, file reservations, and perform full-text search with FTS5 when available (with an automatic LIKE fallback).
  258. - Where it lives: built into the HTTP server in `mcp_agent_mail.http` under the `/mail` path.
  259. - Who it's for: humans reviewing activity; agents should continue to use the MCP tools/resources API.
  260. ### Launching the Web UI
  261. Recommended (simple):
  262. ```bash
  263. scripts/run_server_with_token.sh
  264. # then open http://127.0.0.1:8765/mail
  265. ```
  266. Advanced (manual commands):
  267. ```bash
  268. uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765
  269. # or:
  270. uv run uvicorn mcp_agent_mail.http:create_app --factory --host 127.0.0.1 --port 8765
  271. ```
  272. Auth notes:
  273. - GET pages in the UI are not gated by the RBAC middleware (it classifies POSTed MCP calls only), but if you set a bearer token the separate BearerAuth middleware protects all routes by default.
  274. - For local dev, set `HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=true` (and optionally `HTTP_BEARER_TOKEN`), so localhost can load the UI without headers.
  275. - Health endpoints are always open at `/health/*`.
  276. ### Routes and what you can do
  277. - `/mail` (Unified inbox + Projects + Related Projects Discovery)
  278. - Shows a unified, reverse-chronological inbox of recent messages across all projects with excerpts, relative timestamps, sender/recipients, and project badges.
  279. - Below the inbox, lists all projects (slug, human name, created time) with sibling suggestions.
  280. - Suggests **likely sibling projects** when two slugs appear to be parts of the same product (e.g., backend vs. frontend). Suggestions are ranked with heuristics and, when `LLM_ENABLED=true`, an LLM pass across key docs (`README.md`, `AGENTS.md`, etc.).
  281. - Humans can **Confirm Link** or **Dismiss** suggestions from the dashboard. Confirmed siblings become highlighted badges but *do not* automatically authorize cross-project messaging; agents must still establish `AgentLink` approvals via `request_contact`/`respond_contact`.
  282. - `/mail/projects` (Projects index)
  283. - Dedicated projects list view; click a project to drill in.
  284. - `/mail/{project}` (Project overview + search + agents)
  285. - Rich search form with filters:
  286. - Scope: subject/body/both, Order: relevance or time, optional "boost subject".
  287. - Query tokens: supports `subject:foo`, `body:"multi word"`, quoted phrases, and bare terms.
  288. - Uses FTS5 bm25 scoring when available; otherwise falls back to SQL LIKE on subject/body with your chosen scope.
  289. - Results show subject, sender, created time, thread id, and a highlighted snippet when using FTS.
  290. - Agents panel shows registered agents for the project with a link to each inbox.
  291. - Quick links to File Reservations and Attachments for the project header.
  292. - `/mail/{project}/inbox/{agent}` (Inbox for one agent)
  293. - Reverse-chronological list with subject, sender, created time, importance badge, thread id.
  294. - Pagination (`?page=N&limit=M`).
  295. - `/mail/{project}/message/{id}` (Message detail)
  296. - Shows subject, sender, created time, importance, recipients (To/Cc/Bcc), thread messages.
  297. - Body rendering:
  298. - If the server pre-converted markdown to HTML, it's sanitized with Bleach (limited tags/attributes, safe CSS via CSSSanitizer) and then displayed.
  299. - Otherwise markdown is rendered client-side with Marked + Prism for code highlighting.
  300. - Attachments are referenced from the message frontmatter (WebP files or inline data URIs).
  301. - `/mail/{project}/search?q=...` (Dedicated search page)
  302. - Same query syntax as the project overview search, with a token "pill" UI for assembling/removing filters.
  303. - `/mail/{project}/file_reservations` (File Reservations list)
  304. - Displays active and historical file reservations (exclusive/shared, path pattern, timestamps, released/expired state).
  305. - `/mail/{project}/attachments` (Messages with attachments)
  306. - Lists messages that contain any attachments, with subject and created time.
  307. - `/mail/unified-inbox` (Cross-project activity)
  308. - Shows recent messages across all projects with thread counts and sender/recipients.
  309. ### Human Overseer: Sending Messages to Agents
  310. Sometimes a human operator needs to guide or redirect agents directly, whether to handle an urgent issue, provide clarification, or adjust priorities. The **Human Overseer** feature provides a web-based message composer that lets humans send high-priority messages to any combination of agents in a project.
  311. **Access:** Click the prominent **"Send Message"** button (with the Overseer badge) in the header of any project view (`/mail/{project}`), or navigate directly to `/mail/{project}/overseer/compose`.
  312. #### What Makes Overseer Messages Special
  313. 1. **Automatic Preamble**: Every message includes a formatted preamble that clearly identifies it as coming from a human operator and instructs agents to:
  314. - **Pause current work** temporarily
  315. - **Prioritize the human's request** over existing tasks
  316. - **Resume original plans** afterward (unless modified by the instructions)
  317. 2. **High Priority**: All overseer messages are automatically marked as **high importance**, ensuring they stand out in agent inboxes.
  318. 3. **Policy Bypass**: Overseer messages bypass normal contact policies, so humans can always reach any agent regardless of their contact settings.
  319. 4. **Special Sender Identity**: Messages come from a special agent named **"HumanOverseer"** (automatically created per project) with:
  320. - Program: `WebUI`
  321. - Model: `Human`
  322. - Contact Policy: `open`
  323. #### The Message Preamble
  324. Every overseer message begins with this preamble (automatically prepended):
  325. ```
  326. ---
  327. 🚨 MESSAGE FROM HUMAN OVERSEER 🚨
  328. This message is from a human operator overseeing this project. Please prioritize
  329. the instructions below over your current tasks.
  330. You should:
  331. 1. Temporarily pause your current work
  332. 2. Complete the request described below
  333. 3. Resume your original plans afterward (unless modified by these instructions)
  334. The human's guidance supersedes all other priorities.
  335. ---
  336. [Your message body follows here]
  337. ```
  338. #### Using the Composer
  339. The composer interface provides:
  340. - **Recipient Selection**: Checkbox grid of all registered agents (with "Select All" / "Clear" shortcuts)
  341. - **Subject Line**: Required, shown in agent inboxes
  342. - **Message Body**: GitHub-flavored Markdown editor with preview
  343. - **Thread ID** (optional): Continue an existing conversation or start a new one
  344. - **Preamble Preview**: See exactly how your message will appear to agents
  345. #### Example Use Cases
  346. **Urgent Issue:**
  347. ```
  348. Subject: Urgent: Stop migration and revert changes
  349. The database migration in PR #453 is causing data corruption in staging.
  350. Please:
  351. 1. Immediately stop any migration-related work
  352. 2. Revert commits from the last 2 hours
  353. 3. Wait for my review before resuming
  354. I'm investigating the root cause now.
  355. ```
  356. **Priority Adjustment:**
  357. ```
  358. Subject: New Priority: Security Vulnerability
  359. A critical security vulnerability was just disclosed in our auth library.
  360. Drop your current tasks and:
  361. 1. Update `auth-lib` to version 2.4.1 immediately
  362. 2. Review all usages in src/auth/
  363. 3. Run the full security test suite
  364. 4. Report status in thread #892
  365. This takes precedence over the refactoring work.
  366. ```
  367. **Clarification:**
  368. ```
  369. Subject: Clarification on API design approach
  370. I see you're debating REST vs. GraphQL in thread #234.
  371. Go with REST for now because:
  372. - Our frontend team has more REST experience
  373. - GraphQL adds complexity we don't need yet
  374. - We can always add GraphQL later if needed
  375. Resume the API implementation with REST.
  376. ```
  377. #### How Agents See Overseer Messages
  378. When agents check their inbox (via `fetch_inbox` or `resource://inbox/{name}`), overseer messages appear like any other message but with:
  379. - **Sender**: `HumanOverseer`
  380. - **Importance**: `high` (displayed prominently)
  381. - **Body**: Starts with the overseer preamble, followed by the human's message
  382. - **Visual cues**: In the Web UI, these messages may have special highlighting (future enhancement)
  383. Agents can reply to overseer messages just like any other message, continuing the conversation thread.
  384. #### Technical Details
  385. - **Storage**: Overseer messages are stored identically to agent-to-agent messages (Git + SQLite)
  386. - **Git History**: Fully auditable; message appears in `messages/YYYY/MM/{id}.md` with commit history
  387. - **Thread Continuity**: Can be part of existing threads or start new ones
  388. - **No Authentication Bypass**: The overseer compose form still requires proper HTTP server authentication (if enabled)
  389. #### Design Philosophy
  390. The Human Overseer feature is designed to be:
  391. - **Explicit**: Agents clearly know when guidance comes from a human vs. another agent
  392. - **Respectful**: Instructions acknowledge agents have existing work and shouldn't just "drop everything" permanently
  393. - **Temporary**: Agents are told to resume original plans once the human's request is complete
  394. - **Flexible**: Humans can override this guidance directly in their message body
  395. This creates a clear hierarchy (human → agents) while maintaining the collaborative, respectful tone of the agent communication system.
  396. ### Related Projects Discovery
  397. The Projects index (`/mail`) features an **AI-powered discovery system** that intelligently suggests which projects should be linked together, such as frontend + backend or related microservices.
  398. #### How Discovery Works
  399. **1. Smart Analysis**
  400. The system uses multiple signals to identify relationships:
  401. - **Pattern matching**: Compares project names and paths (e.g., "my-app-frontend" ↔ "my-app-backend")
  402. - **AI understanding** (when `LLM_ENABLED=true`): Reads `README.md`, `AGENTS.md`, and other docs to understand each project's purpose and detect natural relationships
  403. - **Confidence scoring**: Ranks suggestions from 0-100% with clear rationales
  404. **2. Beautiful Suggestions**
  405. Related projects appear as polished cards on your dashboard with:
  406. - 🎯 Visual confidence indicators showing match strength
  407. - 💬 AI-generated rationales explaining the relationship
  408. - ✅ **Confirm Link** - accept the suggestion
  409. - ✖️ **Dismiss** - hide irrelevant matches
  410. **3. Quick Navigation**
  411. Once confirmed, both projects display interactive badges for instant navigation between related codebases.
  412. #### Why Suggestions, Not Auto-Linking?
  413. > **TL;DR**: We keep you in control. Discovery helps you find relationships; explicit approvals control who can actually communicate.
  414. **Agent Mail uses agent-centric messaging**: every message follows explicit permission chains:
  415. ```
  416. Send Message → Find Recipient → Check AgentLink Approval → Deliver
  417. ```
  418. This design ensures:
  419. - **Security**: No accidental cross-project message delivery
  420. - **Transparency**: You always know who can talk to whom
  421. - **Audit trails**: All communication paths are explicitly approved
  422. **Why not auto-link with AI?**
  423. If we let an LLM automatically authorize messaging between projects, we'd be:
  424. - ❌ Bypassing contact policies without human oversight
  425. - ❌ Risking message misdelivery to unintended recipients
  426. - ❌ Creating invisible routing paths that are hard to audit
  427. - ❌ Potentially linking ambiguously-named projects incorrectly
  428. Instead, we give you **discovery + control**:
  429. - ✅ AI suggests likely relationships (safe, read-only analysis)
  430. - ✅ You confirm what makes sense (one click)
  431. - ✅ Agents still use `request_contact` / `respond_contact` for actual messaging permissions
  432. - ✅ Clear separation: discovery ≠ authorization
  433. #### The Complete Workflow
  434. ```
  435. 1. System suggests: "These projects look related" (AI analysis)
  436. ↓
  437. 2. You confirm: "Yes, link them" (updates UI badges)
  438. ↓
  439. 3. Agents request: request_contact(from_agent, to_agent, to_project)
  440. ↓
  441. 4. You approve: respond_contact(accept=true)
  442. ↓
  443. 5. Messages flow: Agents can now communicate across projects
  444. ```
  445. **Think of it like LinkedIn**: The system suggests connections, but only *you* decide who gets to send messages.
  446. ### Search syntax (UI)
  447. The UI shares the same parsing as the API's `_parse_fts_query`:
  448. - Field filters: `subject:login`, `body:"api key"`
  449. - Phrase search: `"build plan"`
  450. - Combine terms: `login AND security` (FTS)
  451. - Fallback LIKE: scope determines whether subject, body, or both are searched
  452. ### Prerequisites to see data
  453. The UI reads from the same SQLite + Git artifacts as the MCP tools. To populate content:
  454. 1) Ensure a project exists (via tool call or CLI):
  455. - Ensure/create project: `ensure_project(human_key)`
  456. 2) Register one or more agents: `register_agent(project_key, program, model, name?)`
  457. 3) Send messages: `send_message(...)` (attachments and inline images are supported; images may be converted to WebP).
  458. Once messages exist, visit `/mail`, click your project, then open an agent inbox or search.
  459. ### Implementation and dependencies
  460. - Templates live in `src/mcp_agent_mail/templates/` and are rendered by Jinja2.
  461. - Markdown is converted with `markdown2` on the server where possible; HTML is sanitized with Bleach (with CSS sanitizer when available).
  462. - Tailwind CSS, Lucide icons, Alpine.js, Marked, and Prism are loaded via CDN in `base.html` for a modern look without a frontend build step.
  463. - All rendering is server-side; there's no SPA router. Pages degrade cleanly without JavaScript.
  464. ### Security considerations
  465. - HTML sanitization: Only a conservative set of tags/attributes are allowed; CSS is filtered. Links are limited to http/https/mailto/data.
  466. - Auth: Use bearer token or JWT when exposing beyond localhost. For local dev, enable localhost bypass as noted above.
  467. - Rate limiting (optional): Token-bucket limiter can be enabled; UI GET requests are light and unaffected by POST limits.
  468. ### Troubleshooting the UI
  469. - Blank page or 401 on localhost: Either unset `HTTP_BEARER_TOKEN` or set `HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=true`.
  470. - No projects listed: Create one with `ensure_project`.
  471. - Empty inbox: Verify recipient names match exactly and messages were sent to that agent.
  472. - Search returns nothing: Try simpler terms or the LIKE fallback (toggle scope/body).
  473. ## Static Mailbox Export (Share & Distribute Archives)
  474. The `share` command group exports a project’s mailbox into a portable, read‑only bundle that anyone can review in a browser. It’s designed for auditors, stakeholders, or teammates who need to browse threads, search history, or prove delivery timelines without spinning up the full MCP Agent Mail stack.
  475. ### Why export to static bundles?
  476. **Compliance and audit trails**: Deliver immutable snapshots of project communication to auditors or compliance officers. The static bundle includes cryptographic signatures for tamper-evident distribution.
  477. **Stakeholder review**: Share conversation history with product managers, executives, or external consultants who don't need write access. They can browse messages, search threads, and view attachments in their browser without authentication.
  478. **Offline access**: Create portable archives for air-gapped environments, disaster recovery backups, or situations where internet connectivity is unreliable.
  479. **Long-term archival**: Preserve project communication in a format that will remain readable decades from now. Static HTML requires no database server, no runtime dependencies, and survives software obsolescence better than proprietary formats.
  480. **Secure distribution**: Encrypt bundles with age for confidential projects. Only recipients with the private key can decrypt and view the contents.
  481. ### What's included in an export
  482. Each bundle contains:
  483. - **Self-contained**: Everything ships in a single directory (HTML, CSS/JS, SQLite snapshot, attachments). Drop it on a static host or open it locally.
  484. - **Rich reader UI**: Gmail-style inbox with project filters, search, and full-thread rendering—each message is shown with its metadata and Markdown body, just like in the live web UI.
  485. - **Fast search & filters**: FTS-backed search and precomputed per-message summaries keep scrolling and filtering responsive even with large archives.
  486. - **Verifiable integrity**: SHA-256 hashes for every asset plus optional Ed25519 signing make authenticity and tampering checks straightforward.
  487. - **Chunk-friendly archives**: Large databases can be chunked for httpvfs streaming; a companion `chunks.sha256` file lists digests for each chunk so clients can trust streamed blobs without recomputing hashes.
  488. - **One-click hosting**: The interactive wizard can publish straight to GitHub Pages or Cloudflare Pages, or you can serve the bundle locally with the CLI preview command.
  489. ## Disaster Recovery Archives (`archive` commands)
  490. Use the `archive` subcommands when you need a *restorable* snapshot (not just a read-only share bundle). Each ZIP under `./archived_mailbox_states/` includes:
  491. - A SQLite snapshot processed by the same cleanup pipeline as `share`, but using the `archive` scrub preset so ack/read state, recipients, attachments, and message bodies remain untouched.
  492. - A byte-for-byte copy of the storage Git repo (`STORAGE_ROOT`), preserving markdown artifacts, attachments, and hook scripts.
  493. ### Quick ref
  494. ```bash
  495. # Save current state (defaults to the lossless preset)
  496. uv run python -m mcp_agent_mail.cli archive save --label nightly
  497. # List available restore points (JSON is handy for scripts)
  498. uv run python -m mcp_agent_mail.cli archive list --json
  499. # Restore after a disaster (backs up any existing DB/storage before overwriting)
  500. uv run python -m mcp_agent_mail.cli archive restore archived_mailbox_states/<file>.zip --force
  501. ```
  502. During restore the CLI:
  503. 1. Extracts the ZIP into a temp directory.
  504. 2. Moves any existing `storage.sqlite3`, WAL/SHM siblings, and `STORAGE_ROOT` into timestamped `.backup-<ts>` folders so nothing is lost.
  505. 3. Copies the snapshot back to the configured database path and rebuilds the storage repo from the archive contents.
  506. Every archive writes a `metadata.json` manifest describing the projects captured, scrub preset, and a friendly reminder of the exact `archive restore …` command to run later.
  507. ### Reset safety net
  508. `clear-and-reset-everything` now offers to create one of these archives before deleting anything. By default it prompts interactively; pass `--archive/--no-archive` to force a choice, and pair with `--force --no-archive` for non-interactive automation. When an archive is created successfully, the CLI prints both the path and the restore command so you can undo the reset later.
  509. ## Mailbox Health: `am doctor`
  510. The `doctor` command group provides comprehensive diagnostics and repair capabilities for maintaining mailbox health. It emphasizes **data safety**—creating backups before any destructive operation and using semi-automatic repair to prevent accidental data loss.
  511. ### Why `am doctor`?
  512. Over time, mailbox state can drift:
  513. - **Stale locks**: Process crashes leave behind `.archive.lock` or `.commit.lock` files that block operations
  514. - **Orphaned records**: Agents get deleted but their message recipients remain in the database
  515. - **FTS index desync**: Full-text search index falls out of sync with actual messages
  516. - **Expired file reservations**: Reservations expire but aren't cleaned up
  517. - **WAL files**: SQLite WAL/SHM files accumulate (normal during operation, but worth monitoring)
  518. The doctor commands detect these issues and offer safe, automatic repair.
  519. ### Diagnostic checks
  520. Run comprehensive diagnostics on your mailbox:
  521. ```bash
  522. # Check all projects
  523. uv run python -m mcp_agent_mail.cli doctor check
  524. # Check with verbose output
  525. uv run python -m mcp_agent_mail.cli doctor check --verbose
  526. # JSON output for automation
  527. uv run python -m mcp_agent_mail.cli doctor check --json
  528. ```
  529. **What it checks:**
  530. | Check | Status | Description |
  531. |-------|--------|-------------|
  532. | Locks | OK/WARN | Detects stale archive and commit locks from crashed processes |
  533. | Database | OK/ERROR | Runs `PRAGMA integrity_check` for SQLite corruption |
  534. | Orphaned Records | OK/WARN | Finds message recipients without corresponding agents |
  535. | FTS Index | OK/WARN | Compares message count vs FTS index entries |
  536. | File Reservations | OK/INFO | Counts expired reservations pending cleanup |
  537. | WAL Files | OK/INFO | Reports presence of SQLite WAL/SHM files |
  538. **Example output:**
  539. ```
  540. MCP Agent Mail Doctor - Diagnostic Report
  541. ==================================================
  542. Check Status Details
  543. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  544. Locks OK No stale locks found
  545. Database OK Database integrity check passed
  546. Orphaned OK No orphaned records found
  547. FTS Index OK FTS index synchronized (1,234 messages)
  548. File Res. INFO 4 expired reservation(s) pending cleanup
  549. WAL Files OK No orphan WAL/SHM files
  550. All checks passed!
  551. ```
  552. ### Semi-automatic repair
  553. The repair command uses a **semi-automatic approach**:
  554. - **Safe repairs** (locks, expired reservations) are applied automatically
  555. - **Data-affecting repairs** (orphan cleanup) require confirmation
  556. - A **backup is created before any changes**
  557. ```bash
  558. # Preview what would be repaired (dry-run)
  559. uv run python -m mcp_agent_mail.cli doctor repair --dry-run
  560. # Run repairs with prompts for data changes
  561. uv run python -m mcp_agent_mail.cli doctor repair
  562. # Auto-confirm all repairs (for automation)
  563. uv run python -m mcp_agent_mail.cli doctor repair --yes
  564. # Specify custom backup location
  565. uv run python -m mcp_agent_mail.cli doctor repair --backup-dir /path/to/backups
  566. ```
  567. **Repair workflow:**
  568. 1. **Create backup** — Git bundle + SQLite copy created before any changes
  569. 2. **Safe repairs** (auto-applied):
  570. - Heal stale locks (removes orphaned `.archive.lock`, `.commit.lock` files)
  571. - Release expired file reservations (marks `released_ts` in database)
  572. 3. **Data repairs** (require confirmation):
  573. - Delete orphaned message recipients
  574. - Rebuild FTS index (if needed)
  575. ### Backup management
  576. Doctor creates timestamped backups before repairs. You can also manage backups directly:
  577. ```bash
  578. # List all available backups
  579. uv run python -m mcp_agent_mail.cli doctor backups
  580. # JSON output for scripting
  581. uv run python -m mcp_agent_mail.cli doctor backups --json
  582. ```
  583. **Backup contents:**
  584. Each backup includes:
  585. - `database.sqlite3` — Complete SQLite database copy
  586. - `database.sqlite3-wal`, `database.sqlite3-shm` — WAL files if present
  587. - `archive.bundle` or `{project}.bundle` — Git bundle of the archive repository
  588. - `manifest.json` — Metadata: when created, why, what's included, restore instructions
  589. **Directory structure:**
  590. ```
  591. {storage_root}/backups/
  592. 2026-01-06T12-30-45_doctor-repair/
  593. manifest.json
  594. database.sqlite3
  595. archive.bundle
  596. ```
  597. ### Restore from backup
  598. If something goes wrong, restore from any backup:
  599. ```bash
  600. # Preview what would be restored
  601. uv run python -m mcp_agent_mail.cli doctor restore /path/to/backup --dry-run
  602. # Restore (prompts for confirmation)
  603. uv run python -m mcp_agent_mail.cli doctor restore /path/to/backup
  604. # Skip confirmation prompt
  605. uv run python -m mcp_agent_mail.cli doctor restore /path/to/backup --yes
  606. ```
  607. **Restore process:**
  608. 1. Validates backup manifest exists and is readable
  609. 2. Shows backup metadata (creation time, reason, contents)
  610. 3. **Creates a pre-restore backup** of current state (safety net)
  611. 4. Restores SQLite database from backup
  612. 5. Restores Git archive from bundle
  613. 6. Reports any errors encountered
  614. **Safety features:**
  615. - Current database saved as `*.sqlite3.pre-restore` before overwrite
  616. - Current archive saved as `*.pre-restore` directory before overwrite
  617. - Errors during restore are captured and reported
  618. ### Best practices
  619. 1. **Run diagnostics regularly**: `am doctor check` is fast and non-destructive
  620. 2. **Review before repair**: Use `--dry-run` first to see what would change
  621. 3. **Keep backups**: Don't delete old backups until you've verified the system is healthy
  622. 4. **Automate checks**: Include `am doctor check --json` in your CI/monitoring for early warning
  623. ### Quick Start: Interactive Deployment Wizard
  624. The easiest way to export and deploy is the interactive wizard, which supports both GitHub Pages and Cloudflare Pages:
  625. ```bash
  626. # Via CLI (recommended)
  627. uv run python -m mcp_agent_mail.cli share wizard
  628. # Or run the script directly
  629. ./scripts/share_to_github_pages.py
  630. ```
  631. #### What the wizard does
  632. The wizard provides a fully automated end-to-end deployment experience:
  633. 1. **Session resumption**: Detects interrupted sessions and offers to resume exactly where you left off, avoiding re-export
  634. 2. **Configuration management**: Remembers your last settings and offers to reuse them, saving time on repeated exports
  635. 3. **Deployment target selection**: Choose between GitHub Pages, Cloudflare Pages, or local export
  636. 4. **Automatic CLI installation**: Detects and installs missing tools (`gh` for GitHub, `wrangler` for Cloudflare)
  637. 5. **Guided authentication**: Step-by-step browser login flows for GitHub and Cloudflare
  638. 6. **Smart project selection**:
  639. - Shows all available projects in a formatted table
  640. - Supports multiple selection modes: `all`, single number (`1`), lists (`1,3,5`), or ranges (`1-3`, `2-5,8`)
  641. - Remembers your previous selection for quick re-export
  642. 7. **Redaction configuration**: Choose between `standard` (scrub secrets like API keys/tokens, keep agent names) or `strict` (redact all message bodies)
  643. 8. **Cryptographic signing**: Optional Ed25519 signing with automatic key generation or reuse of existing keys. Generated keys are written to `~/.mcp-agent-mail/signing-keys/` (mode 0700, never to the cwd) so they cannot be accidentally `git add -f`'d into a repository
  644. 9. **Pre-flight validation**: Checks that GitHub repo names are available before starting the export
  645. 10. **Deployment summary**: Shows what will be deployed (project count, bundle size, target, signing status) and asks for confirmation
  646. 11. **Export and preview**: Exports the bundle and launches an interactive preview server with automatic port detection (tries 9000-9100)
  647. 12. **Interactive preview controls**:
  648. - Press **'r'** to force browser refresh (manual cache bust)
  649. - Press **'d'** to skip preview and deploy immediately
  650. - Press **'q'** to quit preview server
  651. 13. **Automatic viewer asset refresh**: Always ensures latest HTML/JS/CSS from source tree are used, even when reusing bundles
  652. 14. **Real-time deployment**: Streams git and deployment output in real-time so you can follow the progress
  653. 15. **Automatic deployment**: Creates repos, enables Pages, pushes code, and gives you the live URL
  654. #### Session resumption (new in latest version)
  655. If you interrupt the wizard (close terminal, Ctrl+C during preview, etc.), it saves your progress to `~/.mcp-agent-mail/wizard-session/`. When you run the wizard again:
  656. ```
  657. Incomplete session detected
  658. Projects: 3 selected
  659. Stage: preview
  660. Workspace: ~/.mcp-agent-mail/wizard-session/bundle
  661. Resume where you left off? (Y/n):
  662. ```
  663. **What gets saved:**
  664. - Selected projects and scrub preset
  665. - Deployment configuration (target, repo name, etc.)
  666. - Signing key preferences and paths
  667. - Exported bundle (in session workspace)
  668. - Current stage (preview, deploy)
  669. **Resume scenarios:**
  670. - **Closed terminal during preview**: Resume → Skip re-export → Launch preview immediately
  671. - **Changed your mind after export**: Resume → "Reuse bundle?" → Preview or re-export
  672. - **Want to deploy later**: Resume → Press 'd' in preview → Deploy without re-exporting
  673. - **Made viewer code changes**: Resume → Assets auto-refresh from source tree
  674. After successful deployment, the session state is automatically cleared. Sessions also clear if they become invalid (workspace deleted, projects removed, etc.).
  675. #### Configuration persistence
  676. The wizard saves your configuration to `~/.mcp-agent-mail/wizard-config.json` after each successful deployment. On subsequent runs, it will show:
  677. ```
  678. Previous Configuration Found
  679. Projects: 3 selected
  680. Redaction: standard
  681. Target: github-new
  682. Use these settings again? (Y/n):
  683. ```
  684. This allows rapid re-deployment with the same settings. The saved configuration includes:
  685. - Selected project indices (validates against current project list)
  686. - Redaction preset
  687. - Deployment target and parameters (repo name, privacy, project name)
  688. - Signing preferences (whether to sign, whether to generate new key)
  689. - Last used signing key path (offered as default when not generating new key)
  690. Configuration is project-agnostic: if you add or remove projects, the wizard validates saved indices and prompts for re-selection if needed.
  691. **Difference between session and config:**
  692. - **Session state** (`wizard-session/`): Temporary, for resuming interrupted runs, includes exported bundle
  693. - **Config file** (`wizard-config.json`): Persistent, for "use last settings" across fresh runs, no bundle
  694. #### Multi-project selection
  695. The project selector supports flexible selection syntax:
  696. ```
  697. Available Projects:
  698. # Slug Path
  699. 1 backend-abc123 /abs/path/backend
  700. 2 frontend-xyz789 /abs/path/frontend
  701. 3 infra-def456 /abs/path/infra
  702. 4 scripts-ghi789 /abs/path/scripts
  703. Select projects to export (e.g., 'all', '1,3,5', or '1-3'):
  704. ```
  705. **Selection modes:**
  706. - `all`: Export all projects (default)
  707. - `1`: Export project #1 only
  708. - `1,3,5`: Export projects #1, #3, and #5
  709. - `1-3`: Export projects #1, #2, and #3 (inclusive range)
  710. - `2-4,7`: Export projects #2, #3, #4, and #7 (combined range and list)
  711. Invalid selections (out of range, malformed) are rejected with helpful error messages and the wizard prompts again.
  712. #### Dynamic port allocation
  713. The preview server automatically detects an available port in the range 9000-9100 instead of failing if port 9000 is in use. The actual port is displayed:
  714. ```
  715. Launching preview server...
  716. Using port 9001 (Ctrl+C to stop server)
  717. Waiting for server to start...
  718. ✓ Server ready, opening browser at http://127.0.0.1:9001
  719. ```
  720. This prevents port conflicts when multiple previews are running or when port 9000 is used by other services.
  721. #### Deployment summary panel
  722. Before starting the export, the wizard shows a comprehensive summary:
  723. ```
  724. ═══ Deployment Summary ═══
  725. Projects: 3 selected
  726. Bundle size: ~32 MB
  727. Redaction: standard
  728. Target: GitHub Pages
  729. Repository: mailbox-viewer-2024
  730. Visibility: Private
  731. Signing: Enabled (Ed25519)
  732. Proceed with export and deployment? (Y/n):
  733. ```
  734. This gives you a final chance to review all settings and cancel if needed. The bundle size is estimated based on ~10 MB per project plus ~2 MB for static assets.
  735. #### Real-time deployment streaming
  736. Git operations and Cloudflare deployments stream output in real-time so you can see exactly what's happening:
  737. ```
  738. Initializing git repository and pushing...
  739. Initializing repository...
  740. Initialized empty Git repository in /tmp/mailbox-preview-abc123/.git/
  741. ✓ Initializing repository complete
  742. Adding files...
  743. ✓ Adding files complete
  744. Creating commit...
  745. [main (root-commit) 1a2b3c4] Initial mailbox export
  746. 425 files changed, 123456 insertions(+)
  747. ✓ Creating commit complete
  748. Pushing to GitHub...
  749. Enumerating objects: 430, done.
  750. Counting objects: 100% (430/430), done.
  751. Delta compression using up to 8 threads
  752. Compressing objects: 100% (425/425), done.
  753. Writing objects: 100% (430/430), 12.34 MiB | 5.67 MiB/s, done.
  754. ✓ Pushing to GitHub complete
  755. ✓ Successfully pushed to owner/mailbox-viewer-2024
  756. ```
  757. This provides transparency and helps diagnose issues if deployment fails.
  758. #### Platform-specific details
  759. **For GitHub Pages:**
  760. - Wizard detects your package manager (brew/apt/dnf) and offers automated installation of `gh` CLI
  761. - For apt/dnf, shows complete manual installation instructions (including repo setup) since automation requires sudo
  762. - Runs `gh auth login` interactively to authenticate via browser
  763. - Creates new repository with your specified name and visibility (public/private)
  764. - Initializes git, commits, and pushes with streaming output
  765. - Enables GitHub Pages automatically via the GitHub API
  766. - Provides the GitHub Pages URL (may take 1-2 minutes to become live)
  767. **For Cloudflare Pages:**
  768. - Detects npm and offers automated installation of `wrangler` CLI
  769. - Runs `wrangler login` interactively to authenticate via browser
  770. - Deploys directly to Cloudflare's global CDN (no git repository needed)
  771. - Streams wrangler output in real-time
  772. - Provides the `.pages.dev` URL immediately (site is live instantly)
  773. - Benefits: instant deployment, 275+ global locations, automatic HTTPS, unlimited requests on free tier
  774. **For local export:**
  775. - Saves bundle to specified directory
  776. - No CLI installation or authentication required
  777. - Suitable for manual deployment to custom hosting or inspection
  778. #### Error handling and recovery
  779. The wizard includes comprehensive error handling:
  780. - **Pre-flight validation**: Checks GitHub repo availability before starting export to avoid conflicts
  781. - **Port conflict resolution**: Automatically finds an available port for preview server
  782. - **Invalid selection handling**: Validates project selections and prompts for correction
  783. - **CLI installation failures**: Shows manual installation instructions if automatic installation fails
  784. - **Git operation failures**: Each git step is validated; stops on first failure with clear error message
  785. - **Deployment failures**: Distinguishes between repo creation, push, and Pages enablement failures
  786. If deployment fails after export, the bundle remains in the temp directory and can be deployed manually using the git commands shown in the manual deployment section below.
  787. The wizard handles all operations automatically. For manual control or advanced options, see the detailed workflows below.
  788. ### Basic export workflow (manual)
  789. **1. Export a bundle**
  790. ```bash
  791. # Export all projects to a directory
  792. uv run python -m mcp_agent_mail.cli share export --output ./my-bundle
  793. # Export specific projects only
  794. uv run python -m mcp_agent_mail.cli share export \
  795. --output ./my-bundle \
  796. --project backend-abc123 \
  797. --project frontend-xyz789
  798. # Export with Ed25519 signing for tamper-evident distribution
  799. uv run python -m mcp_agent_mail.cli share export \
  800. --output ./my-bundle \
  801. --signing-key ./keys/signing.key \
  802. --signing-public-out ./keys/signing.pub
  803. # Export and encrypt with age for secure distribution
  804. uv run python -m mcp_agent_mail.cli share export \
  805. --output ./my-bundle \
  806. --age-recipient age1abc...xyz \
  807. --age-recipient age1def...uvw
  808. ```
  809. The export process:
  810. 1. Creates a snapshot of the SQLite database (read-only, no WAL/SHM files)
  811. 2. Copies message bodies, attachments, and metadata into the bundle structure
  812. 3. Applies redaction rules based on the scrub preset (default: `standard`)
  813. 4. Generates `manifest.json` with SHA-256 hashes for all assets
  814. 5. Optionally signs the manifest with Ed25519 (produces `manifest.sig.json`)
  815. 6. Packages everything into a ZIP archive (optional, enabled by default)
  816. 7. If chunking is enabled, writes the segmented database plus a `chunks.sha256` manifest so streamed pages can be verified cheaply
  817. 8. Optionally encrypts the ZIP with age (produces `bundle.zip.age`)
  818. ### Refresh an existing bundle
  819. Once you have published a bundle you can refresh it in place without re-running the full wizard. Every export records the settings that were used (projects, scrub preset, attachment thresholds, chunking config) inside `manifest.json`. The new `share update` command reads those defaults, regenerates the SQLite snapshot and viewer assets in a temporary directory, and then replaces the bundle atomically—removing obsolete chunked files or attachments along the way.
  820. ```bash
  821. # Refresh bundle using the originally recorded settings
  822. uv run python -m mcp_agent_mail.cli share update ./my-bundle
  823. # Override one or more export options while updating
  824. uv run python -m mcp_agent_mail.cli share update ./my-bundle \
  825. --project backend-abc123 \
  826. --inline-threshold 16384 \
  827. --chunk-threshold 104857600
  828. # Re-sign and package the refreshed bundle
  829. uv run python -m mcp_agent_mail.cli share update ./my-bundle \
  830. --zip \
  831. --signing-key ./keys/signing.key
  832. ```
  833. When chunking was enabled previously but the refreshed snapshot no longer needs it, `share update` cleans up the `chunks/` directory, `chunks.sha256`, and `mailbox.sqlite3.config.json` automatically, ensuring the bundle tree matches the new manifest. You can still tweak any setting at update time; overrides are written back into the `export_config` section of `manifest.json` for the next refresh.
  834. **2. Preview locally**
  835. ```bash
  836. # Serve the bundle on localhost:9000
  837. uv run python -m mcp_agent_mail.cli share preview ./my-bundle
  838. # Custom port and auto-open browser
  839. uv run python -m mcp_agent_mail.cli share preview ./my-bundle \
  840. --port 8080 \
  841. --open-browser
  842. ```
  843. This launches a lightweight HTTP server that serves the static files. Open `http://127.0.0.1:9000/viewer/` in your browser to explore the archive.
  844. **Interactive preview controls:**
  845. - **'r'**: Force browser reload (bumps manual cache-bust token, triggers viewer refresh)
  846. - **'d'**: Request deployment (exits with code 42; wizard detects and proceeds to deploy)
  847. - **'q'**: Quit preview server
  848. - **Ctrl+C**: Stop preview server
  849. The preview server automatically refreshes viewer assets from the source tree if available, ensuring you always see the latest HTML/JS/CSS during development.
  850. **3. Verify integrity**
  851. ```bash
  852. # Verify SRI hashes and signature
  853. uv run python -m mcp_agent_mail.cli share verify ./my-bundle
  854. # Verify with explicit public key (overrides manifest.sig.json)
  855. uv run python -m mcp_agent_mail.cli share verify ./my-bundle \
  856. --public-key AAAA...base64...
  857. ```
  858. Verification checks:
  859. - SHA-256 hashes for all vendor libraries (Marked.js, DOMPurify, SQL.js)
  860. - SHA-256 hashes for the SQLite database and attachments
  861. - Ed25519 signature over the canonical manifest (if present)
  862. **4. Decrypt (if encrypted)**
  863. ```bash
  864. # Decrypt with age identity file (private key)
  865. uv run python -m mcp_agent_mail.cli share decrypt bundle.zip.age \
  866. --identity ~/.age/key.txt
  867. # Decrypt with passphrase (interactive prompt)
  868. uv run python -m mcp_agent_mail.cli share decrypt bundle.zip.age \
  869. --passphrase
  870. # Specify custom output path
  871. uv run python -m mcp_agent_mail.cli share decrypt bundle.zip.age \
  872. --output ./decrypted-bundle.zip \
  873. --identity ~/.age/key.txt
  874. ```
  875. After decryption, unzip the archive and use `share preview` to view it.
  876. ### Export options reference
  877. | Option | Type | Default | Description |
  878. | :-- | :-- | :-- | :-- |
  879. | `--output`, `-o` | Path | (required) | Directory where the static bundle will be written |
  880. | `--project`, `-p` | List | All projects | Limit export to specific project slugs or human keys (repeatable) |
  881. | `--inline-threshold` | Bytes | 65536 (64KB) | Inline attachments smaller than this as base64 data URIs |
  882. | `--detach-threshold` | Bytes | 26214400 (25MB) | Mark attachments larger than this as external (not bundled) |
  883. | `--scrub-preset` | String | `standard` | Redaction preset: `standard` or `strict` (see Redaction presets section) |
  884. | `--chunk-threshold` | Bytes | 20971520 (20MB) | Split SQLite database into chunks if it exceeds this size |
  885. | `--chunk-size` | Bytes | 4194304 (4MB) | Chunk size when splitting large databases |
  886. | `--dry-run` | Flag | false | Generate security summary and preview without writing files |
  887. | `--zip` / `--no-zip` | Flag | true | Package the bundle into a ZIP archive |
  888. | `--signing-key` | Path | None | Path to Ed25519 signing key (32-byte raw seed) |
  889. | `--signing-public-out` | Path | None | Write the Ed25519 public key to this file after signing |
  890. | `--age-recipient` | String | None | age public key for encryption (repeatable for multiple recipients) |
  891. | `--interactive`, `-i` | Flag | false | Launch interactive wizard (prints guidance; full wizard TBD) |
  892. ### Security features
  893. **XSS protection (DOMPurify + CSP)**
  894. Message bodies are rendered using a defense-in-depth pipeline:
  895. 1. **Marked.js** parses GitHub-Flavored Markdown into HTML
  896. 2. **DOMPurify** sanitizes the HTML, removing dangerous tags and attributes
  897. 3. **Content Security Policy** restricts script sources, blocks inline event handlers, and limits network access
  898. This prevents malicious content in message bodies from executing JavaScript or exfiltrating data.
  899. **CSP configuration notes:**
  900. - `script-src`: Allows self, CDNs (Tailwind, Alpine.js), and `'unsafe-eval'` (required for SQL.js WebAssembly)
  901. - `connect-src`: Allows `*` (all origins) to support preview mode polling and flexible deployment scenarios
  902. - `style-src`: Allows self, inline styles (for Tailwind), and font CDNs
  903. - Trusted Types removed for browser compatibility (Firefox, Safari don't support it yet)
  904. **Cryptographic signing (Ed25519)**
  905. When you provide a signing key, the export process:
  906. 1. Generates a canonical JSON representation of `manifest.json`
  907. 2. Signs it with Ed25519 (fast, 64-byte signatures, 128-bit security)
  908. 3. Writes the signature and public key to `manifest.sig.json`
  909. Recipients can verify the signature using `share verify` to ensure:
  910. - The bundle hasn't been modified since signing
  911. - The bundle was created by someone with the private key
  912. - All assets match their declared SHA-256 hashes
  913. **Requirements and fallback:**
  914. - Requires PyNaCl >= 1.6.0 (installed automatically with this package)
  915. - If PyNaCl is unavailable or signing fails, export gracefully falls back to unsigned mode
  916. - Wizard reuses existing signing keys by default (no re-generation unless requested)
  917. - Private keys are automatically excluded from git via `.gitignore` (signing-*.key pattern)
  918. **Encryption (age)**
  919. The `age` encryption tool (https://age-encryption.org/) provides modern, secure file encryption. When you provide recipient public keys, the export process encrypts the final ZIP archive. Only holders of the corresponding private keys can decrypt it.
  920. Generate keys with:
  921. ```bash
  922. # Install age (example for macOS)
  923. brew install age
  924. # Generate a new key pair
  925. age-keygen -o key.txt
  926. # Public key is printed to stdout; share it with exporters
  927. # Private key is saved to key.txt; keep it secret
  928. ```
  929. **Redaction presets**
  930. The export pipeline supports configurable scrubbing to remove sensitive data:
  931. - `standard`: Clears acknowledgment/read state, removes file reservations and agent links, scrubs secrets (GitHub tokens, Slack tokens, OpenAI keys, bearer tokens, JWTs) from message bodies and attachment metadata. Retains agent names (which are already meaningless pseudonyms like "BlueMountain"), full message bodies, and attachments.
  932. - `strict`: All standard redactions plus replaces entire message bodies with "[Message body redacted]" placeholder and removes all attachments from the bundle.
  933. All presets apply redaction to message subjects, bodies, and attachment metadata before the bundle is written.
  934. ### Static viewer features
  935. The bundled HTML viewer provides:
  936. **Dashboard layout**:
  937. - **Gmail-style three-pane interface**: Projects sidebar, message list (center), and detail pane (right)
  938. - **Bundle metadata header**: Shows bundle creation time, export settings, and scrubbing preset
  939. - **Summary panels**: Side-by-side panels displaying projects included, attachment statistics, and redaction summary
  940. - **Message list**: Virtual-scrolled message list with sender, subject, snippet, and importance badges
  941. - **Raw manifest viewer**: Collapsible JSON display of the complete manifest for verification
  942. **Advanced boolean search** (new): Powered by SQLite FTS5 with LIKE fallback, supports complex queries:
  943. - **Boolean operators**: `(auth OR login) AND NOT admin`
  944. - **Quoted phrases**: `"build plan"` (exact match)
  945. - **Parentheses**: Control precedence like `(A OR B) AND (C OR D)`
  946. - **Operator precedence**: NOT > AND > OR (e.g., `A OR B AND C` = `A OR (B AND C)`)
  947. - **Automatic debouncing**: 140ms delay avoids hammering the database on every keystroke
  948. - **Performance**: FTS5 search is 10-100x faster than LIKE on large datasets
  949. **Lazy message loading** (performance optimization):
  950. - Initial load fetches only 280-character snippets for all messages (3-6x faster)
  951. - Full message body loaded on-demand when you click a message
  952. - Dramatically reduces memory usage and initial load time
  953. **Virtual scrolling** (new): Clusterize.js-powered virtual list rendering:
  954. - Smoothly handles 100,000+ messages without slowdown
  955. - Only ~30 DOM nodes exist at any time (visible rows + buffers)
  956. - Maintains native scrollbar feel with keyboard navigation
  957. **Markdown rendering**: Message bodies are rendered with GitHub-Flavored Markdown, supporting code blocks, tables, task lists, and inline images.
  958. **Opportunistic OPFS caching**: The SQLite database is cached in Origin Private File System (OPFS) in the background:
  959. - First load: Downloads from network, caches to OPFS during idle time
  960. - Subsequent loads: Instant from OPFS (even faster than IndexedDB)
  961. - Automatic cache key validation prevents stale data
  962. **Dark mode**: Toggle between light and dark themes with localStorage persistence. Dark mode state is managed by the main viewer controller for consistency.
  963. **Attachment preview**: Inline images render directly in message bodies. External attachments show file size and download links.
  964. **Message detail view**: Click any message in the list to load its full body (lazy), view metadata (sender, recipients, timestamp, importance), and browse attachments.
  965. **No server required**: After the initial HTTP serving (which can be a static file host like S3, GitHub Pages, or Netlify), all functionality runs client-side. No backend, no API calls, no authentication.
  966. **Browser compatibility**: Works in all modern browsers (Chrome, Firefox, Safari, Edge) with graceful fallbacks for missing features (OPFS, FTS5).
  967. ### Deployment options
  968. **Option 1: GitHub Pages (automated via wizard)**
  969. ```bash
  970. # Use the wizard for fully automated deployment
  971. uv run python -m mcp_agent_mail.cli share wizard
  972. # Select: GitHub Pages → provide repo name → wizard handles everything
  973. ```
  974. Or manually:
  975. ```bash
  976. # Export and unzip
  977. uv run python -m mcp_agent_mail.cli share export --output ./bundle --no-zip
  978. cd bundle
  979. # Initialize git and push to GitHub
  980. git init
  981. git add .
  982. git commit -m "Initial export"
  983. git remote add origin git@github.com:yourorg/project-archive.git
  984. git push -u origin main
  985. # Enable GitHub Pages in repo settings (source: main branch, root directory)
  986. ```
  987. **Option 2: Cloudflare Pages (automated via wizard)**
  988. ```bash
  989. # Use the wizard for instant global CDN deployment
  990. uv run python -m mcp_agent_mail.cli share wizard
  991. # Select: Cloudflare Pages → provide project name → wizard deploys directly
  992. ```
  993. Or manually with wrangler CLI:
  994. ```bash
  995. # Export and deploy
  996. uv run python -m mcp_agent_mail.cli share export --output ./bundle --no-zip
  997. npx wrangler pages deploy ./bundle --project-name=project-archive
  998. # Your site is live at: https://project-archive.pages.dev
  999. ```
  1000. **Benefits of Cloudflare Pages:**
  1001. - Instant deployment (no git repo required)
  1002. - Global CDN with 275+ locations
  1003. - Automatic HTTPS and DDoS protection
  1004. - Zero-downtime updates
  1005. - Generous free tier (500 builds/month, unlimited requests)
  1006. **Option 3: S3 + CloudFront**
  1007. ```bash
  1008. # Export and unzip
  1009. uv run python -m mcp_agent_mail.cli share export --output ./bundle --no-zip
  1010. # Upload to S3
  1011. aws s3 sync ./bundle s3://your-bucket/archives/project-2024/ --acl public-read
  1012. # Access via CloudFront
  1013. # https://d123abc.cloudfront.net/archives/project-2024/
  1014. ```
  1015. **Option 4: Nginx static site**
  1016. ```nginx
  1017. server {
  1018. listen 443 ssl;
  1019. server_name archives.example.com;
  1020. ssl_certificate /etc/letsencrypt/live/archives.example.com/fullchain.pem;
  1021. ssl_certificate_key /etc/letsencrypt/live/archives.example.com/privkey.pem;
  1022. root /var/www/archives/project-2024;
  1023. index index.html;
  1024. # Enable gzip for efficient transfer
  1025. gzip on;
  1026. gzip_types text/html text/css application/javascript application/json application/wasm;
  1027. # Cache static assets
  1028. location ~* \.(js|css|wasm|png|jpg|webp)$ {
  1029. expires 1y;
  1030. add_header Cache-Control "public, immutable";
  1031. }
  1032. # CSP headers are already in index.html meta tag
  1033. # Add HTTPS-only and frame protection
  1034. add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
  1035. add_header X-Frame-Options "DENY" always;
  1036. add_header X-Content-Type-Options "nosniff" always;
  1037. }
  1038. ```
  1039. **Option 5: Encrypted distribution via file sharing**
  1040. For confidential archives:
  1041. ```bash
  1042. # Export with age encryption
  1043. uv run python -m mcp_agent_mail.cli share export \
  1044. --output ./bundle \
  1045. --signing-key ./signing.key \
  1046. --age-recipient age1auditor... \
  1047. --age-recipient age1manager...
  1048. # This produces bundle.zip.age
  1049. # Upload to Dropbox, Google Drive, or send via secure file transfer
  1050. # Recipients decrypt locally
  1051. uv run python -m mcp_agent_mail.cli share decrypt bundle.zip.age \
  1052. --identity ~/.age/key.txt
  1053. # Verify integrity
  1054. unzip bundle.zip
  1055. uv run python -m mcp_agent_mail.cli share verify ./bundle
  1056. # Preview locally
  1057. uv run python -m mcp_agent_mail.cli share preview ./bundle
  1058. ```
  1059. ### Example workflows
  1060. **Quarterly audit package**
  1061. ```bash
  1062. # Export Q4 2024 communications for audit
  1063. uv run python -m mcp_agent_mail.cli share export \
  1064. --output ./audit-q4-2024 \
  1065. --scrub-preset strict \
  1066. --signing-key ./audit-signing.key \
  1067. --signing-public-out ./audit-signing.pub \
  1068. --age-recipient age1auditor@firm.example
  1069. # Produces: audit-q4-2024.zip.age
  1070. # Send to auditor with audit-signing.pub
  1071. # Auditor verifies:
  1072. age -d -i auditor-key.txt audit-q4-2024.zip.age > audit-q4-2024.zip
  1073. unzip audit-q4-2024.zip
  1074. python -m mcp_agent_mail.cli share verify ./audit-q4-2024 \
  1075. --public-key $(cat audit-signing.pub)
  1076. ```
  1077. **Executive summary for stakeholders**
  1078. ```bash
  1079. # Export high-importance threads only
  1080. # (filter in UI after export, or use SQL to create filtered snapshot)
  1081. uv run python -m mcp_agent_mail.cli share export \
  1082. --output ./exec-summary \
  1083. --project backend-prod \
  1084. --scrub-preset standard
  1085. # Host on internal web server
  1086. cp -r ./exec-summary /var/www/exec-archives/2024-12/
  1087. # Share link: https://internal.example.com/exec-archives/2024-12/
  1088. ```
  1089. **Disaster recovery backup**
  1090. ```bash
  1091. # Monthly encrypted backup
  1092. uv run python -m mcp_agent_mail.cli share export \
  1093. --output ./backup-$(date +%Y-%m) \
  1094. --scrub-preset none \
  1095. --signing-key ./dr-signing.key \
  1096. --age-recipient age1dr@company.example
  1097. # Store in off-site backup system
  1098. aws s3 cp backup-2024-12.zip.age s3://dr-backups/mcp-mail/ \
  1099. --storage-class GLACIER_IR
  1100. # Restore procedure documented in runbook
  1101. ```
  1102. ### Troubleshooting exports
  1103. **Export fails with "Database locked"**
  1104. The export takes a snapshot using SQLite's Online Backup API. If the server is actively writing, wait a few seconds and retry. For large databases, consider temporarily stopping the server during export.
  1105. **Bundle size is too large**
  1106. Use `--detach-threshold` to mark large attachments as external references. These won't be included in the bundle but will show file metadata in the viewer.
  1107. ```bash
  1108. # Bundle files under 1MB, mark larger files as external
  1109. uv run python -m mcp_agent_mail.cli share export \
  1110. --output ./bundle \
  1111. --detach-threshold 1048576
  1112. ```
  1113. Alternatively, filter to specific projects with `--project`.
  1114. **Encrypted bundle won't decrypt**
  1115. Verify you're using the correct identity file:
  1116. ```bash
  1117. # Get your public key from your identity file
  1118. age-keygen -y identity.txt
  1119. # Ensure this public key was included in the --age-recipient values during export
  1120. # If you have multiple identity files, try each one
  1121. age -d -i identity.txt bundle.zip.age > bundle.zip
  1122. ```
  1123. **Signature verification fails**
  1124. Signature verification requires:
  1125. 1. The original `manifest.json` (unmodified)
  1126. 2. The `manifest.sig.json` file (contains signature and public key)
  1127. 3. All assets referenced in the manifest with matching SHA-256 hashes
  1128. If verification fails, the bundle may have been tampered with or corrupted during transfer. Re-export and re-transfer.
  1129. **Viewer shows blank page or errors**
  1130. Check browser console for errors. Common issues:
  1131. - **OPFS not supported**: Older browsers may not support Origin Private File System. The viewer will fall back to in-memory mode (slower).
  1132. - **Database too large**: Browsers limit in-memory database size to ~1-2GB. Use chunking (`--chunk-threshold`) for very large archives.
  1133. - **CSP violations**: If hosting the bundle, ensure the web server doesn't add conflicting CSP headers. The viewer's CSP is defined in `index.html` and should not be overridden.
  1134. ### On-disk layout (per project)
  1135. ```
  1136. <store>/projects/<slug>/
  1137. agents/<AgentName>/profile.json
  1138. agents/<AgentName>/inbox/YYYY/MM/<msg-id>.md
  1139. agents/<AgentName>/outbox/YYYY/MM/<msg-id>.md
  1140. messages/YYYY/MM/<msg-id>.md
  1141. messages/threads/<thread-id>.md # optional human digest maintained by the server
  1142. file_reservations/<sha1-of-path>.json
  1143. attachments/<xx>/<sha1>.webp
  1144. ```
  1145. ### Message file format
  1146. Messages are GitHub-Flavored Markdown with JSON frontmatter (fenced by `---json`). Attachments are either WebP files referenced by relative path or inline base64 WebP data URIs.
  1147. ```markdown
  1148. ---json
  1149. {
  1150. "id": 1234,
  1151. "thread_id": "TKT-123",
  1152. "project": "/abs/path/backend",
  1153. "project_slug": "backend-abc123",
  1154. "from": "GreenCastle",
  1155. "to": ["BlueLake"],
  1156. "cc": [],
  1157. "created": "2025-10-23T15:22:14Z",
  1158. "importance": "high",
  1159. "ack_required": true,
  1160. "attachments": [
  1161. {"type": "file", "media_type": "image/webp", "path": "projects/backend-abc123/attachments/2a/2a6f.../diagram.webp"}
  1162. ]
  1163. }
  1164. ---
  1165. # Build plan for /api/users routes
  1166. ... body markdown ...
  1167. ```
  1168. ### Data model (SQLite)
  1169. - `projects(id, human_key, slug, created_at)`
  1170. - `agents(id, project_id, name, program, model, task_description, inception_ts, last_active_ts, attachments_policy, contact_policy)`
  1171. - `messages(id, project_id, sender_id, thread_id, subject, body_md, created_ts, importance, ack_required, attachments)`
  1172. - `message_recipients(message_id, agent_id, kind, read_ts, ack_ts)`
  1173. - `file_reservations(id, project_id, agent_id, path_pattern, exclusive, reason, created_ts, expires_ts, released_ts)`
  1174. - `agent_links(id, a_project_id, a_agent_id, b_project_id, b_agent_id, status, reason, created_ts, updated_ts, expires_ts)`
  1175. - `project_sibling_suggestions(id, project_a_id, project_b_id, score, status, rationale, created_ts, evaluated_ts, confirmed_ts, dismissed_ts)`
  1176. - `fts_messages(message_id UNINDEXED, subject, body)` + triggers for incremental updates
  1177. ### Concurrency and lifecycle
  1178. - One request/task = one isolated operation
  1179. - Archive writes are guarded by a per-project `.archive.lock` under `projects/<slug>/`
  1180. - Git index/commit operations are serialized across the shared archive repo by a repo-level `.commit.lock`
  1181. - DB operations are short-lived and scoped to each tool call; FTS triggers keep the search index current
  1182. - Artifacts are written first, then committed as a cohesive unit with a descriptive message
  1183. - Attachments are content-addressed (sha1) to avoid duplication
  1184. ## How it works (key flows)
  1185. 1) Create an identity
  1186. - `register_agent(project_key, program, model, name?, task_description?)` → creates/updates a named identity, persists profile to Git, and commits.
  1187. 2) Send a message
  1188. - `send_message(project_key, sender_name, to[], subject, body_md, cc?, bcc?, attachment_paths?, convert_images?, importance?, ack_required?, thread_id?, auto_contact_if_blocked?)`
  1189. - Writes a canonical message under `messages/YYYY/MM/`, an outbox copy for the sender, and inbox copies for each recipient; commits all artifacts.
  1190. - Optionally converts images (local paths or data URIs) to WebP and embeds small ones inline.
  1191. ```mermaid
  1192. sequenceDiagram
  1193. participant Agent
  1194. participant Server
  1195. participant DB
  1196. participant Git
  1197. Agent->>Server: call send_message
  1198. Server->>DB: insert message and recipients
  1199. DB-->>Server: ok
  1200. Server->>Git: write canonical markdown
  1201. Server->>Git: write outbox copy
  1202. Server->>Git: write inbox copies
  1203. Server->>Git: commit
  1204. Server-->>Agent: result
  1205. ```
  1206. 3) Check inbox
  1207. - `fetch_inbox(project_key, agent_name, since_ts?, urgent_only?, unread_only?, include_bodies?, limit?)` returns recent messages, preserving thread_id where available. Pass `unread_only=true` to skip messages this recipient has already explicitly marked read (cuts token-burn for polling agents).
  1208. - `acknowledge_message(project_key, agent_name, message_id)` marks acknowledgements.
  1209. 4) Avoid conflicts with file reservations (leases)
  1210. - `file_reservation_paths(project_key, agent_name, paths[], ttl_seconds, exclusive, reason)` records an advisory lease in DB and writes JSON reservation artifacts in Git; conflicts are reported if overlapping active exclusives exist (reservations are still granted; conflicts are returned alongside grants).
  1211. - `release_file_reservations(project_key, agent_name, paths? | file_reservation_ids?)` releases active leases (all if none specified). JSON artifacts remain for audit history.
  1212. - Optional: install a pre-commit hook in your code repo that blocks commits conflicting with other agents' active exclusive file reservations.
  1213. ```mermaid
  1214. sequenceDiagram
  1215. participant Agent
  1216. participant Server
  1217. participant DB
  1218. participant Git
  1219. Agent->>Server: call file_reservation_paths
  1220. Server->>DB: expire old leases and check overlaps
  1221. DB-->>Server: conflicts or grants
  1222. Server->>DB: insert file reservation rows
  1223. Server->>Git: write file reservation JSON files
  1224. Server->>Git: commit
  1225. Server-->>Agent: granted paths and any conflicts
  1226. ```
  1227. 5) Search & summarize
  1228. - `search_messages(project_key, query, limit?)` uses FTS5 over subject and body.
  1229. - `summarize_thread(project_key, thread_id, include_examples?)` extracts key points, actions, and participants from the thread.
  1230. - `reply_message(project_key, message_id, sender_name, body_md, ..., sender_token?)` creates a subject-prefixed reply, preserving or creating a thread.
  1231. ### Semantics & invariants
  1232. - Identity
  1233. - Names are memorable adjective+noun and unique per project; `name_hint` is sanitized (alnum) and used if available
  1234. - `whois` returns the stored profile; `list_agents` can filter by recent activity
  1235. - `last_active_ts` is bumped on relevant interactions (messages, inbox checks, etc.)
  1236. - Threads
  1237. - Replies inherit `thread_id` from the original; if missing, the reply sets `thread_id` to the original message id
  1238. - Subject lines are prefixed (e.g., `Re:`) for readability in mailboxes
  1239. - Attachments
  1240. - Image references (file path or data URI) are converted to WebP; small images embed inline when policy allows
  1241. - Non-absolute `attachment_paths` (and markdown image paths) resolve relative to the project archive root under `STORAGE_ROOT/projects/<slug>/`, not the code repo root
  1242. - Absolute attachment paths are disabled by default. Enabling `ALLOW_ABSOLUTE_ATTACHMENT_PATHS=true` on a networked deployment turns message sending into a filesystem read primitive for whatever paths the server process can access.
  1243. - Stored under `attachments/<xx>/<sha1>.webp` and referenced by relative path in frontmatter
  1244. - File Reservations
  1245. - TTL-based; exclusive means "please don't modify overlapping surfaces" for others until expiry or release
  1246. - Conflict detection is per exact path pattern; shared reservations can coexist, exclusive conflicts are surfaced
  1247. - JSON artifacts remain in Git for audit even after release (DB tracks release_ts)
  1248. - Search
  1249. - External-content FTS virtual table and triggers index subject/body on insert/update/delete
  1250. - Queries are constrained to the project id and ordered by `created_ts DESC`
  1251. ## Contact model and "consent-lite" messaging
  1252. Goal: make coordination "just work" without spam across unrelated agents. The server enforces per-project isolation by default and adds an optional consent layer within a project so agents only contact relevant peers.
  1253. ### Isolation by project
  1254. - All tools require a `project_key`. Agents only see messages addressed to them within that project.
  1255. - An agent working in Project A is invisible to agents in Project B unless explicit cross-project contact is established (see below). This avoids distraction between unrelated repositories.
  1256. ### Policies (per agent)
  1257. - `open`: accept any targeted messages in the project.
  1258. - `auto` (default): allow messages when there is obvious shared context (e.g., same thread participants; recent overlapping active file reservations; recent prior direct contact within a TTL); otherwise requires a contact request.
  1259. - `contacts_only`: require an approved contact link first.
  1260. - `block_all`: reject all new contacts (errors with CONTACT_BLOCKED).
  1261. Use `set_contact_policy(project_key, agent_name, policy)` to update.
  1262. ### Request/approve contact
  1263. - `request_contact(project_key, from_agent, to_agent, reason?, ttl_seconds?, registration_token?)` creates or refreshes a pending link and sends a small ack_required "intro" message to the recipient.
  1264. - `respond_contact(project_key, to_agent, from_agent, accept, ttl_seconds?, registration_token?)` approves or denies; approval grants messaging until expiry.
  1265. - `list_contacts(project_key, agent_name)` surfaces outbound links with target projects and audit flags for expiry/messageability.
  1266. Auth note: these tools require either an agent already authenticated in the current MCP session, or the relevant `registration_token`. `send_message(..., auto_contact_if_blocked=true)` only auto-approves when both agents are already authenticated in the same MCP session; otherwise it creates a pending `request_contact` and **fails loud** with `CONTACT_REQUIRED` (the underlying message body is *not* queued — once the recipient approves, the sender must re-call `send_message` to actually deliver the payload).
  1267. `macro_contact_handshake(..., auto_accept=true)` follows the same rule for new approvals: it only auto-approves when the target agent is already authenticated in the current MCP session or when `target_registration_token` is supplied explicitly. If the link is already approved, the macro reuses that approval. Otherwise the request remains pending and the macro reports a `response_error`.
  1268. ### Auto-allow heuristics (no explicit request required)
  1269. - Same thread: replies or messages to thread participants are allowed.
  1270. - Recent overlapping file reservations: if sender and recipient hold active file reservations in the project, messaging is allowed.
  1271. - Recent prior contact: a sliding TTL allows follow-ups between the same pair.
  1272. These heuristics minimize friction while preventing cold spam.
  1273. ### Cross-project coordination (frontend vs backend repos)
  1274. When two repos represent the same underlying project (e.g., `frontend` and `backend`), you have two options:
  1275. 1) Use the same `project_key` across both workspaces. Agents in both repos operate under one project namespace and benefit from full inbox/outbox coordination automatically.
  1276. 2) Keep separate `project_key`s and establish explicit contact:
  1277. - In `backend`, agent `GreenCastle` calls:
  1278. - `request_contact(project_key="/abs/path/backend", from_agent="GreenCastle", to_agent="BlueLake", reason="API contract changes", registration_token="<GreenCastle token>")`
  1279. - In `frontend`, `BlueLake` calls:
  1280. - `respond_contact(project_key="/abs/path/backend", to_agent="BlueLake", from_agent="GreenCastle", accept=true, registration_token="<BlueLake token>")`
  1281. - After approval, messages can be exchanged; in default `auto` policy the server allows follow-up threads/reservation-based coordination without re-requesting.
  1282. Important: You can also create reciprocal links or set `open` policy for trusted pairs. The consent layer is on by default (CONTACT_ENFORCEMENT_ENABLED=true) but is designed to be non-blocking in obvious collaboration contexts.
  1283. <!-- Consolidated in API Quick Reference → Tools below to avoid duplication -->
  1284. ## Resource layer (read-only URIs)
  1285. Expose common reads as resources that clients can fetch. See API Quick Reference → Resources for the full list and parameters.
  1286. Example (conceptual) resource read:
  1287. ```json
  1288. {
  1289. "method": "resources/read",
  1290. "params": {"uri": "resource://inbox/BlueLake?project=/abs/path/backend&limit=20&agent_token=<registration_token>"}
  1291. }
  1292. ```
  1293. <!-- Parameters consolidated in API Quick Reference → Resources -->
  1294. ```mermaid
  1295. sequenceDiagram
  1296. participant Client
  1297. participant Server
  1298. participant DB
  1299. Client->>Server: read inbox resource
  1300. Server->>DB: select messages for agent
  1301. DB-->>Server: rows
  1302. Server-->>Client: inbox data
  1303. ```
  1304. <!-- View URIs consolidated in API Quick Reference → Resources -->
  1305. ## File Reservations and the optional pre-commit guard
  1306. - Guard status and pre-push
  1307. - Print guard status:
  1308. - `mcp-agent-mail guard status /path/to/repo`
  1309. - Install both guards (pre-commit + pre-push):
  1310. - `mcp-agent-mail guard install <project_key> <repo_path> --prepush`
  1311. - Pre-commit honors `WORKTREES_ENABLED` and `AGENT_MAIL_GUARD_MODE` (`warn` advisory).
  1312. - Pre-push enumerates to-be-pushed commits (`rev-list`) and uses `diff-tree` with `--no-ext-diff`.
  1313. - Composition-safe install (chain-runner):
  1314. - A Python chain-runner is written to `.git/hooks/pre-commit` and `.git/hooks/pre-push`.
  1315. - It executes `hooks.d/<hook>/*` in lexical order, then `<hook>.orig` if present (existing hooks are preserved, not overwritten).
  1316. - Agent Mail installs its guard as `hooks.d/pre-commit/50-agent-mail.py` and `hooks.d/pre-push/50-agent-mail.py`.
  1317. - Windows shims (`pre-commit.cmd/.ps1`, `pre-push.cmd/.ps1`) are written to invoke the Python chain-runner.
  1318. - Matching and safety details:
  1319. - Renames/moves are handled: both the old and new names are checked (`git diff --cached --name-status -M -z`).
  1320. - NUL-safe end-to-end: paths are collected and forwarded as NUL-delimited to avoid ambiguity.
  1321. - Git-native matching: reservations are checked using Git wildmatch pathspec semantics against repo-root relative paths; `core.ignorecase` is honored.
  1322. - Emergency bypass (use sparingly): set `AGENT_MAIL_BYPASS=1`, or use native Git `--no-verify`. In `warn` mode the guard never blocks.
  1323. ## Git-based project identity (opt-in)
  1324. - Gate: `WORKTREES_ENABLED=1` or `GIT_IDENTITY_ENABLED=1` enables git-based identity features. Default off.
  1325. - Identity modes (default `dir`): `dir`, `git-remote`, `git-toplevel`, `git-common-dir`.
  1326. - Inspect identity for a path:
  1327. - Resource (MCP): `resource://identity/%2Fabs%2Fpath` (absolute paths must be URL-encoded inside the resource segment)
  1328. - CLI (diagnostics): `mcp-agent-mail mail status /abs/path`
  1329. - Precedence (when gate is on):
  1330. 1) Committed marker `.agent-mail-project-id` (recommended)
  1331. 2) Discovery YAML `.agent-mail.yaml` with `project_uid:`
  1332. 3) Private marker under Git common dir `.git/agent-mail/project-id`
  1333. 4) Remote fingerprint: normalized `origin` URL + default branch
  1334. 5) `git-common-dir` hash; else dir hash
  1335. - Migration helpers:
  1336. - Write committed marker: `mcp-agent-mail projects mark-identity . --commit`
  1337. - Scaffold discovery file: `mcp-agent-mail projects discovery-init . --product <product_uid>`
  1338. Example identity payload (resource):
  1339. ```json
  1340. {
  1341. "project_uid": "c5b2c86b-7c36-4de6-9a0a-2c4e1c3a1c4a",
  1342. "slug": "repo-a1b2c3d4e5",
  1343. "identity_mode_used": "git-remote",
  1344. "canonical_path": "github.com/owner/repo",
  1345. "human_key": "/abs/worktree/path",
  1346. "repo_root": "/abs/repo",
  1347. "git_common_dir": "/abs/repo/.git",
  1348. "branch": "feature/x",
  1349. "worktree_name": "repo-wt-x",
  1350. "core_ignorecase": true,
  1351. "normalized_remote": "github.com/owner/repo"
  1352. }
  1353. ```
  1354. ## Adopt/Merge legacy projects (optional)
  1355. Consolidate legacy per-worktree projects into a canonical one (safe, explicit, and auditable).
  1356. - Plan the merge (no changes):
  1357. - `mcp-agent-mail projects adopt <from> <to> --dry-run`
  1358. - Apply the merge (moves artifacts and re-keys DB rows):
  1359. - `mcp-agent-mail projects adopt <from> <to> --apply`
  1360. - Safeguards and behavior:
  1361. - Requires both projects be in the same repository (validated via `git-common-dir`).
  1362. - Moves archived Git artifacts from `projects/<old-slug>/…` to `projects/<new-slug>/…` while preserving history.
  1363. - Re-keys database rows (`agents`, `messages`, `file_reservations`) from source to target project.
  1364. - Records `aliases.json` under the target with `"former_slugs": [...]` for discoverability.
  1365. - Aborts if agent-name conflicts would break uniqueness in the target (fix names, then retry).
  1366. - Idempotent where possible; dry-run always prints a clear plan before apply.
  1367. ## Build slots and helpers (opt-in)
  1368. - `amctl env` prints helpful environment keys:
  1369. - `SLUG`, `PROJECT_UID`, `BRANCH`, `AGENT`, `CACHE_KEY`, `ARTIFACT_DIR`
  1370. - Example: `mcp-agent-mail amctl env --path . --agent AliceDev`
  1371. - `am-run` wraps a command with those keys set:
  1372. - Example: `mcp-agent-mail am-run frontend-build -- npm run dev`
  1373. - Auth: when talking to the HTTP server, `am-run` now auto-loads the local agent `registration_token` from the database when possible. You can also pass `--registration-token` or set `AGENT_MAIL_REGISTRATION_TOKEN`.
  1374. - Build slots (advisory, per-project coarse locking):
  1375. - Flags:
  1376. - `--ttl-seconds`: lease duration (default 3600)
  1377. - `--shared/--exclusive`: non-exclusive or exclusive lease (default exclusive)
  1378. - `--block-on-conflicts`: exit non-zero if exclusive conflicts are detected before starting
  1379. - Acquire:
  1380. - Tool: `acquire_build_slot(project_key, agent_name, slot, ttl_seconds=3600, exclusive=true)`
  1381. - Renew:
  1382. - Tool: `renew_build_slot(project_key, agent_name, slot, extend_seconds=1800)`
  1383. - Release (non-destructive; marks released):
  1384. - Tool: `release_build_slot(project_key, agent_name, slot)`
  1385. - Notes:
  1386. - Slots are recorded under the project archive `build_slots/<slot>/<agent>__<branch>.json`
  1387. - `exclusive=true` reports conflicts if another active exclusive holder exists
  1388. - Intended for long-running tasks (dev servers, watchers); pair with `am-run` and `amctl env`
  1389. ## Product Bus
  1390. Group multiple repositories (e.g., frontend, backend, infra) under a single product for product‑wide inbox/search and shared threads.
  1391. - Ensure a product:
  1392. - `mcp-agent-mail products ensure MyProduct --name "My Product"`
  1393. - Link a project (slug or path) into the product:
  1394. - `mcp-agent-mail products link MyProduct .`
  1395. - Inspect product and linked projects:
  1396. - `mcp-agent-mail products status MyProduct`
  1397. - Product‑wide message search (FTS):
  1398. - `mcp-agent-mail products search MyProduct "urgent AND deploy" --agent Alice --registration-token "$AGENT_MAIL_REGISTRATION_TOKEN" --limit 50`
  1399. - Product‑wide inbox:
  1400. - `mcp-agent-mail products inbox MyProduct Alice --registration-token "$AGENT_MAIL_REGISTRATION_TOKEN" --limit 50 --urgent-only --include-bodies --since-ts "2025-11-01T00:00:00Z"`
  1401. - Product‑wide thread summarization:
  1402. - `mcp-agent-mail products summarize-thread MyProduct "bd-123" --agent Alice --registration-token "$AGENT_MAIL_REGISTRATION_TOKEN" --per-thread-limit 100 --no-llm`
  1403. - Auth note:
  1404. - Product-wide search, inbox, and thread summarization now require an authenticated agent identity. These commands accept `--registration-token` / `AGENT_MAIL_REGISTRATION_TOKEN` and will auto-use a single unambiguous locally stored token when that is possible.
  1405. ## Containers
  1406. - Build and run locally:
  1407. ```bash
  1408. docker build -t mcp-agent-mail .
  1409. docker run --rm -p 8765:8765 \
  1410. -e HTTP_HOST=0.0.0.0 \
  1411. -e STORAGE_ROOT=/data/mailbox \
  1412. -v agent_mail_data:/data \
  1413. mcp-agent-mail
  1414. ```
  1415. - Or with Compose:
  1416. ```bash
  1417. docker compose up --build
  1418. ```
  1419. - Notes:
  1420. - Runs as an unprivileged user (`appuser`, uid 10001).
  1421. - Includes a HEALTHCHECK against `/health/liveness`.
  1422. - The server reads config from `.env` via python-decouple. You can mount it read-only into the container at `/app/.env`.
  1423. - Default bind host is `0.0.0.0` in the container; port `8765` is exposed.
  1424. - Persistent archive lives under `/data/mailbox` (mapped to the `agent_mail_data` volume by default).
  1425. - **Bind-mount uid mismatches:** if you bind-mount a host directory (instead of a named volume) into `/data/mailbox`, the files on the host are typically owned by uid 1000 rather than the container's `appuser` (uid 10001). Git would normally refuse to operate on such a "dubious ownership" directory, which surfaces as the non-obvious error `Unknown parameter: --cached` on diff/status. The image now whitelists `/data/mailbox` (and, as a catch-all inside the container only, `*`) via `git config --global --add safe.directory`. If you rebuild from a fork that omits that step, either re-add the safe.directory lines or `chown -R 10001:10001` the host path (see issue #143).
  1426. Notes
  1427. - A unique `product_uid` is stored for each product; you can reference a product by uid or name.
  1428. - Server tools also exist for orchestration: `ensure_product`, `products_link`, `search_messages_product`, and `resource://product/{key}`.
  1429. Exclusive file reservations are advisory but visible and auditable:
  1430. - A reservation JSON is written to `file_reservations/<sha1(path)>.json` capturing holder, pattern, exclusivity, created/expires
  1431. - The pre-commit guard scans active exclusive reservations and blocks commits that touch conflicting paths held by another agent
  1432. - Agents must set `AGENT_NAME` so the guard knows who "owns" the commit
  1433. - The server continuously evaluates reservations for staleness (agent inactivity + mail/filesystem/git silence) and releases abandoned locks automatically; the `force_release_file_reservation` tool uses the same heuristics and notifies the previous holder when another agent clears a stale lease
  1434. Install the guard into a code repo (conceptual tool call):
  1435. ```json
  1436. {
  1437. "method": "tools/call",
  1438. "params": {
  1439. "name": "install_precommit_guard",
  1440. "arguments": {
  1441. "project_key": "/abs/path/backend",
  1442. "code_repo_path": "/abs/path/backend"
  1443. }
  1444. }
  1445. }
  1446. ```
  1447. ## Configuration
  1448. Configuration is loaded from an existing `.env` via `python-decouple`. Do not use `os.getenv` or auto-dotenv loaders.
  1449. ### Changing the HTTP Port
  1450. If port 8765 is already in use (e.g., by Cursor's Python extension), you can change it:
  1451. **Option 1: During installation**
  1452. One-liner with custom port:
  1453. ```bash
  1454. curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --port 9000 --yes
  1455. ```
  1456. Or with local script:
  1457. ./scripts/install.sh --port 9000 --yes
  1458. ```
  1459. **Option 2: After installation (CLI)**
  1460. ```bash
  1461. # Change port using CLI command
  1462. uv run python -m mcp_agent_mail.cli config set-port 9000
  1463. # View current port configuration
  1464. uv run python -m mcp_agent_mail.cli config show-port
  1465. # Restart server for changes to take effect
  1466. scripts/run_server_with_token.sh
  1467. ```
  1468. **Option 3: Manual .env edit**
  1469. ```bash
  1470. # Edit .env file manually with your text editor (recommended)

Lines 2,001–2,624 are not shown. The link to the file on GitHub has every line.

scripts/install.sh · Bundled script · 1,045 lines · 3 findings marked
  1. #!/usr/bin/env bash
  2. set -euo pipefail
  3. # MCP Agent Mail — TL;DR installer
  4. # - Installs uv (if missing)
  5. # - Sets up Python 3.14 venv with uv
  6. # - Syncs dependencies
  7. # - Runs auto-detect integration and starts the HTTP server on port 8765
  8. #
  9. # Usage examples:
  10. # ./scripts/install.sh --yes
  11. # ./scripts/install.sh --dir "$HOME/mcp_agent_mail" --yes
  12. # curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 13 on GitHub
  13. REPO_URL="https://github.com/Dicklesworthstone/mcp_agent_mail"
  14. REPO_NAME="mcp_agent_mail"
  15. BRANCH="main"
  16. # Default clone location follows XDG Base Directory spec so that
  17. # `curl | bash` from inside an unrelated project does not drop an
  18. # untracked sibling directory into that project (see GH#145).
  19. DEFAULT_CLONE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/${REPO_NAME}"
  20. CLONE_DIR=""
  21. YES=0
  22. NO_START=0
  23. START_ONLY=0
  24. PROJECT_DIR=""
  25. INTEGRATION_TOKEN="${INTEGRATION_BEARER_TOKEN:-}"
  26. HTTP_PORT_OVERRIDE=""
  27. SKIP_BEADS=0
  28. SKIP_BV=0
  29. BEADS_INSTALL_URL="https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh"
  30. BV_INSTALL_URL="https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/main/install.sh"
  31. SUMMARY_LINES=()
  32. LAST_BR_VERSION=""
  33. LAST_BV_VERSION=""
  34. usage() {
  35. cat <<EOF
  36. MCP Agent Mail installer
  37. Options:
  38. --dir DIR Clone/use repo at DIR (default: \${XDG_DATA_HOME:-\$HOME/.local/share}/mcp_agent_mail)
  39. --branch NAME Git branch to clone (default: main)
  40. --port PORT HTTP server port (default: 8765); sets HTTP_PORT in .env
  41. --skip-beads Do not install the Beads Rust (br) CLI automatically
  42. --skip-bv Do not install the Beads Viewer (bv) TUI automatically
  43. -y, --yes Non-interactive; assume Yes where applicable
  44. --no-start Do not run integration/start; just set up venv + deps
  45. --start-only Skip clone/setup; run integration/start in current repo
  46. --project-dir PATH Pass-through to integration (where to write client configs)
  47. --token HEX Use/set INTEGRATION_BEARER_TOKEN for this run
  48. -h, --help Show help
  49. Examples:
  50. ./scripts/install.sh --yes
  51. ./scripts/install.sh --port 9000 --yes
  52. ./scripts/install.sh --dir "\$HOME/mcp_agent_mail" --yes
  53. curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 58 on GitHub
  54. curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 59 on GitHub
  55. EOF
  56. }
  57. while [[ $# -gt 0 ]]; do
  58. case "$1" in
  59. --dir) shift; CLONE_DIR="${1:-}" ;;
  60. --dir=*) CLONE_DIR="${1#*=}" ;;
  61. --branch) shift; BRANCH="${1:-}" ;;
  62. --branch=*) BRANCH="${1#*=}" ;;
  63. --port) shift; HTTP_PORT_OVERRIDE="${1:-}" ;;
  64. --port=*) HTTP_PORT_OVERRIDE="${1#*=}" ;;
  65. -y|--yes) YES=1 ;;
  66. --no-start) NO_START=1 ;;
  67. --start-only) START_ONLY=1 ;;
  68. --project-dir) shift; PROJECT_DIR="${1:-}" ;;
  69. --project-dir=*) PROJECT_DIR="${1#*=}" ;;
  70. --token) shift; INTEGRATION_TOKEN="${1:-}" ;;
  71. --token=*) INTEGRATION_TOKEN="${1#*=}" ;;
  72. --skip-beads) SKIP_BEADS=1 ;;
  73. --skip-bv) SKIP_BV=1 ;;
  74. -h|--help) usage; exit 0 ;;
  75. *) echo "Unknown option: $1" >&2; usage; exit 2 ;;
  76. esac
  77. shift || true
  78. done
  79. # Define logging helpers early so they're available for validation
  80. info() { printf "\033[1;36m[INFO]\033[0m %s\n" "$*"; }
  81. ok() { printf "\033[1;32m[ OK ]\033[0m %s\n" "$*"; }
  82. warn() { printf "\033[1;33m[WARN]\033[0m %s\n" "$*"; }
  83. err() { printf "\033[1;31m[ERR ]\033[0m %s\n" "$*"; }
  84. # Validate port if provided
  85. if [[ -n "${HTTP_PORT_OVERRIDE}" ]]; then
  86. if ! [[ "${HTTP_PORT_OVERRIDE}" =~ ^[0-9]+$ ]]; then
  87. err "Port must be a number (got: ${HTTP_PORT_OVERRIDE})"
  88. exit 1
  89. fi
  90. if [[ "${HTTP_PORT_OVERRIDE}" -lt 1 || "${HTTP_PORT_OVERRIDE}" -gt 65535 ]]; then
  91. err "Port must be between 1 and 65535 (got: ${HTTP_PORT_OVERRIDE})"
  92. exit 1
  93. fi
  94. fi
  95. need_cmd() { command -v "$1" >/dev/null 2>&1 || return 1; }
  96. record_summary() {
  97. SUMMARY_LINES+=("$1")
  98. }
  99. print_summary() {
  100. if [[ ${#SUMMARY_LINES[@]} -eq 0 ]]; then
  101. return 0
  102. fi
  103. echo
  104. info "Installation summary"
  105. local line
  106. for line in "${SUMMARY_LINES[@]}"; do
  107. echo " - ${line}"
  108. done
  109. }
  110. find_br_binary() {
  111. if command -v br >/dev/null 2>&1; then
  112. command -v br
  113. return 0
  114. fi
  115. local candidates=("${HOME}/.local/bin/br" "${HOME}/bin/br" "/usr/local/bin/br")
  116. local candidate
  117. for candidate in "${candidates[@]}"; do
  118. if [[ -x "${candidate}" ]]; then
  119. printf '%s\n' "${candidate}"
  120. return 0
  121. fi
  122. done
  123. return 1
  124. }
  125. maybe_add_br_path() {
  126. local binary_path="$1"
  127. local dir
  128. dir=$(dirname "${binary_path}")
  129. if [[ ":${PATH}:" != *":${dir}:"* ]]; then
  130. export PATH="${dir}:${PATH}"
  131. ok "Temporarily added ${dir} to PATH so this session can invoke 'br' immediately"
  132. fi
  133. }
  134. rewrite_path_snippet() {
  135. local rc_file="$1"
  136. local marker="$2"
  137. local end_marker="$3"
  138. local snippet="$4"
  139. local tmp
  140. tmp=$(mktemp "${rc_file}.XXXXXX") || return 1
  141. local in_block=0
  142. local replaced=0
  143. local line
  144. while IFS='' read -r line || [[ -n "${line}" ]]; do
  145. if [[ "${in_block}" -eq 0 && "${line}" == "${marker}" ]]; then
  146. printf '%s' "${snippet}" >> "${tmp}"
  147. in_block=1
  148. replaced=1
  149. continue
  150. fi
  151. if [[ "${in_block}" -eq 1 ]]; then
  152. if [[ "${line}" == "${end_marker}" ]]; then
  153. in_block=0
  154. fi
  155. continue
  156. fi
  157. printf '%s\n' "${line}" >> "${tmp}"
  158. done < "${rc_file}"
  159. if [[ "${in_block}" -eq 1 ]]; then
  160. rm -f "${tmp}"
  161. return 1
  162. fi
  163. if [[ "${replaced}" -eq 0 ]]; then
  164. rm -f "${tmp}"
  165. return 1
  166. fi
  167. if ! mv "${tmp}" "${rc_file}"; then
  168. rm -f "${tmp}"
  169. return 1
  170. fi
  171. return 0
  172. }
  173. append_path_snippet() {
  174. local dir="$1"
  175. local rc_file="$2"
  176. if [[ -z "${rc_file}" ]]; then
  177. return 1
  178. fi
  179. local marker="# >>> MCP Agent Mail br path ${dir}"
  180. local end_marker="# <<< MCP Agent Mail br path"
  181. local snippet=""
  182. printf -v snippet '%s\nif [[ ":$PATH:" != *":%s:"* ]]; then\n export PATH="%s:$PATH"\nfi\n%s\n' \
  183. "${marker}" "${dir}" "${dir}" "${end_marker}"
  184. if [[ -f "${rc_file}" ]] && grep -Fq "${marker}" "${rc_file}"; then
  185. if rewrite_path_snippet "${rc_file}" "${marker}" "${end_marker}" "${snippet}"; then
  186. ok "Updated ${dir} PATH snippet via ${rc_file}"
  187. return 0
  188. fi
  189. warn "Existing PATH snippet in ${rc_file} could not be updated automatically"
  190. return 1
  191. fi
  192. if ! touch "${rc_file}" >/dev/null 2>&1; then
  193. return 1
  194. fi
  195. {
  196. printf '\n%s' "${snippet}"
  197. } >> "${rc_file}"
  198. ok "Added ${dir} to PATH via ${rc_file}"
  199. return 0
  200. }
  201. persist_br_path() {
  202. local binary_path="$1"
  203. local dir
  204. dir=$(dirname "${binary_path}")
  205. local shell_name=""
  206. if [[ -n "${SHELL:-}" ]]; then
  207. shell_name=$(basename "${SHELL}")
  208. fi
  209. local -a rc_candidates=()
  210. if [[ "${shell_name}" == "zsh" ]]; then
  211. rc_candidates+=("~/.zshrc")
  212. elif [[ "${shell_name}" == "bash" ]]; then
  213. rc_candidates+=("~/.bashrc")
  214. fi
  215. rc_candidates+=("~/.bashrc" "~/.zshrc" "~/.profile")
  216. local appended=0
  217. local seen_rc=""
  218. local rc
  219. for rc in "${rc_candidates[@]}"; do
  220. [[ -n "${rc}" ]] || continue
  221. local rc_path
  222. rc_path="${rc/#~/${HOME}}"
  223. if [[ -z "${rc_path}" ]]; then
  224. continue
  225. fi
  226. # Check if we've already seen this path (Bash 3.2 compatible string matching)
  227. if [[ ":${seen_rc}:" == *":${rc_path}:"* ]]; then
  228. continue
  229. fi
  230. seen_rc="${seen_rc}:${rc_path}"
  231. if append_path_snippet "${dir}" "${rc_path}"; then
  232. appended=1
  233. break
  234. fi
  235. done
  236. if [[ "${appended}" -eq 0 ]]; then
  237. warn "Could not persist PATH update automatically; ensure ${dir} is in your PATH."
  238. fi
  239. }
  240. ensure_br_path_ready() {
  241. local binary_path="$1"
  242. maybe_add_br_path "${binary_path}"
  243. persist_br_path "${binary_path}"
  244. }
  245. install_bd_alias() {
  246. # Install 'bd' alias pointing to 'br' for backwards compatibility
  247. local shell_name=""
  248. if [[ -n "${SHELL:-}" ]]; then
  249. shell_name=$(basename "${SHELL}")
  250. fi
  251. # Always check for and remove any old bd binary that might shadow the alias
  252. # This runs every time to catch cases where bd was reinstalled after a previous run
  253. local old_bd_paths=("${HOME}/.local/bin/bd" "${HOME}/bin/bd" "/usr/local/bin/bd")
  254. for old_bd_path in "${old_bd_paths[@]}"; do
  255. if [[ -x "${old_bd_path}" ]] && [[ ! -L "${old_bd_path}" ]]; then
  256. # It's an executable file (not a symlink), rename it
  257. info "Found old bd binary at ${old_bd_path}, renaming to bd.old"
  258. mv "${old_bd_path}" "${old_bd_path}.old" 2>/dev/null || warn "Could not rename old bd binary at ${old_bd_path}"
  259. fi
  260. done
  261. # Determine target RC file based on shell
  262. local rc_file=""
  263. if [[ "${shell_name}" == "zsh" ]]; then
  264. rc_file="${HOME}/.zshrc"
  265. elif [[ "${shell_name}" == "bash" ]]; then
  266. rc_file="${HOME}/.bashrc"
  267. else
  268. # Fallback: try zshrc first (common on macOS), then bashrc
  269. if [[ -f "${HOME}/.zshrc" ]]; then
  270. rc_file="${HOME}/.zshrc"
  271. elif [[ -f "${HOME}/.bashrc" ]]; then
  272. rc_file="${HOME}/.bashrc"
  273. else
  274. warn "Could not determine shell RC file for 'bd' alias"
  275. record_summary "Alias 'bd -> br': skipped (no shell RC file found)"
  276. return 1
  277. fi
  278. fi
  279. local marker="# >>> MCP Agent Mail bd alias"
  280. local end_marker="# <<< MCP Agent Mail bd alias"
  281. local alias_cmd="alias bd='br'"
  282. local snippet=""
  283. printf -v snippet '%s\n%s\n%s\n' "${marker}" "${alias_cmd}" "${end_marker}"
  284. # Check if marker already exists
  285. if [[ -f "${rc_file}" ]] && grep -Fq "${marker}" "${rc_file}"; then
  286. # Update existing snippet
  287. if rewrite_path_snippet "${rc_file}" "${marker}" "${end_marker}" "${snippet}"; then
  288. ok "Updated 'bd' alias in ${rc_file}"
  289. record_summary "Alias 'bd -> br': updated in ${rc_file}"
  290. # Also define it for the current session
  291. alias bd='br' 2>/dev/null || true
  292. return 0
  293. fi
  294. warn "Existing 'bd' alias in ${rc_file} could not be updated automatically"
  295. record_summary "Alias 'bd -> br': update failed in ${rc_file}"
  296. return 1
  297. fi
  298. # Check if user has a different 'bd' alias already (without our markers)
  299. if [[ -f "${rc_file}" ]] && grep -q "^alias bd=" "${rc_file}"; then
  300. warn "An existing 'bd' alias was found in ${rc_file}; skipping to avoid conflict"
  301. record_summary "Alias 'bd -> br': skipped (existing alias found)"
  302. return 0
  303. fi
  304. # Append new snippet
  305. if ! touch "${rc_file}" >/dev/null 2>&1; then
  306. warn "Could not write to ${rc_file}"
  307. record_summary "Alias 'bd -> br': failed (cannot write to ${rc_file})"
  308. return 1
  309. fi
  310. {
  311. printf '\n%s' "${snippet}"
  312. } >> "${rc_file}"
  313. ok "Added 'bd' alias (bd -> br) to ${rc_file}"
  314. record_summary "Alias 'bd -> br': added to ${rc_file}"
  315. # Also define it for the current session
  316. alias bd='br' 2>/dev/null || true
  317. return 0
  318. }
  319. install_am_alias() {
  320. # Install 'am' alias to quickly start the MCP Agent Mail server
  321. local repo_dir="$1"
  322. local shell_name=""
  323. if [[ -n "${SHELL:-}" ]]; then
  324. shell_name=$(basename "${SHELL}")
  325. fi
  326. # Determine target RC file based on shell
  327. local rc_file=""
  328. if [[ "${shell_name}" == "zsh" ]]; then
  329. rc_file="${HOME}/.zshrc"
  330. elif [[ "${shell_name}" == "bash" ]]; then
  331. rc_file="${HOME}/.bashrc"
  332. else
  333. # Fallback: try zshrc first (common on macOS), then bashrc
  334. if [[ -f "${HOME}/.zshrc" ]]; then
  335. rc_file="${HOME}/.zshrc"
  336. elif [[ -f "${HOME}/.bashrc" ]]; then
  337. rc_file="${HOME}/.bashrc"
  338. else
  339. warn "Could not determine shell RC file for 'am' alias"
  340. return 1
  341. fi
  342. fi
  343. local marker="# >>> MCP Agent Mail alias"
  344. local end_marker="# <<< MCP Agent Mail alias"
  345. local alias_cmd="alias am='cd \"${repo_dir}\" && scripts/run_server_with_token.sh'"
  346. local snippet=""
  347. printf -v snippet '%s\n%s\n%s\n' "${marker}" "${alias_cmd}" "${end_marker}"
  348. # Check if marker already exists
  349. if [[ -f "${rc_file}" ]] && grep -Fq "${marker}" "${rc_file}"; then
  350. # Update existing snippet
  351. if rewrite_path_snippet "${rc_file}" "${marker}" "${end_marker}" "${snippet}"; then
  352. ok "Updated 'am' alias in ${rc_file}"
  353. record_summary "Alias 'am': updated in ${rc_file}"
  354. return 0
  355. fi
  356. warn "Existing 'am' alias in ${rc_file} could not be updated automatically"
  357. return 1
  358. fi
  359. # Check if user has a different 'am' alias already
  360. if [[ -f "${rc_file}" ]] && grep -q "^alias am=" "${rc_file}"; then
  361. warn "An existing 'am' alias was found in ${rc_file}; skipping to avoid conflict"
  362. record_summary "Alias 'am': skipped (existing alias found)"
  363. return 0
  364. fi
  365. # Append new snippet
  366. if ! touch "${rc_file}" >/dev/null 2>&1; then
  367. warn "Could not write to ${rc_file}"
  368. return 1
  369. fi
  370. {
  371. printf '\n%s' "${snippet}"
  372. } >> "${rc_file}"
  373. ok "Added 'am' alias to ${rc_file} (run 'am' to start the server)"
  374. record_summary "Alias 'am': added to ${rc_file}"
  375. # Also define it for the current session
  376. # shellcheck disable=SC2139
  377. alias am="cd \"${repo_dir}\" && scripts/run_server_with_token.sh" 2>/dev/null || true
  378. return 0
  379. }
  380. verify_br_binary() {
  381. local binary_path="$1"
  382. if ! "${binary_path}" --version >/dev/null 2>&1; then
  383. err "Beads Rust CLI at ${binary_path} failed 'br --version'. You can retry or rerun the installer with --skip-beads to handle it yourself."
  384. return 1
  385. fi
  386. local version_line
  387. version_line=$("${binary_path}" --version 2>/dev/null | head -n 1 || true)
  388. if [[ -z "${version_line}" ]]; then
  389. version_line="br --version command succeeded"
  390. fi
  391. LAST_BR_VERSION="${version_line}"
  392. ok "Beads Rust CLI ready (${version_line})"
  393. }
  394. find_bv_binary() {
  395. if command -v bv >/dev/null 2>&1; then
  396. command -v bv
  397. return 0
  398. fi
  399. local candidates=("${HOME}/.local/bin/bv" "${HOME}/bin/bv" "/usr/local/bin/bv")
  400. local candidate
  401. for candidate in "${candidates[@]}"; do
  402. if [[ -x "${candidate}" ]]; then
  403. printf '%s\n' "${candidate}"
  404. return 0
  405. fi
  406. done
  407. return 1
  408. }
  409. maybe_add_bv_path() {
  410. local binary_path="$1"
  411. local dir
  412. dir=$(dirname "${binary_path}")
  413. if [[ ":${PATH}:" != *":${dir}:"* ]]; then
  414. export PATH="${dir}:${PATH}"
  415. ok "Temporarily added ${dir} to PATH so this session can invoke 'bv' immediately"
  416. fi
  417. }
  418. verify_bv_binary() {
  419. local binary_path="$1"
  420. if ! "${binary_path}" --version >/dev/null 2>&1; then
  421. warn "Beads Viewer at ${binary_path} failed 'bv --version'"
  422. return 1
  423. fi
  424. local version_line
  425. version_line=$("${binary_path}" --version 2>/dev/null | head -n 1 || true)
  426. if [[ -z "${version_line}" ]]; then
  427. version_line="bv --version command succeeded"
  428. fi
  429. LAST_BV_VERSION="${version_line}"
  430. ok "Beads Viewer ready (${version_line})"
  431. return 0
  432. }
  433. ensure_uv() {
  434. if need_cmd uv; then
  435. ok "uv is already installed"
  436. record_summary "uv: already installed"
  437. return 0
  438. fi
  439. info "Installing uv (Astral)"
  440. if ! need_cmd curl; then err "curl is required to install uv"; exit 1; fi
  441. curl -LsSf https://astral.sh/uv/install.sh | sh
  442. export PATH="${HOME}/.local/bin:${PATH}"
  443. if need_cmd uv; then ok "uv installed"; record_summary "uv: installed"; else err "uv install failed"; exit 1; fi
  444. }
  445. ensure_jq() {
  446. # jq is needed for safe JSON merging in integration scripts
  447. if need_cmd jq; then
  448. ok "jq is already installed"
  449. record_summary "jq: already installed"
  450. return 0
  451. fi
  452. info "jq not found - needed for safe config merging"
  453. # Try to install automatically
  454. local installed=0
  455. if [[ "$(uname -s)" == "Darwin" ]]; then
  456. # macOS - use Homebrew
  457. if need_cmd brew; then
  458. info "Installing jq via Homebrew"
  459. if brew install jq >/dev/null 2>&1; then
  460. installed=1
  461. fi
  462. fi
  463. elif [[ -f /etc/debian_version ]]; then
  464. # Debian/Ubuntu
  465. if need_cmd apt-get; then
  466. info "Installing jq via apt"
  467. if sudo apt-get update -qq >/dev/null 2>&1 && sudo apt-get install -y -qq jq >/dev/null 2>&1; then
  468. installed=1
  469. fi
  470. fi
  471. elif [[ -f /etc/fedora-release ]] || [[ -f /etc/redhat-release ]]; then
  472. # Fedora/RHEL
  473. if need_cmd dnf; then
  474. info "Installing jq via dnf"
  475. if sudo dnf install -y -q jq >/dev/null 2>&1; then
  476. installed=1
  477. fi
  478. elif need_cmd yum; then
  479. info "Installing jq via yum"
  480. if sudo yum install -y -q jq >/dev/null 2>&1; then
  481. installed=1
  482. fi
  483. fi
  484. elif [[ -f /etc/alpine-release ]]; then
  485. # Alpine
  486. if need_cmd apk; then
  487. info "Installing jq via apk"
  488. if sudo apk add --quiet jq >/dev/null 2>&1; then
  489. installed=1
  490. fi
  491. fi
  492. fi
  493. if [[ ${installed} -eq 1 ]] && need_cmd jq; then
  494. ok "jq installed"
  495. record_summary "jq: installed"
  496. return 0
  497. fi
  498. # Couldn't auto-install
  499. warn "Could not auto-install jq"
  500. warn "Integration scripts will fall back to safe mode (won't overwrite existing configs)"
  501. warn "To install manually:"
  502. warn " macOS: brew install jq"
  503. warn " Ubuntu: sudo apt install jq"
  504. warn " Fedora: sudo dnf install jq"
  505. record_summary "jq: not installed (manual install recommended)"
  506. return 0 # Don't fail the installer, just warn
  507. }
  508. update_existing_repo() {
  509. # Pull latest changes from origin for an existing repo
  510. # This ensures users get bug fixes and updates when re-running the installer
  511. local repo_path="$1"
  512. info "Pulling latest changes from origin/${BRANCH}"
  513. if ! (cd "${repo_path}" && git fetch origin "${BRANCH}" --depth 1 2>/dev/null); then
  514. warn "Could not fetch from origin; continuing with existing code"
  515. return 0
  516. fi
  517. # Check if there are updates
  518. local local_sha remote_sha
  519. local_sha=$(cd "${repo_path}" && git rev-parse HEAD 2>/dev/null || echo "unknown")
  520. remote_sha=$(cd "${repo_path}" && git rev-parse "origin/${BRANCH}" 2>/dev/null || echo "unknown")
  521. if [[ "${local_sha}" == "${remote_sha}" ]]; then
  522. ok "Already up to date (${local_sha:0:8})"
  523. record_summary "Repo: already up to date"
  524. return 0
  525. fi
  526. # Guard against data loss: a hard reset to origin/BRANCH silently discards any
  527. # local commits that have not been pushed. Only fast-forward when HEAD is an
  528. # ancestor of origin/BRANCH; if local history has diverged, refuse to reset.
  529. #
  530. # The guard needs real history. This clone is shallow (`--depth 1`), so
  531. # `merge-base --is-ancestor` cannot connect HEAD to the fetched tip and would
  532. # return non-zero for EVERY update — even an ordinary no-local-commits
  533. # fast-forward. Deepen the branch first so ancestry is genuinely determinable;
  534. # only enforce the guard once we actually have the history to evaluate it.
  535. if [[ "$(cd "${repo_path}" && git rev-parse --is-shallow-repository 2>/dev/null)" == "true" ]]; then
  536. (cd "${repo_path}" && git fetch origin "${BRANCH}" --unshallow 2>/dev/null) \
  537. || (cd "${repo_path}" && git fetch origin "${BRANCH}" --depth 200 2>/dev/null) \
  538. || true
  539. fi
  540. if [[ "$(cd "${repo_path}" && git rev-parse --is-shallow-repository 2>/dev/null)" != "true" ]]; then
  541. if ! (cd "${repo_path}" && git merge-base --is-ancestor HEAD "origin/${BRANCH}" 2>/dev/null); then
  542. warn "Local repo has commits not on origin/${BRANCH}; refusing to reset (would discard your work)"
  543. warn "Resolve manually: cd '${repo_path}' && git log --oneline origin/${BRANCH}..HEAD"
  544. record_summary "Repo: update skipped (local commits diverge from origin/${BRANCH})"
  545. return 0
  546. fi
  547. fi
  548. # Stash any local changes to avoid conflicts
  549. local has_changes=0
  550. if (cd "${repo_path}" && git diff --quiet 2>/dev/null) && (cd "${repo_path}" && git diff --cached --quiet 2>/dev/null); then
  551. has_changes=0
  552. else
  553. has_changes=1
  554. info "Stashing local changes before update"
  555. (cd "${repo_path}" && git stash push -m "installer-auto-stash-$(date +%Y%m%d%H%M%S)" 2>/dev/null) || true
  556. fi
  557. # Reset to origin/BRANCH to get latest code
  558. if (cd "${repo_path}" && git reset --hard "origin/${BRANCH}" 2>/dev/null); then
  559. ok "Updated to latest (${local_sha:0:8} → ${remote_sha:0:8})"
  560. record_summary "Repo: updated ${local_sha:0:8} → ${remote_sha:0:8}"
  561. else
  562. warn "Could not update repo; continuing with existing code"
  563. record_summary "Repo: update failed, using existing"
  564. fi
  565. # Restore stashed changes if any
  566. if [[ "${has_changes}" -eq 1 ]]; then
  567. if (cd "${repo_path}" && git stash pop 2>/dev/null); then
  568. ok "Restored local changes"
  569. else
  570. warn "Could not restore stashed changes; they're saved in git stash"
  571. fi
  572. fi
  573. }
  574. ensure_repo() {
  575. # Determine target directory
  576. if [[ -z "${CLONE_DIR}" ]]; then CLONE_DIR="${DEFAULT_CLONE_DIR}"; fi
  577. # If we're already in the repo (local run), use it and update
  578. if [[ -f "pyproject.toml" ]] && grep -q '^name\s*=\s*"mcp-agent-mail"' pyproject.toml 2>/dev/null; then
  579. REPO_DIR="$PWD"
  580. ok "Using existing repo at: ${REPO_DIR}"
  581. update_existing_repo "${REPO_DIR}"
  582. return 0
  583. fi
  584. # If directory exists and looks like the repo, use it and update
  585. if [[ -d "${CLONE_DIR}" ]] && [[ -f "${CLONE_DIR}/pyproject.toml" ]] && grep -q '^name\s*=\s*"mcp-agent-mail"' "${CLONE_DIR}/pyproject.toml" 2>/dev/null; then
  586. REPO_DIR="${CLONE_DIR}"
  587. ok "Using existing repo at: ${REPO_DIR}"
  588. update_existing_repo "${REPO_DIR}"
  589. return 0
  590. fi
  591. # Otherwise clone
  592. info "Cloning ${REPO_URL} (branch=${BRANCH}) to ${CLONE_DIR}"
  593. need_cmd git || { err "git is required to clone"; exit 1; }
  594. git clone --depth 1 --branch "${BRANCH}" "${REPO_URL}" "${CLONE_DIR}"
  595. REPO_DIR="${CLONE_DIR}"
  596. ok "Cloned repo"
  597. record_summary "Repo: cloned into ${REPO_DIR}"
  598. }
  599. ensure_python_and_venv() {
  600. info "Ensuring Python 3.14 and project venv (.venv)"
  601. uv python install 3.14
  602. if [[ ! -d "${REPO_DIR}/.venv" ]]; then
  603. (cd "${REPO_DIR}" && uv venv -p 3.14)
  604. ok "Created venv at ${REPO_DIR}/.venv"
  605. record_summary "Venv: created at ${REPO_DIR}/.venv"
  606. else
  607. ok "Found existing venv at ${REPO_DIR}/.venv"
  608. record_summary "Venv: existing at ${REPO_DIR}/.venv"
  609. fi
  610. }
  611. sync_deps() {
  612. info "Syncing dependencies with uv"
  613. # uv auto-detects ${REPO_DIR}/.venv without needing activation, which is
  614. # both simpler and avoids the POSIX-only `.venv/bin/activate` path
  615. # (Windows layout is `.venv/Scripts/activate`). See GH#144.
  616. (
  617. cd "${REPO_DIR}"
  618. uv sync
  619. )
  620. ok "Dependencies installed"
  621. record_summary "Dependencies: uv sync complete"
  622. }
  623. configure_port() {
  624. if [[ -z "${HTTP_PORT_OVERRIDE}" ]]; then
  625. return 0
  626. fi
  627. local env_file="${REPO_DIR}/.env"
  628. local tmp="${env_file}.tmp.$$"
  629. info "Configuring HTTP_PORT=${HTTP_PORT_OVERRIDE} in .env"
  630. # Set trap to cleanup temp file
  631. trap "rm -f \"${tmp}\" 2>/dev/null" EXIT INT TERM
  632. # Set secure umask for .env file operations, save original to restore later
  633. local old_umask
  634. old_umask=$(umask)
  635. umask 077
  636. if [[ -f "${env_file}" ]]; then
  637. # File exists - update or append
  638. if grep -q '^HTTP_PORT=' "${env_file}"; then
  639. # Replace existing value
  640. if ! sed "s/^HTTP_PORT=.*/HTTP_PORT=${HTTP_PORT_OVERRIDE}/" "${env_file}" > "${tmp}"; then
  641. err "Failed to update HTTP_PORT in .env"
  642. rm -f "${tmp}" 2>/dev/null
  643. trap - EXIT INT TERM
  644. umask "${old_umask}"
  645. return 1
  646. fi
  647. else
  648. # Append new value
  649. if ! { cat "${env_file}"; echo "HTTP_PORT=${HTTP_PORT_OVERRIDE}"; } > "${tmp}"; then
  650. err "Failed to append HTTP_PORT to .env"
  651. rm -f "${tmp}" 2>/dev/null
  652. trap - EXIT INT TERM
  653. umask "${old_umask}"
  654. return 1
  655. fi
  656. fi
  657. # Atomic move
  658. if ! mv "${tmp}" "${env_file}"; then
  659. err "Failed to write .env file"
  660. rm -f "${tmp}" 2>/dev/null
  661. trap - EXIT INT TERM
  662. umask "${old_umask}"
  663. return 1
  664. fi
  665. else
  666. # Create new file
  667. if ! echo "HTTP_PORT=${HTTP_PORT_OVERRIDE}" > "${tmp}"; then
  668. err "Failed to create .env file"
  669. rm -f "${tmp}" 2>/dev/null
  670. trap - EXIT INT TERM
  671. umask "${old_umask}"
  672. return 1
  673. fi
  674. if ! mv "${tmp}" "${env_file}"; then
  675. err "Failed to write .env file"
  676. rm -f "${tmp}" 2>/dev/null
  677. trap - EXIT INT TERM
  678. umask "${old_umask}"
  679. return 1
  680. fi
  681. fi
  682. # Ensure secure permissions (in case file existed with wrong perms)
  683. chmod 600 "${env_file}" 2>/dev/null || warn "Could not set .env permissions to 600"
  684. trap - EXIT INT TERM
  685. umask "${old_umask}"
  686. ok "HTTP_PORT set to ${HTTP_PORT_OVERRIDE}"
  687. record_summary "HTTP port: ${HTTP_PORT_OVERRIDE}"
  688. }
  689. run_integration_and_start() {
  690. if [[ "${NO_START}" -eq 1 ]]; then
  691. warn "--no-start specified; skipping integration/start"
  692. return 0
  693. fi
  694. info "Running auto-detect integration and starting server"
  695. (
  696. cd "${REPO_DIR}"
  697. # Child script uses `uv run python` which auto-detects the venv, so
  698. # we skip `source .venv/bin/activate` (Unix-only path, see GH#144).
  699. export INTEGRATION_BEARER_TOKEN="${INTEGRATION_TOKEN}"
  700. args=()
  701. if [[ "${YES}" -eq 1 ]]; then args+=("--yes"); fi
  702. if [[ -n "${PROJECT_DIR}" ]]; then args+=("--project-dir" "${PROJECT_DIR}"); fi
  703. bash scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh "${args[@]}"
  704. )
  705. }
  706. ensure_beads() {
  707. if [[ "${SKIP_BEADS}" -eq 1 ]]; then
  708. warn "--skip-beads specified; not installing Beads Rust CLI"
  709. record_summary "Beads Rust CLI: skipped (--skip-beads)"
  710. return 0
  711. fi
  712. local br_path
  713. if br_path=$(find_br_binary); then
  714. verify_br_binary "${br_path}" || exit 1
  715. ensure_br_path_ready "${br_path}"
  716. install_bd_alias
  717. record_summary "Beads Rust CLI: ${LAST_BR_VERSION}"
  718. return 0
  719. fi
  720. info "Installing Beads Rust (br) CLI"
  721. if ! need_cmd curl; then
  722. err "curl is required to install Beads Rust automatically"
  723. exit 1
  724. fi
  725. # Download first, then execute — avoids nested curl|bash stdin corruption
  726. local br_tmp_script
  727. br_tmp_script=$(mktemp "${TMPDIR:-/tmp}/br-install.XXXXXX.sh")
  728. if ! curl -fsSL "${BEADS_INSTALL_URL}?$(date +%s)" -o "${br_tmp_script}"; then
  729. rm -f "${br_tmp_script}"
  730. err "Failed to download Beads Rust installer. You can install manually via: curl -fsSL ${BEADS_INSTALL_URL} | bash"
  731. exit 1
  732. fi
  733. if ! bash "${br_tmp_script}"; then
  734. rm -f "${br_tmp_script}"
  735. err "Failed to install Beads Rust automatically. You can install manually via: curl -fsSL ${BEADS_INSTALL_URL} | bash"
  736. exit 1
  737. fi
  738. rm -f "${br_tmp_script}"
  739. hash -r 2>/dev/null || true
  740. if br_path=$(find_br_binary); then
  741. verify_br_binary "${br_path}" || exit 1
  742. ensure_br_path_ready "${br_path}"
  743. install_bd_alias
  744. record_summary "Beads Rust CLI: ${LAST_BR_VERSION}"
  745. return 0
  746. fi
  747. err "Beads Rust installer finished but 'br' was not detected. Ensure its install directory is on PATH or rerun with --skip-beads to handle installation manually."
  748. exit 1
  749. }
  750. install_cli_stub() {
  751. # Install a helpful "mcp-agent-mail" command that explains this is NOT a CLI tool
  752. # This catches agents that mistakenly try to run it as a shell command
  753. local stub_dir="${HOME}/.local/bin"
  754. local stub_path="${stub_dir}/mcp-agent-mail"
  755. mkdir -p "${stub_dir}" 2>/dev/null || true
  756. cat > "${stub_path}" <<'STUB_EOF'
  757. #!/usr/bin/env bash
  758. # MCP Agent Mail — Helpful Stub for Confused Agents
  759. #
  760. # If you're seeing this, you (or an AI agent) tried to run "mcp-agent-mail"
  761. # as a CLI command. That's a common mistake!
  762. cat <<'MSG'
  763. ╔══════════════════════════════════════════════════════════════════════════════╗
  764. ║ ║
  765. ║ 🚫 MCP Agent Mail is NOT a CLI tool! ║
  766. ║ ║
  767. ║ It's an MCP (Model Context Protocol) server that provides tools to your ║
  768. ║ AI coding agent. You should already have access to these tools as part ║
  769. ║ of your available MCP tools. ║
  770. ║ ║
  771. ║ ✅ CORRECT USAGE: ║
  772. ║ Use the MCP tools directly, for example: ║
  773. ║ • mcp__mcp-agent-mail__register_agent ║
  774. ║ • mcp__mcp-agent-mail__send_message ║
  775. ║ • mcp__mcp-agent-mail__fetch_inbox ║
  776. ║ ║
  777. ║ ❌ INCORRECT USAGE: ║
  778. ║ Running shell commands like: ║
  779. ║ • mcp-agent-mail send --to BlueLake ... ║
  780. ║ • mcp-agent-mail --help ║
  781. ║ ║
  782. ║ 📚 For documentation, see: ║
  783. ║ https://github.com/Dicklesworthstone/mcp_agent_mail ║
  784. ║ ║
  785. ╚══════════════════════════════════════════════════════════════════════════════╝
  786. MSG
  787. exit 1
  788. STUB_EOF
  789. chmod +x "${stub_path}" 2>/dev/null || true
  790. # Also create common aliases/variants agents might try
  791. for variant in "mcp_agent_mail" "mcpagentmail" "agentmail" "agent-mail"; do
  792. local variant_path="${stub_dir}/${variant}"
  793. if [[ ! -f "${variant_path}" ]]; then
  794. ln -sf "${stub_path}" "${variant_path}" 2>/dev/null || true
  795. fi
  796. done
  797. ok "Installed helpful CLI stub at ${stub_path}"
  798. record_summary "CLI stub: installed (catches mistaken CLI usage)"
  799. }
  800. ensure_bv() {
  801. if [[ "${SKIP_BV}" -eq 1 ]]; then
  802. warn "--skip-bv specified; not installing Beads Viewer"
  803. record_summary "Beads Viewer: skipped (--skip-bv)"
  804. return 0
  805. fi
  806. local bv_path
  807. if bv_path=$(find_bv_binary); then
  808. if verify_bv_binary "${bv_path}"; then
  809. maybe_add_bv_path "${bv_path}"
  810. record_summary "Beads Viewer: ${LAST_BV_VERSION}"
  811. else
  812. warn "Beads Viewer found but verification failed; continuing without bv"
  813. record_summary "Beads Viewer: found but failed verification"
  814. fi
  815. return 0
  816. fi
  817. info "Installing Beads Viewer (bv) TUI (optional)"
  818. if ! need_cmd curl; then
  819. warn "curl not available; skipping Beads Viewer installation"
  820. record_summary "Beads Viewer: skipped (no curl)"
  821. return 0
  822. fi
  823. # Download first, then execute — avoids nested curl|bash stdin corruption
  824. local bv_tmp_script
  825. bv_tmp_script=$(mktemp "${TMPDIR:-/tmp}/bv-install.XXXXXX.sh")
  826. if ! curl -fsSL "${BV_INSTALL_URL}" -o "${bv_tmp_script}" || ! bash "${bv_tmp_script}"; then
  827. rm -f "${bv_tmp_script}"
  828. warn "Beads Viewer installation failed (non-fatal). You can install manually via: curl -fsSL ${BV_INSTALL_URL} | bash"
  829. record_summary "Beads Viewer: installation failed (optional)"
  830. return 0
  831. fi
  832. rm -f "${bv_tmp_script}"
  833. hash -r 2>/dev/null || true
  834. if bv_path=$(find_bv_binary); then
  835. if verify_bv_binary "${bv_path}"; then
  836. maybe_add_bv_path "${bv_path}"
  837. record_summary "Beads Viewer: ${LAST_BV_VERSION}"
  838. else
  839. warn "Beads Viewer installed but verification failed"
  840. record_summary "Beads Viewer: installed but failed verification"
  841. fi
  842. return 0
  843. fi
  844. warn "Beads Viewer installer finished but 'bv' was not detected. You can install manually via: curl -fsSL ${BV_INSTALL_URL} | bash"
  845. record_summary "Beads Viewer: not detected after install (optional)"
  846. return 0
  847. }
  848. offer_doc_blurbs() {
  849. if [[ "${YES}" -eq 1 ]]; then
  850. info "Docs helper available anytime via: uv run python -m mcp_agent_mail.cli docs insert-blurbs"
  851. return 0
  852. fi
  853. echo
  854. echo "Would you like to automatically detect your code projects and insert the relevant blurbs for Agent Mail into your AGENTS.md and CLAUDE.md files?"
  855. echo "You will be able to confirm for each detecting project if you want to do that. Otherwise, just skip that, but be sure to add the blurbs yourself manually for the system to work properly."
  856. read -r -p "[y/N] " doc_choice
  857. doc_choice=$(printf '%s' "${doc_choice}" | tr -d '[:space:]')
  858. case "${doc_choice}" in
  859. y|Y)
  860. (
  861. cd "${REPO_DIR}" && uv run python -m mcp_agent_mail.cli docs insert-blurbs
  862. ) || warn "Docs helper encountered an issue. You can rerun it later with: uv run python -m mcp_agent_mail.cli docs insert-blurbs"
  863. ;;
  864. *)
  865. info "Skipping automatic doc updates; remember to add the blurbs manually."
  866. ;;
  867. esac
  868. }
  869. main() {
  870. if [[ "${START_ONLY}" -eq 1 ]]; then
  871. info "--start-only specified: skipping clone/setup; starting integration"
  872. REPO_DIR="$PWD"
  873. record_summary "Repo: existing at ${REPO_DIR} (--start-only)"
  874. ensure_beads
  875. ensure_bv
  876. install_cli_stub
  877. install_am_alias "${REPO_DIR}"
  878. configure_port
  879. if ! run_integration_and_start; then
  880. err "Integration failed; aborting."
  881. exit 1
  882. fi
  883. record_summary "Integration: auto-detect + server start"
  884. print_summary
  885. offer_doc_blurbs
  886. exit 0
  887. fi
  888. ensure_uv
  889. ensure_jq
  890. ensure_beads
  891. ensure_bv
  892. install_cli_stub
  893. ensure_repo
  894. ensure_python_and_venv
  895. sync_deps
  896. install_am_alias "${REPO_DIR}"
  897. configure_port
  898. if ! run_integration_and_start; then
  899. err "Integration failed; aborting."
  900. exit 1
  901. fi
  902. record_summary "Integration: auto-detect + server start"
  903. print_summary
  904. offer_doc_blurbs
  905. echo
  906. ok "All set!"
  907. echo "Next runs (open a new terminal or run 'source ~/.zshrc' / 'source ~/.bashrc'):"
  908. echo " am # quick alias to start the server"
  909. echo " # or manually (uv auto-detects .venv, no activate needed):"
  910. echo " cd \"${REPO_DIR}\""
  911. echo " uv run python -m mcp_agent_mail.cli"
  912. }
  913. # Handle three execution modes:
  914. # 1. Direct: ./install.sh → BASH_SOURCE[0] == $0 → run main
  915. # 2. Sourced: . install.sh → BASH_SOURCE[0] != $0 → skip main
  916. # 3. Piped: curl ... | bash -s → BASH_SOURCE[0] is unset → run main
  917. if [[ -z "${BASH_SOURCE[0]:-}" ]] || [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  918. main "$@"
  919. fi

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.