agent-hub-mcp 0.2.0__tar.gz

agent_hub_mcp-0.2.0/.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Database (runtime-generated)
+*.db
+*.db-wal
+*.db-shm
+
+# Secrets (NEVER commit these)
+agents.env
+.mcp.json
+config.yaml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution
+dist/
+build/
+*.egg-info/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage

agent_hub_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ma Zheng (mazhengeod)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_hub_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,234 @@
+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.

agent_hub_mcp-0.2.0/README.md

@@ -0,0 +1,207 @@
+# 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.

agent_hub_mcp-0.2.0/docs/architecture.md

@@ -0,0 +1,72 @@
+# Architecture
+
+## Data Model
+
+```
+┌─────────┐     ┌──────────┐     ┌─────────────┐
+│  Agent   │────►│   Task   │────►│    Round    │
+│ (auth)   │     │ (root)   │     │ (dispatch)  │
+└─────────┘     └──────────┘     └──────┬──────┘
+                                         │
+                                  ┌──────┴──────┐
+                                  │ Assignment  │
+                                  │ (per agent) │
+                                  └──────┬─────┘
+                                         │
+                                  ┌──────┴──────┐
+                                  │   Handoff   │
+                                  │ (completion)│
+                                  └─────────────┘
+```
+
+## State Machines
+
+### Task States
+```
+draft → awaiting_operator_approval → dispatched → completed
+                                                  ↘ closed
+```
+
+### Round States
+```
+awaiting_operator_approval → dispatched → in_progress → awaiting_review → completed
+                 ↖──────────────────────────────────────────────────────────┘
+                                              (changes_requested → new round)
+```
+
+### Assignment States
+```
+pending → claimed → in_progress → completed
+                                      ↘ cancelled
+```
+
+## Authentication Flow
+
+1. Admin creates `~/.config/agent-hub/agents.env` with `AGENT_ID=TOKEN` pairs
+2. Agent connects via MCP with `Authorization: Bearer <TOKEN>` header
+3. Server verifies token against `agents.env`, returns `agent_id`
+4. All subsequent tool calls are scoped to that agent
+
+## Message Flow
+
+- Agents send messages to specific agents (`to_agent`) or broadcast (`to_agent=null`)
+- Messages support deduplication via `dedupe_key`
+- `hop_count` tracks message forwarding depth (max 3 hops)
+- Inbox is pull-based: agents call `inbox_pull` to retrieve unread messages
+
+## Lock Mechanism
+
+- Distributed locks with TTL-based lease expiry
+- Acquire with `lock_acquire(key, resource_type, resource_id, ttl_seconds)`
+- Release with `lock_release(key)` — only the lock holder can release
+- Expired locks are automatically cleaned up on next `acquire` call
+
+## Operator Gate
+
+The operator (human) acts as a gate between Round submission and Assignment dispatch:
+
+1. Dispatcher creates a task and submits a round plan
+2. Round enters `awaiting_operator_approval` state
+3. Operator uses `hubctl approve <round-id>` or `hubctl reject <round-id>`
+4. Approved rounds become `dispatched` — agents can now claim assignments
+5. Rejected rounds stay in `awaiting_operator_approval` for re-planning

agent_hub_mcp-0.2.0/docs/deployment.md

@@ -0,0 +1,87 @@
+# Deployment Guide
+
+## Local Development
+
+```bash
+# Clone and install
+git clone https://github.com/mazhengeod/agent-hub.git
+cd agent-hub
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Configure tokens
+mkdir -p ~/.config/agent-hub
+cp examples/agents.env.example ~/.config/agent-hub/agents.env
+# Edit agents.env with your tokens
+
+# Run
+python -m agent_hub.server
+```
+
+## Production (systemd)
+
+```bash
+# Use the installer script
+./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` | Bind address (use `0.0.0.0` for LAN access) |
+| `AGENT_HUB_PORT` | `8765` | Bind port |
+| `AGENT_HUB_DB` | `~/.local/share/agent-hub/hub.db` | SQLite database path |
+
+## Connecting Multiple Agents
+
+Each agent needs its own token in `agents.env`:
+
+```env
+claude-code=token-alpha-bravo-charlie
+codex-desktop=token-delta-echo-foxtrot
+my-agent=token-golf-hotel-india
+```
+
+Each agent's MCP client configuration uses its own token:
+
+```json
+{
+  "mcpServers": {
+    "agent-hub": {
+      "type": "streamable-http",
+      "url": "http://127.0.0.1:8765/mcp",
+      "headers": { "Authorization": "Bearer token-alpha-bravo-charlie" }
+    }
+  }
+}
+```
+
+## Database Backups
+
+The SQLite database is at `~/.local/share/agent-hub/hub.db`. Back it up with:
+
+```bash
+sqlite3 ~/.local/share/agent-hub/hub.db ".backup /path/to/backup.db"
+```
+
+## Troubleshooting
+
+**Server won't start**: Check if port 8765 is already in use:
+```bash
+lsof -i :8765
+```
+
+**Agent can't connect**: Verify token in `.mcp.json` matches `agents.env`.
+
+**Database locked**: Ensure only one server instance is running. WAL mode handles concurrent reads well.

agent_hub_mcp-0.2.0/examples/agents.env.example

@@ -0,0 +1,8 @@
+# Agent token configuration
+# Format: AGENT_ID=BEARER_TOKEN
+# Generate tokens with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+#
+# Example:
+# claude-code=vd0Fe9dR8OqSKSamST4qYb3VlCxct4xI
+# codex-desktop=another-secret-token-here
+# my-agent=my-generated-token

agent_hub_mcp-0.2.0/examples/config.yaml.example

@@ -0,0 +1,26 @@
+# Agent Hub configuration
+# Place at ~/.config/agent-hub/config.yaml
+
+# Maximum rounds per task (default: 3)
+max_rounds: 3
+
+# Maximum assignments per round (default: 6)
+max_assignments_per_round: 6
+
+# Maximum messages per task round (default: 40)
+max_messages_per_task: 40
+
+# Maximum hop count for messages (default: 3)
+max_hop_count: 3
+
+# Maximum simultaneous assignments per agent (default: 4)
+max_simultaneous_assignments: 4
+
+# Assignment lease duration in minutes (default: 90)
+lease_minutes: 90
+
+# Auto-approve rounds without operator review (default: false)
+auto_approve: false
+
+# Auto-create next round on changes_requested (default: false)
+auto_create_next_round: false