releases/ClaudeMailbox
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

feat(mcp): identity-via-arg + plugin ships .mcp.json

Browse Source 
MCP tools (send/check_inbox/peek_inbox/list_mailboxes) now accept the
caller's mailbox name as an explicit argument (from/name), falling back
to the X-Mailbox header for legacy single-session HTTP setups. This
unblocks multi-session coordination through a shared .mcp.json — each
Claude session passes its own session-derived name on every call,
instead of relying on a single transport header that all sessions
would share.

The plugin now ships .mcp.json (no header), and the SessionStart
announcement spells out the exact args to pass to each mcp__mailbox__*
tool so Claude wires it up automatically.
This commit is contained in:
Mika Kuns
2026-05-19 11:50:58 +02:00
parent 462d6561e1
commit 9fd321043f
7 changed files with 179 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
plugin/README.md
View File

@@ -37,11 +37,24 @@ The `SessionStart` hook announces the current session's mailbox name in the conv
| Hook | Command | Effect |
|---|---|---|
| `SessionStart` | `claude-mailbox session-announce` | Prints `"Claude-Mailbox: this session is mailbox \`X\`"` so Claude knows its own identity. |
| `SessionStart` | `claude-mailbox session-announce` | Tells Claude its mailbox name for this session and instructs it on the `from` / `name` args to pass to MCP tools. |
| `UserPromptSubmit` | `claude-mailbox check --hook` | Pulls unread messages for the session's mailbox and injects them as context. Silent on empty inbox; emits a one-line setup hint when the daemon is unreachable. |
Cost: one local HTTP round-trip per prompt + Node coldstart (~100ms on Windows).
## MCP tools
The plugin also ships a `.mcp.json` so Claude has direct access to the mailbox via tool calls. Because the X-Mailbox header would be the same for two parallel sessions sharing one `.mcp.json`, **each MCP tool takes the caller's mailbox name as an explicit argument** (from the SessionStart announcement):
| Tool | Required args | Purpose |
|---|---|---|
| `mcp__mailbox__send` | `from`, `to`, `body` | Send a message to another mailbox. |
| `mcp__mailbox__check_inbox` | `name` | Pull all undelivered messages for your mailbox (marks delivered). |
| `mcp__mailbox__peek_inbox` | `name` | Non-consuming count of pending messages. |
| `mcp__mailbox__list_mailboxes` | `name` | Discover known mailboxes and `pendingForYou` counts. |
The SessionStart announcement spells out the exact args to pass, so Claude picks them up automatically.
## Slash commands
| Command | What it does |
@@ -50,12 +63,17 @@ Cost: one local HTTP round-trip per prompt + Node coldstart (~100ms on Windows).
| `/claude-mailbox:mailbox-status` | Read-only health check. No changes. |
| `/claude-mailbox:mailbox-update` | Update the daemon to the latest npm version and restart it. |
## Sending a message to a peer session
## Coordinating two Claude Code sessions
From inside Claude Code, use the MCP tool (the daemon already exposes `mcp__mailbox__*`). From any shell:
1. Open two Claude Code sessions in the same (or different) project.
2. Each session's SessionStart hook announces its mailbox name in context.
3. In session A you can say: *"I have a second session running. Use `mcp__mailbox__list_mailboxes` to find it and send `<msg>`."* Claude will discover the peer's mailbox and send via `mcp__mailbox__send`.
4. Session B's `UserPromptSubmit` hook pulls the message on its next prompt and injects it as context.
You can also send from any shell:
```sh
claude-mailbox list # find the recipient's mailbox name
claude-mailbox list
claude-mailbox send --from probe --to backend-a8b3c1d2 --body "hi"
```