We will be undergoing planned maintenance on Oct 7th 6:00AM UTC / Oct 7th 2:00AM ET

Flo

An open source MCP operating layer for hands-free service operations.

Comment

Problem

Technicians work with occupied hands: gloves, tools, vehicles and machinery. Finding a work order, checking parts, preparing an estimate and scheduling a repair can mean repeatedly stopping the job to navigate different systems. Customers face a different problem: knowing what is happening with their repair without exposing someone else's information.

Solution

Flo demonstrates a conversational shop workflow backed by real structured MCP tool execution. Open work order 1842, record an alternator diagnosis, search compatible offers from three simulated suppliers, compare alternatives, calculate an estimate, simulate customer approval, resume the job and prepare a purchase with Bay 2 scheduling. Nothing is purchased or scheduled until the explicit confirmation passes server-side checks. All shop purchases and messages are simulated service operations, not real supplier orders or customer notifications.

A separate AWS-hosted customer site uses real Login with Amazon. Amazon identifies the visitor; a separately authorized shop mapping determines repair access. The tested fictional customer can read repair 1842 but cannot read another customer's 2842 or an unknown repair. Unlinked visitors remain signed in without repair access and can sign out. These hosted projections are independent test fixtures, not synchronized shop data; they have no estimate or scheduled appointment.

Why This Matters

The prototype makes a concrete interface tradeoff: short conversational commands for hands-busy work, visual comparisons for detail, and explicit confirmation for transactions. Its reusable contribution is the separation of intent, structured tools, deterministic business rules and authority. Adapters could support other service industries later; no commercial shop integration or measured productivity improvement is claimed.

How We Used AI

Flo is a custom Alexa-style simulation, not a certified Alexa+ add-on. Its current command routing and reference resolution are deterministic and bounded. Browser speech input is optional; typed commands remain available. The model does not independently plan an arbitrary workflow.

The optional deployed narrator calls Amazon Bedrock Converse with Amazon Nova Lite for one short qualitative lead sentence. Flo sends a minimal, non-personal payload, validates the response and falls back locally on failure. Code, not the model, owns part choice, fitment, money, permissions, approval and transaction state. Bedrock is not used to decide repair ownership. Official Alexa+ account linking, host integration, MCP App packaging and certification remain incomplete.

How We Used Codex

Codex assisted the TypeScript implementation, deterministic engine and permission tests, transaction-integrity debugging, Docker/CI checks, AWS deployment review, and reconciliation of release claims with recorded results. The owner handled account sign-in and approved scoped cloud changes. Tests and service read-backs, not generated explanations alone, are the evidence for implementation claims. No Kiro Crew or Strands usage is claimed.

Key Features

  • MCP Streamable HTTP with a tested 2025-11-25 negotiation; 25 non-demo shop tools plus three demo controls. These are mock-backend tools, not production-certified commercial operations.
  • Four HTTP mock services for shop, inventory, supplier and customer operations.
  • Deterministic fitment, integer-cent estimates and explicit comparison rankings.
  • Approval-to-estimate/SKU binding, role checks, single-use confirmation, idempotency, scheduling conflict checks and audit records.
  • Job context survives a new conversation in the local running process; restarting or resetting the mock environment is not durable shop persistence.
  • A local read-only owner preview omits shop cost, supplier details and margin.
  • Separate hosted LWA sign-in, durable trusted linking and fictional repair isolation, with private enrollment authority and negative-access checks.

Architecture

Local: browser simulator → MCP client → Flo Streamable HTTP server → orchestrator and deterministic engines → HTTP adapters → four mock services.

Hosted customer: browser → HTTPS API Gateway/Lambda → validated LWA identity and session → trusted customer link → customer-safe DynamoDB repair projection. Private enrollment approval is distinct from customer consent/redemption.

