Foreman MCP

Ask your business. Your business answers.

Comment

Foreman MCP turns Alexa+ into the voice operations chief of a field-service business.

The owner of a remodeling, plumbing, HVAC or landscaping company does not have an information problem — they have a chasing problem. Job status lives in workers' heads, leads cool off while nobody answers, crews arrive without materials, and the owner spends the day on the phone assembling facts that the business already knows.

Foreman MCP connects that business to Alexa+ through a self-hosted Model Context Protocol server (spec 2025-11-25, Streamable HTTP) with 11 tools. The owner asks and orders by voice — "How is my business today?", "Prepare tomorrow", "Which leads haven't I answered?" — and the server does the work against the business's real operating state:

  • A composite daily briefing, not a one-turn answer: today's schedule, tomorrow's unassigned jobs, leads past the response SLA, low stock and the dispatch outbox in one spoken summary.
  • An agentic morning dispatch. run_morning_dispatch prepares tomorrow end to end: it detects gaps a human would miss (jobs with no crew, a crew double-booked, material shortfalls aggregated across all of tomorrow's jobs, leads waiting past the first-response SLA), composes a dispatch per crew, queues an owner summary with ready-to-send lead replies, and drafts an approval-gated shopping list for the shortfalls.
  • State between sessions. Jobs, crews, leads, inventory, the outbox, shopping drafts and a full audit log live in a persistent store with atomic write-through. A field update reported today is still on the job's thread tomorrow; a lead reply closes its follow-up clock permanently. Restart the server and the business remembers — our automated gate proves it across two boots.
  • Purchasing with a human gate. Shopping lists are drafts in pending_approval. The server never buys anything; the owner approves in the operations console.
  • A live operations console that makes voice visible: schedule, leads, inventory risk, dispatch outbox, pending approvals and audit trail, plus a voice-command simulator that calls the same MCP tools an Alexa+ client calls.

The demo business is a fictional San Antonio remodeling company (3 crews, 7 jobs, 5 leads, 11 inventory items, 555 phone numbers), seeded relative to the current day so the demo never goes stale: there is always a job tomorrow with no crew, stale leads and low thinset for the dispatch flow to catch.

Foreman MCP is the Alexa+ expression of the ELTIGRELABS thesis: the worker talks, the system understands, the company records, the owner asks, and the company answers.

Try it / testing instructions for judges

No account, credentials or payment are needed. In the console, use the voice-command simulator buttons — each one sends the same MCP tools/call an Alexa+ client sends. Good first run: "How is my business today?", then "Prepare tomorrow.", then watch the outbox, shopping approvals and audit trail change.

Run it locally:

npm install
npm run build
npm start            # MCP at http://localhost:3000/mcp, console at /console
npm run verify       # 48-assertion end-to-end gate across two server boots

Raw protocol smoke test:

curl -s -X POST https://foreman-mcp.vercel.app/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"judge-smoke","version":"1.0.0"}}}'

The hosted demo uses the shared fictional dataset; actions taken through the tools (assigning crews, logging updates, replying to leads) mutate that demo state, which is itself the demonstration of state between sessions.

Built With

  • amazon-bedrock
  • aws-sdk-for-javascript
  • model-context-protocol
  • node.js
  • streamable-http
  • typescript
  • zod
Share this project:

Updates

Submission history