cware-hil-mcp

Human-in-the-loop MCP hub for Claude Code agents, answered in Obsidian.

Agents call MCP tools to ask a human a question, request approval, or report status. This standalone hub holds the queue and exposes an MCP endpoint; the Obsidian plugin is the human's UI.

Claude Code agents ──HTTP /mcp──▶  hub (Node, :22360)  ◀──ws /bridge──  Obsidian plugin
                                   └ SQLite queue (survives restarts)

Shared domain types + the bridge protocol live in cware-hil-lib (a git dependency).

Build

npm install
npm run build

Requires Node ≥ 22 (developed on Node 26; the hub uses the built-in node:sqlite, so there is no native build step).

Run

node dist/cli.js start            # or: cc-hitl start  (once linked/installed)
node dist/cli.js status           # health check
node dist/cli.js stop
node dist/cli.js token            # print the bearer token

State lives in ~/.cc-hitl/ (hub.json holds the token; hub.db is the queue). The hub binds to 127.0.0.1 by default; override with --host <addr> or CC_HITL_HOST (e.g. 0.0.0.0 to accept connections from other machines).

This container serves no UI — only /mcp, /bridge, and /health (and a plain pointer at /). The web UI is a separate deployable, cware-hil-ui, that you point at this hub for a setup page + live dashboard. The CLI also prints the connection snippets on start (and via cc-hitl setup).

Docker

export CC_HITL_TOKEN=$(openssl rand -hex 24)
docker compose up -d --build
docker compose exec hub node dist/cli.js status

The container binds 0.0.0.0 and compose publishes it on 127.0.0.1:22360. State persists in the hub-data volume (CC_HITL_HOME=/data). Without compose:

docker build -t cware-hil-mcp .
docker run -d --name cc-hitl -p 127.0.0.1:22360:22360 \
  -e CC_HITL_TOKEN=$CC_HITL_TOKEN -v cc-hitl-data:/data cware-hil-mcp

Exposing beyond loopback: once published on a LAN/public interface, the bearer token is the only thing protecting /mcp and /bridge. Use a strong CC_HITL_TOKEN and put a TLS reverse proxy in front.

Prebuilt images

CI publishes images to GitHub Container Registry on every push to main:

docker pull ghcr.io/kiliansen/cware-hil-mcp:latest      # newest build
docker pull ghcr.io/kiliansen/cware-hil-mcp:0.1         # latest 0.1.x
docker pull ghcr.io/kiliansen/cware-hil-mcp:0.1.1       # exact version

Versioning is driven by commit messages (Conventional Commits): fix: bumps the patch, feat: the minor, and feat!: / a BREAKING CHANGE: footer the major. A commit with no conventional prefix bumps the patch. Each push tags the repo (vX.Y.Z) and pushes matching X.Y.Z, X.Y, X, and latest image tags. See .github/workflows/docker.yml.

Connect Claude Code

cc-hitl start prints the exact command (or use the cware-hil-ui setup page). In your project:

claude mcp add --transport http --scope project hitl http://127.0.0.1:22360/mcp \
  --header "Authorization: Bearer <token>"

Set a long per-server timeout (the printed snippet uses 24h) because the ask tools block until a human answers.

Tools agents get

• ask_user(prompt, title?, agent_label?) — open question, returns typed text. Blocks.
• ask_choice(prompt, choices[], multi?, …) — pick one/several (+ optional note). Blocks.
• request_approval(title, body, diff?) — approve/reject + comment. Blocks.
• notify(message, level?) — fire-and-forget notice. Non-blocking.
• update_status(label?, status?, current_task?, progress?, done?) — dashboard feed. Non-blocking.

Test

npm test        # builds, then runs the integration + resilience suites

These spawn a real hub on a temp CC_HITL_HOME and drive each tool through an MCP client + bridge WebSocket client.