Skip to content
danielh-officialPublic

About

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Quiz API

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) or select_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.

Run it

cp .env.example .env
docker compose up -d --build
curl localhost:8000/up

Postgres 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.

/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

GitHub sign-in (production)

  1. Create an OAuth app at https://github.com/settings/developers:
    • Homepage: APP_URL
    • Callback: <APP_URL>/auth/callback
  2. Fill in these values in .env:
    • GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET
    • JWT_SIGNING_KEY and STORAGE_ENCRYPTION_KEY: random strings (see the comments in .env.example)
    • ALLOWED_USERS: your GitHub login
  3. 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.

Deploy

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.

Render

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

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 redeploy

In the service settings, set the healthcheck path to /up and the region next to your database. Railway sets PORT itself.

Fly

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 deploy

Check 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.

AWS Lambda

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.

  1. Install the AWS CLI, Terraform and Docker, and sign in with aws login.
  2. Create a Cloudflare API token with Zone → DNS → Edit on your zone only.
  3. Create .env.aws (gitignored) with DOMAIN_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 optionally PLUGIN_MARKETPLACE and BUDGET_EMAIL.
  4. 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.
  5. Point the GitHub OAuth app at https://<DOMAIN_NAME> and https://<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).

Avoiding suspension

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 /docs run their own flows.
  • No open redirects. Dynamic client registration only accepts callbacks on loopback, claude.ai, claude.com, chatgpt.com, /docs and /app/oauth/callback (CLIENT_REDIRECT_URIS in app/auth.py). Without that list, anyone could register a client and hand out /authorize links on your domain that end on their own site. To support another MCP client, add its callback there.
  • Stay out of search. robots.txt disallows everything and every page is noindex.
  • 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.

Connect an AI

  • Claude Code: install the plugin (below), or run claude mcp add --transport http quiz-api <APP_URL>/mcp. Then run /mcp to 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, so APP_URL must 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>/mcp and 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 }.

Claude Code plugin

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-plugins

The 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.

REST API

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.

Develop

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.py

Tests 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 logic
  • app/api.py and app/mcp.py: thin wrappers over the services
  • app/auth.py: OAuth and user mapping
  • app/web.py and app/templates/: the static home page and robots.txt
  • infra/ and deploy/aws.sh: the AWS deployment (Terraform), .github/workflows/: CI and deploys

About

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages