npm package: @skvil/piertotum
Description: MCP + HTTP broker for multi-instance Claude Code communication
Author: LCGF00
Latest version: 1.0.6

<div align="center">
  <img src="https://raw.githubusercontent.com/Skvil-IA/skvil-piertotum/main/logo.png" width="150" alt="Skvil-Piertotum logo" />

# Skvil-Piertotum

[![npm version](https://img.shields.io/npm/v/@skvil/piertotum)](https://www.npmjs.com/package/@skvil/piertotum)
[![Node.js](https://img.shields.io/node/v/@skvil/piertotum)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**Let your Claude Code instances talk to each other.**

Skvil-Piertotum is a lightweight MCP + HTTP broker that connects multiple Claude Code terminals — across projects, machines, WSL, or VMs — so they can exchange messages and share context.

```
Claude Code (API project)          Claude Code (Frontend project)
      │                                       │
      │  sp_send / sp_broadcast               │  sp_read
      └──────────────┬────────────────────────┘
                     │ HTTP
              ┌──────┴──────┐
              │   broker    │
              │  :4800      │
              │             │
              │  messages   │
              │  contexts   │
              │  agents     │
              └─────────────┘
```

</div>

---

## How it works

Two components, zero infrastructure:

**`broker.js`** — a tiny Express HTTP server that holds all state in memory (agents, message queues, shared key/value context). Run it once on any machine in your network.

**`mcp-server.js`** — an MCP stdio server that runs inside each Claude Code instance. It auto-registers on startup, heartbeats every 30s, and exposes 10 tools so Claude can send/receive messages and share data with other instances.

---

## Quick Start

### 1. Install

**Requirements:** Node.js 18 or later (`node --version` to check).

**Option A — via npm (recommended):**
```bash
npm install -g @skvil/piertotum
```

**Option B — from source:**
```bash
git clone https://github.com/Skvil-IA/skvil-piertotum
cd skvil-piertotum
npm install
```

### 2. Start the broker

Run this once, on any machine accessible to your terminals:

```bash
# if installed globally:
skvil-piertotum-broker

# without installing (npx):
npx --package=@skvil/piertotum skvil-piertotum-broker

# custom port:
skvil-piertotum-broker 5000

# from source:
node broker.js
```

The broker listens on `0.0.0.0` — reachable from any IP on your network.

> **Tip:** Run the broker on your main machine or a server that stays on. Use `hostname -I` (Linux/WSL) or `ipconfig` (Windows) to find its IP.

### 3. Add the MCP server to each Claude Code terminal

Each terminal gets a unique `AGENT_ID`:

```bash
# Terminal 1 — API project
claude mcp add skvil-piertotum \
  -e BROKER_URL=http://YOUR-IP:4800 \
  -e AGENT_ID=api \
  -e AGENT_NAME="API Project" \
  -e PROJECT_NAME="my-saas" \
  -- skvil-piertotum-mcp

# Terminal 2 — Frontend project
claude mcp add skvil-piertotum \
  -e BROKER_URL=http://YOUR-IP:4800 \
  -e AGENT_ID=front \
  -e AGENT_NAME="Frontend Project" \
  -e PROJECT_NAME="my-saas" \
  -- skvil-piertotum-mcp
```

> Not installed globally? Replace `skvil-piertotum-mcp` with:
> `npx --package=@skvil/piertotum skvil-piertotum-mcp`

If everything is on the same machine, use `BROKER_URL=http://localhost:4800`.

### 4. Or configure via `~/.claude.json`

```json
{
  "mcpServers": {
    "skvil-piertotum": {
      "type": "stdio",
      "command": "skvil-piertotum-mcp",
      "env": {
        "BROKER_URL": "http://192.168.1.10:4800",
        "AGENT_ID": "api",
        "AGENT_NAME": "API Project",
        "PROJECT_NAME": "my-saas"
      }
    }
  }
}
```

> Each terminal must have a **different** `AGENT_ID`.

---

## Usage examples

Once configured, just talk to Claude naturally:

### See who's connected

```
Register in the broker and show me who else is online
```

### Send context from one project to another

**In the API terminal:**
```
I just finished the auth endpoints. Send the full request/response
structure to the 'front' terminal as type 'endpoint'.
```

**In the Frontend terminal:**
```
Read incoming messages and use the endpoint spec to build the Axios services.
```

### Share a schema or config

**In the API terminal:**
```
Save the full Prisma schema we just defined to shared context under the key 'db-schema'.
```

**In any other terminal:**
```
Read the shared context 'db-schema' and use it as the source of truth for TypeScript types.
```

### Broadcast an announcement

```
Broadcast to all agents that the base API URL changed from /api/v1 to /api/v2.
```

### Check system status

```
Show broker status with all connected agents and their unread message counts.
```

---

## Available MCP Tools

| Tool | Description |
|---|---|
| `sp_register` | Re-register this terminal (runs automatically on startup) |
| `sp_list_agents` | List all connected agents with staleness indicators |
| `sp_send` | Send a message to a specific agent |
| `sp_broadcast` | Send a message to all connected agents |
| `sp_read` | Read received messages (with pagination and explicit ACK) |
| `sp_clear` | Delete all messages in this agent's queue |
| `sp_set_context` | Save shared data by key (schema, config, endpoints, etc.) |
| `sp_get_context` | Read shared data by key |
| `sp_list_contexts` | List all available context keys |
| `sp_status` | Broker status: uptime, agents, unread counts, context count |

---

## Environment Variables

### MCP server (`mcp-server.js`)

| Variable | Default | Description |
|---|---|---|
| `BROKER_URL` | `http://localhost:4800` | URL of the broker |
| `AGENT_ID` | machine hostname | Unique identifier for this instance — **must differ per terminal** |
| `AGENT_NAME` | `SP-{id}` | Human-readable display name |
| `PROJECT_NAME` | `unknown` | Used for grouping agents by project |

### Broker (`broker.js`)

| Variable | Default | Description |
|---|---|---|
| `BROKER_PORT` | `4800` | Port to listen on (also accepts first CLI argument) |

---

## Broker REST API

The broker exposes a plain HTTP API — useful for debugging or integration:

```bash
# Status overview
curl http://localhost:4800/status

# List agents
curl http://localhost:4800/agents

# Read messages for an agent (unread only, limit 10)
curl "http://localhost:4800/messages/api?unread=true&limit=10"

# ACK messages by ID
curl -X POST http://localhost:4800/messages/api/ack \
  -H "Content-Type: application/json" \
  -d '{"ids": ["msg_123", "msg_456"]}'

# Send a message
curl -X POST http://localhost:4800/messages/send \
  -H "Content-Type: application/json" \
  -d '{"from":"api","to":"front","content":"hello","type":"text"}'

# Shared context
curl http://localhost:4800/context
curl http://localhost:4800/context/db-schema
```

Full endpoint reference:

```
POST   /agents/register             Register an agent
GET    /agents                      List agents
POST   /agents/:agentId/heartbeat    Heartbeat (404 if not registered)
DELETE /agents/:agentId              Deregister agent

POST   /messages/send               Send to one agent
POST   /messages/broadcast          Send to all agents except sender
GET    /messages/:agentId            Read messages (?unread=true, ?limit=N)
POST   /messages/:agentId/ack       Mark message IDs as read
DELETE /messages/:agentId            Clear all messages

POST   /context                     Save context entry
GET    /context                     List context keys
GET    /context/:key                Read context value
DELETE /context/:key                Delete context entry

GET    /status                      Broker overview
```

---

## Design Notes

- **In-memory only** — all state is lost if the broker restarts. Agents re-register automatically on the next heartbeat (within 30s). For persistence, adapt the broker to use SQLite.
- **Resource limits** — max 100 agents, 200 messages per queue (oldest dropped), 1000 context keys, 100 KB per context value, 512 KB per message.
- **Stale agent cleanup** — agents that miss 3 heartbeats (90s) are automatically removed.
- **Message types** — `text`, `code`, `schema`, `endpoint`, `config`. Used by agents to route and handle responses appropriately.
- **ES modules** — both files use `import/export` (`"type": "module"` in `package.json`).

---

## Use Cases

**Monorepo with multiple services**
Each service runs in its own terminal. When the API changes a contract, it notifies the frontend automatically.

**Distributed setup (PC + WSL + VM)**
Run the broker on the host machine. WSL and VM terminals connect via the host IP.

**Multi-agent orchestration**
An orchestrator terminal delegates tasks to worker terminals. Workers report status via shared context. The orchestrator checks `sp_get_context("{worker}-status")` before assigning new work.

**Team knowledge sharing**
Each developer registers their terminal. Share schemas, decisions, and context across the team in real time — without copy-pasting into chat.

---

## Contributing

Issues and pull requests are welcome. For non-trivial changes, please open an issue first to discuss the approach.

## License

MIT — see [LICENSE](./LICENSE).

## References

The tool design, security hardening, and MCP best practices in this project were based on:

- [Writing tools for agents — Anthropic Engineering](https://www.anthropic.com/engineering/writing-tools-for-agents)
- [MCP Security Best Practices — Model Context Protocol](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices)