Mortdecai
131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
# 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
|