LineLedger — Factory-Floor Co-pilot

A voice-first assistant for a plant manager or line operator, backed by a self-hosted Model Context Protocol (MCP) server over Streamable HTTP. Built for the Build, Ship, Shape: Amazon Developer Hackathon (Alexa+ track).

The web app simulates the voice-assistant experience in a browser. It is not connected to a physical Alexa+ device.

Demo data disclosure

All production, handover, follow-up and stock records are synthetic demo data. In the plant profile the data comes from a seeded simulation of a fictional contract manufacturer, Tarnby Works, with seven lines and a simulated clock. Nothing is connected to a real factory, PLC, inventory or customer, and no PLC, OPC UA, Modbus or MQTT integration was built or tested. LineLedger reads and reports; it never controls equipment, real or simulated. The UI shows "SYNTHETIC DEMO DATA" and the simulated clock at all times.

Speech input uses the browser's Web Speech API. In Chrome, speech recognition sends audio to the browser vendor's speech service. This project does not run that service. Text input always works, and the microphone starts only after you click Listen.

Related MCP server: Nordic Thingy:52 MCP Server

Zero-cost, local-first

By default: no paid service, no cloud API calls, no credentials in this repository. The optional language-model agent runs against a local Ollama server on loopback only.

Two AWS integrations are available as opt-in switches (Amazon Bedrock for the agent model, Amazon DynamoDB as the store). They are off unless you turn them on, and nothing in this repository needs an AWS account to run, test or judge it. See AWS integrations.

What it does

The plant profile (npm run dev:plant) runs Tarnby Works, a fictional contract manufacturer with seven lines, three shifts and about 100 people, as a live simulation inside the server (server/sim.ts, plant/plant.json): breaks, random stops with realistic reason codes, slow cycles and warm-up after restarts, rejects with reject codes, raw material drawn from stock, and Line 2's heat-sealer temperature. The story day scripts a sealer overheat on Line 2 (warning at 13:14, trip at 13:23, heater band swapped at 13:58, restart at 14:02) and a coil jam on Line 5, over the random model. The dashboard follows it live over the MCP session. A plant manager can ask, by typing or speaking:

• "how are the lines doing right now", "is line 2 running", "why is line 2 down", "how long has line 2 been stopped", "is the sealer temperature normal": live state, reason code, minutes in state, rate, pace against the target to date, alarms and the sealer's temperature against its warn and trip limits.

• "shift summary", "shift summary for shift A": output per line; for the shift in progress, against the target to date (pace), with on-track, at-risk and behind status.

• "show the trend for the last 10 shifts", "plant events".

• "add handover note for line 2: sealer jaw ran hot again, tripped 13:23": saved in the store (SQLite by default, or Amazon DynamoDB), kept across restarts.

• "add follow-up: inspect sealer thermocouple, owner Ravi, due 2026-10-24, line 2", "open follow-ups", "close follow-up 3".

• "stock of heater band", "stock of hdpe": live stock, reorder status, suggested order quantity and days of cover; "receive 20000 kg hdpe" books a goods receipt (an ERP record, not a machine command).

• "how many 600x400x300 12kg boxes fit in a 20ft container": calls the standalone container-load-planner package (MIT, pinned to commit 3c4fe91).

