agent-switchboard

vitaminR/agent-switchboard

3.3

If you are the rightful owner of agent-switchboard and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Agent Patchbay is a versatile tool designed to streamline agent communication using Redis Streams and the Model Context Protocol (MCP).

Tools
5
Resources
0
Prompts
0

Agent switchboard — Redis + MCP ⚡️

Build the future of agentic communication. Agent SwitchBoard is a Swiss‑army knife for connecting agents, tools, and humans using Redis Streams and the Model Context Protocol (MCP). It ships with:

  • A production‑ready MCP server (Node) exposing Redis as a durable agent bus.
  • A REST bridge (FastAPI) so non‑MCP agents can still publish/consume.
  • Docker Compose for one‑command bring‑up (Redis + MCP + Bridge).
  • Ready‑to‑paste wiring examples for Gemini Code Assist, Claude Code, and GitHub Copilot.

Why this repo? Fragmented agent comms slow teams down. MCP standardizes how agents talk to tools; Redis gives you a fast, durable, observable message bus. SwitchBoard glues them together with pragmatic defaults.

1. Quickstart (Docker)

git clone <your-fork-url>
cd agent-switchboard
docker compose up --build -d
# check health
curl -s localhost:8002/healthz

Now point your MCP‑capable client at the MCP server (stdio) or the HTTP bridge:

  • Gemini Code Assist (local stdio) → see examples/gemini-settings.json
  • Claude Code (stdio/http) → see examples/claude-mcp.json
  • GitHub Copilot (stdio/http) → see examples/vscode-mcp.json

2. Why Redis + MCP? (vs Kafka, RabbitMQ, DBs & Files)

Redis Streams:

  • Durable log with IDs & replay; consumer groups for scale‑out.
  • Milliseconds latency, minimal ops overhead.
  • Great for agent traffic: tasks, results, heartbeats, audit trails.

MCP:

  • An open standard for connecting LLMs/agents to tools and data.
  • Works across Claude, Gemini, Copilot, and OpenAI Agents.
  • Integrate once → reuse everywhere.

Compared:

  • Kafka/RabbitMQ: powerful, but overkill for many teams; ops burden.
  • Postgres LISTEN/NOTIFY: lightweight pub/sub but not durable/replayable.
  • Filesystem/HTTP-only: easy, but brittle; no semantics for exactly‑once, acks, or back‑pressure.

References: MCP docs & guides from Anthropic, the protocol site, GitHub Copilot, and Gemini. (See repo footer for links.)

3. Architecture

MCP Clients (Claude | Gemini | Copilot | OpenAI Agents)
        │
        ├── STDIO ───────────────► Node MCP Server (this repo)
        │                           ├── Tools: xadd, xreadgroup, xack, xpending, publish, ping
        │                           └── Talks Redis Streams & Pub/Sub
        │
        └── HTTP/SSE (optional) ─► REST Bridge (FastAPI) ─► Redis
                                     └─ For non‑MCP agents (simple POST /publish)

4. Wiring (Local vs Cloud)

4.1 Local (on your dev box)

  • Gemini Code Assist: Chat → ~/.gemini/settings.json → "mcpServers" (see examples/gemini-settings.json).
  • Claude Code → .mcp.json / CLI with type: "stdio" | "http" (see examples/claude-mcp.json).
  • GitHub Copilot Chat → .vscode/mcp.json (see examples/vscode-mcp.json).

4.2 Cloud

  • Host the REST bridge or a proper HTTP/SSE MCP server behind TLS.
  • For quick demos: ngrok http 8002 → use https://…/mcp (when you add a proper MCP HTTP endpoint).
  • OpenAI Agents / Responses: register a remote MCP endpoint and call tools (see “Future Work: HTTP MCP Gateway”).

5. For non‑MCP agents: the SwitchBoard 🩹

  • REST publish: POST /publish with { "fields": {...} } → writes to agent:events.
  • CLI feeders: wrap existing shell scripts to post tasks & acks.
  • Webhook sinks: add small subscribers to forward Streams → webhooks/Slack.
  • Goal: be the catch‑all so every tool can participate, even before it speaks MCP.

