Finwisp Home

An English home learning screen that teaches how to read companies with SEC filings. Voice and text input, learning cards, quizzes, and family memory are implemented. Educational use only, not investment advice.

Home Hub / CLI → rule-based orchestrator → official MCP client → Streamable HTTP /mcp → SEC EDGAR + education + memory

Public MCP endpoint (for judges)

https://finwisp-home-mcp.linsizhen.workers.dev/mcp — Streamable HTTP (MCP spec 2025-11-25), stateless JSON mode, no auth, hosted on Cloudflare Workers (free plan). GET https://finwisp-home-mcp.linsizhen.workers.dev/health returns a discovery JSON.

Connect any MCP client that speaks Streamable HTTP:

# Codex CLI (~/.codex/config.toml) — verified 2026-10-15, see docs/demo/public-codex-transcript.txt
[mcp_servers.finwisp]
url = "https://finwisp-home-mcp.linsizhen.workers.dev/mcp"
default_tools_approval_mode = "approve"

# Claude Code (standard remote-HTTP syntax; not tested by us)
claude mcp add --transport http finwisp https://finwisp-home-mcp.linsizhen.workers.dev/mcp

# SDK check script in this repo (verified): initialize, tools/list, WFC financials -> metrics -> card
npm run remote-check -- https://finwisp-home-mcp.linsizhen.workers.dev/mcp

Public-endpoint limits: 60 requests/min per IP, 256 KiB request bodies, at most 20 SEC concepts per get_financials call, SEC calls cached (6–24 h) and paced ≤ ~4.8 req/s per Worker isolate. Quiz state and learning profiles on the public endpoint are ephemeral, per-isolate memory; profiles are also partitioned per caller using a hashed IP. Deployment details: docs/DEPLOY.md. Educational use only, not investment advice.

Related MCP server: SEC EDGAR MCP Server

Run the Home Hub

npm ci --cache /tmp/finwisp-npm
export SEC_CONTACT_EMAIL='<your SEC contact email>'
npm run hub

Open http://127.0.0.1:8796. npm run hub builds the Vite/React UI and serves it with the Node/tsx host. It starts a loopback MCP server in the same process by default. Set MCP_URL=http://127.0.0.1:8787/mcp to connect to an existing server instead. HOST defaults to 127.0.0.1; HUB_PORT defaults to 8796. API Host and supplied Origin must name localhost, a loopback address, or the configured HOST. Keep one MCP process for shared SEC pacing and profile writes.

Try “COST net margin”, “AAPL revenue growth”, or “continue where we left off”. The last request reads family memory and reviews concepts missed in the last three quizzes. Advice requests receive a refusal, three research questions, and a disclaimer before any tool runs. See policy.

The large microphone button uses browser SpeechRecognition with a webkit fallback. Read aloud uses speechSynthesis and is opt-in. Browser support and microphone permission vary; text input always works. Browser speech services may process audio remotely. There is no LLM in the app. Microphone input normally needs localhost or HTTPS.

Build or preview separately:

npm run web:build
npm run web:preview
# UI-only preview: http://127.0.0.1:4173 (API requires the Hub)
# For development with API proxy, run the Hub and then in a second terminal:
npx --no-install vite --config web/vite.config.ts web

Stop Hub/preview/development with Ctrl+C. The host closes requests, official MCP client sessions and its owned MCP server on shutdown.

POST /api/ask accepts {text, profile_id?} and streams SSE step, result, and error events. Step status is started/completed/failed. Separate tool events include every coach MCP invocation with call_id, tool, status and duration_ms; repeated card and profile calls are retained. POST /api/quiz/grade accepts {quiz_id, answers, profile_id?}; GET /api/profile?profile_id=family reads memory. JSON requests are capped at 16 KiB. The web screen uses the default family profile.

