# Benchside

A workshop journal that remembers the next step, interruption note and exact location of loose parts. A real MCP server and a local web workbench share the same durable state.

![Benchside workbench](artifacts/benchside-desktop.png)

## Run

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 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. Remote Alexa connectivity would require a suitable authenticated deployment; it has not been tested. 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
```

Six domain/HTTP integration tests and four browser tests passed on 2026-09-26, including actual protocol negotiation and server restart. Browser tests use an isolated temporary data directory. See [QA evidence](docs/QA.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.