Local Study App

A local-first, open-source flashcard and quiz app with a FastAPI website and a stdio MCP server for Codex. It uses SQLite, binds only to 127.0.0.1, and has no telemetry or runtime CDN dependencies.

Windows quick start

cd mcp-local-study-app
powershell -ExecutionPolicy Bypass -File scripts/install.ps1
powershell -ExecutionPolicy Bypass -File scripts/start.ps1
Start-Process http://127.0.0.1:8080

Python 3.9+ is supported. Data is stored in %LOCALAPPDATA%\local-study-app\study.db (override with STUDY_DATA_DIR). The MCP server is launched with python -m local_study_app.mcp_server from any directory.

Architecture

FastAPI serves a single-page vanilla JavaScript UI and JSON API. SQLite stores decks, cards, reviews, quiz sessions, and activity. The MCP server wraps the same service layer and communicates over stdio. The app never binds beyond localhost and does not contact external services.

MCP installation

codex mcp add local-study-app -- "C:\path\to\mcp-local-study-app\.venv\Scripts\python.exe" -m local_study_app.mcp_server
codex mcp list

Tools include website lifecycle (start_study_app, open_study_app, get_study_app_status, stop_study_app), deck/card CRUD, quiz generation/submission, reviews/progress, and JSON/CSV import/export.

Example prompts: “Show me my cards due today.” “Generate a quiz from Biology Basics.” “Open my local study website.” “Export my Spanish deck as CSV.”

Tests and scripts

powershell -ExecutionPolicy Bypass -File scripts/test.ps1
powershell -ExecutionPolicy Bypass -File scripts/stop.ps1
powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1

The test suite covers persistence, CRUD, imports/exports, quiz scoring, spaced repetition, health, process idempotence, and MCP tool contracts. Screenshots and the MCP test report live under docs/.

Security

Inputs are typed and validated, SQL uses parameterized queries, HTML is rendered with text nodes, uploads are size-limited and parsed before commit, and import/export filenames are constrained to the application data directory. There is no generic shell MCP tool, analytics, cloud sync, or arbitrary file access.

License

MIT.