Centralized architecture: single MCP server, HTTPS webhooks, register_agent tool

README.md

 # ClawPhone
 
-A job queue MCP server for OpenClaw agents. Enables agents to post jobs for other agents with webhook notifications, authentication, and automatic retry logic.
+A **centralized** job queue MCP server for OpenClaw agents. Enables multiple isolated OpenClaw instances to communicate and delegate jobs to each other.
+
+## Architecture
+
+```
+┌─────────────┐     ┌─────────────────┐     ┌─────────────┐
+│ OpenClaw    │     │  MCP Server    │     │ OpenClaw    │
+│ Lisa   ─────┼────►│  (Central)     │◄────┼─   Nimpho   │
+│             │ MCP │                 │◄────┤             │
+└─────────────┘     └────────┬────────┘     └─────────────┘
+                             │
+                    Webhook (HTTPS)
+```
+
+- **One central MCP server** (can run on any server - one of the instances or a dedicated box)
+- **All OpenClaw instances** connect to this MCP server via MCP
+- **Jobs** are posted from any instance to any other instance via MCP
+- **Notifications** sent via HTTPS webhooks with `verify=False`
 
 ## Features
 
-- **Job Queue**: Post, claim, and track jobs between agents
-- **Per-Agent Webhooks**: Each agent has its own webhook URL for notifications
-- **Bearer Token Authentication**: Secure communication between MCP server and agents
-- **Auto-Retry**: Jobs that aren't claimed get retried at increasing intervals (1min → 2min → 5min → 10min)
-- **HTTPS**: Self-signed certificate support
-- **SQLite**: Simple persistent storage
+- **Central Job Queue**: Single MCP server handles jobs from all instances
+- **Agent Registry**: Each OpenClaw instance registers with its webhook URL
+- **HTTPS Webhooks**: Server notifies agents via HTTPS (verify=false)
+- **Bearer Token Auth**: Secure communication
+- **Auto-Retry**: Unclaimed jobs retry at intervals (1→2→5→10 min)
+- **SQLite Storage**: Simple persistent queue
 
 ## Installation
 
 ```bash
-# Clone or copy to target directory
-cp -r clawphone /home/share/clawphone
+# Clone
+git clone https://git.nexlab.net/lisa/clawphone.git /opt/clawphone
 
-# Install dependencies (if needed)
+# Install deps
 pip install fastapi uvicorn aiosqlite httpx cryptography
 
-# Copy init script
-sudo cp etc/init.d/clawphone /etc/init.d/
-sudo chmod +x /etc/init.d/clawphone
-sudo update-rc.d clawphone defaults
+# Configure agents
+cp agents.json.example agents.json
+# Edit agents.json with your instance URLs and tokens
 ```
 
 ## Configuration
 
-Edit `/home/share/clawphone/agents.json`:
+Create `agents.json`:
 
 ```json
 {
-  "agent_name": {
-    "hook": "https://your-server.com/api/agent/hook",
-    "token": "agent_bearer_token"
+  "lisa": {
+    "hook": "https://lisa.nexlab.net/hooks/agent",
+    "token": "your-openclaw-hook-token"
+  },
+  "nimpho": {
+    "hook": "https://nimpho.nexlab.net/hooks/agent", 
+    "token": "your-openclaw-hook-token"
+  },
+  "postino": {
+    "hook": "https://postino.nexlab.net/hooks/agent",
+    "token": "your-openclaw-hook-token"
   }
 }
 ```
 
-Optionally set a global API token in `/home/share/clawphone/.env`:
-
+Optionally set a global API token in `.env`:
 ```
 CLAWPHONE_TOKEN=your_global_token
 ```
 
-## Usage
-
-### Start Server
+## Running
 
 ```bash
 # Manual
-sudo /etc/init.d/clawphone start
+python3 /opt/clawphone/mcp_server.py
 
-# Or directly
-python3 /home/share/clawphone/mcp_server.py
+# Or with the init script
+sudo /etc/init.d/clawphone start
 ```
 
-### MCP Tools
+## MCP Tools
 
 | Tool | Description |
 |------|-------------|
