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
INSTALL.md
+193
View File
@@ -0,0 +1,193 @@
# Workbench — AI-Guided Setup
You are an AI assistant helping a user set up Workbench. Follow these steps in order. Do not ask the user what they have — detect it yourself. Present options conversationally.
## Step 0: Clone and Install
If the repo is not already cloned locally, clone it:
```bash
git clone <repo-url>
cd workbench-server
```
Install the package:
```bash
pip install .
```
If `pip install` fails due to PEP 668, use:
```bash
pip install --break-system-packages .
```
Verify it installed:
```bash
workbench --version
```
If already installed, skip to Step 1.
## Step 1: Detect the Environment
Run these commands and collect the output. Do NOT ask the user:
```bash
# Python
python3 --version
# Platform
uname -s -r -m
# Access topology
echo "SSH_CONNECTION=$SSH_CONNECTION"
# SSH usage detection
ls ~/.ssh/config 2>/dev/null && echo "ssh config: found" || echo "ssh config: not found"
grep -l "ControlMaster\|ControlPath" ~/.ssh/config 2>/dev/null && echo "ssh multiplexing: configured" || echo "ssh multiplexing: not configured"
ls ~/.ssh/known_hosts 2>/dev/null && wc -l < ~/.ssh/known_hosts 2>/dev/null && echo "known hosts (suggests SSH usage)" || true
```
## Step 2: Create Project Directory
```bash
mkdir -p ~/workbench
```
## Step 3: Configure SSH ControlMaster (if applicable)
If the user SSHes to remote machines (detected by known_hosts having entries, or the user mentions remote work), set up SSH connection multiplexing so the AI CLI can reuse authenticated SSH connections without needing to re-enter passwords or touch physical keys.
Ask the user: "Do you SSH into remote machines as part of your work? If so, I can configure SSH connection multiplexing — this lets you authenticate once, and my SSH commands piggyback on your open connection without needing a password."
If yes:
```bash
mkdir -p ~/.ssh/sockets
chmod 700 ~/.ssh/sockets
```
Check if ControlMaster is already configured:
```bash
grep -q "ControlMaster" ~/.ssh/config 2>/dev/null && echo "Already configured" || echo "Not configured"
```
If not configured, add to `~/.ssh/config` (create if needed):
```bash
touch ~/.ssh/config
chmod 600 ~/.ssh/config
cat >> ~/.ssh/config << 'SSHEOF'
# Workbench: SSH connection multiplexing
# First connection authenticates normally (password, key, etc.)
# Subsequent connections reuse the tunnel — no re-auth needed
Host *
ControlMaster auto
ControlPath ~/.ssh/sockets/%r@%h-%p
ControlPersist yes
SSHEOF
```
Explain to the user how it works:
> **How this works:** When you SSH into a remote machine, the connection stays open in the background. During that time, any other SSH command to the same host — including ones I run — reuses your authenticated tunnel. No password prompt, no key tap. The tunnel stays open until the original session closes or the connection drops — your key/auth provider handles its own timeout. Just open an SSH session to your target machine before asking me to work on it.
If the user's `~/.ssh/config` already has Host-specific blocks, add the ControlMaster settings under a `Host *` block at the **end** of the file so it acts as a default without overriding specific host configs.
## Step 4: Configure MCP
Add the Workbench MCP server to the user's AI CLI configuration.
**Detect which CLI they're using** by checking for config files:
```bash
ls ~/.claude/settings.json 2>/dev/null && echo "Claude Code detected"
ls ~/.gemini/settings.json 2>/dev/null && echo "Gemini CLI detected"
ls ~/.config/gemini/settings.json 2>/dev/null && echo "Gemini CLI detected (alt path)"
```
The MCP server configuration:
```json
{
"mcpServers": {
"workbench": {
"command": "workbench",
"args": ["mcp"]
}
}
}
```
Add this to the appropriate config file for the detected CLI. For unknown CLIs, print the JSON and tell the user to add it to their MCP settings. The server command is `workbench mcp` on stdio transport.
## Step 5: Smoke Test
```bash
workbench list
```
Should print "No projects found in ~/workbench/" (or list existing projects if any).
## Step 6: Write START.md
Write `~/workbench/START.md` — a personalized startup guide for this user's environment.
Include:
- Setup date
- Platform details
- MCP configuration that was applied (which CLI, what config)
- How to start a session
- SSH ControlMaster status
- How to access the workbench page (open URL in browser)
Example:
```markdown
# Workbench — Start Guide
**Setup date:** 2026-03-30
**Platform:** Linux (Ubuntu 24.04)
## Starting a Session
1. Start your AI CLI
2. Ask the AI to create a workbench project — it calls `workbench_scaffold` and returns a URL
3. Open the URL in your browser
4. The AI pushes content to the page in real-time
## MCP Configuration
Configured in `~/.claude/settings.json`:
```json
{
"mcpServers": {
"workbench": {
"command": "workbench",
"args": ["mcp"]
}
}
}
```
## Environment
- Python: 3.11.4
- SSH ControlMaster: configured
## Notes
- The HTTP server binds to 0.0.0.0 — open the URL from any device on your LAN
- If you restart your AI CLI, the server keeps running — just call workbench_scaffold again
- Session logs are saved in ~/workbench/<project>/session.md
```
Adapt the content to match what you actually detected and configured. This file is for future AI sessions to read, so be precise.
## Done
Tell the user setup is complete and how to start their first session.
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