mcp-p2p-swarm-mesh

A decentralized, multi-agent peer-to-peer (P2P) Model Context Protocol (MCP) router built strictly in Python 3.10+. It bridges physically distributed, independent MCP servers into an encrypted, self-healing swarm mesh, complete with an interactive Streamlit Web Application Control Center.

🌟 Key Architecture & Capabilities

• 👑 Gateway Node Lifecycle (FR-01): Bridges upstream MCP clients (Claude Desktop, Cursor, Autonomous Agents) over standard Stdio and SSE transports.

• 🌐 P2P Transport & Dynamic Discovery (FR-02): Decentralized node discovery over asynchronous UDP gossip protocol and encrypted mutual TLS 1.3 socket streams.

• 📋 Dynamic Capability Registry (FR-03): Aggregates tools, resources, and prompt templates into a unified catalog exposed via mesh://capabilities/registry.

• ⚡ Distributed Task Delegation (FR-04): Routes execution payloads via mesh_delegate_task to specific or auto-selected peers with progress streaming.

• 🤝 Swarm Consensus Orchestration (FR-05): Coordinates multi-agent deliberation routines (swarm_consensus_review) with customizable quorum thresholds and variance synthesis.

• 🔐 Zero-Trust Security (NFR-02): Cryptographic Ed25519 identity, ephemeral TLS X.509 certs, and EdDSA-signed capability JWT tokens with replay-attack nonce caching.

• 🛡️ Fault Tolerance & Isolation (NFR-03): Heartbeat decay failure detector isolating SUSPECT nodes at 10s and evicting DEAD nodes at 15s with automatic split-brain recovery.

• ⚡ High Performance (NFR-04): Verified intra-mesh routing overhead strictly < 50ms (measured ~3.5ms on localhost).

Related MCP server: genswarms-fleet-mcp

🖥️ Streamlit Control Center (app.py)

The repository includes a modern, operator-grade Streamlit web application with 5 interactive views:

1. Mesh Topology Matrix: Live Graphviz network graph and node status table with color-coded health states (ALIVE, SUSPECT, DEAD).

2. Capability Registry Browser: Searchable tools inventory, schema inspector, and live mesh://capabilities/registry JSON manifest viewer.

3. Task Delegation Workbench: Real-time form to issue delegated calls, generate signed EdDSA JWT tokens, and monitor execution latencies.

4. Swarm Consensus Chamber: Interactive multi-agent consensus prompts, quorum adjustments, and score synthesis.

5. Security & Framing Telemetry: Cryptographic key inspector, wire frame codec diagrams, and replay nonce cache monitor.

🚀 Quick Start

1. Installation

git clone https://github.com/shinevijayan03/mcp-p2p-swarm-mesh.git
cd mcp-p2p-swarm-mesh

# Create virtualenv
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install package
pip install -e ".[dev]"

2. Launch the Streamlit Control Center

streamlit run app.py

Open your browser at http://127.0.0.1:8501.

3. Run Gateway Server

# Stdio transport mode (e.g. for Claude Desktop)
python -m mcp_mesh.gateway.server --mcp-mode stdio

# SSE transport mode
python -m mcp_mesh.gateway.server --mcp-mode sse --mcp-port 8000

🧪 Testing

The repository maintains an exhaustive test suite covering unit tests, integration tests, chaos network simulations, and security penetration vectors:

# Run all tests
pytest -v

# Run with test coverage report
pytest --cov=mcp_mesh --cov-report=term-missing tests/

Result: 28 passed, 0 failed (100% pass rate).

📚 Technical Specifications

• IMPLEMENTATION_PLAN.md — Implementation roadmap, WBS, and risk mitigations.

• ARCHITECTURE.md — Topology, wire framing format, gossip state machines, and sequence diagrams.

• SOFTWARE_DESIGN.md — Module hierarchy, Pydantic schemas, event loops, and wire protocols.

• TEST_STRATEGY.md — Testing pyramid, async mocks, chaos injection, and benchmark setups.

• TEST_CASES.md — Granular test cases mapping to FR-01..FR-05, NFR-01..NFR-04, and EC-01..EC-04.

• DEPLOYMENT_PLAN.md — Virtualenv cluster guide, Docker, Docker Compose, and monitoring specs.

• USAGE_GUIDE.md — Claude Desktop integration, Python MCP client SDK, and custom worker node creation.

• PRIORITIZED_PLAN.md — 7-stage prioritized implementation roadmap.

📄 License

MIT License.