-| `post_job` | Post a new job for an agent |
+| `register_agent` | Register an agent (name, hook URL, token) |
+| `post_job` | Post a job for a specific agent |
 | `claim_job` | Claim a pending job |
 | `update_job_status` | Update job to "working" or "done" |
 | `list_jobs` | List jobs (filter by agent/status) |
 | `get_job` | Get job details |
-| `list_agents` | List configured agents |
+| `list_agents` | List registered agents |
 
-### API Examples
+## API Examples
 
 ```bash
-# List jobs
-curl -k -H "Authorization: Bearer TOKEN" \
-  https://localhost:8765/tools/list_jobs
+# Register an agent
+curl -k -X POST https://localhost:8765/tools/register_agent \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"lisa","hook":"https://lisa.nexlab.net/hooks/agent","token":"hook-token"}'
 
-# Post a job
-curl -k -X POST -H "Authorization: Bearer TOKEN" \
+# Post a job (Lisa asking Nimpho to do something)
+curl -k -X POST https://localhost:8765/tools/post_job \
+  -H "Authorization: Bearer TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"sender":"agent-a","target_agent":"agent-b","title":"Do something"}' \
-  https://localhost:8765/tools/post_job
+  -d '{"sender":"lisa","target_agent":"nimpho","title":"Check server status","description":"Run uptime command on ganeti1"}'
 
-# Claim a job
-curl -k -X POST -H "Authorization: Bearer TOKEN" \
+# Claim a job (Nimpho claims the job)
+curl -k -X POST https://localhost:8765/tools/claim_job \
+  -H "Authorization: Bearer TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"job_id":"uuid-here","agent":"agent-b"}' \
-  https://localhost:8765/tools/claim_job
+  -d '{"job_id":"uuid-here","agent":"nimpho"}'
 
 # Update job status
-curl -k -X POST -H "Authorization: Bearer TOKEN" \
+curl -k -X POST https://localhost:8765/tools/update_job_status \
+  -H "Authorization: Bearer TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"job_id":"uuid-here","status":"done","agent":"agent-b"}' \
-  https://localhost:8765/tools/update_job_status
+  -d '{"job_id":"uuid-here","status":"done","agent":"nimpho","result":"Server is up"}'
 ```
 
 ## Webhook Events
 
-The MCP server sends POST requests to agent webhooks with these events:
+The MCP server sends POST requests to agent webhooks:
 
-| Event | Description |
-|-------|-------------|
+| Event | Payload |
+|-------|---------|
 | `new_job` | New job posted for agent |
 | `job_pending` | Job retry notification |
 | `job_claimed` | Job was claimed |
 | `job_status_changed` | Job status updated |
-| `job_failed` | Job expired (not claimed) |
+| `job_done` | Job completed with result |
+| `job_failed` | Job expired |
+
+All webhooks use HTTPS with `verify=False`.
 
 ## License
 
@@ -116,8 +143,6 @@ Stefy Lanza <stefy@nexlab.net>
 
 ## Donations
 
-If you find this project useful, consider donating:
-
 | Crypto | Address |
 |--------|---------|
 | Bitcoin (BTC) | `bc1q3zlkpu95amtcltsk85y0eacyzzk29v68tgc5hx` |
@@ -126,6 +151,4 @@ If you find this project useful, consider donating:
 
 ---
 
-<p align="center">
-  Made with 🧠 and 🔧 by Stefy
-</p>
+<p align="center">Made with 🧠 and 🔧 by Stefy</p>

agents.json

 {
-  "coderino": {
-    "hook": "https://lisa.nexlab.net/hooks/agent",
-    "token": "clawphone_hook_token_2024"
-  },
-  "marketta": {
-    "hook": "https://lisa.nexlab.net/hooks/agent", 
-    "token": "clawphone_hook_token_2024"
-  },
-  "postino": {
-    "hook": "https://lisa.nexlab.net/hooks/agent",
-    "token": "clawphone_hook_token_2024"
+  "example": {
+    "hook": "https://your-instance.nexlab.net/hooks/agent",
+    "token": "your-openclaw-hook-token"
   }
 }