Quiz IDs derive from question content; a seeded Fisher–Yates shuffle makes options stable per ID. Definition distractors use other glossary meanings; numeric distractors use unique percentages separated after rounding. Every question type shuffles all options, including the correct one; an optional unsigned seed supports reproducible checks. Keys and explanations stay in a server-side map (one hour, at most 1,000 quizzes). No HMAC token is issued. After restart or expiry, generate the quiz again; keys are never returned by make_quiz. Grading returns the correct text and explanation only after submission.

Profiles are gitignored JSON under data/profiles/ (PROFILE_DIR can override it). IDs allow 1–64 letters, digits, underscores or hyphens. Fields are conceptsLearned (count/lastSeen), quizHistory (score/missedConcepts/time), companiesFollowed, and lastSession. Writes serialize within one process and use a private temporary file followed by atomic rename. Files are capped at 64 KiB; history, companies and concepts at 100 each; summaries at 1,000 characters. Use one writer process per directory. Concepts explored are recorded when a lesson completes; counts indicate exposure, not proof of mastery. Quiz results are saved only when profile_id is supplied. Use Reset demo profile in the UI to reset only family via POST /api/profile/reset; no MCP reset tool is exposed. Profiles are local shared household memory, not authenticated accounts.

Requires Node 20.19+ and uses tsx. No LLM or Python worker is started.

npm ci
# Supply your organization's real contact through the environment:
export SEC_CONTACT_EMAIL='<your SEC contact email>'
npm run mcp

Default endpoint: http://127.0.0.1:8787/mcp; PORT changes the port. .env.example contains placeholders only; environment variables must be exported (the app does not automatically load .env files). SEC_APP_NAME defaults to FinwispHome/0.1. SEC_USER_AGENT overrides the entire User-Agent. Without a contact, the app warns and uses contact@example.com.

npm test
npm run smoke
npm run demo -- COST
npm run demo -- NVDA growth
npm run live-check
npm run hub:check
npx --no-install tsc

Tests are offline and serial. Smoke starts a temporary loopback server, uses the official SDK client, lists tools, performs a fresh live AAPL lookup, checks raw protocol negotiation, and shuts down. Demo runs six real HTTP MCP steps and prints JSON step events and results, closing its session and server. Live-check uses four fresh requests for COST/NVDA/AAPL and writes accession provenance to docs/LIVE_CHECK.md.

Default financial metrics: Revenue, NetIncomeLoss, GrossProfit, Assets, Liabilities, OperatingIncomeLoss, CostOfRevenue, NetCashProvidedByUsedInOperatingActivities. Revenue aliases are Revenues, RevenueFromContractWithCustomerExcludingAssessedTax, SalesRevenueNet, and RevenueFromContractWithCustomerIncludingAssessedTax. CostOfRevenue also uses CostOfGoodsAndServicesSold. Concept names and slash-separated aliases remain accepted.

Aliases merge across periods rather than selecting one concept for all years. Only 10-K/FY flow facts spanning 350–380 days and instant balance facts are retained. Deduplication is by unit and period end, preferring latest filed, then by fiscal year. Comparative fiscal years are calculated from the fact period's relationship to the current fiscal period within its accession, since SEC fy labels the filing. Facts dated after their filing date are forward-looking and ignored. The N years count back from the company's latest annual report, so a concept it stopped tagging returns no figures rather than old ones; values are descending and each identifies its concept. Within one filing Revenues (total) is preferred over contract revenue, which can be a subset. Equal filing dates favor alias order. Missing concepts produce empty arrays. These aliases can differ in accounting scope; this is not full accounting normalization.

HTTP sessions own an SDK server and transport and share one SEC client. Initialize with POST, send Mcp-Session-Id, and DELETE to end a session. Host and supplied Origin must be loopback; native clients without Origin are accepted. Tool responses have text and structured content. SEC and validation failures return explicit tool errors.

