# 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`](./SPEC.md).

## Quick start

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

Register in `~/.claude.json` under `mcpServers`:

```json
{
  "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`](./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`](./LICENSE).