Metadata-Version: 2.4
Name: agent-hub-mcp
Version: 0.2.0
Summary: Agent Hub MCP — multi-agent task coordination with MCP transport
Author-email: Ma Zheng <mazhengeod@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent-hub,mcp,multi-agent,task-coordination
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]>=1.8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: uuid7>=0.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Agent Hub MCP

> Multi-agent task coordination server built on the [Model Context Protocol](https://modelcontextprotocol.io/)

Agent Hub is a lightweight coordination layer for multi-agent workflows. It provides structured task dispatch, assignment tracking, inter-agent messaging, handoff documents, and human-in-the-loop approval — all accessible via the MCP protocol.

## ✨ Features

- 🔌 **MCP Streamable HTTP** — any MCP client connects directly
- 📋 **Task → Round → Assignment** state machine with operator approval gates
- 💬 **Inter-agent messaging** with deduplication and inbox pull
- 🤝 **Structured handoff documents** — agents pass work with context, not just messages
- 🔒 **Distributed locks** with TTL-based lease expiry
- 🛡️ **Bearer token authentication** — each agent authenticates independently
- 📦 **Zero-dependency database** — SQLite with WAL mode, no external DB needed
- ⚡ **5-minute setup** — install, configure tokens, run

## 🚀 Quick Start

### Install

```bash
# Clone and install
git clone https://github.com/mazhengeod/agent-hub.git
cd agent-hub
pip install -e .

# Or with uv (recommended)
uv pip install -e .
```

### Configure Agent Tokens

Create `~/.config/agent-hub/agents.env`:

```env
# Format: AGENT_ID=BEARER_TOKEN
claude-code=your-secret-token-here
codex-desktop=another-secret-token
```

Optionally, create `~/.config/agent-hub/config.yaml` for tuning:

```yaml
max_rounds: 3
max_assignments_per_round: 6
max_messages_per_task: 40
lease_minutes: 90
```

### Run

```bash
# Start the MCP server (defaults to 127.0.0.1:8765)
python -m agent_hub.server

# Or use the CLI
hubctl serve
```

### Connect from Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "agent-hub": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token-here"
      }
    }
  }
}
```

## 🏗️ Architecture

### State Machine

```
Task (draft)
  │
  ├─► Round 1: awaiting_operator_approval
  │     ├─► Operator approves ─► dispatched
  │     │     ├─► Assignment: pending ─► claimed ─► in_progress ─► completed
  │     │     └─► All assignments done ─► awaiting_review
  │     └─► Operator rejects ─► back to awaiting_operator_approval
  │
  └─► Review verdict: approved ─► Task completed
      Review verdict: changes_requested ─► Round 2 (re-plan)
```

### 16 MCP Tools

| Tool | Description |
|------|-------------|
| `hub_status` | Server version and transport info |
| `agent_register` | Register an agent with name and capabilities |
| `agent_heartbeat` | Ping to confirm agent is alive |
| `inbox_pull` | Pull unread messages for the calling agent |
| `message_send` | Send a message to another agent |
| `message_ack` | Mark a message as read |
| `task_draft_create` | Create a new task in draft state |
| `round_plan_submit` | Submit a round plan with assignments |
| `assignment_list` | List assignments for the calling agent |
| `assignment_claim` | Claim a pending assignment |
| `assignment_progress` | Report progress on an assignment |
| `assignment_complete` | Complete an assignment with a handoff document |
| `handoff_get` | Retrieve a handoff document |
| `review_submit` | Submit a review verdict (approved/changes_requested) |
| `lock_acquire` | Acquire a distributed lock with TTL |
| `lock_release` | Release a held lock |

### Operator CLI

`hubctl` provides manual operator controls:

```bash
hubctl approve <round-id> [note]   # Approve a round for dispatch
hubctl reject  <round-id> [note]    # Reject a round (needs re-plan)
hubctl close   <task-id>            # Close a task
hubctl status  <round-id>           # Show round status
hubctl list-tasks                   # List all tasks
hubctl list-rounds [task-id]        # List rounds
```

## 🔐 Security

- **Bearer token auth** — each agent has its own token in `agents.env`
- **Tokens are SHA-256 hashed** in the database, never stored in plaintext
- **Local-only by default** — server binds to `127.0.0.1:8765`
- **No external dependencies** — SQLite WAL mode, no Redis/Postgres needed

> ⚠️ **Never commit `agents.env` or `.mcp.json` to version control.** They contain authentication tokens.

## 🚢 Production Deployment

### systemd

A template service file is provided in `systemd/agent-hub.service.template`. Install with:

```bash
# Generate service file with your user and path
./scripts/install.sh

# Or manually:
sed -e "s|%USER%|$(whoami)|g" \
    -e "s|%WORKDIR%|$(pwd)|g" \
    -e "s|%VENV%|$(pwd)/.venv|g" \
    systemd/agent-hub.service.template > ~/.config/systemd/user/agent-hub.service

systemctl --user daemon-reload
systemctl --user enable --now agent-hub
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_HUB_HOST` | `127.0.0.1` | Server bind address |
| `AGENT_HUB_PORT` | `8765` | Server bind port |
| `AGENT_HUB_DB` | `~/.local/share/agent-hub/hub.db` | SQLite database path |

## 📂 Project Structure

```
agent-hub/
├── src/agent_hub/
│   ├── __init__.py       # Package init
│   ├── server.py          # FastMCP server with 16 tools
│   ├── service.py         # State machine logic & rules
│   ├── storage.py         # SQLite storage layer
│   ├── models.py          # Pydantic data models
│   ├── auth.py            # Bearer token verification
│   └── cli.py             # hubctl operator CLI
├── migrations/
│   └── 001_init.sql       # Database schema
├── tests/                 # Test suite
├── examples/              # Example configs
├── systemd/               # Service templates
├── docs/                  # Documentation
└── pyproject.toml         # Package config
```

## 🧪 Development

```bash
# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run with auto-reload (if using uvicorn)
python -m agent_hub.server
```

## 📄 License

[MIT](LICENSE) — use it, fork it, ship it.

## 🙏 Acknowledgments

Built with [FastMCP](https://github.com/jlowin/fastmcp) and the [Model Context Protocol](https://modelcontextprotocol.io/) specification.