Spaced-repetition multiple-choice quizzes as a small FastAPI + PostgreSQL REST API, with an MCP server at /mcp
so Claude, ChatGPT and other MCP clients can quiz you and write questions. Sign-in is GitHub OAuth, and only
GitHub logins listed in ALLOWED_USERS can use it.
- Decks nest. Questions are
single(4 options, 1 correct) orselect_two(5 options, 2 correct). - Scheduling uses FSRS with whole-day intervals. The confidence you give with each answer sets the rating.
- Each deck has a daily new-question limit that follows Anki v3 rules. The study day starts at 4am in your timezone.
cp .env.example .env
docker compose up -d --build
curl localhost:8000/upPostgres listens on localhost:5433, with two databases: quiz and test. Migrations run when the API
container starts.
Locally, sign-in is mocked: with no GitHub credentials in .env and APP_URL on localhost, every request (REST
and MCP) is the user dev, with no token or GitHub round trip. Without GitHub credentials, the server
refuses to start on any other APP_URL, and always in the production image (APP_ENV=production in the Dockerfile),
so production can't end up open by accident.
- http://localhost:8000/ is the home page: how to connect an AI and run your own copy.
- http://localhost:8000/app is the browser study UI (Jinja + HTMX + Tailwind). Locally with mocked auth it is the
devuser. http://localhost:8000/app/sql is SQL practice: topics, problems with a SQL editor, test runs and submissions. - http://localhost:8000/docs has the OpenAPI docs, where Authorize signs you in to try the REST API.
/app styles are Tailwind; the SQL editor is CodeMirror bundled by esbuild. app/static/app.css and
app/static/editor.js are gitignored and built in the Docker image (Node only at build time). Locally:
cd frontend && pnpm install && pnpm watch # rebuilds app/static/app.css and editor.js as you edit
# or: pnpm build # one-shot CSS + editor bundle, e.g. before pytest- Create an OAuth app at https://github.com/settings/developers:
- Homepage:
APP_URL - Callback:
<APP_URL>/auth/callback
- Homepage:
- Fill in these values in
.env:GITHUB_CLIENT_IDandGITHUB_CLIENT_SECRETJWT_SIGNING_KEYandSTORAGE_ENCRYPTION_KEY: random strings (see the comments in.env.example)ALLOWED_USERS: your GitHub login
- Restart with
docker compose up -d.
The API is its own OAuth 2.1 authorization server, built on FastMCP's GitHubProvider. It supports dynamic
client registration, PKCE and a consent screen. OAuth clients and tokens live in the kv_store table,
encrypted. The same bearer tokens work for /mcp and for the REST API. /docs (client
swagger-ui) is a public PKCE client that registers itself when the server starts.
The home page is static: it has no sign-in, because MCP clients and /docs run their own OAuth flows. The only
JavaScript is the Copy buttons.
Any host that runs a Dockerfile works, including AWS Lambda: the last stage (prod) is the production image,
listens on $PORT (default 8080), runs migrations on start and serves a health check at /up. The live instance
runs on AWS Lambda. Keep Postgres off the app host (e.g. a free
Neon project, in the same region): if the host suspends or deletes the app, your data survives
and you redeploy elsewhere. For Neon, use the direct (non-pooled) URL without &channel_binding=require, which
asyncpg rejects.
Every host needs the same settings: APP_URL (the public URL, no trailing slash), DATABASE_URL,
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, ALLOWED_USERS, and optionally PLUGIN_MARKETPLACE. Generate
JWT_SIGNING_KEY and STORAGE_ENCRYPTION_KEY with python -c "import secrets; print(secrets.token_urlsafe(32))"
(Render generates them for you). Then point the GitHub OAuth app's homepage and callback at the new URL.
Moving hosts: set the new APP_URL, update the GitHub OAuth app, and update the plugin URL (see
Claude Code plugin). Reusing the old keys and database keeps registered clients working; new
keys mean every client signs in again.
New → Blueprint, pick the repo: render.yaml sets up a free Docker web service in Virginia with the health check,
generates both keys and prompts for the rest. The free plan sleeps when idle, so the first request after a while
takes up to a minute.
railway init # new project, from the repo root
railway up # builds the Dockerfile's prod stage
railway variables --set "DATABASE_URL=..." --set "GITHUB_CLIENT_ID=..." # and the rest
railway domain # public URL; set APP_URL to it, then redeployIn the service settings, set the healthcheck path to /up and the region next to your database. Railway sets
PORT itself.
fly launch --no-deploy # detects the Dockerfile, writes fly.toml; pick region iad for Neon us-east-1
fly secrets set DATABASE_URL=... GITHUB_CLIENT_ID=... # and the rest; APP_URL=https://<app>.fly.dev
fly deployCheck that fly.toml has internal_port = 8080, and add an [[http_service.checks]] with path = "/up". With
auto_stop_machines on, idle machines stop and the dashboard shows the app as suspended: that's scale-to-zero,
not an account action.
infra/main.tf (Terraform) runs the same image on Lambda, with Lambda Web
Adapter turning invocations into HTTP requests, behind an HTTP
API on your own domain. It also manages the domain's two Cloudflare DNS records (certificate validation and the
CNAME), so the domain's parent must be a Cloudflare zone. Everything lives in us-east-1, next to a Neon us-east-1
database.
Cost for a personal instance is close to $0: Lambda's always-free allowance (1M requests and 400,000 GB-seconds a
month) covers it, the HTTP API is $1 per million requests, and ECR keeps only the last 3 images (about $0.10 per
GB-month). AWS has no hard spending cap; set BUDGET_EMAIL to get an email when a month passes $1 or is forecast
to pass $5. The HTTP API throttles to 5 requests per second (bursts of 20), so a bot flood gets 429s at the gateway
instead of running the function: the worst case stays a few dollars a day rather than unbounded. This is a cost
ceiling at the edge, not per-user rate limiting in the app.
- Install the AWS CLI, Terraform and Docker, and sign in with
aws login. - Create a Cloudflare API token with Zone → DNS → Edit on your zone only.
- Create
.env.aws(gitignored) withDOMAIN_NAME(e.g.quiz-api.example.com),DATABASE_URL,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET,JWT_SIGNING_KEY,STORAGE_ENCRYPTION_KEY,ALLOWED_USERS,CLOUDFLARE_API_TOKEN, and optionallyPLUGIN_MARKETPLACEandBUDGET_EMAIL. - Run
deploy/aws.sh. The first run asks to create the ECR repository, then builds and pushes the image, then shows the full plan and asks again. Creating the certificate waits a few minutes for validation. - Point the GitHub OAuth app at
https://<DOMAIN_NAME>andhttps://<DOMAIN_NAME>/auth/callback.
After that, pushes to main deploy themselves: .github/workflows/deploy.yml runs the tests and mypy, builds the
image on an arm64 runner, pushes it to ECR and points the function at it, then checks /up. GitHub signs in to AWS
with a short-lived OIDC token that only the repo's main branch can trade for the quiz-api-github-deploy role, which
may only push to the ECR repository and update the function; no AWS keys are stored in GitHub. Forks skip the deploy
job. Infrastructure changes (anything in infra/) stay manual: run deploy/aws.sh, which also ships your local
checkout, and shows the plan before applying. The API only answers on your domain (the default execute-api URL is
off). The first request after a quiet spell cold-starts the function, which takes a few seconds.
Terraform state stays local in infra/terraform.tfstate: gitignored, readable only by you, and holding the secrets
in plain text. Don't commit it or share it; lose it and Terraform no longer knows what it created (import or delete
the resources by hand).
Hosts scan for phishing and suspend first, and ask later. A small app on a shared domain (*.onrender.com,
*.up.railway.app, *.fly.dev, *.execute-api.amazonaws.com) whose page leads with "Sign in with GitHub" looks a lot like the credential
phishing those domains are known for. This has happened to this project on Render. What keeps the risk down:
- Use your own domain. Every host above supports custom domains, and the AWS setup requires one. Scanners and blocklists treat shared host subdomains with suspicion, and one bad neighbour can get the whole suffix flagged.
- No login page on
/. The home page is static: it explains the project, calls itself a personal instance and has no sign-in form or password field. Browser OAuth for the study UI lives under/app(not the marketing home). MCP clients and Swagger's Authorize on/docsrun their own flows. - No open redirects. Dynamic client registration only accepts callbacks on loopback,
claude.ai,claude.com,chatgpt.com,/docsand/app/oauth/callback(CLIENT_REDIRECT_URISinapp/auth.py). Without that list, anyone could register a client and hand out/authorizelinks on your domain that end on their own site. To support another MCP client, add its callback there. - Stay out of search.
robots.txtdisallows everything and every page isnoindex. - One account per person. Railway's fair use policy bans multiple trial accounts, and every host's acceptable use policy lets it suspend without notice (Render, Railway, Fly, AWS).
If you're suspended anyway: check the domain in Google Safe
Browsing and request a review there if it's listed,
then appeal to the host (Render through the dashboard's support, Railway at support@railway.app, Fly through
support or its community forum, AWS through a support case). Point to the public repo and explain that sign-in is limited to ALLOWED_USERS.
Meanwhile, deploy to another host: the database lives elsewhere, so nothing is lost.
- Claude Code: install the plugin (below), or run
claude mcp add --transport http quiz-api <APP_URL>/mcp. Then run/mcpto sign in. - Claude.ai / Claude Desktop: Customize → Connectors → "+" → Add custom connector →
<APP_URL>/mcp. On Team and Enterprise, an owner first adds it under Organization settings → Connectors. The connection comes from Anthropic's servers, soAPP_URLmust be publicly reachable (not localhost). - ChatGPT (Plus, Pro, Business, Enterprise, Edu; web only): Settings → Security and login → Developer mode, then
ChatGPT Plugins → "+" → create a developer-mode app with
<APP_URL>/mcpand OAuth.
The home page shows the same steps, plus the plugin install commands when PLUGIN_MARKETPLACE is set (e.g.
danielh-official/agent-plugins); otherwise it shows only claude mcp add.
Claude Code's prompt suggestions (the greyed-out next message) can give answers away. Study from a folder whose
.claude/settings.json has { "promptSuggestionEnabled": false }.
plugins/quiz-api/ bundles the MCP server config (.mcp.json) and the quiz-api skill, which covers the study
loop, writing good questions and reviewing progress. It's listed in the danielh-official-plugins marketplace
(danielh-official/agent-plugins), which points back at this directory.
claude plugin marketplace add danielh-official/agent-plugins
claude plugin install quiz-api@danielh-official-pluginsThe plugin has no default server. Quiz API is self-hosted: fork this repo, deploy your own instance, then
set QUIZ_API_URL to your instance's MCP URL (https://<your-domain>/mcp) before starting your client, e.g.
export QUIZ_API_URL=https://<your-domain>/mcp. Without it the plugin's MCP server won't connect. Validate with
claude plugin validate plugins/quiz-api.
For local development the repo's .envrc sets QUIZ_API_URL to http://localhost:8000/mcp: with direnv (direnv allow once),
claude run inside this repo talks to your local, mocked server.
For Claude.ai or ChatGPT, zip the skill folder (cd plugins/quiz-api/skills && zip -r quiz-api.zip quiz-api)
and upload it under Skills.
Every route needs Authorization: Bearer <token>, except /up, /, /robots.txt, /docs and the OAuth endpoints.
| Method | Path | |
|---|---|---|
| GET, PATCH, DELETE | /me |
Profile and settings (timezone, desired_retention). DELETE removes everything |
| GET, POST | /decks |
Tree with due/new/total counts (?archived=true for archived); create |
| GET, PATCH, DELETE | /decks/{id} |
GET adds subdecks and questions (?page=) |
| POST | /decks/{id}/questions |
1–50 questions, all-or-nothing |
| GET | /questions/search?q=&deck_id= |
|
| GET, PATCH, DELETE | /questions/{id} |
PATCH: pass option ids back to keep them; reset_progress |
| PUT | /questions/{id}/card |
note, suspended |
| POST | /decks/{id}/sessions |
Start a session, optional size and mode (mixed default, new = unseen only, due = reviews only); returns the latest session summaries |
| GET | /sessions/{id}/next |
Next question without answers, or the summary when done |
| POST | /sessions/{id}/answers |
question_id, selected (option ids), confidence, optional pre_answer_note |
| PATCH | /sessions/{id} |
summary: the running free-form summary, replaced on each call |
| GET, POST | /exams |
List (?upcoming= = incomplete + future/undated start); create |
| GET, PATCH, DELETE | /exams/{id} |
PATCH: name, starts_at, completed, deck_ids |
| GET | /stats?deck_id=&exam_date=&exam_id= |
Calibration, misconceptions, leeches, notes, readiness |
| GET, POST | /sql/topics |
SQL practice topics (flat) with problem/solved counts; create |
| GET, DELETE | /sql/topics/{topic} |
GET lists problems with the dialects each is solved in |
| POST | /sql/topics/{topic}/problems |
title, description, tables, reference_query, test_cases |
| GET, PATCH, DELETE | /sql/topics/{topic}/problems/{problem} |
GET hides hidden cases and the reference query |
| POST | .../problems/{problem}/test-cases |
Rows per table; PATCH/DELETE .../test-cases/{id} (hidden) |
| POST | .../problems/{problem}/run |
query, dialect: visible cases only, not saved |
| POST, GET | .../problems/{problem}/submissions[/{id}] |
Every case, saved; shows the first failing hidden case |
MCP tools: list-decks, get-deck, search-questions, get-performance, create-deck, update-deck,
create-questions, update-question, start-session, next-question, submit-answer, update-session,
update-card, update-settings, list-exams, get-exam, create-exam, update-exam, delete-exam,
list-sql-topics, create-sql-topic, get-sql-topic, create-sql-problem, get-sql-problem, update-sql-problem,
add-sql-test-case, update-sql-test-case, run-sql, submit-sql, get-sql-submission.
Deck/question and SQL deletes are REST-only; delete-exam is allowed on MCP.
SQL practice is separate from decks (no spaced repetition). Dialects: sqlite (default, runs in Python's
sqlite3), mysql, mariadb, tsql, postgres (translated by sqlglot and run in DuckDB, so some behavior such as
integer division follows DuckDB). Each test case runs in a fresh in-memory database with no file or network access,
a 2s limit and a 1000-row cap. Expected output comes from the problem's reference query.
Exams track an upcoming test: name, optional starts_at, linked decks (parent includes subdecks). Readiness
stays computed via /stats or get-performance (exam_id preferred). Mark done with completed: true.
docker compose exec api pytest # inside the container
uv sync && uv run pytest # on the host (uses localhost:5433/test)
uv run pytest tests/test_limits.py -k parent # one file / matching tests
uv run alembic revision --autogenerate -m "..." # after changing app/models.pyTests reset the test database (Alembic downgrade to base, then upgrade) at the start of every run, and
roll back each test's transaction. Compose must be up for Postgres. CI runs pytest and mypy on every push and pull
request (.github/workflows/deploy.yml, which then deploys main), pylint in .github/workflows/pylint.yml, and
ruff format in .github/workflows/ruff.yml.
Layout:
app/services/: all the business logicapp/api.pyandapp/mcp.py: thin wrappers over the servicesapp/auth.py: OAuth and user mappingapp/web.pyandapp/templates/: the static home page androbots.txtinfra/anddeploy/aws.sh: the AWS deployment (Terraform),.github/workflows/: CI and deploys