# MCP Mesh

> **DEPRECATED**: This package has been absorbed into [mcp-iot-gateway](https://github.com/Symbia-Labs/mcp-iot-gateway). The federation functionality is now built-in to the gateway as the `@mcp-iot-gateway/core` federation module. This repository is archived for reference only.

**Peer-to-peer federation for MCP servers.**

MCP Mesh enables decentralized, peer-to-peer communication between MCP servers. It solves the fundamental limitation of MCP's client-server model: a single client can only connect to one server at a time.

```
                    ┌─────────────┐
                    │   Claude    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  mcp-mesh   │  ← One connection
                    └──────┬──────┘
                           │ bridges to many
              ┌────────────┴────────────┐
              │                         │
       ┌──────▼──────┐          ┌──────▼──────┐
       │   factory   │◀────────▶│    edge     │
       │   gateway   │  peers   │   gateway   │
       └─────────────┘          └─────────────┘
```

## Features

- **Bridge Mode** - Re-export remote tools locally with prefixes (`factory_iot_discover`)
- **P2P Connections** - Direct node-to-node communication
- **Hub Mode** - Optional central coordinator for network management
- **meshctl CLI** - Hamachi-style network management
- **Pure MCP** - No protocol extensions, works with any MCP client

## Installation

```bash
npm install mcp-mesh
```

Or run directly:

```bash
npx mcp-mesh --help
```

## Quick Start

### P2P Mode (Direct Connections)

Start a mesh node that bridges to other gateways:

```bash
# Start mesh node bridging to factory and edge gateways
mcp-mesh --port 45679 --name "my-mesh" --bridge factory --bridge edge
```

The bridged tools become available with prefixes:
- `factory_iot_discover` → calls `iot_discover` on factory
- `edge_gateway_status` → calls `gateway_status` on edge

### Hub Mode (Centralized Network)

Start a hub for network coordination:

```bash
# Start hub
mcp-mesh --hub --port 45679 --name "central" --network "mycompany"

# Join from other nodes
mcp-mesh --port 45680 --name "factory-gw" --join http://hub:45679/mcp
```

### Claude Desktop Integration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mcp-mesh": {
      "command": "npx",
      "args": [
        "mcp-mesh",
        "--stdio",
        "--name", "claude-desktop",
        "--bridge", "factory",
        "--bridge", "edge"
      ]
    }
  }
}
```

## CLI Reference

### mcp-mesh

```
mcp-mesh [options]

Options:
  --stdio           Use stdio transport (for MCP clients)
  --port <port>     HTTP server port (default: 45679)
  --name <name>     Human-readable name for this node
  --bridge <spec>   Bridge to a peer (UUID, name, or URL). Repeatable.
  --peer <key=url>  Connect to a peer without bridging. Repeatable.
  --hub             Run as hub (central coordinator)
  --join <url>      Join a hub network by URL
  --network <id>    Network ID (for hub mode)
```

### meshctl

Network management CLI (Hamachi-style):

```
meshctl status              Show local node status
meshctl list                List all nodes in directory
meshctl networks            List available hubs
meshctl network <hub-url>   Show network details
meshctl join <hub-url>      Join a network
meshctl connect <peer>      Connect to peer
meshctl disconnect <peer>   Disconnect from peer
```

## API Usage

### Basic Node

```typescript
import { MeshNode, registerMeshTools } from "mcp-mesh";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

// Create mesh node
const node = new MeshNode({
  name: "my-server",
  url: "http://localhost:45678/mcp",
});

// Add mesh tools to your MCP server
const server = new McpServer({ name: "my-server", version: "1.0" });
registerMeshTools(server, node);

// Connect to peers
await node.bridge("factory");  // Bridge with prefix
await node.connectPeer({ key: "edge", url: "http://edge:45678/mcp" });
```

### Hub Mode

```typescript
const hub = new MeshNode({
  name: "central-hub",
  hub: true,
  networkId: "mycompany",
});

// Nodes register automatically via mesh_hub_register tool
// Or programmatically:
hub.hubRegister({
  id: "node-uuid",
  name: "factory",
  url: "http://factory:45678/mcp",
});

// Get network status
const stats = hub.hubStats();
const nodes = hub.hubListNodes({ onlineOnly: true });
```

### Directory Lookup

```typescript
import { MeshDirectory } from "mcp-mesh";

const directory = new MeshDirectory();

// List all known nodes
const nodes = directory.list();

// Look up by name or UUID
const factory = directory.lookup("factory");
console.log(factory?.url);  // http://127.0.0.1:45678/mcp

// Resolve any specifier (URL, UUID, or name)
const entry = directory.resolve("factory");
```

## MCP Tools

When `registerMeshTools()` is called, these tools are added:

### Peer Management
| Tool | Description |
|------|-------------|
| `mesh_list_peers` | List all peer connections |
| `mesh_add_peer` | Connect to a peer |
| `mesh_remove_peer` | Disconnect from a peer |
| `mesh_call_peer` | Call a tool on a peer |
| `mesh_list_peer_tools` | List tools on a peer |

### Bridge Mode
| Tool | Description |
|------|-------------|
| `mesh_list_bridged_tools` | List tools from bridge peers |
| `mesh_call_bridged` | Call a bridged tool |

### Directory
| Tool | Description |
|------|-------------|
| `mesh_directory_list` | List all nodes in directory |
| `mesh_directory_lookup` | Look up a node |
| `mesh_node_info` | Get this node's info |

### Hub Mode (when `--hub`)
| Tool | Description |
|------|-------------|
| `mesh_hub_register` | Register a node with hub |
| `mesh_hub_heartbeat` | Send heartbeat |
| `mesh_hub_list_nodes` | List registered nodes |
| `mesh_hub_stats` | Get hub statistics |
| `mesh_hub_connect_node` | Connect to a registered node |

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_MESH_DATA_DIR` | Data directory | `~/.config/mcp-mesh` |
| `MCP_MESH_PEERS` | Peers file path | `~/.config/mcp-mesh/peers` |

### Peers File

The directory file at `~/.config/mcp-mesh/peers` uses a hosts-style format:

```
# MCP Mesh Peers
# Format: UUID  URL  [NAME]
#
a7196323-dcc1-4109-abf5-b47c2f99f920  http://127.0.0.1:45678/mcp  factory
9f157a51-7aaa-4f2c-bc38-3c791b604892  http://127.0.0.1:45679/mcp  edge
```

## Architecture

See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed design documentation.

### Topology Options

**P2P (Decentralized)**
```
    A ←──→ B
    ↑       ↑
    │       │
    ↓       ↓
    C ←──→ D
```
- No single point of failure
- Works offline/air-gapped
- Each node manages its own connections

**Hub (Centralized)**
```
        Hub
       / | \
      A  B  C
```
- Central registry and coordination
- Easier network management
- Better for enterprise/audit requirements

**Hybrid**
```
        Hub
       / | \
    Site Site Site
     /\   |    /\
    A  B  C   D  E
```
- Hub for cross-site coordination
- P2P within sites

## License

MIT