flashlearn-mcp

An MCP (Model Context Protocol) server for the FlashLearnAI public API. Add it to Claude Code, Claude Desktop, or any MCP client and say "make me a flashcard deck about X and quiz me on it": the model can generate decks with AI, browse sets, run SM-2 spaced-repetition study sessions, and read API usage, all through your own FlashLearnAI API key.

Built with the official TypeScript SDK v2 (@modelcontextprotocol/server, 2026-07-28 MCP spec). stdio transport. MIT licensed.

Quickstart (under 5 minutes)

Requirements: Node.js 20 or later and a FlashLearnAI API key. Mint a key at flashlearnai.witus.online/developer/keys (sign in, Developer Portal, API Keys, Create key).

git clone https://github.com/dapperAuteur/flashlearn-mcp.git
cd flashlearn-mcp
pnpm install
pnpm build

Claude Code

claude mcp add flashlearn -e FLASHLEARN_API_KEY=fl_pub_your_key_here -- node /absolute/path/to/flashlearn-mcp/dist/index.js

Then in a Claude Code session: "use the flashlearn tools to generate a deck about photosynthesis and quiz me."

Claude Desktop

Add to claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "flashlearn": {
      "command": "node",
      "args": ["/absolute/path/to/flashlearn-mcp/dist/index.js"],
      "env": {
        "FLASHLEARN_API_KEY": "fl_pub_your_key_here"
      }
    }
  }
}

Restart Claude Desktop and the flashlearn tools appear in the tools menu.

After npm publish

Once the package is published to npm, the local path form above can be replaced with npx:

claude mcp add flashlearn -e FLASHLEARN_API_KEY=fl_pub_your_key_here -- npx -y flashlearn-mcp

{
  "mcpServers": {
    "flashlearn": {
      "command": "npx",
      "args": ["-y", "flashlearn-mcp"],
      "env": { "FLASHLEARN_API_KEY": "fl_pub_your_key_here" }
    }
  }
}

Verify without a host

The MCP Inspector exercises the server directly:

FLASHLEARN_API_KEY=fl_pub_your_key_here npx @modelcontextprotocol/inspector node dist/index.js

Connect, open the Tools tab, and run ping. It reports the configured API base and whether a key is set, without calling the API.

Related MCP server: Anki MCP Server

Configuration

The server starts without a key (so hosts can list tools), but every API-backed tool returns an error naming the fix until the key is set.

Tools

Resources: flashlearn://getting-started (how the tools fit together) and flashlearn://openapi (the live OpenAPI 3.1 spec of the underlying API).

What the tools return and why (output trimming)

Tool output goes into a model's context window, so every response is trimmed to what the model needs:

• Cards are reduced to id, front, back. Media URLs, alt text, video fields, multiple-choice options, and answer-key fields are dropped. A raw get_set card can carry 14 fields; the trimmed card carries 3.

• Set descriptions are capped at 160 characters in listings.

• list_sets drops rating and createdAt; they do not help a model pick a deck.

• generate_cards, submit_review, and get_usage pass through shapes that are already compact.

Every tool also declares a zod outputSchema and returns structuredContent, so clients get machine-readable results next to the text block.

Error handling

• API errors become MCP tool errors (isError: true) with the fix in the message: a 401 points at the key dashboard, a quota 429 points at get_usage, a 404 suggests list_sets. Never a silent empty result.

• Burst rate limits (RATE_LIMIT_EXCEEDED) are retried once with a capped backoff. Monthly quota exhaustion (QUOTA_EXCEEDED, same HTTP 429, different code) is never retried, because a retry cannot succeed inside the billing period.

• The API key never appears in logs, errors, or output. The client never interpolates it, and a redaction pass scrubs it from any upstream message as a second fence. test/redaction.test.ts proves this for happy, 401, 429, network-failure, and hostile-echo paths.

Spec vs code notes (upstream API)

This server is coded against the FlashLearnAI OpenAPI spec plus the actual route code. Two places disagree; the server follows the code:

1. The spec's UsageResponse schema shows the usage object as the whole 200 body; the route wraps it in the standard { data, meta } envelope like every other endpoint.

2. The spec documents POST /api/v1/generate as returning 201; the route returns 200 (with source: "shared") when it serves an existing public deck instead of generating.

Both are noted for the flashlearn-ai repo's spec-is-contract cleanup workstream.

Development

pnpm install
pnpm typecheck   # tsc strict, no emit
pnpm lint        # eslint flat config, type-checked rules
pnpm test        # vitest: 33 tests, mocked API, in-process MCP client
pnpm build       # emits dist/
pnpm demo        # live end-to-end demo against production (needs FLASHLEARN_API_KEY)

Tests connect a real MCP client to the real server factory in process (per the SDK v2 testing guide) and mock the FlashLearnAI API at the fetch boundary, so tool behavior, schema validation, error mapping, and redaction are all covered without network access.

Activate the commit guard once per clone:

git config core.hooksPath .githooks

Roadmap

• v1 (this): stdio transport, API-key auth, read/generate/study tools.

• v2: Streamable HTTP transport for a hosted remote server, and OAuth if the product's developer surface grows it. Not started; stdio is the only transport today.

License

MIT. See LICENSE.

flashlearn-mcp