Convoy Watch · Alexa+ Fleet Intelligence

Autonomous, approval-gated commercial trip watcher powered by a self-hosted Streamable HTTP MCP server and Alexa+ voice simulation. Built for the Build, Ship, Shape: Amazon Developer Hackathon (Alexa+ Track).

3-Command Quickstart

# 1. Install dependencies
npm install

# 2. Compile packages, web client, and Node 22 server
npm run build

# 3. Launch unified server (Streamable HTTP MCP, REST simulation, and SPA on port 3000)
npm start

Open http://localhost:3000 to interact with the simulated Echo Show 15 dashboard.

Related MCP server: SHIFT//RELAY

Hackathon Judge Key Instructions

For convenience during hackathon judging and evaluation:

• Judge API Key: judge-alexa-plus-demo-key-2026-v1

• Configure custom supervisor keys via API_SECRET_KEY in your environment (minimum 32 characters in production mode).

• The judge key can be passed via:

  • Header: Authorization: Bearer judge-alexa-plus-demo-key-2026-v1

  • Header: X-API-Key: judge-alexa-plus-demo-key-2026-v1

  • Query parameter: ?apiKey=judge-alexa-plus-demo-key-2026-v1

Testing & Conformance Verification

Convoy Watch ships with 10 comprehensive test suites, covering unit logic, contract tests, security authorization, and real mutation verification:

npm test

Verified Test Suites:

1. @convoy/mcp-provenance Unit Tests: Plate redaction, Uganda bounding box, speed ceilings, haversine teleportation gap check, sequence deduplication, dead-reckoning decay, and confidence blending.

2. MCP Tool Contracts: Zod validation across all 5 tools (start_trip_watch, get_trip_status, list_reroute_options, approve_action, stop_trip_watch).

3. Trip Lifecycle & CAS Persistence: Monotonic versioning, atomic compare-and-set writes, and survival across store restarts.

4. Approval Gate & No-GPS Honesty: Outbound actions held until human authorization; zero-hallucination when telemetry signal drops.

5. Security & Route Auth: Programmatic check verifying that every /mcp and /api/* route rejects missing (401) and invalid (403) keys, while keeping /health public.

6. Cryptographic Audit Trail: SHA-256 hash chaining ($H_i = \text{SHA256}(H_{i-1} \parallel \dots)$) with automated tamper detection.

7. Job Queue & DLQ: Exponential backoff, idempotent execution, and Dead-Letter Queue routing.

8. Dual-Engine NLU & Fallback: Gemini 3.8 Flash function calling with circuit breaker and deterministic rule fallback parser.

9. MCP Protocol Conformance: Real @modelcontextprotocol/sdk Client connecting to POST /mcp over Streamable HTTP at runtime.

10. 3-Fix Real Mutation Verification: Reverts fixes in source code, demonstrates test failure, and restores code cleanly.

Architecture Overview

[Echo Show Voice / Web Console]
               │  JSON-RPC 2.0 (Streamable HTTP)
               ▼
[Single Express Process: POST /mcp · /api/* · React SPA]
               │
        [Security Guard] (API Key Auth, Rate Limiter, Headers)
               │
      [Domain Watcher Core] ──── [Dual NLU Router (Gemini + Rule Fallback)]
               │
      [Human Approval Gate] (approve_action blocks outbound dispatches)
       ├── StateStore (CAS Optimistic Concurrency Control)
       ├── Hash-Chained Audit Log (SHA-256 Append-Only JSONL)
       └── Job Queue & DLQ (Exponential Backoff)

Detailed architectural diagrams and scaling strategies are documented in docs/ARCHITECTURE.md.

Workspace Library: @convoy/mcp-provenance

An independent zero-dependency package located in packages/mcp-provenance:

• Ugandan Plate Redaction: Sanitizes registration plates (UBB 123X -> UBB ***X).

• GPS Validation Invariants: Strict Uganda geographic boundary (-1.5 to +4.3 Lat, 29.5 to 35.1 Lon), 110 km/h speed ceiling, haversine teleportation gap check ($d \le v_{\max} \cdot \Delta t$), and sequence deduplication.

• Dead-Reckoning Discipline: 90-second maximum cap with linear confidence decay, marking excludeFromAlerts after 45s and returning null beyond 90s to prevent coordinate hallucination.

• Confidence-Weighted Blending: $v = \frac{\sum c_i v_i}{\sum c_i}$ falling back to baseline schedule below minimum sample thresholds.

Test independently:

npm --prefix packages/mcp-provenance test

Submission Documentation

• docs/DEVPOST_DESCRIPTION.md — Official Devpost hackathon submission narrative.

• docs/DEMO_SCRIPT.md — Timed 2:30 video demonstration script.

• docs/PRODUCT_FEEDBACK.md — Real architectural findings and feedback from building with the MCP SDK.

• docs/FRICTION_LOG.md — Unvarnished log of genuine technical friction points resolved.

• docs/ARCHITECTURE.md — Full technical architecture and scaling notes.

License

MIT © 2026 Convoy Watch Authors