robot-md-mcp npm · Apache-2.0

The MCP server for ROBOT.md.

Exposes every ROBOT.md command to any MCP-aware agent — Claude Code, Claude Desktop, Gemini CLI, Codex CLI, Cursor, Zed, Continue.dev. One npx command. Zero config files.

§ 01 — Install

One command per surface.

Claude Code (fastest)

$ claude mcp add robot-md -- npx -y robot-md-mcp ./ROBOT.md

Standalone (any harness)

$ npx robot-md-mcp /absolute/path/to/ROBOT.md

Requires Node 18.20+. Uses stdio transport — no network ports, no auth config. The server re-reads the file on every call (no cache, no watcher).

§ 02 — MCP surface

4 resources + 2 tools.

Resources the agent reads at will. Tools the agent invokes on request.

Resource
frontmatter
robot-md://<name>/frontmatter
Full YAML frontmatter parsed to JSON. Contains identity, physics, drivers, safety, capabilities, compliance.
Content-type: application/json
Resource
capabilities
robot-md://<name>/capabilities
Array of capability strings from capabilities[] in frontmatter.
Content-type: application/json
Resource
safety
robot-md://<name>/safety
Safety block: estop config, hitl_gates, max velocities, payload limits.
Content-type: application/json
Resource
body
robot-md://<name>/body
Markdown prose body: Identity, What X Can Do, Safety Gates, Task Routing sections.
Content-type: text/markdown
Tool
validate
(invocable)
Validate the loaded ROBOT.md against JSON Schema + RCAN conformance rules.
Returns: { ok: bool, summary: string, errors: string[] }
Tool
render
(invocable)
Emit canonical YAML of the frontmatter — normalized key order, no comments.
Returns: string (YAML)
§ 03 — Quickstart

First tool call in 30 seconds.

# 1. Wire the MCP server:
$ claude mcp add robot-md -- npx -y robot-md-mcp ./ROBOT.md

# 2. Open Claude Code from your project root:
$ claude

# 3. Confirm the server is connected:
> /mcp
● robot-md  connected
    resources: frontmatter, capabilities, safety, body
    tools:     validate, render

# 4. Ask your robot what it can do:
> what can this robot do?
[reads robot-md://my-robot/capabilities]
This robot exposes 5 capabilities: arm.pick, arm.place,
arm.reach, vision.describe, status.report...
§ 04 — Any harness

Same command, every surface.

The underlying npx -y robot-md-mcp /path/to/ROBOT.md command is the same for every harness. Registration syntax varies.

Harness
How to add
Claude Code CLI
claude mcp add robot-md -- npx -y robot-md-mcp ./ROBOT.md
Claude Desktop
JSON snippet in claude_desktop_config.json — see Claude Code page
Gemini CLI
gemini mcp add robot-md npx -y robot-md-mcp ./ROBOT.md
OpenAI Codex CLI
--mcp-server flag + --dangerously-bypass
Cursor / Zed / Cline
MCP settings: command=npx, args=["-y","robot-md-mcp","./ROBOT.md"]
Claude Code install → ROBOT.md spec → npm: robot-md-mcp → GitHub →