FirstFix MCP: Multimodal Serial-Variant Part Matcher & Stocked-Van Dispatch Engine

Amazon Developer Hackathon 2026 Entry
Primary Track: Alexa+
Secondary Track: Ring
Mini Challenges: AWS Builder Challenge ($5,000 + $5,000 AWS Credits) & Open Source Challenge ($5,000 + $5,000 AWS Credits)
Bonus Submission: Official Rules Section 6 (+10% Friction Log Judging Bonus in docs/FRICTION_LOGS_10_PERCENT_BONUS.md)
Live Public AWS Production Endpoint: https://qe2khmjs7zmipvuuk2ailnsq340lfhrg.lambda-url.us-east-1.on.aws/

🚀 30-SECOND JUDGE QUICK-START (LIVE CLOUD DEMO)

Judges can test the fully deployed system immediately over public HTTPS with zero local installation:

Instant curl Verification Commands:

# 1. Query the live MCP server for all 5 registered tools
curl -X POST https://qe2khmjs7zmipvuuk2ailnsq340lfhrg.lambda-url.us-east-1.on.aws/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"judge-list-test","method":"tools/list"}'

# 2. Execute deterministic serial-variant BOM diagnosis (Carrier AC 24ACC636 -> CARRIER-HC98JA045D Capacitor)
curl -X POST https://qe2khmjs7zmipvuuk2ailnsq340lfhrg.lambda-url.us-east-1.on.aws/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id":"judge-carrier-diag",
    "method": "tools/call",
    "params": {
      "name": "diagnose_equipment_and_bom",
      "arguments": {
        "brand": "Carrier",
        "modelNumber": "24ACC636A003",
        "serialNumber": "2023W19482",
        "errorCode": "E4"
      }
    }
  }'

# 3. Query live Amazon DynamoDB (FirstFixMcpState) records in us-east-1
curl https://qe2khmjs7zmipvuuk2ailnsq340lfhrg.lambda-url.us-east-1.on.aws/api/aws/dynamo-records

# 4. Query live B2B contractor FSM webhook dispatches (ServiceTitan / Jobber)
curl https://qe2khmjs7zmipvuuk2ailnsq340lfhrg.lambda-url.us-east-1.on.aws/v1/fsm/dispatches

Related MCP server: AutoRev MCP Server

🎯 THE $150–$180 "SECOND TRUCK ROLL" PROBLEM

In residential trade services (HVAC, plumbing, and major appliance repair), over 37% of service calls fail on the first visit. The root cause is almost always the same:

1. A homeowner calls a repair service because their dishwasher won't drain or their water heater shut down.

2. The dispatcher books whatever contractor is available on the calendar.

3. The technician drives across town, opens the appliance, and discovers that the manufacturer changed part engineering mid-production (e.g. Bosch moving from an AC twist-lock pump to a brushless DC pump in batch FD99).

4. The technician does not have the updated part on their van. They charge a trip fee, order the part, and schedule a second visit 7 days later.

5. The Cost: The unstocked "second truck roll" costs the contractor $150 to $180 in wasted labor, fuel, and scheduling capacity, while leaving the homeowner stranded without essential appliances.

FirstFix MCP solves this natively inside Alexa+ and Ring:
AI handles multimodal vision (reading rating-plate photos) and conversational guidance, while 100% of OEM part numbers, serial runs, pricing, and safety halts come strictly from our deterministic engine. Alexa+ only dispatches contractors who physically have the required OEM part on their van today.

🔬 SERIAL-VARIANT DISAMBIGUATION: WHY DETERMINISTIC CODE MATTERS

LLMs frequently hallucinate mechanical part numbers or confuse revision numbers. FirstFix enforces a strict rule: Zero AI Guesswork on Physical Parts.

🏛️ SYSTEM ARCHITECTURE & AWS CLOUD TOPOLOGY

FirstFix MCP is deployed live to AWS us-east-1 with 100% serverless, zero-idle-cost infrastructure:

