carter-mcp

An MCP server that lets an AI assistant (e.g. Claude) author and push CAR-TER layouts to a paired iPhone/iPad in real time.

CAR-TER turns a phone or tablet into any control surface you can describe — tabs, grids, and controls (gauges, sliders, joysticks, maps, graphs, live logs, chat, web views…) rendered as native UI and wired to your server over a WebSocket mesh (MeshSocket). This server gives a model the tools to build those layouts conversationally and see them appear on the device as it works.

What it does

• Reads CAR-TER's live control documentation so the model builds against the real, current catalog instead of guessing — every control type, its fields, and worked examples.

• Edits incrementally — a server-held draft buffer (begin_edit, add_control, move_control, add_group, preview_buffer, push_buffer…) with validation, snapshots/revert, and grid layout.

• Pushes live to a device — pair by QR over a zero-config local relay (no account, same Wi-Fi) or a gateway, then push/preview layouts and read control values back.

• Wires to your data — probe a running service's traffic, auto-wire controls to it, infer a layout from a schema, generate service/adapter stubs, and lint a draft against real frames.

• 57 tools in total, exposed over stdio via FastMCP under the name carter.

Related MCP server: Argent

Install

Requires Python 3.11+.

pip install -e .        # or: pip install -r requirements.txt

This pulls carterkit (the layout-authoring engine — catalog, buffer, grid, validation, codegen, theming), which brings meshsocket transitively, plus the mcp SDK and qrcode.

Repo layout

server.py            stdio entry point (what MCP registrations run)
carter_mcp/          the server package
  app.py             FastMCP instance + session instructions
  state.py           mutable per-session state
  mesh.py            connection runtime: local relay, QR, routed RPC
  protocol.py        pure wire-protocol builders/formatters (device-free tests)
  content.py         resolved docs/catalog content, default spans
  sources.py         live definition/demo sources + drift detection
  tools/             the 57 MCP tools, grouped: docs, buffer, session,
                     device, wiring, generators
tests/               pytest suite (pure logic — no device or network needed)

Run it from an MCP client

The server speaks MCP over stdio. Point your client at server.py:

// e.g. Claude Desktop's claude_desktop_config.json, or a Claude Code MCP entry
{
  "mcpServers": {
    "carter": {
      "command": "python",
      "args": ["/absolute/path/to/carter-mcp/server.py"]
    }
  }
}

Then ask the assistant to build you a panel — it will read the control docs, draft a layout, show you a QR to pair your device, and push the layout live.

To run it directly for a smoke test:

python server.py          # serves MCP on stdio
python -m carter_mcp      # same thing

Where the knowledge comes from

The MCP is a thin tool layer over the current truth, not a vendored copy of it (see carter_mcp/sources.py):

• Control definitions (the catalog + doc prose) are fetched from the website — carterbeaudoin.net/CAR-TER/catalog.json — cached on disk with a TTL.

• Authoring demos (example snippets + the builder engine) come from the installed carterkit; it also checks PyPI so it can tell you to upgrade a stale kit.

The check_sources tool reports drift between the website, the installed carterkit, and a paired device so mismatches are visible rather than silent.

Configuration

All optional — the defaults target the zero-config local relay:

Tests

python -m pytest -q

Related

• carterkit — the Python layout library + client this depends on.

• meshsocket — the underlying WebSocket mesh transport.

• CAR-TER docs — the control reference and integration guide.

• PROTOCOL.md — the read-back / truthful-push wire contract with the device.

Notes

• The sample-layout tools read the layouts bundled with the CAR-TER app repo when this repo sits beside it in the CAR-TER workspace (as it does in development). In a standalone checkout that set is simply empty — build layouts from the catalog and examples instead.

• Tool failures (bad JSON, validation errors, not-connected, timeouts) are returned as plain explanatory text with the MCP isError flag left false — deliberate, so the model reads and reacts to the message instead of a client short-circuiting on the flag. Don't key automation on isError.

License

MIT — see LICENSE.