workbench-server/README.md

Workbench

MCP server that lets any AI CLI spin up interactive hardware diagnostic web pages served over LAN.

You describe the problem, hand the AI a manual or datasheet, and it builds a live diagnostic tool you can open on your phone at the workbench. Measurements, schematics, checklists, and session logs — all updated in real-time as you work.

What It Does

+------------------------------------------+
|  Phone Browser (at workbench)            |
|  +-------------------+----------------+ |
|  | Diagnostic Page   | Terminal Panel | |
|  | - Schematic       | (ttyd/tmux)    | |
|  | - Checklist       |                | |
|  | - Measurements    | AI session     | |
|  | - Log feed        | runs here      | |
|  +-------------------+----------------+ |
+------------------------------------------+

The AI generates all diagnostic content — schematics, component databases, test procedures, checklists. The server just provides the plumbing: HTTP file serving, WebSocket state push, and session logging.

MCP Tools

Tool	What it does
workbench_scaffold	Creates a project directory, writes the HTML shell, starts the HTTP/WebSocket server, returns the LAN URL
workbench_state	Pushes arbitrary JSON state to the browser. Include template (HTML), styles (CSS), script (JS) fields to update the page
workbench_log	Appends to session.md (human-readable) and session.jsonl (machine-readable), pushes to browser log feed
workbench_read_log	Returns recent log entries so the AI can resume a previous session
workbench_list	Lists all projects and their active/inactive status
workbench_stop	Stops the HTTP/WebSocket server, logs session end to cost-log.jsonl

Setup

Requirements

• Python 3.10+
• mcp and aiohttp packages

pip install mcp aiohttp

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "workbench": {
      "command": "/path/to/workbench",
      "args": ["mcp"]
    }
  }
}

Any MCP-compatible AI CLI

Point your client at the server:

python3 server.py  # runs on stdio transport

CLI

The workbench script provides standalone commands:

workbench serve <name> [port]  # serve a project without MCP (default port 8070)
workbench list                 # list all projects
workbench mcp                  # start the MCP server
workbench help                 # show usage

How It Works

1. AI calls workbench_scaffold("io102", "Heathkit IO-102 Focus Diagnostic")
2. Server creates ~/workbench/io102/ with the HTML shell, log files, and state file
3. Server starts HTTP + WebSocket on a free port, returns http://192.168.0.141:8070
4. AI reads the equipment manual, builds a diagnostic page, calls workbench_state with HTML/CSS/JS
5. Browser updates live via WebSocket
6. As the user takes measurements, AI calls workbench_log to record everything
7. Session log is always human-readable — anyone can follow what happened without AI access

Project Structure

Each project lives in ~/workbench/<name>/:

~/workbench/io102/
  index.html        # scaffold shell + AI-generated content
  state.json        # current state (pushed to browser on connect)
  session.md        # human-readable diagnostic log
  session.jsonl     # machine-readable log (one JSON object per line)
  cost-log.jsonl    # session start/end tracking
  assets/           # manuals, datasheets, images

Design Principles

• AI builds the content — no templates, no rigid schemas. The AI reads the manual and generates everything.
• Context light — MCP tools return short confirmations. The AI has full freedom.
• Everything is logged — dual-format session logs that humans and AIs can both read.
• LAN-native — no cloud, no auth. Served on your local network.

Origin

Built for troubleshooting a 1971 Heathkit IO-102 oscilloscope with a defocused CRT. The AI read the service manual, identified the likely fault (drifted carbon composition resistors in the HV focus voltage divider), and generated an interactive diagnostic page with circuit schematic, component test procedures, and a checklist — all viewable on a phone at the workbench.

License

MIT