feat: agent relay mode — bridge AI agent to PeerJS players

[reifocS]

Summary

• Add maginet-agent/ MCP server that lets Claude Code play Magic: The Gathering
• Relay architecture: the browser hosting the WS connection acts as a bridge between the agent and PeerJS players — no custom WebSocket transport needed
• Agent's shapes appear under the relay browser's peer ID, so remote players see a normal PeerJS peer
• 20+ MCP tools: deck loading, card play, tap/untap, counters, text/rect placement, action log

How it works

Agent (MCP/WS) ←——→ Relay Browser ←—PeerJS—→ Opponent

1. Relay browser connects to agent via ws://localhost:3210
2. Agent plays cards → relay applies them as local shapes → PeerJS syncs to all players
3. Opponent plays cards → PeerJS syncs to relay → relay forwards to agent via WS
4. Relay doesn't play — open a second tab to play against the agent

Architecture

  graph LR
      subgraph "Your Machine"
          CC["Claude Code<br/>(LLM)"]
          MCP["MCP Server<br/>(Node.js)"]
          CC -- "stdio<br/>MCP protocol" --> MCP
          MCP -- "WebSocket<br/>localhost:3210" --> Relay
      end

      subgraph "Browsers"
          Relay["Relay Tab<br/>(bridges WS ↔ PeerJS)"]
          You["Your Tab<br/>(player)"]
          Opp["Opponent<br/>(player)"]
      end

      Relay -- "PeerJS<br/>WebRTC" --> You
      Relay -- "PeerJS<br/>WebRTC" --> Opp

      style Relay fill:#f9f,stroke:#333,stroke-width:2px
      style MCP fill:#bbf,stroke:#333,stroke-width:2px

Loading

Data flow

  sequenceDiagram
      participant Agent as MCP Agent
      participant Relay as Relay Browser
      participant Player as Opponent (PeerJS)

      Note over Relay: User clicks "Start Relay"
      Relay->>Agent: WebSocket connect

      Agent->>Relay: sync:agent-shapes (agent plays card)
      Relay->>Relay: setShapes() — applies as local shapes
      Relay->>Player: PeerJS sync patch (relay's peer ID)

      Player->>Relay: PeerJS sync patch (opponent plays card)
      Relay->>Agent: sync:remote-shapes (all players' shapes)

      Player->>Relay: action-log (opponent drew a card)
      Relay->>Agent: action-log (forwarded)
      Agent->>Relay: action-log (agent's action)
      Relay->>Player: action-log (forwarded via PeerJS)

Loading

Alternative to PR #34

This replaces the dual sync client approach from #34 with a simpler relay pattern:

• No src/sync/transport/websocket.ts (deleted)
• No separate agentSyncClient in peerStore
• Single code path, less complexity
• Agent visible to all PeerJS peers through relay's identity

Test plan

• 32 agent-side tests passing (state, visibility, server, MCP tools, e2e)
• 21 browser-side tests passing
• Lint clean
• Both packages build
• Manual: start MCP server, open relay tab, click "Relay", open second tab, connect via PeerJS, verify agent plays are visible

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
excalightdraw	Ready	Preview, Comment	Mar 29, 2026 3:39pm