docs: add README with setup, usage, and design overview

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 20:57:51 -04:00
parent 9dd2c2fbc7
commit 98a61a8320
1 changed files with 117 additions and 0 deletions
@@ -0,0 +1,117 @@
+# 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
+
+```bash
+pip install mcp aiohttp
+```
+
+### Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "workbench": {
+      "command": "/path/to/workbench",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Any MCP-compatible AI CLI
+
+Point your client at the server:
+
+```bash
+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