# AgentMesh MCP (Lite Edition)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Protocol: MCP](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)
[![Python: >=3.10](https://img.shields.io/badge/Python->=3.10-yellow.svg)](https://python.org/)

**AgentMesh MCP** is a resilient Model Context Protocol (MCP) server designed to coordinate multi-agent AI swarms (Claude, Cursor, CrewAI, LangGraph, custom subagents) without cloud deadlocks, race conditions, or duplicated work.

Powered by a high-throughput, zero-dependency SQLite WAL engine, AgentMesh provides mutual-exclusion task claiming and atomic state transitions so multiple autonomous agents can collaborate seamlessly in parallel.

---

## 🎯 The Problem

When running multiple AI agents in parallel:
1. **Collision & Race Conditions:** Multiple agents attempt to tackle the same problem or modify the same files simultaneously, destroying each other's work.
2. **Zombie Locks:** If an agent times out or crashes during an API call, tasks get stuck indefinitely.
3. **Cloud Overhead:** Setting up Redis, RabbitMQ, or Celery just to let 3 local AI agents work together is overkill and introduces privacy leakage.

**AgentMesh** solves this locally and deterministically with a lightweight, standardized MCP server.

---

## ✨ Features (Lite Edition)

- 🔒 **Atomic Mutual Exclusion:** Guaranteed single-claim mechanics using SQLite WAL `BEGIN IMMEDIATE` transactions.
- ⚡ **Zero External Dependencies:** Built with pure Python 3 standard library (`sqlite3`, `json`, `uuid`).
- 🛠️ **Full MCP Compliance:** Implements MCP standard (`tools/list`, `tools/call`, `initialize`, `ping`) over `stdio`.
- 📊 **Real-time Observability:** CLI and MCP tools to inspect swarm board status, active worker counts, and queue depth.

---

## 🚀 Quickstart

### 1. Installation

```bash
git clone https://github.com/johannschiffer/agentmesh-mcp.git
cd agentmesh-mcp
pip install -e .
```

### 2. Configure in Claude Desktop or Cursor

Add to your `claude_desktop_config.json` or Cursor MCP settings:

```json
{
  "mcpServers": {
    "agentmesh": {
      "command": "python",
      "args": ["-m", "agentmesh.cli", "run"]
    }
  }
}
```

### 3. CLI Inspection

Check the current state of your swarm at any time:

```bash
# View board metrics
agentmesh status

# List pending or active tasks
agentmesh list --status pending
```

---

## 🛠️ MCP Tools Reference

| Tool | Parameters | Description |
|---|---|---|
| `create_task` | `title`, `description`, `priority`, `metadata` | Adds a task to the queue in `pending` state |
| `claim_task` | `agent_id` | Atomically claims the highest priority pending task |
| `complete_task` | `task_id`, `agent_id`, `result` | Marks task as completed with output payload |
| `fail_task` | `task_id`, `agent_id`, `error` | Marks task as failed with error details |
| `get_task` | `task_id` | Retrieves complete task state and payload |
| `list_tasks` | `status`, `agent_id`, `limit` | Queries tasks with status and worker filters |
| `get_board_status` | none | Returns high-level metrics of the entire swarm |

---

## 🚀 Upgrade to AgentMesh Pro

Need enterprise capabilities for production autonomous swarms?

The **AgentMesh Pro Edition** adds:
- ⛓️ **DAG Dependency Engine:** Complex multi-step task graphs (`depends_on`). Subtasks stay locked until parents pass. Cycle-detection prevents infinite deadlock loops.
- 💓 **Heartbeat & Zombie Lease Reclaimer:** Automatic detection of crashed or frozen agents. Automatically revokes expired leases back to the pool.
- 🧠 **ACID Shared Memory Blackboard:** Namespaced key-value store with TTL for inter-agent context and artifact sharing.
- 📈 **Swarm Cost & Token Ledger:** Telemetry tracking execution time, token burn, and API costs per agent.
- 🐳 **Production Docker & Compose:** Ready-to-ship container configurations.
- 🧪 **Comprehensive Pytest Suite:** 100% test coverage ready for CI/CD.

👉 **[Get AgentMesh Pro on Gumroad ($14.99 USD)](https://johanld.gumroad.com/l/hbqhfh)**

---

## 📄 License

MIT © 2026 [Johann Schiffer](https://github.com/johannschiffer)