Finwisp Home

An Alexa+-style family learning hub: ask about a US company by voice or text and get cards and quizzes built from real SEC filings, served by a self-hosted MCP server. Education only, never advice.

Comment

Inspiration

My family wanted to understand the companies we hear about every day, like Costco, Apple and Nvidia. We did not want stock tips. Most "finance assistants" go straight to "should I buy?". The real filings answer better questions: how a company earns money, how much of its revenue becomes profit, and how much it owes. Alexa+ is moving to MCP-based add-ons, so I wanted to know: what would a safe, family-friendly learning add-on for the kitchen-counter screen look like, built on public SEC data?

What it does

Finwisp Home is a self-hosted MCP server plus a simulated Alexa+ home hub (a web app). You ask by voice or text, for example "COST net margin", "AAPL revenue growth", "WFC gross margin" or "continue where we left off":

  • Real SEC EDGAR data. It finds the company, reads its filings and pulls annual US GAAP facts. It computes metrics such as net margin, revenue growth, operating margin and liabilities-to-assets. Every card shows the SEC accession number it came from.
  • Visible agent steps. A progress rail (Find company → Read filings → Pull numbers → Compute → Make cards → Quiz) and live MCP tool chips show every tool call with its status and duration.
  • Learning cards in plain English, with a multi-year trend chart, e.g. "In FY2026 Costco kept 3.0% of revenue as net income ($9.2B of $303.2B)."
  • Private, shuffled quizzes. Answer keys stay on the server until you submit. Grading explains each answer.
  • Family memory across sessions. It remembers concepts explored, companies followed and missed concepts. "Continue where we left off" builds review cards and a focused three-question re-quiz from the missed concepts.
  • Education-only policy. Questions like "Should I buy Nvidia?", price targets or "will it go up after earnings?" are refused before any tool runs. They are reframed into 3 questions you can check yourself, answered with that company's real filing numbers. There is no trade tool.
  • Bank-aware cards. Banks such as Wells Fargo and JPMorgan do not report gross profit or operating income. Finwisp detects this from the filing data, explains why those margins do not apply, and adds a "Net Interest Share" card instead of saying "insufficient data".
  • Voice. A big "Tap to speak" button uses browser speech recognition. Read-aloud is optional. Text input always works.

The same /mcp endpoint works with other MCP clients. In a recorded run, the OpenAI Codex CLI called lookup_company → get_financials → compute_metrics → make_card over Streamable HTTP and produced the same Costco card (transcript in docs/demo/).

What it is not: it does not run on a real Echo device or inside Alexa+. Per the hackathon FAQ, participants cannot connect a self-hosted MCP server to Alexa+ devices or the developer console (that tooling is for select partners). Finwisp Home therefore uses the simulated-experience path: a web hub whose backend is a real MCP client of the server.

