clark-mcp

clark-mcp

Local, offline natural-language interface to Clark (the warehouseworkforce RL agent). Plain English in → real staffing decisions out.No cloud, no API cost, no data egress.

Ask "what's the opening plan for the east dock Tuesday, and whathappens if two pickers call off?" — a local LLM turns that into realClark tool calls and explains the result honestly. Nothing leaves themachine.

What it is

you ──text──▶ hermes3:8b (Ollama, local)
                   │  tool calls (MCP, stdio)
                   ▼
              clark-mcp server  ──HTTP──▶  clark serve  (localhost inference API)
                                                 │
                                                 ▼  real Clark RL inference

Three thin layers, each independently testable, no shared process:

• clark serve (in the clarkrepo) — a minimal localhost inference API: 5 stateless read routes,weights loaded once. Not part of this repo; this repo consumes it.
• clark_mcp/server.py — a real MCP server (any MCP host can useit) exposing 5 tools: clark_list_facilities, clark_facility_info,clark_get_plan, clark_what_if, clark_explain_decision.
• clark_mcp/agent.py — a fully-local client: a Hermes-3-8B modelin Ollama drives those tools and explains the result. Zero externalcalls.

Nothing here re-implements inference — every tool delegates to Clark'slocalhost API over HTTP. clark_explain_decision returns Clark's planplus the facility's rules as grounding; the explanation is themodel's, not Clark policy introspection (Clark is an RL policy — itemits actions, not reasons).

See docs/ARCHITECTURE.md for the full design,tool contracts, the honesty model, and the fine-tune pipeline.

The honesty model (why this is built the way it is)

This system is designed to be a truthful staffing tool, not aconfident one. Three rules are enforced structurally, not by promptalone:

1. Never invent a plan. Plans/what-ifs always come from a live toolcall; a tool error or unknown facility is reported plainly, neverpapered over with a plausible-looking fabrication.
2. Explain, don't introspect. Clark is an RL policy. The systemdescribes what it assigned and interprets it against the facility'srules — it never claims to know why the network chose it.
3. Opening assignment ≠ outcome. A plan is the start-of-dayassignment, not a simulated end-of-day grade. What-ifs compareopening assignments across scenarios, not projected results.

A trained Clark genuinely fails some days (a roster can be too thin forits volume). The tool is meant to surface those failures honestly —not to be tuned until it always "wins."

Run (all local)

# 1. Clark inference API (from the clark repo, on a stable checkpoint)
clark serve --model <checkpoint.pt> --facilities-dir clark/data/configs --port 8000

# 2. Ollama with the model pulled
ollama pull hermes3:8b

# 3. this:
pip install -e .
python -m clark_mcp.agent          # interactive
# or run the MCP server for any MCP host:
clark-mcp

Tests

pip install -e ".[dev]"
pytest                              # tool layer, against a fake clark client

The pure tool layer (tools.py) is unit-tested with an injected fakeclient. The agent.py LLM loop and MCP stdio transport aresmoke-tested, not regression-covered — exercised once manually(hermes3:8b → MCP → clark-mcp → Clark), not in CI.

Status

Honest scope of the result: the pipeline works end to end; planquality is only as good as the Clark checkpoint behind it, and answerfluency is base-Hermes until the Phase 3 fine-tune lands.

Project memory

Architectural decisions and constraints are recorded under.context/ (context-keeper): why the runtime isHTTP-decoupled from Clark, why every fine-tune payload must belive-captured, why the dataset is quality-gated against the gold set.Read these before changing the contract.