# Esco (AgentTalk MCP Server & LAN P2P Bridge)

Esco is a robust, lightweight, and high-performance **Model Context Protocol (MCP)** integration for the **AgentTalk** communication bus. It enables multiple AI coding agents (such as Claude, Codex, Clew, OpenCode, OpenClaw, and Hermes-Agent) to communicate and coordinate asynchronously.

By extending AgentTalk's file-based message bus, Esco introduces **Peer-to-Peer (P2P) LAN discovery and messaging**, allowing agents running on separate machines in the same local network to automatically find and talk to each other without central servers.

---

## 🚀 Key Features

*   **P2P LAN Discovery**: Automatic peer discovery on local networks using **UDP Broadcast** on port `9999`. 
*   **Direct HTTP Messaging**: Messages are routed directly to target peers using dedicated **HTTP POST** servers bound on ports `18000-18100`.
*   **Identity Registration System**: Agents can claim their roster name and role via `register_identity()` once, mapping process isolation to logical names.
*   **Blocking Wait Loop**: The `wait_for_message()` tool allows agents to enter a low-overhead, perpetual listening state to wait for incoming commands.
*   **Decentralized & Serverless**: Works fully offline and locally without cloud subscriptions.

---

## 📁 Repository Structure

```
Esco/
├── src/agenttalk/             # Core AgentTalk library (message store, CLI, wrapper)
│   └── store.py               # File-backed message bus implementation
├── agenttalk_mcp/             # Our MCP server implementation
│   ├── server.py              # FastMCP server entry point (stdio or sse transport)
│   ├── lan_p2p.py             # UDP broadcast discovery & HTTP P2P messaging engine
│   ├── example_workflow.py    # Working 2-agent task handoff example
│   └── client_simulator.py    # Console-based inter-agent simulation runner
├── AGENT_MCP_GUIDE.md         # Setup manual for Claude, Codex, Clew, etc.
├── .gitignore                 # Excludes __pycache__, runtime .agenttalk/ store, graphify-out/
└── README.md                  # This file
```

---

## 🛠️ Getting Started

### 1. Requirements
Ensure you have Python 3.10+ and the official `mcp` library installed:
```bash
pip install mcp
```

### 2. Local Simulation
You can test the MCP server functionality and P2P communication loops locally:
```bash
python agenttalk_mcp/client_simulator.py
```

Or run a real end-to-end multi-agent task handoff (a lead agent assigns work, a worker performs it and reports back, the lead verifies the result):
```bash
python agenttalk_mcp/example_workflow.py
```

The server supports two transports (see [AGENT_MCP_GUIDE.md](AGENT_MCP_GUIDE.md) for full details):
- **stdio** (default) — each agent spawns its own server subprocess.
- **sse** — one shared server (`AGENTTALK_TRANSPORT=sse`) that multiple agents/machines connect to over HTTP.

### 3. Registering the MCP Server in Agent Clients
To register the server for use, configure the command `python D:/Projects/Github/Esco/agenttalk_mcp/server.py` in your agent configuration.

For **Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "agenttalk-mcp": {
      "command": "python",
      "args": [
        "D:/Projects/Github/Esco/agenttalk_mcp/server.py"
      ]
    }
  }
}
```

For **Codex** (`~/.codex/config.toml`):
```toml
[mcp_servers.agenttalk]
command = "python"
args = ["D:/Projects/Github/Esco/agenttalk_mcp/server.py"]
```

See [AGENT_MCP_GUIDE.md](file:///D:/Projects/Github/Esco/AGENT_MCP_GUIDE.md) for full configuration details.

---

## 🤝 How Agents Communicate Freely

When configured with this MCP server, agents should adhere to the following workflow:
1.  **Register Identity**: At startup, call `register_identity(name="agent_name")`.
2.  **Send Message**: To communicate, invoke `send_message(recipient="target_agent", body="message content")`.
3.  **Enter Listen Loop**: To wait for incoming responses, block on `wait_for_message()`. The tool's system instruction enforces that the agent must call this tool at the end of its turn to remain online.