- clawdforge_session_new / _turn / _close / _list / _get
- Wraps the v0.2 session HTTP surface (POST /sessions, POST
/sessions/{id}/turn, GET/DELETE /sessions/{id}, GET /sessions)
- Tool descriptions tuned for LLM consumption: when to prefer session_new
vs run, idempotency contract on close, file_token attachment via files[]
- session_turn returns two content blocks: prose text (concat'd text events)
for direct LLM consumption + structured trace JSON (turn_index,
stop_reason, duration_ms, events) for tool-calling agents
- 404/410/auth errors from upstream surface as MCP errors with actionable
messages; no Python tracebacks leak through
- tests/test_sessions.py: 22 new tests covering the 5 tools + 404 + schema
validation + idempotent close
- tests/test_server.py: new v0.1 schema-pin regression test
- README "Sessions (v0.2)" section with example open/turn/turn/close chain
- Bump version 0.1.0 -> 0.2.0
v0.1 tools (clawdforge_healthz / _run / _upload_file) are byte-identical.
Spec: memory/spec-clawdforge-v0.2.md
Server core: 940861f
Drops a Model Context Protocol server into clients/mcp/ that wraps the
clawdforge HTTP surface so MCP-aware clients (Claude Desktop, Claude Code,
Cursor, Zed, custom agents) can call it as a native tool — claude talking
to claude through the LAN bridge.
Three tools exposed:
- clawdforge_healthz -> GET /healthz
- clawdforge_run -> POST /run
- clawdforge_upload_file -> POST /files
Admin endpoints intentionally NOT exposed; token minting stays human-gated.
Implementation notes:
- Built on the official `mcp` Python SDK (>=1.0). asyncio-native server,
stdio transport, low-level Server class with @list_tools / @call_tool
handlers.
- Self-contained `requests` HTTP wrapper rather than depending on the
sibling clients/python SDK — keeps clawdforge-mcp installable
standalone. Same error taxonomy (ForgeError / ForgeAPIError /
ForgeAuthError / ForgeTransportError).
- Sync HTTP calls offloaded via asyncio.to_thread so a slow `claude -p`
can't stall the MCP event loop.
- Errors are formatted into a single 'clawdforge error: ...' text block
with isError=True; tracebacks never leak through the JSON-RPC pipe.
- Logging goes to stderr (CLAWDFORGE_MCP_LOG=DEBUG to enable). stdout
is reserved for JSON-RPC framing.
- Config via env: CLAWDFORGE_URL (default http://localhost:8800) and
CLAWDFORGE_TOKEN (required). MCP clients pass these via their `env`
config block.
Tests: 12 unit tests covering tool discovery, healthz, run-success,
run-with-files, run-empty-prompt, run-subprocess-502, run-auth-401,
upload happy path, upload missing file, unknown tool, server factory.
HTTP layer mocked via `responses`. Plus a manual end-to-end stdio
smoke (initialize + tools/list round-trip) verified during build.
Includes ready-to-paste Claude Desktop and Claude Code config examples,
and a README documenting install, env, all three tools, and operational
notes (stdout-is-sacred, error wrapping, no streaming).
