flashcards-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run

npm install
npm run build    # tsc → dist/
npm test         # build + Node test runner (in-memory auth/storage)

Deployed as Vercel serverless functions. No local stdio mode.

Tests use Node's built-in test runner. MCP HTTP regression tests exercise the real transport with in-memory auth/storage, without Google sign-in or a live database.

Architecture

This is an MCP (Model Context Protocol) flashcard server deployed as Vercel serverless functions over HTTP, with OAuth 2.1 auth and Firebase Google Sign-In. Each user's data is isolated by Firebase UID.

Entry point

• api/mcp.ts — HTTP mode. Uses KVStore (Upstash Redis). Deployed as a Vercel serverless function. Initialization, ping, initialized notifications, and tool listing are public and never access user storage. All tool calls and other requests require OAuth 2.1 Bearer token validation. Extracts user ID from the access token and scopes all data access to that user.

Storage abstraction

StoreBackend interface (src/store.ts) abstracts persistence. One implementation:

• KVStore (src/kv-store.ts) — Upstash Redis via @upstash/redis, keyed per-user as user:{uid}:flashcards

Stores the shape: { projects: Project[], flashcards: Flashcard[] }.

Tool registration

src/tools.ts exports registerTools(server, store) which wires up all MCP tools (CRUD for projects/flashcards, due card retrieval, review recording). The tools are framework-agnostic — they take a StoreBackend and work identically regardless of backing store.

Spaced repetition

src/sr.ts uses ts-fsrs to schedule cards with FSRS. Review quality maps to Anki-style ratings: 1 = Again, 2 = Hard, 3 = Good, 4 = Easy. Cards store FSRS memory state (stability, difficulty, fsrs_state, review/lapse counts, learning step, and last_review) instead of SM-2 ease/repetition fields.