Storefront Voice Ops

Run your online store by talking to Alexa+, with real actions behind every answer.

Storefront Voice Ops is an open-source MCP server (Streamable HTTP, MCP spec 2025-11-25) that lets a small online store owner run their shop by voice through Alexa+. It connects to a real Shopify or WooCommerce store, uses Amazon Bedrock for intelligence, and protects every write action with a confirmation step and an audit log.

Ask things like:

• "How did my store do today?"

• "What is running low?"

• "Ship order 1042 with TCS."

• "Draft a restock message to my hoodie supplier."

Status: early build. The MCP server, tool layer, adapters, and safety layer are being built in stages. Any capability described here is only claimed once it exists in code and is tested.

Try it in 60 seconds

A public demo endpoint and simulator link will be published here once deployed (see Hackathon). Until then, run it locally and open the simulator:

git clone <repo-url> && cd storefront-voice-ops
npm install
cp .env.example .env
npm run dev      # simulator: http://localhost:3000   MCP endpoint: /mcp

The simulator is a three-pane web app: talk (typing or the microphone), watch the store state, and inspect every tool call. It reaches the MCP server over the real protocol.

Related MCP server: ai.studio/etsy-gold

Hackathon

• Track: Alexa+

• Mini challenges: AWS Builder, Open Source

• Proof that the track technology is really used in code:

  • MCP server entry point: src/server.ts

  • Tool registration: src/mcp/ (tools/resources/prompts)

  • Bedrock integration: src/ai/bedrock.ts

  • Reusable adapter package: packages/store-adapters/ (@voice-ops/store-adapters) — the StoreAdapter contract, mock, Shopify (Admin GraphQL), and WooCommerce (REST v3) adapters ship as a standalone, publishable npm workspace with its own README and the shared defineAdapterContract test suite.

Architecture

Alexa+ (or the built-in simulator)
      |  MCP over Streamable HTTP — POST /mcp  (stateful sessions)
      v
Storefront Voice Ops MCP server (Node + TypeScript)
  - tools / resources / prompts (Zod-validated)
  - safety: auth, origin check, rate limit, confirmation, audit
  - StoreAdapter interface
      |-- MockAdapter      (deterministic demo + tests)
      |-- ShopifyAdapter   (GraphQL Admin API)
      |-- WooCommerceAdapter (REST v3)
  - Amazon Bedrock (Converse API) for briefings, drafting, and the agent loop
      |
  SQLite (local) / DynamoDB (cloud) for pending actions and the audit log

Tools

18 tools, 3 resources, and 3 prompts are documented in docs/tool-reference.md.

Safety design

• Read tools answer instantly.

• Write tools are confirmation-gated: the first call returns a pending action; only confirm_action executes it, and the action expires after CONFIRM_TTL_SECONDS.

• Destructive or large-impact actions (cancel_order, a stock change of 50+ units) also require a spoken code, so a misheard "yes" alone cannot fire them.

• Confirmations are keyed per MCP session, so a "yes" in one session never runs another's action.

• Every write is recorded in the audit log (who, what, and the outcome).

• All inputs are validated with Zod; model output and tool arguments are treated as untrusted.

• Store data (product names, notes) is data, never instructions.

Run locally

npm install
cp .env.example .env
npm run dev          # start the server (http://localhost:3000)
npm test             # unit + contract tests (Vitest)
npm run test:smoke   # MCP client smoke test against a running server
npm run test:e2e     # simulator end-to-end tests (Playwright)
npm run eval         # AI eval set (offline; USE_BEDROCK=1 to run against the model)
npm run typecheck    # TypeScript
npm run lint         # ESLint

Environment variables

See .env.example for the full list. Never commit a real .env.

To point the server at a real store, set STORE_PROVIDER=shopify (with SHOPIFY_STORE_DOMAIN, SHOPIFY_ADMIN_TOKEN) or STORE_PROVIDER=woocommerce (with WOO_BASE_URL, WOO_KEY, WOO_SECRET). Both adapters map onto the same tool surface — no tool or prompt changes — and every upstream failure is turned into a typed error (NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, UPSTREAM) that the safety layer renders as a spoken, human reply.

Connecting Alexa+

Connection details are recorded in docs/alexa-plus-notes.md, including confirmed facts from the Amazon Developer documentation and any open questions. The project also ships a simulator web app so there is always a working link to demo.

AWS services used

Documented in docs/aws-usage.md as they are added.

What was built during the hackathon

The repository was created inside the submission window. The starting point was a small scaffold (7 tools on mock data, a Bedrock briefing helper, and a smoke test); everything else is being built during the event. See STATUS.md and the git history.

License

MIT — see LICENSE. Contributions welcome, see CONTRIBUTING.md.