Seth/workbench-server
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: README and INSTALL.md — AI-guided setup with SSH ControlMaster

Browse Source
This commit is contained in:
Mortdecai
2026-03-30 07:36:09 -04:00
parent 0c2c7def09
commit c97adfc561
2 changed files with 298 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+105 -94
View File
@@ -1,116 +1,127 @@
# Workbench
MCP server that lets any AI CLI spin up interactive hardware diagnostic web pages served over LAN.
An MCP server that lets your AI build interactive web pages you can open in your browser — diagnostic tools, dashboards, guided procedures, anything.
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
The AI has full control over the HTML, CSS, and JavaScript. It pushes content to the browser in real-time via WebSocket. You see it update live as the AI works.
```
+------------------------------------------+
| Phone Browser (at workbench) |
| +-------------------+----------------+ |
| | Diagnostic Page | Terminal Panel | |
| | - Schematic | (ttyd/tmux) | |
| | - Checklist | | |
| | - Measurements | AI session | |
| | - Log feed | runs here | |
| +-------------------+----------------+ |
+------------------------------------------+
┌─────────────────────┐ ┌──────────────────────────────┐
│ AI CLI │ │ Browser │
│ │ │ │
│ > diagnose the HV │ HTTP │ ┌────────────────────────┐ │
│ focus circuit │ + WS │ │ AI-generated content │ │
│ ├────────►│ │ schematics, tables, │ │
│ AI pushes HTML/CSS/ │ │ │ checklists, dashboards│ │
│ JS to the browser │ │ │ — updated live │ │
│ │ │ ├────────────────────────┤ │
│ │ │ │ Session Log │ │
│ │ │ │ 14:32 R412: FAIL │ │
└──────────────────────┘ └──────────────────────────────┘
```
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
Give your AI the repo URL and tell it to set you up:
```
Clone https://git.sethpc.xyz/Seth/workbench-server and set it up for me
```
Or if you've already cloned it, open your AI CLI in the repo and say:
```
Read INSTALL.md and set me up
```
The AI clones the repo (if needed), installs the package, configures the MCP server, and writes a personalized `START.md` for future sessions.
That's it. The AI handles everything.
## What It Does
Workbench is an [MCP server](https://modelcontextprotocol.io). Once configured, your AI CLI has access to these tools:
| Tool | What it does |
|------|-------------|
| `workbench_scaffold` | Creates a project and starts the HTTP server. Returns the URL. |
| `workbench_state` | Pushes HTML/CSS/JS to the browser page via WebSocket |
| `workbench_log` | Records a session log entry (saved to disk + shown in browser) |
| `workbench_read_log` | Reads recent log entries (for session resume) |
| `workbench_list` | Lists all projects and their status |
| `workbench_stop` | Stops the HTTP server and ends the session |
The AI generates all content — HTML, CSS, JavaScript. Workbench is just the plumbing.
### Server Persistence
Workbench servers survive AI CLI restarts. If you restart your AI and it calls `workbench_scaffold` again, it detects the existing running server and reattaches — no duplicates, no lost connections. The browser stays connected throughout.
## Usage
Once set up, just talk to your AI. It decides when to use the workbench.
**Hardware diagnostic:**
> "I need to troubleshoot the focus circuit on this oscilloscope. Here's the service manual."
**Guided procedure:**
> "Walk me through replacing the capacitors on this PCB. Show me the layout and a checklist."
**Data collection:**
> "I need to measure and record voltages at 12 test points on this power supply."
**Dashboard:**
> "Build me a live status dashboard for my homelab services."
The AI creates the project, starts the server, gives you a URL, and builds the page. Open the URL in your browser and watch it update in real-time.
## Project Data
Each session creates a project in `~/workbench/`:
```
~/workbench/
START.md # Personalized startup guide (created during setup)
io102/
index.html # Scaffold HTML (WebSocket client)
state.json # Current page state
session.md # Human-readable session log
session.jsonl # Machine-readable log (for AI session resume)
cost-log.jsonl # Session tracking
assets/ # Images, manuals, datasheets
```
Session logs are always human-readable. Anyone can follow what happened without AI access.
## Requirements
- Python 3.10+
- `mcp` and `aiohttp` packages
- A web browser
- Any MCP-compatible AI CLI
```bash
pip install mcp aiohttp
```
## Platform Support
### Claude Code
| Platform | Status |
|----------|--------|
| Linux | Full support |
| macOS | Full support |
| Windows | Via WSL2 |
Add to `~/.claude/settings.json`:
## FAQ
```json
{
"mcpServers": {
"workbench": {
"command": "/path/to/workbench",
"args": ["mcp"]
}
}
}
```
**Does the browser need to be on the same machine?**
No. The HTTP server binds to `0.0.0.0` — any device on your LAN can open the URL.
### Any MCP-compatible AI CLI
**What happens if I restart my AI CLI?**
The HTTP server keeps running. When the AI calls `workbench_scaffold` again, it detects the existing server and reattaches. The browser stays connected.
Point your client at the server:
**Can I resume a previous session?**
Yes. Projects persist on disk. The AI calls `workbench_read_log` to catch up on what happened.
```bash
python3 server.py # runs on stdio transport
```
**What AI CLIs work with this?**
Any that supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) over 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.
**Can I use this over SSH?**
Yes. The AI runs on the remote host and the HTTP server is accessible over the network. Open the URL from any browser on the LAN.
## License