# Latchbook

**From “the washer is leaking again” to a cited, approval-first service brief.**

Latchbook is a local, voice-first home service agent built for the Alexa+ track of the 2026 Amazon Developer Hackathon. It has a real Model Context Protocol (MCP) Streamable HTTP endpoint implementing protocol version `2025-11-25`, plus an independent web simulator that shows the same tool workflow. It does **not** claim to be a deployed Alexa+ add-on or to use gated Alexa+ developer tools.

The agent asks a symptom-specific follow-up when a report is incomplete, identifies the appliance, retrieves home records and earlier service outcomes, checks the recorded warranty date, audits evidence quality, and drafts a service case. A human must explicitly approve before the brief is marked shareable. Nothing is sent, booked, purchased, or changed outside this local application.

## Why this is more than Q&A

The product addresses the messy moment *before* service: people repeat a problem without the model number, prior incident, manual warning, or warranty context. A generic chatbot can answer a question; Latchbook keeps a persistent local repair history and turns a spoken observation into a sourced, reviewable handoff.

The simulator's natural-language router is intentionally narrow and deterministic—no paid model or hidden cloud service. The actual Alexa+-track integration is the MCP server, whose tools can be discovered and invoked by a compatible MCP client. The simulator demonstrates the intended voice + visual experience without pretending to be the restricted Alexa+ preview toolkit.

## At a glance

| Capability | Implementation |
|---|---|
| Alexa+ track technology | Self-hosted MCP Streamable HTTP endpoint using protocol `2025-11-25` |
| Agent workflow | Adaptive incident interview, source retrieval, evidence audit, and persistent draft |
| Available tools | Twelve discoverable MCP tools with JSON Schema inputs and structured output |
| Memory | Persistent interviews, records, case outcomes, approval state, and event history |
| Provenance | Every new case carries record IDs, an evidence assessment, related-case IDs, and a visible tool trail |
| Human control | Speech or text cannot approve a case; the export route also enforces approval |
| Cost | No API key, runtime dependency, account, cloud service, or physical device |
| Verification | Thirteen automated protocol, security, persistence, and workflow tests |

## How the workflow fits together

```mermaid
flowchart LR
    A[Voice or typed observation] --> B{Enough detail?}
    B -->|No| C[Ask one targeted follow-up]
    B -->|Yes| D[Retrieve local records and prior outcomes]
    C --> D
    D --> E[Check warranty and evidence quality]
    E --> F[Draft cited service case]
    F --> G{Human review}
    G -->|Approve| H[Copyable service brief]
    G -->|Do not approve| I[Draft remains local]
    H --> J[Household records outcome after resolution]
    J --> D
```

This is deliberately a handoff workflow rather than an automated repair or marketplace flow. The agent compiles what the household knows, preserves uncertainty, and stops at the point where a person should decide what happens next.

## Tool catalogue

| Tool | Purpose | Effect |
|---|---|---|
| `find_appliance` | Resolve a household appliance by name, kind, or model | Read only |
| `search_home_records` | Retrieve relevant manual, warranty, incident, and user-note evidence | Read only |
| `check_warranty` | Compare today with the locally recorded warranty end date | Read only; never decides coverage |
| `list_service_cases` | Read persistent draft, approved, and closed cases | Read only |
| `get_active_incident_intake` | Recover an unfinished incident interview | Read only |
| `start_incident_intake` | Save the first report and ask a symptom-specific follow-up | Local state only |
| `answer_incident_intake` | Record the household's follow-up observation | Local state only |
| `assess_evidence` | Flag missing context, stale records, and conflicting warranty notes | Read only; never diagnoses |
| `draft_service_case` | Create a case using an observed symptom and valid record IDs | Local state only |
| `approve_service_case` | Mark a reviewed draft ready to copy | Requires explicit human confirmation |
| `close_service_case` | Save a household-reported outcome as a citable record | Requires explicit human confirmation |
| `add_home_record` | Add a user-provided plain-text note for later retrieval | Local state only |

## Why the approval boundary matters

Latchbook deals with information that can affect safety, service costs, and warranty expectations. It therefore separates three kinds of information:

- **Observed:** what the person says happened.
- **Recorded:** what a local manual excerpt, note, date, or prior incident says.
- **Verified:** what a qualified provider would still need to confirm.

The agent never converts recorded information into a diagnosis or coverage promise. It cannot approve a case from a spoken phrase, and the server refuses to export a draft even if someone bypasses the visible interface.

## Run at zero software cost

Requires Node.js 22 or newer. No `npm install` is necessary because the application has no runtime dependencies.

```bash
npm start
```

