{"id":47823676,"url":"https://github.com/lleontor705/agent-mailbox-mcp","last_synced_at":"2026-04-03T19:18:14.985Z","repository":{"id":348187256,"uuid":"1195024333","full_name":"lleontor705/agent-mailbox-mcp","owner":"lleontor705","description":"MCP Server for inter-agent messaging — SQS-style mailbox for multi-agent AI systems","archived":false,"fork":false,"pushed_at":"2026-03-31T06:24:54.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-31T07:49:42.348Z","etag":null,"topics":["ai","mailbox","mcp","messaging","model-context-protocol","multi-agent"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lleontor705.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T05:35:04.000Z","updated_at":"2026-03-31T05:40:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lleontor705/agent-mailbox-mcp","commit_stats":null,"previous_names":["lleontor705/agent-mailbox-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lleontor705/agent-mailbox-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fagent-mailbox-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fagent-mailbox-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fagent-mailbox-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fagent-mailbox-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lleontor705","download_url":"https://codeload.github.com/lleontor705/agent-mailbox-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fagent-mailbox-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31372201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","mailbox","mcp","messaging","model-context-protocol","multi-agent"],"created_at":"2026-04-03T19:18:14.205Z","updated_at":"2026-04-03T19:18:14.974Z","avatar_url":"https://github.com/lleontor705.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" width=\"100\" height=\"100\" alt=\"agent-mailbox-mcp\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eagent-mailbox-mcp\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMCP + A2A messaging server for multi-agent AI systems\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/agent-mailbox-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/agent-mailbox-mcp?color=blue\u0026label=npm\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lleontor705/agent-mailbox-mcp/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/lleontor705/agent-mailbox-mcp/ci.yml?label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/node-%3E%3D18-brightgreen\" alt=\"Node\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Mailbox-style messaging · A2A task delegation · Resource coordination · Web dashboard\u003cbr\u003e\n  Works with \u003cstrong\u003eClaude Code\u003c/strong\u003e, \u003cstrong\u003eCodex CLI\u003c/strong\u003e, \u003cstrong\u003eGemini CLI\u003c/strong\u003e, and any MCP-compatible client\n\u003c/p\u003e\n\n---\n\n## Why?\n\nAI agents working in multi-agent systems need to **communicate, delegate tasks, and coordinate resources**. Without a messaging layer:\n\n- Agents can't send results to each other\n- No way to delegate complex work to specialized agents\n- Multiple agents editing the same file cause conflicts\n- Failed or expired messages are silently lost\n\n**agent-mailbox-mcp** provides the messaging infrastructure your agents need — combining [MCP](https://modelcontextprotocol.io/) (agent-to-tools) with [A2A](https://a2aprotocol.ai/) (agent-to-agent) in a single server.\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/architecture.svg\" alt=\"Architecture\" width=\"850\"\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n```bash\n# stdio mode (default — use with Claude Code, Codex, Gemini)\nnpx -y agent-mailbox-mcp\n\n# HTTP mode (enables A2A, dashboard, SSE streaming)\nMAILBOX_TRANSPORT=http npx -y agent-mailbox-mcp\n# → Dashboard: http://localhost:4820/dashboard\n# → Agent Card: http://localhost:4820/.well-known/agent-card.json\n# → A2A endpoint: http://localhost:4820/a2a\n```\n\n## Configure Your AI Client\n\n### Claude Code\n\n```bash\nclaude mcp add agent-mailbox --transport stdio -- npx -y agent-mailbox-mcp\n```\n\n### Codex CLI (`~/.codex/config.toml`)\n\n```toml\n[mcp_servers.agent-mailbox]\ncommand = \"npx\"\nargs = [\"-y\", \"agent-mailbox-mcp\"]\n```\n\n### Gemini CLI (`settings.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-mailbox\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-mailbox-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code (MCP extension)\n\n```json\n{\n  \"servers\": {\n    \"agent-mailbox\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-mailbox-mcp\"]\n    }\n  }\n}\n```\n\n## Features\n\n### Messaging (12 tools)\n\nSend, receive, search, and manage messages between agents with priority, threading, deduplication, and auto-expiration.\n\n```\n→ msg_send(sender: \"coordinator\", recipient: \"analyst\", subject: \"Q1 Report\", body: \"Generate the Q1 revenue report\", priority: \"high\")\n← { sent: true, message_id: \"msg-a1b2c3\", thread_id: \"thr-d4e5f6\" }\n\n→ msg_read_inbox(agent: \"analyst\")\n← { count: 1, messages: [{ subject: \"Q1 Report\", priority: \"high\", ... }] }\n\n→ msg_acknowledge(message_id: \"msg-a1b2c3\", reply_body: \"Report ready: revenue up 23% QoQ\")\n```\n\n### A2A Task Delegation (5 tools)\n\nDelegate complex work to specialized agents. Tasks have a full lifecycle with state tracking, artifacts, and streaming.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/a2a-flow.svg\" alt=\"A2A Task Flow\" width=\"750\"\u003e\n\u003c/p\u003e\n\n```\n→ a2a_submit_task(from_agent: \"manager\", to_agent: \"researcher\", message: \"Find top 5 competitors\")\n← { task_id: \"task-x1y2z3\", status: \"submitted\" }\n\n→ a2a_respond_task(task_id: \"task-x1y2z3\", message: \"Analysis complete: ...\", status: \"completed\", artifact_name: \"competitor-report\")\n```\n\n### Resource Coordination (4 tools)\n\nAdvisory locking for files, APIs, or any shared resource. Prevents agents from stepping on each other's work.\n\n```\n→ resource_acquire(resource_id: \"data/config.yaml\", agent: \"editor-1\", lease_type: \"exclusive\", ttl_seconds: 60)\n← { acquired: true }\n\n→ resource_acquire(resource_id: \"data/config.yaml\", agent: \"editor-2\")\n← { acquired: false, holder: { agent_id: \"editor-1\", expires_at: \"...\" } }\n```\n\n### Dead-Letter Queue (3 tools)\n\nExpired and failed messages go to a DLQ instead of being lost. Retry or purge them.\n\n```\n→ dlq_list()\n← { count: 2, entries: [{ reason: \"expired\", subject: \"Important task\", ... }] }\n\n→ dlq_retry(dlq_id: \"dlq-abc123\")\n← { retried: true, new_message_id: \"msg-...\" }\n```\n\n### Web Dashboard\n\nReal-time monitoring of agents, messages, tasks, leases, and DLQ — accessible at `/dashboard` when running in HTTP mode.\n\n### HTTP + A2A Protocol\n\nFull [A2A protocol](https://a2aprotocol.ai/) support over JSON-RPC 2.0:\n\n- **Agent Cards** at `/.well-known/agent-card.json` for discovery\n- **SSE Streaming** at `/a2a/tasks/:id/stream` for real-time task updates\n- **Push Notifications** via webhooks with exponential backoff retry\n- **JWT Authentication** with granular scopes\n\n### Encryption at Rest\n\nOptional AES-256-GCM encryption for message bodies. Set `MAILBOX_ENCRYPTION_KEY` to enable — transparent to tools.\n\n## All 27 Tools\n\n| Category | Tools | Description |\n|----------|-------|-------------|\n| **Messaging** | `msg_send` `msg_read_inbox` `msg_acknowledge` `msg_broadcast` `msg_search` `msg_request` `msg_list_threads` `msg_get` `msg_delete` `msg_count` `msg_update_status` | Full messaging lifecycle with priority, threading, dedup |\n| **Registry** | `agent_register` `msg_list_agents` `msg_activity_feed` | Agent discovery and monitoring |\n| **A2A Tasks** | `a2a_submit_task` `a2a_get_task` `a2a_cancel_task` `a2a_list_tasks` `a2a_respond_task` | Task delegation with state machine |\n| **Resources** | `resource_acquire` `resource_release` `resource_check` `resource_list` | Advisory resource leasing |\n| **Dead Letter** | `dlq_list` `dlq_retry` `dlq_purge` | Failed message recovery |\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MAILBOX_DIR` | `~/.agent-mailbox` | Database directory |\n| `MAILBOX_DB` | `~/.agent-mailbox/mailbox.db` | Full database path |\n| `MAILBOX_TTL` | `86400` | Message TTL in seconds (default 24h) |\n| `MAILBOX_PORT` | `4820` | HTTP server port |\n| `MAILBOX_TRANSPORT` | `stdio` | Transport: `stdio`, `http`, or `both` |\n| `MAILBOX_AUTH_SECRET` | — | JWT signing secret (empty = auth disabled) |\n| `MAILBOX_ENCRYPTION_KEY` | — | AES-256-GCM key (empty = no encryption) |\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](docs/getting-started.md) | Installation, configuration, first message |\n| [Tools Reference](docs/tools-reference.md) | All 27 tools with parameters and examples |\n| [A2A Protocol Guide](docs/a2a-guide.md) | Task delegation, Agent Cards, streaming, webhooks |\n| [Examples](docs/examples.md) | Real-world usage patterns |\n| [Skill Guide](docs/SKILL.md) | Guide for AI agents on how to use the mailbox |\n\n## Development\n\n```bash\ngit clone https://github.com/lleontor705/agent-mailbox-mcp.git\ncd agent-mailbox-mcp\nnpm install\nnpm run dev          # stdio server\nnpm run serve        # HTTP server with dashboard\nnpm test             # 111 tests\nnpm run build        # TypeScript compilation\nnpm run inspect      # MCP inspector\n```\n\n## Tech Stack\n\n- **TypeScript** with strict mode\n- **SQLite** (WAL mode) via better-sqlite3 — zero external services\n- **Express** for HTTP transport\n- **MCP SDK** (@modelcontextprotocol/sdk) for protocol compliance\n- **Zod** for runtime input validation\n- **Node.js crypto** for JWT and AES-256-GCM — zero auth dependencies\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flleontor705%2Fagent-mailbox-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flleontor705%2Fagent-mailbox-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flleontor705%2Fagent-mailbox-mcp/lists"}