# claude-mcp

MCP server that turns Claude Code into a structured software-engineering worker
that an orchestrator (e.g. Hermes) can drive over HTTP: submit a coding task, poll for
a normalized result, then resume or review it — instead of shelling out to
`claude -p`.

**Milestones 1–7 are complete.** For architecture, the full tool/result
contract, configuration, and deployment, see
**[docs/system-details.md](docs/system-details.md)**.

## Requirements

- Python 3.12–3.14
- The `claude` CLI installed and authenticated (`claude_health` reports whether
  it is visible and logged in)

## Quick setup

```bash
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
./setup.sh
```

`./setup.sh` is interactive: it asks for the values that must be set (only
`workspace.projects_root` is required — the rest have defaults), writes your
per-machine `config/worker.yaml`, generates a systemd unit, and can install and
start the service. To do it by hand instead:

```bash
cp config/worker.yaml.example config/worker.yaml   # then set workspace.projects_root
python -m claude_mcp                                # serves http://127.0.0.1:8765/mcp
```

`config/worker.yaml` is per-machine and gitignored; `projects_root` (where the
worker may operate) is the one value with no default. Full configuration and the
systemd service are covered in the [system details](docs/system-details.md).

## Connect an orchestrator

Register the server as a **streamable-HTTP** MCP server:

```json
{
  "mcpServers": {
    "claude-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```

Then call `claude_health` (no arguments). It returns `{"status": "ok", ...}` plus
`claude_cli.found` and `auth.logged_in` — **gate delegation on both being true.**

## Usage: the tools

| Tool | Purpose |
|------|---------|
| `claude_health()` | Server/CLI/auth readiness check. |
| `claude_run_task(project, mode, task, branch?)` | Submit a coding task; returns immediately with a queued `job_id`. |
| `claude_get_task(job_id)` | Poll a job → status and, when terminal, the normalized result. |
| `claude_cancel_task(job_id)` | Cancel a queued or running job. |
| `claude_resume_task(job_id, instruction)` | Continue a completed job in its captured session. |
| `claude_review_task(job_id, instruction?)` | Independent read-only review, with a bounded remediation loop. |

Minimal flow — submit an `implement` task:

```json
{
  "project": "<projects_root>/myapp",
  "mode": "implement",
  "task": { "objective": "Add a /health endpoint returning 200 {\"status\":\"ok\"}" }
}
```

It returns `{"status": "queued", "job_id": "claude-…"}`. Poll
`claude_get_task(job_id)` until the status is terminal (`completed`, `failed`,
`timeout`, `cancelled`, or `blocked`); a `completed` result carries `summary`,
`files_changed`, and `commit`. The complete input/output schema, error codes, and
hands-on recipes are in the [system details](docs/system-details.md) and the skill
references below.

## How it works alongside the skill

The MCP server is the **mechanism**; the companion **skill** is the **playbook**.
This repo ships an agent skill at
[`skills/claude-mcp-worker/`](skills/claude-mcp-worker/) that teaches an
orchestrator *when and how* to use these tools: the golden rule (delegate any
code change to `claude_run_task` rather than editing files directly), the
submit → poll → resume → review flow, and gating on `claude_health` before
delegating. Point your orchestrator at both — the server URL above, and the skill
(`SKILL.md` plus `references/{tool-reference,result-schema,testing-recipe}.md`).

## Test

```bash
pytest -v
```

## Learn more

- **[docs/system-details.md](docs/system-details.md)** — architecture, milestones
  & roadmap, full configuration, systemd deployment, and the complete tool/result
  contract.
- **[skills/claude-mcp-worker/](skills/claude-mcp-worker/)** — the
  orchestrator-facing skill and its references.
- **[docs/superpowers/](docs/superpowers/)** — per-milestone specs and plans.