Sahayak

A voice-first money coach for first-time borrowers, built as an Alexa+ add-on (MCP server).

Sahayak means "helper" in Hindi. Many people sign loans they don't fully understand: "12% flat" sounds like 12%, fees are taken before the cash arrives, and the monthly payment is the only number anyone mentions. Sahayak explains what a loan really costs, in plain spoken language, checks whether the payment is realistic, and keeps track of loans and repayments across conversations.

Built for the Amazon Developer Hackathon 2026, Alexa+ track.

Sahayak gives financial education, not regulated financial advice. It never recommends specific lenders or investments.

Try it

No accounts, API keys or hardware needed. Python 3.11+ (developed on 3.14).

git clone https://github.com/shreesh1802/Sahayak.git
cd Sahayak
python -m venv .venv
.venv/Scripts/activate        # Windows; on macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python run_demo.py

run_demo.py starts the MCP server and the Alexa+ simulator, then opens http://127.0.0.1:8080. Click Review an offer, answer the two follow-up questions ("flat", then "my income is 25000 and expenses 14000"), and open Behind the scenes to see the real MCP calls. Press Ctrl+C to stop both.

• python run_demo.py --fresh first deletes the saved demo data, so you start from an empty state.

• python run_demo.py --no-browser doesn't open a window; --port and --web-port change the ports.

• Voice input uses your browser's speech recognition (Chrome or Edge); typing and the buttons always work.

Related MCP server: expense-tracker-mcp-server

What it does

How it works

 Alexa+ (MCP client)  ──Streamable HTTP──▶  Sahayak MCP server
   language, speech,        spec 2025-11-25      tools · resources · elicitation
   hosts the MCP App screen                             │
                                                        ▼
                                          core/ loan maths · SQLite memory

• server/mcp_server.py is the Alexa+ add-on: 8 tools, 2 resources (the user's loans, and the on-screen card), and elicitation for missing details.

• server/ui/card.html is the MCP App view: the on-screen card, served by the server as the ui://sahayak/card resource (text/html;profile=mcp-app) and linked from every tool through _meta.ui.resourceUri. A host renders it in a sandboxed iframe and sends it each tool result over postMessage. The view has no network access and escapes all text it displays. A host without MCP Apps support just shows the tool's text answer.

• agents/pipeline.py is the multi-agent layer behind one tool, review_loan_offer ("should I take this loan?"). Alexa+ makes a single call; behind it a supervisor plans and re-plans which specialists to run: a loan analyst (true cost), an affordability agent (skipped if the budget is unknown), and a coach (questions to ask the lender and a lesson chosen from the findings). A verifier then checks that every number in the spoken answer traces to the calculator, rejecting and replacing any draft that does not.

• core/loan.py does all the maths deterministically (flat vs reducing interest, fees, true yearly rate via IRR, affordability). Every number that is spoken comes from this calculator; no language model touches the figures.

• core/store.py is the memory (SQLite): budget, loans, repayments and lesson progress persist across sessions.

• web/ is a simulated Alexa+ experience: voice input, spoken replies and an Echo Show–style screen. It acts as an MCP client and as an MCP Apps host: it reads each tool's _meta.ui.resourceUri, fetches the view from the server, mounts it in a sandboxed iframe (allow-scripts only, so the view cannot reach the page) and runs the host side of the handshake (ui/initialize, ui/notifications/initialized, then tool-input and tool-result). The "Behind the scenes" panel shows every message. The host is my own implementation of the subset of the protocol this app needs; it is not Amazon's.

• agents/router.py is a rule-based intent router standing in for Alexa+'s own language understanding.

Running the pieces yourself

run_demo.py is a convenience; the two servers are ordinary processes. In two terminals:

python -m server.mcp_server   # MCP server on http://127.0.0.1:8000/mcp
python -m web.app             # simulator on  http://127.0.0.1:8080

mcp<2 in requirements.txt is deliberate: mcp 2.x renamed FastMCP and changed other APIs. See docs/FRICTION_LOG.md.

Tests

python -m pytest                 # 118 unit tests: loan maths, router, agents, verifier, MCP App contract, theme, hardening, launcher
python -m eval.smoke http://127.0.0.1:8000/mcp   # 26 end-to-end checks against a running server

The end-to-end check also verifies the Alexa+ latency budget (under 500 ms; typically 9 to 60 ms per tool call here), the declared screens, that every result carries structuredContent (what the MCP App card reads), input validation, and the multi-agent review. A theme test keeps every text and background colour pair above WCAG contrast. Use 127.0.0.1, not localhost, on Windows: localhost added about 280 ms per connection in testing.

Public URL

To reach the server from the internet (a tunnel, an access token, and the allowed-host setting the MCP SDK needs), see docs/HOSTING.md. It also explains why that is a protected demo endpoint and not real Alexa+ account linking.

Honest limitations

• The agents are not LLM-driven. The supervisor's planner, the specialists and the composer are rule-based code; what is real is the orchestration (planning and re-planning, chained steps, skipping a step when data is missing) and the verifier guard. They sit behind plain function interfaces so a model-backed planner or composer could replace them, and the verifier would still re-check every figure. No model has been run against this: an attempt to enable Amazon Bedrock on a new account failed (see the friction log).

• Not connected to real Alexa+. It was tested with the included simulator, not Amazon's simulator or a device. In particular the MCP App view has only run in my own host. I built it from the MCP Apps spec (2026-01-26), which has internal inconsistencies (for example its transport snippet sends initialize with capabilities, while the text and the SDK's types specify ui/initialize with appInfo and appCapabilities; the view follows the SDK types). I have checked its messages against those types, but I have not run it against Amazon's host.

• No capability negotiation for MCP Apps. The spec says hosts advertise io.modelcontextprotocol/ui and servers should register UI tools only when it is present. The Python MCP SDK (1.x) has no way for a client to send it, so the server always declares the screen and relies on the text fallback for hosts that ignore it.

• Authentication is a demo user. In production the user id comes from the OAuth access token Alexa+ sends on every request (the Alexa+ MCP Toolkit requires OAuth 2.1 with PKCE).

• Affordability thresholds (loan payments above 40% of income, under a 10% cushion) are stated rules of thumb, not credit advice.

• English only, and voice accuracy depends on the browser's speech recognition: a mis-heard amount (for example "8" for "8,000") is queried back ("did you mean 8,000?") rather than guessed.

Project layout

run_demo.py   one-command launcher for the whole demo
server/       the MCP server (tools, resources, elicitation) and server/ui/card.html, the MCP App view
core/         loan maths, memory, narration, lessons
agents/       intent router and the multi-agent pipeline (supervisor, specialists, verifier)
web/          the simulated Alexa+ experience and MCP Apps host
eval/         end-to-end smoke test
tests/        unit tests
docs/         friction log and the public-URL guide

Feedback on the tooling

Notes on onboarding and friction, written as they happened, are in docs/FRICTION_LOG.md.

Licence

MIT. See LICENSE.