mermate-openclaw-mcp

name	mermate-openclaw-mcp
description	Use when the user wants to build, extend, or debug the Python MCP bridge that exposes Mermate actions and stage flows to OpenClaw or other MCP clients.

Mermate OpenClaw MCP

Treat the Express API as the source of truth. The MCP layer should stay thin and map directly onto real routes.

Authoring Discipline

Everything in this MCP service is written under ponytail (full intensity): the laziest solution that actually works. Concretely:

• One tool per real route. No synthetic workflows, no speculative tools "for later" — later can scaffold for itself.
• Stdlib and existing code first: extend mcp_service/client.py transport or server.py tools; never add a new dependency for what the shared client already does.
• Deletion over addition: if a route dies, its tool dies in the same diff.
• Shortest correct diff wins; deliberate simplifications get a ponytail: comment naming the ceiling.

Parent application model: .windsurf/skills/mermate/SKILL.md (master) with mermate-agentic-infra owning the bridge's invariants (fire-and-forget telemetry, replayable SSE, tool↔route parity). This file governs how the bridge is written; those govern what it must preserve.

Files to inspect first:

• mcp_service/server.py
• mcp_service/client.py
• .mcp.json
• server/routes/render.js
• server/routes/tla.js
• server/routes/ts.js
• server/routes/agent.js
• server/routes/search.js
• server/routes/transcribe.js

Build rules:

• Keep stage parity with the live pipeline: render -> TLA+ -> TypeScript, plus agent/run and agent/finalize.
• When a new Mermate route is added, add or update a matching MCP tool instead of inventing a synthetic workflow first.
• Keep HTTP transport logic in mcp_service/client.py; keep tool definitions in mcp_service/server.py.
• For SSE routes, preserve stage transitions and terminal events. Do not drop preview_ready, final_render, done, or error.
• Normalize markdown to md at the bridge boundary so clients can use human-friendly input while Mermate keeps its native mode values.
• Use resources for stable reference material like the stage map or tool-to-route map.

Expected stage mapping:

• /api/render -> mermate_render
• /api/render/tla -> mermate_render_tla
• /api/render/ts -> mermate_render_ts
• /api/agent/run -> mermate_agent_run
• /api/agent/finalize -> mermate_agent_finalize
• /api/projects/:id/pipeline -> mermate_get_project_pipeline

OpenClaw integration rules:

• Keep the repo-level .mcp.json pointing at the repo-local .venv-mcp/bin/python -m mcp_service command on this machine.
• Use MERMATE_URL for the sidecar base URL; default to http://127.0.0.1:3333.
• If the repo moves, update the absolute command and cwd values in .mcp.json.
• Prefer additive tool coverage over changing existing tool names, because wrapper prompts may already depend on them.

Verification:

• python3 -m unittest test/test_mermate_mcp_service.py
• python3 -m compileall mcp_service
• PYTHONPATH=/tmp/mermate_mcp_inspect:. python3 -c "from mcp_service.server import mcp; print(mcp.name)"