# SevaRelay

**The next shift, without the guesswork.**

A local-only service-desk handover prototype: find the cases waiting on evidence, inspect why, preview an English or Hindi desk note, and explicitly confirm what the next operator should see.

> **Alexa+ simulation · Synthetic demo data · No live payments.** This is not an Amazon product or an actual Alexa+ connection. AI assistants helped build the prototype; the running application uses deterministic rules, not an LLM. Every case, person, place, checklist and service record is fictional.

## Run in under a minute

Requires **Node.js 22 or newer** and a modern desktop/mobile browser. Tested with Node 24.19.0. No npm dependencies, keys, accounts, cloud services, installs, or build step are required.

```sh
cd seva-relay
npm start
```

Open **http://127.0.0.1:4173**. Use `PORT=4174 npm start` if that port is occupied. The server always binds to `127.0.0.1`; it cannot be exposed by setting a host environment variable. Stop with `Ctrl+C`.

```sh
npm test    # Domain, client-logic and actual HTTP protocol/security tests
npm run check
npm run smoke  # Full real MCP handshake → preview → confirm → handover over loopback HTTP
```

No `npm install` is needed. The UI must be served by this server, not opened using `file://` or a generic static preview: it makes actual MCP requests.

Verified on 21 October 2026: **57 automated tests**, the real MCP smoke workflow, and a fresh independent browser check of preview/cancel/confirm, Hindi output, filters, handover, reset and interrupted-server recovery. Forced async races are covered by deterministic client/HTTP tests; no new mobile-layout or screen-reader sweep was performed. See the [verification record](docs/TESTING.md) for exact scope.

## Try the useful workflow

1. Read the six-case queue and choose **C-1042 / Meera**.
2. Inspect the evidence: a request reference exists, but the **receipt copy is missing**. No transaction outcome is inferred.
3. Choose a draft language and preview the **receipt-copy follow-up**.
4. Cancel once: the local action count must stay unchanged. Preview again and explicitly confirm.
5. The action count increases; the receipt **stays pending**. Nothing was sent.
6. Open **C-1051 / Sana** and confirm readiness for the local handover.
7. Generate the shift handover. It separates unresolved evidence from recorded desk notes and ready cases.
8. Expand the protocol trace to inspect the real initialization, tool discovery and tool calls.

The text box supports a small documented set of deterministic shortcuts. It is not an open-ended natural-language assistant. Unrecognized instructions do not cause a tool action. The language setting changes drafts/handover text, not the entire interface; original checklist labels remain in English for traceability.

## What is real, and what is simulated?

| Component | Status |
|---|---|
| JSON-RPC lifecycle, tool discovery and tool execution | Real MCP requests over local Streamable HTTP |
| Queue, evidence, preview, human-confirmed desk log | Working application logic |
| Isolation, duplicate-safe confirmation, stale/expired preview protection | Working and tested |
| Alexa+ interaction | Clearly labeled web simulation; no Amazon backend |
| AI at runtime | None; deterministic intent routing and templates |
| People, services, receipts, document requirements | Fictional fixtures, not operational or regulatory advice |
| Customer contact, payments, bookings, official submissions | Not implemented; never performed |
| Persistence | Session memory only; not a production database |

## MCP interface

**Protocol:** `2025-11-25` · **Endpoint:** `http://127.0.0.1:4173/mcp`

The browser is an actual MCP client:

1. `initialize` with its supported version, capabilities and client info.
2. Capture the returned `Mcp-Session-Id`.
3. Send `notifications/initialized` (HTTP 202, empty body).
4. Call `tools/list`, then `tools/call` using the session and `MCP-Protocol-Version` headers.

POST requests send `Accept: application/json, text/event-stream`. This server selects JSON responses, a valid Streamable HTTP mode. `GET /mcp` returns 405 because no standalone SSE stream is offered. `DELETE /mcp` closes a session. No batch JSON-RPC, resources, prompts, subscriptions, sampling, or task-augmented tools are advertised.

| Tool | Purpose | Changes |
|---|---|---|
| `get_desk_snapshot` | Queue, metrics, local event log | None |
| `get_case_brief` | Checklist, evidence, recommended action | None |
| `draft_next_action` | Create a five-minute English/Hindi preview | Temporary preview only |
| `confirm_next_action` | Record an explicitly reviewed preview | Current synthetic session only |
| `get_handover_brief` | Evidence-based shift handover | None |

Every tool has a bounded input schema with no extra properties. Results include JSON-compatible `structuredContent` and matching text content. Unknown methods/tools produce protocol errors; tool-input and domain failures use `isError: true`.

See [architecture](docs/ARCHITECTURE.md), [security and limitations](docs/SECURITY.md), and the [verification record](docs/TESTING.md).

## Reset and data lifecycle

Each browser page starts an independent synthetic desk. Refresh starts a fresh session; reconnect retries the existing session and can finish an interrupted handshake without discarding notes. It offers a fresh start only when the server confirms that the old session is missing or expired; a transient connection failure leaves it available for another retry. **Reset demo** explicitly discards the current session. A process restart discards all sessions. Idle sessions expire after 30 minutes. Confirmed-action receipts remain retryable for the session's lifetime, even after their original preview deadline. There is no disk data store, analytics, cookies, telemetry, external font, or outbound network call. Do not enter real personal data.

## Competition context and disclosure

Prepared privately as a possible **Build, Ship, Shape: Amazon Developer Hackathon / Alexa+** simulated-experience entry. The organizer allows custom, text-based deterministic simulations built with AI tools; the official FAQ permits a self-hosted MCP service with a custom front end. This prototype goes beyond a static mockup by implementing the protocol and working state transitions. It does **not** claim acceptance, certification, real Alexa integration, customer adoption, prize eligibility, measured impact, AWS usage, or Kiro usage. [Organizer clarification](https://amazonappdev2026.devpost.com/forum_topics/45058-clarification-on-simulated-alexa-web-experience-requirements), [FAQ](https://amazonappdev2026.devpost.com/details/faqs).

## License and publication status

This new SevaRelay prototype source includes the entrant-approved [MIT License](LICENSE), copyright 2026 Atul Bhat, using the [standard MIT text](https://opensource.org/license/mit). No existing DuePe code or private customer data is included. The MIT source license does not imply rights to Amazon/Alexa trademarks or other third-party material.

Public source repository: [sturomark/seva-relay](https://github.com/sturomark/seva-relay). This repository publishes the new prototype source, tests, technical documentation and MIT license. Source publication does not establish a hosted service, a public demo-video link, eligibility, or a submitted contest entry; those remain separate verification steps.