The web page shows the chat, a live MCP trace of the real JSON-RPC traffic (including the server's pushes), seven live line cards, a simulated-clock chip and an alarm ticker. Without the plant profile the server keeps the small two-line seed and no simulation, as the tests use it.

The plant profile has no hand-written demo rows. On a fresh plant database the server first simulates the seven days before the story day (about 0.1 s, its own random streams, stock back at the starting levels afterwards), so the shift history and the trend hold simulated shifts for all seven lines; notes and follow-ups start empty. A plant database made before this change (data/plant.sqlite) loses exactly the old seeded notes, follow-ups and shift rows when the server starts, keeps its own rows and stock, and gets the same week of history.

Run it

Requirements: Node 22.12 or newer. No cloud account and no API key.

npm install
npm run dev:plant         # MCP server with the Tarnby Works plant on http://127.0.0.1:8787/mcp (data/plant.sqlite)
npm run dev:web           # web client on http://127.0.0.1:5173 (proxies /mcp, /api and /agent)

Open the web URL, then type a request or click an example button. npm run dev:server instead starts the two-line seed without a simulation.

If port 5173 is busy, run both commands with WEB_PORT=5273 (the server's Origin allowlist follows it). PORT changes the server port. To reset the demo data, stop the server and delete data/.

Plant switches: LINELEDGER_SIM_SPEED (simulated seconds per real second, default 120: one simulated hour in 30 seconds; the story's 14:10 to 16:15 stretch runs as a x300 time-lapse, shown on the clock chip), LINELEDGER_SIM_HOLDS=on (the clock pauses 12 seconds at 12:58, 13:15 and 13:23 so a presenter can speak; the chip shows HOLD), LINELEDGER_SIM_SEED (default 1; the same seed gives the same day at any speed), LINELEDGER_SIM_FAULTS=off (scripted stops only), LINELEDGER_SIM_STORY=off (no story). The story day runs on a fresh plant database: it starts at 12:55 with shift A already simulated from 06:00. A restarted server resumes where the plant stopped: with every flush (each 15 simulated minutes, and at shutdown) the simulation saves its whole live state (clock, per-line state and counters, open stops and alarms, random streams, recent events) in the store, and the same seed then continues the same day. The plant clock does not run while the server is down. A database from before this was saved continues with the shift after the latest one on record. npm run plant:reset deletes the plant database to replay the story; npm run plant:story-check runs the story day headless and checks its numbers (Line 2 trips at 13:23, Line 2 shift A good units, plant shift A output, HDPE reorder time, heater bands left).

Verify

npm run typecheck        # server, tests, scripts and web
npm test                 # vitest: MCP client over real HTTP against the LineLedger server, hardening, rule-based planner
npm run test:dynamodb    # the same tests against the DynamoDB store on DynamoDB Local (see AWS integrations)
npm run test:e2e         # Playwright: a real browser against the real server and simulation (see End-to-end tests)
npm run check:contrast   # recomputes WCAG contrast from web/src/style.css
npm run build            # vite build -> dist/web
npm run preflight:mcp    # raw initialize and SDK client both report protocolVersion 2025-11-25

MCP evidence

Spec version: the server negotiates 2025-11-25. npm run preflight:mcp checks it twice: from the raw initialize response on the wire, and from transport.protocolVersion in the SDK client. tests/server.test.ts asserts it again.

Where @modelcontextprotocol/sdk 1.32.1 is imported and called at runtime:

Transport behaviour: stateful Streamable HTTP. initialize creates a session and returns its Mcp-Session-Id; later POSTs, the GET /mcp event stream (server push) and DELETE /mcp (end of session) must carry it. A missing id gets 400, an unknown or ended one 404. Sessions idle for 30 minutes are closed, and past 100 sessions the least recently used one is closed. Sessions live in server memory; the data lives in the store, so a restart loses sessions but not data, and clients reconnect. LINELEDGER_MCP_MODE=stateless restores the earlier one-server-per-POST mode (no push; GET and DELETE return 405). The server binds to 127.0.0.1 only, requests are checked for Host and Origin, and request bodies are limited to 64 KB. A server-side trace tap records every JSON-RPC message in and out, including the pushed notifications, and streams it to the UI, so the trace panel shows only real traffic.

Tools: get_shift_summary (pace fields for the shift in progress), get_shift_history, create_handover_note, list_handover_notes, create_follow_up, list_follow_ups, close_follow_up, check_stock (live stock and days of cover in the plant profile), plan_container_load, and in the plant profile get_live_line_status, get_factory_events and receive_stock (a goods receipt). No tool starts, stops or repairs a line.

Resource (subscribable, plant profile): plant://snapshot, the whole live plant in one JSON document. When the simulation changes, subscribed sessions get notifications/resources/updated (at most once a second) and read it again; the trace shows each push followed by the resources/read.

When one session creates a handover note or a follow-up or closes a follow-up, the server also sends a data_changed logging notice to every session, so a second browser tab refreshes its lists without a click. After a server restart the old session id gets a 404; the browser client opens a new session and retries once.

Architecture

browser (web/)  <--stateful MCP session-->  MCP server (server/)  -->  store: SQLite (default)
   chat, trace, live dashboard   (POST, GET push, DELETE)   Express + MCP SDK      or Amazon DynamoDB (LINELEDGER_STORE=dynamodb)
                                                            plant simulation       container-load-planner
                                                            (sim.ts, plant.json)
        |                                    ^
        +--- optional: /agent proxy ---> agent/ (Strands) --MCP client--+
                                           model: local Ollama (default)
                                              or Amazon Nova on Bedrock (LINELEDGER_MODEL_PROVIDER=bedrock)

• server/: TypeScript MCP server (Express 5, zod 4) with the Tarnby Works simulation (sim.ts, seeded, stepped one simulated minute at a time, so a seed gives the same day at any speed). It keeps live state in memory and writes the shift in progress, finished shifts and stock levels to the store every 15 simulated minutes and at each shift end, so the existing tools read its output.

• plant/plant.json: the plant's single source of truth (lines, stations, cycle times, targets, failure and reject parameters, bill of materials, stock, crews, the story day). The tools talk to a Store interface (server/store.ts) with two implementations: store-sqlite.ts (node:sqlite, default) and store-dynamodb.ts (AWS SDK for JavaScript v3).

• web/: Vite + vanilla TypeScript client. The default planner is a deterministic rule-based mapper (web/src/planner.ts, no LLM) from request text to tool calls.

• agent/: optional Python service using Strands Agents with an explicit model (local Ollama by default, Amazon Nova on Bedrock as an option), the MCP server's tools, an AWS-environment scrub and a loopback-only check.

• docs/: UI specification, implementation decisions, download manifest, friction log, product feedback and the demo video plan.

Optional: local-model agent

Status: works, but not reliable enough to be the default. With qwen3:4b-instruct on CPU only, a 10-prompt spike picked a correct tool for every prompt that needs one, answered in about 3 to 17 s per turn (36 s for the first call, which loads the model), and made argument or reasoning mistakes on 3 of 10 prompts. Details and the graded table are in docs/spike-results.md. The web client therefore defaults to the rule-based planner.

python3 -m venv .venv && .venv/bin/python -m pip install -r agent/requirements.txt
npm run test:agent       # 18 tests: AWS env scrub, explicit model, Nova-only and profile guards, loopback-only,
                         # model-call cap, MCP tool discovery, reconnect after a server restart. No AWS call.

Running the agent needs a local Ollama server (not installed by this repository). See docs/download-approval-manifest.md for the no-sudo steps. Then:

npm run dev:agent        # http://127.0.0.1:8788, model qwen3:4b-instruct

and press "Planner: rules (no LLM)" in the web client to switch it to "Planner: agent model".

AWS integrations (optional)

Status, 2026-10-22: code and tests are in this repository. They were run against a local DynamoDB emulator and with mocked AWS credentials only. [OWNER: update this line after the live run, for example "Run against Amazon Bedrock (Nova Lite, us-east-1) and a DynamoDB table on a Free-plan account on 2026-10-23", and link the graded spike table.]

Other switches: LINELEDGER_BEDROCK_MODEL (default us.amazon.nova-lite-v1:0, must start with amazon.nova- or us.amazon.nova-), LINELEDGER_AWS_REGION (default us-east-1), LINELEDGER_DYNAMODB_TABLE (default lineledger), LINELEDGER_DYNAMODB_ENDPOINT (DynamoDB Local, loopback only).

Not used on purpose: SQS (nothing slow to queue yet), DynamoDB Streams (the server publishes its own events, and the table keeps streams off), Kinesis, Amazon MQ and ElastiCache (no workload for them).

Fallbacks to self-hosted services

An AWS outage, missing credentials or a throttled model never ends in an error page. Each AWS piece has a self-hosted twin that takes over by itself (LINELEDGER_FALLBACK=off turns them all off):

Redis and Celery are not used: SQLite, a JSONL file and cron already cover these jobs without another server to run. While the primary store is down, new notes and follow-ups exist only in SQLite and the DynamoDB rows are not shown; the two stores are not synced (noted in server/store-fallback.ts).

Safety rules in the code

• Real AWS is reached only through a project-only profile: AWS_PROFILE=lineledger, with AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE both inside ~/.aws-lineledger/. Otherwise the agent and the server refuse to start, so the machine's default ~/.aws profile is never used by accident. Key variables (AWS_ACCESS_KEY_ID and others) are refused or scrubbed; keys live only in the project file.

• Bedrock: only Amazon Nova model ids. Anthropic and other Marketplace models are rejected at startup (they need a card and are not free). max_tokens 512, at most 4 model calls per request, token usage logged per turn and shown in the chat.

• DynamoDB: one table, provisioned 5 RCU / 5 WCU, no index, stream, backup or replica, created with the AWS CLI (scripts/create-table.sh), never from the console. Ids come from an atomic counter; closing a follow-up is a conditional write. Reads are strongly consistent.

• The IAM user for the project needs only docs/aws-iam-policy.json (replace ACCOUNT_ID).

Try the DynamoDB store locally (no AWS account)

docker run --rm -p 8000:8000 amazon/dynamodb-local:3.3.1     # DynamoDB Local, in memory
npm run test:dynamodb                                        # every server and store test on both stores
export LINELEDGER_DYNAMODB_ENDPOINT=http://127.0.0.1:8000
npm run dynamodb:local-table && npm run dynamodb:seed
LINELEDGER_STORE=dynamodb npm run dev:server                 # the page footer shows "store: Amazon DynamoDB"

Run against AWS (owner only, Free-plan account)

export AWS_CONFIG_FILE=$HOME/.aws-lineledger/config AWS_SHARED_CREDENTIALS_FILE=$HOME/.aws-lineledger/credentials AWS_PROFILE=lineledger
aws sts get-caller-identity                                  # must be the project account
scripts/create-table.sh                                      # creates and checks the table
npm run dynamodb:seed
LINELEDGER_STORE=dynamodb npm run dev:server
LINELEDGER_MODEL_PROVIDER=bedrock npm run dev:agent          # Nova Lite in us-east-1
.venv/bin/python scripts/agent_spike.py > spike-nova-lite.md # 10 prompts, graded by hand afterwards

Alerts and the scheduled report (after the table exists; the deploying profile needs more rights than docs/aws-iam-policy.json, so use the account owner for this one command):

scripts/deploy-report.sh you@example.com                     # topic, Lambda, schedule (06:00, 14:00, 22:00 UTC)
# confirm the subscription in the email AWS sends, then:
aws lambda invoke --function-name lineledger-shift-report /dev/stdout
LINELEDGER_NOTIFY=sns LINELEDGER_SNS_TOPIC_ARN=<TopicArn from the stack output> LINELEDGER_STORE=dynamodb npm run dev:server

Teardown after judging: scripts/deploy-report.sh --delete, delete the table and the IAM user, check Billing shows no charge, delete ~/.aws-lineledger/. The full plan, cost estimate and cut lines are in docs/aws-integration-plan.md.

End-to-end tests

npm run test:e2e starts the real server in the plant profile (story day, seed 1, x120, in-memory SQLite) and the Vite client on their own ports (8790, 5190), then drives Chromium through: the stateful session and live push; the scripted Line 2 sealer trip, with the chat explaining it and the trace showing the pushes; the operator questions through the rule-based planner; a check that nothing on the page controls a line; persistence across a reload with a new session; reconnecting after the server ends the session; and the container-load planner. With LINELEDGER_TEST_DYNAMODB_ENDPOINT set, the server runs on the DynamoDB store instead. First run: npx playwright install chromium.

Limits

• The simulation runs inside the server process. A real deployment would receive machine data from an edge gateway (OPC UA, Modbus or MQTT to an ingest endpoint); no such ingest was built.

• The plant percent in the shift summary adds different products (brackets, crates, kits) weighted by target. It is a target-weighted figure, not a physical quantity.

• MCP sessions live in one server process's memory, so the server cannot be scaled out or run on serverless as is; use LINELEDGER_MCP_MODE=stateless for that, which gives up server push.

License

MIT. See LICENSE.