# Benchside

A workshop journal that remembers the next step, interruption note and exact location of loose parts. A real MCP server and web workbench share the same durable state. The local app keeps a file on your computer; the hosted app keeps a separate online workspace for each browser.

![Benchside return ticket and parts tray, using a clearly labeled fictional sample](artifacts/design-20260927/gallery/laptop-viewport.png)

## Hosted app

[Open Benchside](https://benchside.dgkv.chatgpt.site). The online workshop is scoped to a private browser cookie; clearing cookies loses access. Other browsers get separate workshops. There is no account login or recovery. Use fictional data for this public prototype and download a copy of anything you want to retain. See [hosting boundaries and build](docs/HOSTING.md).

The hosted MCP endpoint is `https://benchside.dgkv.chatgpt.site/api/mcp`. Compatible clients must retain the returned workshop cookie between requests. All nine tools below are available through the genuine SDK transport.

## Run locally

Requires Node.js 22 or newer.

```sh
npm ci
npm start
```

Open http://127.0.0.1:4318. Start a project with your own steps or try the explicitly labeled sample. Record a completion, stash a part, pause with a next-action note, reload and ask where you left off. Resume and undo a mistaken completion.

There is no API key, paid service, live language model, Echo connection or Alexa certification. The command simulator uses a finite grammar and is labeled accordingly. Physical completion records only what the user reports. Sample steps and actions are illustrative.

## Actual MCP integration

The official `@modelcontextprotocol/sdk` implements protocol **2025-11-25** over Streamable HTTP at `http://127.0.0.1:4318/mcp`. Any compatible local MCP client can initialize, list tools and call them. The workbench itself calls these tools over HTTP; it does not use a separate mock data path.

| Tool | Purpose |
| --- | --- |
| `list_projects` | List recorded project progress |
| `create_project` | Create user-authored steps |
| `get_project` | Read current revision, steps, parts and history |
| `get_resume_briefing` | Read the exact saved checkpoint and parts locations |
| `complete_step` | Record the current step complete |
| `undo_completion` | Reopen the last completed step |
| `stash_part` | Record/update a named part, quantity and location |
| `pause_project` | Save interruption and next-action notes |
| `resume_project` | Resume without losing context |

Read the project before writing. Writes require its current `expected_revision`, a unique UUID `request_id`, and the relevant identifiers. Retry the exact payload with the same request ID after an ambiguous response. Stale revisions fail; a duplicate request cannot skip another step. Tool descriptions instruct an agent to record completion only on explicit user confirmation.

The transport is stateless JSON-response mode: POST is supported; standalone GET/SSE and DELETE return 405. This is permitted by the [2025-11-25 transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).

## Command simulator

```text
where did I leave off?
done
undo
resume
stash 6 brass screws @ blue tray
pause: the phone rang | next: label the left tray
```

Unknown commands are rejected without changing state. Optional browser speech synthesis reads the exact briefing; it is not speech recognition or a voice assistant connection.

## Persistence and boundaries

Data is saved by atomic file replacement to `data/workshop.json`; `BENCHSIDE_DATA_DIR` chooses another directory. Only one server may use a data directory. A normal Ctrl-C releases its lock. After an abrupt crash, first confirm the old process is gone, back up the directory, then remove only the abandoned `workshop.lock`. Corrupt data causes startup to fail without changing it. A project export is a readable copy; there is no UI import feature. Back up the full data directory for recovery.

The local service binds to loopback only and rejects unexpected Host/Origin headers. It has no authentication and must not be exposed as a public multi-user server. The separate hosted build provides browser-cookie isolation; it is not account-authenticated Alexa connectivity and has not been tested with Alexa. Limits: 20 projects, 50 steps per project, 100 named parts, 1,000 history events/receipts per project, 4 MB persisted store, 64 KB HTTP request. Atomic replacement protects against partial writes in ordinary process failures; power-loss durability is not guaranteed.

## Verify

```sh
npx playwright install chromium
npm test
npm run test:browser
npm run test:hosted
```

The 2026-09-27 hosted pass ran 14 local/domain/recovery tests, seven browser journeys and seven actual workerd/D1 tests, all passing. The six original domain/HTTP tests and seven redesign browser journeys are retained. Checks include actual protocol negotiation, server restart, checkpoint accuracy, parts locations, keyboard recovery and phone/enlarged-text reflow. Browser tests use an isolated temporary data directory. See [QA evidence](docs/QA.md), [design rationale](docs/DESIGN.md), [research and plan](docs/PLAN.md), [developer feedback](docs/FEEDBACK.md) and [submission draft](docs/SUBMISSION.md).

New application code began on 2026-09-26. Codex researched, designed, wrote and verified this prototype under autonomous delegation; no human maker trial, usage metric, device test or competition acceptance is claimed. Existing dependencies are disclosed in package.json and package-lock.json. MIT license; no affiliation with Amazon or the MCP project is implied.