flowchart TD
    subgraph ClientLayer["Echo Show 15 & Alexa+ Clients"]
        ES15["Echo Show 15 Multimodal Display (1080p)"]
        Voice["Alexa+ Voice Host (Streaming Audio)"]
        Camera["Rating Plate Image Upload (JPEG/PNG)"]
    end

    subgraph AWSCloud["AWS us-east-1 Cloud Infrastructure"]
        LambdaUrl["AWS Lambda Function URL (Public HTTPS Auth: NONE)<br/>https://qe2khmjs7zmipvuuk2ailnsq340lfhrg.lambda-url.us-east-1.on.aws"]
        
        subgraph ServerlessCompute["AWS Lambda (nodejs20.x, 512MB, 30s)"]
            Handler["Express HTTP Bridge (src/aws/lambdaHandler.ts)"]
            MCPEngine["MCP 2025-11-25 Streamable HTTP Server (POST /mcp)"]
            UCPEngine["Universal Commerce Protocol (2026-01-11 Checkout)"]
            BookingEngine["Alexa+ Local Booking SPI (com.amazon.alexa.localbooking.v1)"]
            RingController["Ring Smart Access Controller (Arrival Windows)"]
            DeterministicBOM["Deterministic OEM BOM Engine (Zero Hallucination)"]
        end

        subgraph ManagedServices["AWS Managed Cloud Services"]
            Bedrock["Amazon Bedrock Nova Pro<br/>us.amazon.nova-pro-v1:0 (Rating-Plate Vision)"]
            DynamoDB["Amazon DynamoDB<br/>FirstFixMcpState (PAY_PER_REQUEST)"]
        end
    end

    Camera -->|Upload Image| Handler
    Voice -->|Voice Intent| MCPEngine
    ES15 -->|Render UI Apps| Handler

    Handler --> MCPEngine
    Handler --> UCPEngine
    Handler --> BookingEngine
    Handler --> RingController

    MCPEngine --> DeterministicBOM
    Handler -->|Async Perception| Bedrock
    DeterministicBOM -->|State Sync & Audit| DynamoDB

📦 OPEN SOURCE MINI CHALLENGE DELIVERABLES

To maximize community impact, FirstFix MCP delivers two standalone open-source contributions:

1. Standalone SDK: packages/alexa-plus-ucp-mcp-kit

An MIT-licensed, zero-dependency TypeScript toolkit that solves the top 5 protocol integration friction points:

• normalizeMcpStreamableHeaders(): Normalizes Accept headers to prevent HTTP 406 rejections from stateless clients.

• createUcpIdempotencyStore(ttlMs): 24-hour RFC-compliant Idempotency-Key store with SHA-256 payload fingerprinting and automatic HTTP 409 Conflict detection on mutated bodies.

• buildUcpEnvelope(params): Generates compliant dev.ucp.shopping.checkout (2026-01-11) envelopes for /checkout-sessions, /complete, and /cancel.

• createCorrelationTokenBridge(): Generates and verifies HMAC-SHA256 cryptographically linked correlationToken values binding UCP sessions to Local Booking SPI appointments and Ring access passes.

• buildMcpAppPostMessageScript(): Generates the client-side JSON-RPC 2.0 window.parent.postMessage bridge (ui/initialize, ui/message, ui/update-context) for text/html;profile=mcp-app visual cards.

• validateAddonImageDimensions(): Validates PNG IHDR binary headers to prevent store submission rejection.

👉 Explore the SDK: packages/alexa-plus-ucp-mcp-kit/README.md

2. Community Agent Skill: AmazonAppDev/devices-agent-skills

A ready-to-merge contribution bundle for https://github.com/AmazonAppDev/devices-agent-skills:

• Standard agentskills.io compliant instructions teaching AI coding assistants (Claude Code, Cursor, Antigravity) how to build Alexa+ Add-Ons and UCP servers without friction.

• Complete pull request template ready for submission.

👉 View Contribution Bundle: open-source-contribution/devices-agent-skills/

📑 HACKATHON DOCUMENTATION SUITE

All official submission materials and judging bonus documents are organized in docs/:

1. Friction Logs (+10% Bonus): 8 structured friction logs covering MCP headers, Express streams, Bedrock latency, UCP envelopes, and Lambda URL policies.

2. 5-Part Product Feedback: Comprehensive feedback for Amazon teams across Alexa+ Add-Ons, MCP Apps, UCP, Local Booking SPI, and Bedrock.

3. Demo Video Script & Shot List: Timed, 2:45 scene-by-scene script and screen-recording runbook.

4. Devpost Submission Master: Ready-to-paste Devpost text for all form fields.

🧪 AUTOMATED TEST SUITE (60/60 TESTS PASSING)

FirstFix MCP maintains strict test-driven development across all 6 project sprints:

# Run all 60 tests across Sprints 1–6
npm test

🛠️ LOCAL DEVELOPMENT RUNBOOK

Prerequisites

• Node.js v18+ (tested on Node.js v24.15.0)

• npm v9+ (tested on npm v11.12.1)

• AWS Account with Bedrock Nova Pro access (for live AI features)

1. Clone & Install

git clone https://github.com/hsalman-saeed/firstfix-mcp-alexa-plus.git
cd firstfix-mcp-alexa-plus
npm install --legacy-peer-deps

2. Configure Environment

cp .env.example .env
# Edit .env with your AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION=us-east-1

3. Start Local Development Server

npm start
# Server opens at http://localhost:3001

4. Deploy Live to AWS (1-Command Automation)

npm run deploy:aws
# Automatically bundles Lambda handler, provisions DynamoDB table, updates IAM roles,
# and configures the public HTTPS Function URL in us-east-1!

📄 LICENSE

This project is open-source software licensed under the MIT License.