mailbox-mcp

MCP server for inter-agent mailbox communication. Structured API over the existing <repo>/.claude/{inbox,outbox}/*.md file convention used by Grygoriy's Claude-Code orchestration setup.

Status: Phase 1 in development.

Full spec: see SPEC.md.

Quick start

npm install
npm run build
npm start                # runs the MCP server over stdio

Register in ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "mailbox": {
      "command": "node",
      "args": ["C:\\Users\\Gree\\workspace\\tools\\mailbox-mcp\\dist\\index.js"]
    }
  }
}

Restart Claude Code. Verify via /mcp — should list mailbox as connected.

Tool surface (Phase 1)

• mail_send(to, topic, body, [status, refs, reply_to, labels]) — drop a mail into target agent's inbox
• mail_list(agent, folder, [status, since, labels, limit]) — list mails
• mail_get(id, agent, folder) — read full mail
• mail_reply(in_reply_to, body, [topic, to, parent_status, initial_status, ...]) — reply + auto-flip parent. Topic defaults to the parent's — same conversation continues; pass an explicit topic only to fork the subject.
• mail_status(id, agent, folder, status) — flip status, audit-logged
• mail_thread(root_id) — full thread tree

See SPEC.md for details.

Phase 2 (planned)

GitLab pipeline / MR watchers + templates + scheduled / conditional send. Separate background daemon.

Layout

src/
├── index.ts              # MCP server entrypoint
├── types.ts              # Mail types
├── config.ts             # Agent enum + paths
├── tools/                # One file per tool
└── storage/              # File I/O, frontmatter, naming, audit

Notes

mail_reply topic behavior — the reply's topic defaults to the parent's topic (same conversation continues). Pass an explicit topic only when the reply forks the subject. Previously the schema required topic; if a caller omitted it, the JS coerced undefined → the literal string "undefined" past the regex-only validator, producing filenames like 2026-07-07-1111-undefined.md and frontmatter with no topic: key — which mail_list then silently skipped as malformed. assertValidTopic now hard-rejects non-string / empty.

License

MIT — see LICENSE.