Message bridge MCP server for sending and reading messages between Claude Code instances across machines and projects via a Cloudflare Worker relay.
Photon has 7 tools with clear action verbs and reasonable descriptions (avg 150 chars). All tools have input schemas with type definitions and parameter descriptions. However, output schemas are not documented, LLMs cannot predict response structure for chaining. Error handling is minimal; no recovery guidance or actionable error messages. Parameter descriptions lack constraints (enums, ranges, formats). The Monitor tool conflates two concerns (arming a watcher + running a shell command), violating single-responsibility. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels. Descriptions are adequate but generic; they lack dependency hints and prerequisites.
Arm a background inbox watcher (recommended, once per session). The watcher polls cheaply for new messages addressed to your identity and emits an event (waking the agent) ONLY when new mail arrives. Stays silent otherwise and does not re-announce mail you already had. Re-arm after IDE reload or MCP restart. If you set or change your workstream with set_identity, re-arm so the watcher follows your new lane.
Check for unread messages addressed to this agent. Returns count of unread messages and basic metadata. Call this at session start to learn if there is waiting mail.
List all active agents and their workstreams for this project. Shows who is currently working the project and which workstream labels are taken. Useful for picking an unclaimed workstream label when calling set_identity.
Read messages addressed to this agent. By default returns all unread messages (any age) and auto-marks them read. Supports filtering by max_age_minutes or since timestamp. Pass all_lanes=true to see messages across all workstreams in the project.
Resolve a project name hint to a list of candidate project identities. Scans ~/dev and ~/Documents (up to 4 levels deep) for Photon-enabled projects. Returns 0, 1, or multiple matches. Do NOT guess project names — always call this first when sending cross-project messages.
Output schemas not documented. check_messages and list_identities lack visible return type definitions. LLMs cannot predict response structure, forcing them to guess field names for downstream chaining.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint). Tools are marked with Risk levels in metadata but not exposed to LLM via schema. LLM cannot reason about side effects or retry safety.
Monitor tool conflates two concerns: arming a background watcher AND executing a shell command. Should split into separate tools (arm_inbox_watcher + run_command) or clarify that 'command' is a preset, not user-supplied.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 56 | 2026-07-28+ | v2 |
Send a message to other agents. Without target=, broadcasts to other agents in your own project. To send cross-project, target= is required and must be a resolved project identity. Messages can include tags for categorization.
Claim a workstream sub-identity for this session (e.g. 'website', 'crypto'). Each workstream has its own read cursor, so one agent reading a message does not mark it read for others. The claim persists across MCP subprocess restarts for this session. Pass workstream=None to drop the claim and return to the base identity.
Parameter descriptions lack constraints. 'max_age_minutes' has no range (1 - 365?). 'tags' array has no length limit or item format. 'workstream' has no pattern (alphanumeric only?). LLMs will pass invalid values.
No error handling guidance. Tools do not document what errors are retryable, user-fixable, or fatal. No recovery hints (e.g., 'If project not found, call resolve_project first'). Agents cannot self-correct.