For agents & developers

Ohmsville read by machines: the discovery files, the URL grammar that makes every circuit a link, a keyless REST API with the real solver behind it, and the MCP connector.

What is Ohmsville, for an agent?

Ohmsville is a spring-terminal electronics lab with a real circuit simulator behind it, and every part of it is addressable: the manual, the lessons and the parts catalogue are JSON, a wired circuit is a URL, and the solver runs on demand over HTTP with no key and no sign-up.

Which discovery files does Ohmsville publish?

Four, all generated from the same authored data the app renders: llms.txt for the shape of the site, llms-full.txt for every experiment and lesson in full, an A2A-style agent card at /.well-known/agent-card.json, and sitemap.xml.

  • llms.txt — what Ohmsville is, the URL grammar, every experiment/recipe/lesson, and links to everything else.
  • llms-full.txt — the same, plus every experiment's and lesson's full text and the schematic DSL.
  • Agent card — an A2A-style description of the shop teacher: its three skills, and what's planned.
  • robots.txt — allows everything, points at the sitemap.
  • sitemap.xml — every static route, campaign and blog post.

How do I open a circuit by URL?

The bench reads its whole state from the URL hash, so a circuit is a link: the activity to open, the board when it differs from the standard kit, the wires as spring pairs, and a campaign to enter. Hand someone the link and they get your board.

/bench#a=<activity>&b=<board>&w=<wire pairs>&c=<campaign>
  • a= — the manual page to open on load: an experiment (exp-<n>) or a recipe id.
  • b= — the board layout, present only when it differs from the standard kit. A standard part is id@col.row; a part pulled from the drawer is +kind:value@col.row, e.g. +resistor:2200@3.1 for a 2.2 kΩ resistor at column 3, row 1.
  • w= — wires, comma-separated spring-spring pairs, e.g. 1-5,6-28.
  • c= — a campaign id, applied once when the page opens.

Example — experiment 1's reference wiring: /bench#a=exp-1&w=1-5,6-28,29-38,39-2

Try it: open experiment 1 wired →

What can the API and the MCP server do?

The REST API serves the manual, the recipes, the lessons and the parts as JSON, turns a circuit document into a bench link and back, and settles a circuit on the real solver to return volts, milliamps, LED brightness, transistor region, relay state and speaker pitch. The MCP server at /mcp offers the same skills as tools, resources and a prompt.

{
  "format": "circuit-city.circuit",
  "version": 1,
  "activity": "exp-1",
  "wires": [
    [
      "battery.+",
      "r330a.a"
    ],
    [
      "r330a.b",
      "led-red.a"
    ],
    [
      "led-red.k",
      "pushbutton.a"
    ],
    [
      "pushbutton.b",
      "battery.-"
    ]
  ]
}

Try it — turn that document into a link, and run it on the real solver:

curl -s -X POST https://ohmsville.com/api/links \
  -H 'content-type: application/json' \
  -d '{"circuit":{"format":"circuit-city.circuit","version":1,"activity":"exp-1","wires":[["battery.+","r330a.a"],["r330a.b","led-red.a"],["led-red.k","pushbutton.a"],["pushbutton.b","battery.-"]]}}'
curl -s -X POST https://ohmsville.com/api/simulate \
  -H 'content-type: application/json' \
  -d '{"circuit":{"format":"circuit-city.circuit","version":1,"activity":"exp-1","wires":[["battery.+","r330a.a"],["r330a.b","led-red.a"],["led-red.k","pushbutton.a"],["pushbutton.b","battery.-"]]},"steps":[{"set":{"switches":{"pushbutton":true}},"settleMs":300}]}'

Full reference at /api/docs (machine-readable: /api/openapi.json, /api/schema/circuit.json), and a walkthrough at docs/API.md. One endpoint needs a key: POST /api/ask asks the shop teacher a question about a circuit, in its usual voice with its board tools switched off. POST /api/keys with your email mails you one, good for 50 questions a UTC day.

Connect the MCP

Ohmsville is a remote MCP server: your agent gets the experiments, the lessons, the parts, the simulator and the link builder as tools it can call. In Claude Code:

claude mcp add --transport http ohmsville https://ohmsville.com/mcp

In Claude.ai or ChatGPT, add a custom connector with the URL https://ohmsville.com/mcp. Then ask for something — "build me a night light that turns on in the dark" — and the model writes a circuit, checks it on the real solver, and hands you a link that opens the bench already wired. Full walkthrough in docs/MCP.md.

What is the shop teacher, and how do I ask it something?

The shop teacher is a Claude agent that can see the live board and act on it: it wires and unwires parts, turns knobs, holds buttons, reads the instruments and explains what it finds. POST /api/ask takes an X-Api-Key, and POST /api/keys mails you one.