Skip to main content
Glama
mcp-p2p-swarm-mesh

mcp-p2p-swarm-mesh

mcp-p2p-swarm-mesh

Python MCP License Tests

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: OmniAgent MCP Mesh

πŸ–₯️ 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that connects any MCP harness (Claude Code, claude.ai, Cursor) to a fleet of GenSwarms swarms for observation, configuration, and optional operation.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables AI agents on different machines to communicate and collaborate directly through relay channels, supporting structured agent contracts, real-time messaging, and human-in-the-loop approval workflows.
      1
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables autonomous agent swarms to coordinate and reach deterministic convergence through epidemic dissemination, causal vector clocks, CRDT reconciliation, quorum-based leader election, and atomic two-phase commit over MCP. It also supports bounded network traffic via rate limiting and conflict-free replication.
      MIT