Open <http://127.0.0.1:8787>. The server binds to localhost only. Typed input works in every modern browser; voice input uses the browser's Speech Recognition API when available. All sample appliance names and documents are fictional. You can paste a user-owned plain-text note to demonstrate live retrieval beyond the seed records.

```bash
npm test
```

The tests verify MCP initialization, tool discovery and invocation, strict local-origin/version handling, the incident interview, evidence checks, outcome learning, persistence, citations, warranty caveats, approval gating, and user-added record retrieval.

### Test coverage

The suite exercises the real HTTP server and isolated temporary data stores. It verifies:

- MCP `2025-11-25` negotiation, initialization notification, tool discovery, and tool calls.
- Local `Host`, `Origin`, content type, `Accept`, and protocol-version enforcement.
- The same persistent workflow through the simulator API.
- Two-turn orchestration with cited evidence and an evidence assessment.
- Approval-gated export and protection against double approval.
- Warranty-date caveats without coverage promises.
- Retrieval of newly added user records.
- Cross-turn case memory and explicit reset behavior.
- Duplicate-draft prevention for repeated reports.
- Reuse of a household-reported service outcome in a later recurring case.
- Detection of conflicting and stale warranty notes.
- Refusal of external booking/contact requests without state mutation.
- Rejection of evidence belonging to a different appliance.

## MCP connection

- Endpoint: `http://127.0.0.1:8787/mcp`
- Transport: Streamable HTTP, JSON-RPC 2.0, JSON response mode (no SSE stream)
- Protocol version: `2025-11-25`
- State: stateless MCP transport; household case data persists in `data/home.json`
- Supported methods: `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`
- Tools: all twelve entries in the catalogue above; use the in-app live MCP inspector to verify the endpoint's actual `initialize` → `notifications/initialized` → `tools/list` → `tools/call` exchange.

The server requires both `application/json` and `text/event-stream` in the MCP POST `Accept` header, accepts the protocol-version header after initialization, returns 202 for the initialized notification, and returns 405 for GET because it does not offer SSE. It validates local `Host` and `Origin` headers; it is **not** a publicly hosted multi-user service.

## Reliability and local security

- The HTTP server binds to `127.0.0.1` rather than all network interfaces.
- Local host and same-origin checks reduce cross-origin and DNS-rebinding risk.
- Requests are JSON-only and capped at 32 KB.
- Static responses include a restrictive Content Security Policy, no-referrer policy, and MIME sniffing protection.
- Store mutations are serialized, written to a temporary file, and atomically renamed.
- Runtime household data and environment files are excluded from Git.
- Sample appliances, documents, incidents, and dates are explicitly fictional.

See [architecture](docs/ARCHITECTURE.md) for the trust boundary and [hackathon audit](docs/HACKATHON_AUDIT.md) for exact submission requirements.

## Demo path

1. Choose **The washer is leaking again**. Answer the targeted follow-up with a location and timing detail, or use the sample answer.
2. Inspect the cited manual, warranty note, prior incident, evidence-quality signals, and actual tool trail. Ask **What is the washer case status?** to prove memory across turns.
3. Click **Review & approve brief**, enter the approver's name, and copy the brief. Nothing is sent externally.
4. Mark the case resolved with a household-reported outcome. Report a similar leak again and see the earlier outcome cited and linked as a prior case.
5. Run the **live MCP check** to show protocol negotiation, twelve discoverable tools, and a real tool call. Optionally add a plain-text home note to show live retrieval.

## Repository map

```text
src/seed.mjs        Fictional demo appliances and records
src/store.mjs       Atomic local JSON persistence
src/evidence.mjs    Evidence integrity checks and provenance signals
src/tools.mjs       The twelve domain/MCP tools
src/agent.mjs       Adaptive simulator orchestrator and brief builder
src/mcp.mjs         MCP 2025-11-25 JSON-RPC lifecycle and tool dispatch
server.mjs          Local HTTP app, simulator routes, and /mcp endpoint
public/             Responsive voice/text/visual simulator
test/               Protocol and workflow tests
```

## Boundaries and next steps

- This prototype does not ingest PDFs or run OCR; user-added records are plain text only.
- Warranty status is a comparison with a stored date, **not** an actual coverage determination.
- Manual excerpts are fictional; they are not real manufacturer instructions or a substitute for a qualified professional.
- The browser speech API is optional and browser-dependent. The typed path is fully functional.
- No contractor marketplace, calendar, email, or Alexa production account is connected. The brief is for a human to review and share.
- A production version would need authentication, household isolation, encryption, consent controls, real integrations, and provider verification before remote hosting.

## License

MIT © 2026 Rehan Raza