6. Usage (MCP tools)

  • Health: redis_ping
  • Produce (durable): redis_xadd(stream="agent:events", fields={"from":"planner","type":"task","payload":"run lint"})
  • Group consume: redis_xgroup_create("agent:events","triage","$") then
    redis_xreadgroup(stream="agent:events", group="triage", consumer="worker-1", id=">", block_ms=15000)
  • Ack: redis_xack(stream="agent:events", group="triage", ids=["<id>"])
  • Pending: redis_xpending(stream="agent:events", group="triage")

7. Roadmap (help wanted)

  • HTTP/SSE MCP Gateway container (serve /mcp per spec; proxy to Redis tools).
  • Req/Rep helper (reply_to, correlation IDs, timeouts).
  • Consumer group ops: xclaim, xdel, xtrim, maxlen policies.
  • Observability: dashboards for PEL size, throughput, latency.
  • Adapters: Slack, GitHub Actions, Jenkins, k6, Datadog, etc.
  • Security: TLS + auth for the bridge; secrets via env/Keychain.

8. Contributing

PRs welcome! Please open an issue with your use‑case (agent flavor, toolchain, cloud). We’ll grow this into the community “SwitchBoard” for agent comms.

9. Links & Credits (learn more)

License: MIT

What this is: a switchboard + mailroom + Jira for agents

This repo is a communication fabric for multiple agents:

  • Switchboard: routes calls between agents and tools via MCP tools.
  • Mailroom: Redis Streams give durable in/out trays with IDs, acks, and replay.
  • Jira for agents: simple task states your agents can coordinate around.

Suggested task states:

  • backlog — queued work not yet claimed
  • in-progress — currently being worked on
  • up-for-vote — needs consensus/approval
  • blocked — waiting on a dependency or human

Practical mapping:

  • Use a durable stream (default agent:events) to post tasks: { type: "task", status, title, payload, reply_to }.
  • Use consumer groups (e.g., triage) for horizontal workers and acknowledgements.
  • Use Pub/Sub channels for ephemeral signals (e.g., vote:approve:<taskId>).
  • Correlate results via reply_to and message IDs; store outputs back to Streams for audit.

This is explicitly for multi-agent communication and orchestration so your agents can talk, coordinate, and ship work together.

Prereqs & dependencies

  • Node.js 18+ (tested with Node 22)
  • Redis 6+
  • NPM dependencies (already included):
    • @modelcontextprotocol/sdk ^1.18.x — MCP v1 server API (stdio transport)
    • zod ^3 — tool input schemas and runtime validation
    • redis ^4 — node-redis client for Streams and Pub/Sub

Why zod? Tool inputs are defined with zod schemas and validated automatically; the MCP SDK converts them to JSON Schema for client UIs. This makes calls from Gemini/Claude/Copilot safer with clearer errors.

EOF

Clients: quick wiring

  • Gemini (VS Code): copy examples/gemini-settings.example.json to your user or project .gemini/settings.json and replace /ABS/PATH with your local path.
  • GitHub Copilot Chat (VS Code MCP preview): copy examples/vscode-mcp.example.json to .vscode/mcp.json and replace /ABS/PATH.
  • Claude: copy examples/claude-mcp.example.json to your MCP config location and replace /ABS/PATH.

Troubleshooting: “0 tools”

  • Use command: "node" and put the server script path in args.
  • Use an absolute path to src/mcp/index.mjs and reload your editor.
  • Ensure Redis is reachable at REDIS_URL=redis://127.0.0.1:6379.
  • Avoid a port conflict if Dockerized Redis is also mapping 6379 on the host.
  • If still empty, run a quick sanity start: 
    REDIS_URL=redis://127.0.0.1:6379 node /ABS/PATH/agent-switchboard/src/mcp/index.mjs
    You should see a startup banner. Then reload your editor and list MCP tools.

EOF

git add examples README.md && git commit -m "docs(examples): add Gemini/Copilot/Claude MCP config examples; add troubleshooting for 0 tools and quick wiring section" && git push