# Workbench

**Open source and safe for work.**

An MCP server that lets your AI build interactive web pages you can open in your browser — diagnostic tools, dashboards, guided procedures, anything.

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.

```
┌─────────────────────┐         ┌──────────────────────────────┐
│  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       │  │
└──────────────────────┘         └──────────────────────────────┘
```

## Setup

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+
- A web browser
- Any MCP-compatible AI CLI

## Platform Support

| Platform | Status |
|----------|--------|
| Linux | Full support |
| macOS | Full support |
| Windows | Via WSL2 |

## FAQ

**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.

**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.

**Can I resume a previous session?**
Yes. Projects persist on disk. The AI calls `workbench_read_log` to catch up on what happened.

**What AI CLIs work with this?**
Any that supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) over stdio transport.

**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

MIT