SEC requests are serialized at least 210 ms apart (under five per second). Run one process to retain the shared limit. Tickers cache for 24 hours; submissions and facts for six hours under gitignored data/cache/. Failed responses are not cached; requests time out after 15 seconds.

See compute design, live verification, Codex HTTP configuration, before/after, and friction log.

SEC data may be delayed, revised, incomplete, or difficult to compare. Read original filings for context. This project provides education, never buy/sell advice.

Readable lessons, recording view, and voice preview

Cards now explain results in plain English (for example, “In FY2026 Costco kept 3.0% of revenue as net income ($9.2B of $303.2B).”). This sentence is illustrative, not a new verified SEC claim. Raw SEC concept identifiers stay in card sources; cards show a small accession line. Numeric quiz options are unique and separated after rounding by at least 1.5 percentage points and 30% relative to the larger displayed magnitude.

The Hub has larger responsive typography, an animated horizontal learning rail with friendly step names and MCP tool chips, card transitions, labelled trend axes, and coloured quiz feedback. Append ?demo=1 for a recording; the tool-call row stays visible, including repeated calls, running/done/error status and duration in ms. Focus states, live announcements, and reduced-motion support remain available.

VOICE_ENGINE=browser is the default. The UI Voice engine selector can choose a Codex preview; the host must also be enabled with VOICE_ENGINE=codex. Selecting the engine starts nothing. Only pressing the voice button starts app-server. Unavailable Codex voice falls back to Web Speech with a notice. Codex voice uses WebRTC, which works with a ChatGPT Codex login. See VOICE.md for the port, tests, the live check and Simon's Mac login/run instructions. The ordinary lesson pipeline and validation scripts start no model sessions.

The rule-based continue flow retrieves missed concepts, shows review cards, and generates a three-question re-quiz restricted to those concepts. Grading refreshes the memory panel. Named-company refusals retrieve actual SEC facts for revenue growth, net margin and liabilities/assets; unavailable data is labelled explicitly. Spoken refusal text is brief.

Recording: 2:45 demo script. Mac setup: Mac voice runbook (Chinese: MAC_VOICE_RUNBOOK.zh.md). Codex voice is an experimental preview that answers by voice; the card/quiz flows are shown with Browser voice or text.

node_modules/.bin/tsx scripts/demo-flow-check.ts verifies live SEC refusal cards and the complete lesson → grade → memory → re-quiz → reset flow on a random port, using a temporary profile directory and no model session.

Bank-aware cards

Banks such as Wells Fargo and JPMorgan do not report gross profit, cost of revenue or operating income. For them, Finwisp Home detects the bank from the filing data: the company reports net interest income, or has a bank SIC code, and has none of the industrial lines. It then explains why gross margin and operating margin do not apply, instead of saying "insufficient data", and adds a Net Interest Share card (net interest income ÷ revenue, group "HOW BANKS EARN"). Other companies, such as Caterpillar, keep the existing behaviour. scripts/live-bank-check.ts checks this against live SEC data and writes docs/LIVE_BANK_CHECK.md.

Kiro and the AWS Builder mini-challenge (honest status)

• The .kiro/steering/ files and the .kiro/specs/bank-aware-cards/ spec (requirements, design, tasks) were written for Kiro.

• Kiro CLI 2.31.1 and Kiro Crew 0.8.0 were installed and signed in with an AWS Builder ID on the build box. Kiro Crew ran on this spec three times on 2026-10-15 (about 28 credits), but produced no code:

  • Headless kirocrew run had every file write rejected. This was true even with dangerously_skip_permissions on, because kiro-cli still refused writes with headless_no_authorization.

  • One run failed at spec decomposition because of free-tier Bedrock throttling.

• The feature was then implemented manually. Kiro did not write the code. See docs/KIRO_LOG.md and FRICTION_LOG.md #22–26.

• It is uncertain whether this counts for the AWS Builder mini-challenge. The rules say Kiro Crew qualifies as a development tool, but here Crew was used for planning attempts only.