Seth/workbench-server

Fork 0

Files

T

Mortdecai 4b551351e1 docs: add open source subheading

2026-03-30 07:38:33 -04:00

5.2 KiB

Raw Permalink Blame History

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

5.2 KiB Raw Permalink Blame History