Add MCP Comms Relay specification and research

[nsheaps]

Summary

This PR introduces the specification and research documentation for the MCP Comms Relay — a publicly reachable relay service that enables two AI agents on opposite sides of a network boundary to exchange messages without either running a public server.

Changes

• docs/specs/draft/mcp-comms-relay.md — Complete specification (v0.1.0) covering:

  • Problem statement: enabling message exchange between claude.ai and local Claude Code agents without public exposure
  • Design architecture: symmetric MCP client topology with a central dial-out relay behind cloudflared
  • Five core MCP tools: advertise, discover, handshake, send, receive (long-poll)
  • OAuth 2.1 + PKCE S256 requirements for claude.ai custom connector integration
  • Docker + docker-compose deployment pattern mirroring portainer-stacks conventions
  • Acceptance criteria (8 scenarios covering OAuth discovery, peer handshake, message flow, presence expiry, and stack deployment)
  • Four-phase implementation roadmap (scaffold → relay core → OAuth layer → containerization, with optional Phase 4 connector helper)

• docs/research/mcp-comms-relay-requirements.md — Research grounding document covering:

  • claude.ai custom connector requirements (Streamable HTTP, OAuth 2.1 + PKCE S256, callback URL)
  • MCP authorization flow and required endpoints (PRM, AS metadata, DCR, token)
  • Practical limits (tool result size, timeouts) that shape the relay design
  • MCP TypeScript SDK guidance (@modelcontextprotocol/sdk v1.x, StreamableHTTPServerTransport)
  • Deployment decision rationale (self-hosted container + cloudflared vs. Cloudflare Workers)
  • Open design questions resolved in the spec

Implementation Notes

• Scope: MVP is single-user, single-room, in-memory broker; file sharing, multi-user, and persistence are explicitly deferred
• Audience: Handler (Nate) and engineers implementing the relay
• Phasing: Phase 0 (this PR) establishes the spec; Phase 1 builds the authless relay core; Phase 2 adds OAuth; Phase 3 containerizes and deploys
• Location: Service will be authored in nsheaps/agents at services/mcp-comms-relay/ with a droppable docker-compose stack

https://claude.ai/code/session_01746yPFhHs256Qvnp54hEH3