Optional narration: server-side signed request → IAM-protected API Gateway/Lambda → DynamoDB model-attempt allowance → Bedrock. CloudWatch records bounded operational logs. Secrets Manager supplies private customer staging configuration. CloudFormation defines reproducible deployments and scoped permissions.

There is no synchronization arrow between hosted repairs and local shop state. AgentCore Runtime/Memory/Gateway are future work, not deployed components.

Testing Instructions

Credential-free judge path: local simulation

Use Node.js 22+ and pnpm 11, or Docker Compose. The public repository contains source, MIT license and example configuration. Do not supply AWS credentials for the local fallback or expose mock services publicly.

pnpm install --frozen-lockfile
pnpm build
pnpm typecheck
pnpm lint
pnpm test
node --test scripts/*.test.mjs
pnpm docker:up

The local owner preview is at http://127.0.0.1:4200/; the separate shop demo is at http://127.0.0.1:4200/shop. Acknowledge the synthetic-data notice. Follow the README workflow. Simulate approval only with the labeled demo control; prepare the transaction, inspect it, then confirm. Start a new conversation before asking about the Ford to demonstrate context. Use pnpm demo:reset only for this disposable local environment.

The best-gross-profit branch selects the $289 shop-cost option, $101.15 gross part profit and $561.33 estimate. The balanced $219 option instead produces a $459.03 estimate. Do not mix these branches in screenshots or narration.

node scripts/docker-smoke.mjs resets the disposable local demo and exercises its full workflow; never point it at staging or a real shop. Linux CI separately executes Docker and isolated customer/enrollment contracts. Some POSIX-only tests are explicitly skipped on Windows.

Hosted customer path

The public site supports real LWA. Signing in does not enroll a judge as a customer and does not grant arbitrary repair access. The unlinked state and sign-out are available without private operator access. The existing linked fictional test identity must not be shared. Use the replacement recording and dated isolation report for that controlled scenario; use the credential-free local route for independent end-to-end judging. Never publish an Amazon password, token, invitation or AWS credential in testing instructions. Any additional hosted judge enrollment requires a separately designated test identity and authorization.

Evidence: hosted pairing, hosted A/B isolation, and CI for release source c63121b. That CI run proves the named source, not future changes or official Alexa testing.

Public Demo Link

https://i4ceh4qpdg.execute-api.us-west-2.amazonaws.com/

Separate, read-only customer staging site with identity/ownership restrictions. It is not a public shop simulator or an authenticated Alexa MCP endpoint.

Public Repository Link

https://github.com/agammann/flo — MIT license; GitHub username agammann.

Known Limitations

  • No official Alexa+ add-on deployment, account-linking flow, Inspector, Amazon simulator/device validation, certification or MCP App package.
  • No AgentCore deployment or general-purpose LLM orchestration.
  • No real supplier, shop, payment, notification or booking integration.
  • Local operational state is in-memory. Hosted test fixtures are separate and have no estimate or schedule; there is no cross-environment synchronization.
  • One real Amazon identity was paired to a fictional A designation; B was an isolated fixture, not a second signed-in Amazon account. This is not a test of real-world repair ownership verification.
  • Throttles and finite model-attempt allowance are not an account-wide dollar cap.
  • Production consumer booking requires integration-route review with Amazon.

Demo

Watch the public 2:54 English demo. English narration and captions are included. It shows the local MCP workflow with the corrected gross-profit comparison and matching estimate. The hosted identity/isolation portion is labeled September 8 evidence, not a freshly recorded authenticated session.

Hackathon tracks and open source

Primary track: Alexa+ (custom simulated experience with real local MCP calls). Planned mini-challenge entries: AWS Builder and Open Source. Repository: https://github.com/agammann/flo. MIT license. GitHub username: agammann.

Open-source contribution adds customer-repair isolation regression coverage and source-linked verification. Commercial shop adapters, production repair-ownership verification and official Alexa deployment remain future work.

Built With

Share this project:

Updates

Submission history