How we built it

  • MCP server: TypeScript on Node 20.19+, using the official MCP TypeScript SDK (@modelcontextprotocol/server and @modelcontextprotocol/client 2.3.1) over Streamable HTTP at /mcp. The smoke test shows the negotiated protocol version 2025-11-25, both through the SDK client and through a raw JSON-RPC initialize. There are 10 tools: lookup_company, get_filings, get_financials, compute_metrics, make_card, make_quiz, grade_quiz, explain_concept, get_learning_profile, update_learning_profile. Tool results carry both text and structured content. Read-only tools are annotated readOnlyHint. Sessions use Mcp-Session-Id and DELETE to close. Host/Origin checks allow loopback only.
  • Public deployment: the same MCP server also runs on Cloudflare Workers (free plan) at https://finwisp-home-mcp.linsizhen.workers.dev/mcp in stateless Streamable HTTP JSON mode. It fetches only the needed SEC companyconcept series (to fit the Worker CPU budget), caches SEC responses, limits each IP to 60 requests/min and 256 KB bodies, keeps the SEC contact address in a Worker secret, and partitions learning profiles per caller by a hashed IP. Verified live with the official SDK client and with Codex CLI as an external MCP client (docs/demo/public-*.txt).
  • SEC EDGAR source: company tickers, submissions and XBRL companyfacts. It declares a User-Agent with a contact, keeps requests at least 210 ms apart (under 5/s; the SEC's limit is 10/s) and caches on disk (tickers 24 h, facts 6 h). Concept aliases are merged across years, because Costco moved its FY2026 revenue to a different XBRL concept. Fiscal years for comparative facts are inferred from period ends.
  • Orchestrator: a deterministic, rule-based coach (no LLM in the main app). It checks the education policy first, then runs the research steps through the official MCP client and streams progress to the page over SSE.
  • Home Hub web app: React + Vite, served by a small Node host. It has the Web Speech API microphone, opt-in speech output, a card carousel, an SVG trend chart, touch-friendly quiz answers and a family memory panel. ?demo=1 gives a recording view.
  • Memory: local JSON household profiles with atomic writes and size limits. These are not authenticated accounts.
  • Optional, experimental: a Codex realtime voice preview (WebRTC). It is off by default and was tested only with a synthetic voice track.
  • Quality: 83 offline tests, all passing (npm test), plus a type-check, a protocol smoke test, and live SEC checks that write their results with accession numbers to docs/LIVE_CHECK.md and docs/LIVE_BANK_CHECK.md. I wrote the code with AI coding assistance. I reviewed and committed it myself.

Challenges we ran into

  • Messy real XBRL data. Costco's revenue concept changes between years. SEC's fy field labels the filing, not the fact, so prior-year comparisons were mislabelled until I inferred the year from period ends. Banks do not report gross profit at all, and Caterpillar has not tagged gross profit since FY2021.
  • A safety policy that is honest about its limits. "What does Costco sell?" is education. "Should my daughter buy Tesla?" is advice. I tested the rule-based detector on held-out phrasings written before tuning. On the last held-out set it scored 17/20, with no false refusals and 3 of 10 advice requests missed. I document this as a conservative pattern detector, not a guarantee.
  • Keeping quizzes honest. An early version exposed answer keys to the learner. They now stay on the server until grading.
  • Agent tooling. I wrote a Kiro spec and steering files for the bank-aware feature and ran Kiro Crew on it three times. Every file write was rejected in headless mode, so I implemented the feature by hand. Details are in the friction log.
  • Clean shutdown of streamed requests and MCP sessions without losing a profile write.

Accomplishments that we're proud of

  • A real, standards-based MCP server (spec 2025-11-25, Streamable HTTP, official SDK), not a mock. It works with the hub and with a third-party MCP client.
  • Every number on screen traces back to an SEC accession number.
  • The advice refusal does not just say "no". It turns the question into three things you can check yourself, with the company's real numbers.
  • Bank-aware cards: the gap in the data becomes a lesson ("why banks have no gross margin").
  • 83/83 tests passing, held-out policy evaluation, a public MCP endpoint anyone can connect to, and a 32-entry friction log.

What we learned

  • MCP structured content plus visible tool calls make a "glass box" assistant. Families can see where every answer came from.
  • Real financial data needs provenance more than cleverness: period ends, concepts and accession numbers.
  • For a home device, the policy must run before any tool, and short spoken refusals matter.
  • Measure safety rules on phrasings you did not tune on, and report the misses.

What's next for Finwisp Home

  • Connect to a real Alexa+ add-on as soon as MCP onboarding opens beyond preview partners.
  • Authenticated multi-household profiles with durable storage (e.g. Durable Objects) behind the public endpoint, plus proper auth.
  • More business models (insurers, REITs), quarterly filings, and side-by-side company comparisons.
  • MCP Apps / richer card UI for screen devices, and broader browser voice support.

Built With

  • cloudflare-workers
  • mcp-typescript-sdk
  • model-context-protocol
  • node.js
  • react
  • sec-edgar
  • server-sent-events
  • streamable-http
  • tsx
  • typescript
  • vite
  • web-speech-api
  • xbrl
  • zod
Share this project:

Updates

Submission history