# flashlearn-mcp

An MCP (Model Context Protocol) server for the [FlashLearnAI](https://flashlearnai.witus.online) 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](https://flashlearnai.witus.online/developer/keys) (sign in, Developer Portal, API Keys, Create key).

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

### Claude Code

```sh
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):

```json
{
  "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`:

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

```json
{
  "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:

```sh
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.

## Configuration

| Env var | Required | Default | Purpose |
|---|---|---|---|
| `FLASHLEARN_API_KEY` | yes | none | API key from the [developer dashboard](https://flashlearnai.witus.online/developer/keys). Sent as `Authorization: Bearer`. Never logged, never echoed in tool output (a test suite asserts this). |
| `FLASHLEARN_API_BASE` | no | `https://flashlearnai.witus.online` | API base URL. The default is the production URL from the FlashLearnAI OpenAPI spec; override it for a local or staging instance. |

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

| Tool | API route | What it does |
|---|---|---|
| `ping` | none | Liveness plus configuration (API base, key set or not). |
| `list_sets` | `GET /api/v1/sets` | List the key's flashcard sets, paginated. |
| `get_set` | `GET /api/v1/sets/{id}` | One set with all cards (owned or public). |
| `generate_cards` | `POST /api/v1/generate` | AI-generate a deck for a topic; reuses an existing public deck for the same topic when one exists. |
| `create_study_session` | `POST /api/v1/study/sessions` | Start a study session; returns shuffled cards. |
| `submit_review` | `POST /api/v1/study/sessions/{id}/complete` | Submit per-card results; updates SM-2 scheduling and returns accuracy stats. |
| `get_usage` | `GET /api/v1/usage` | Billing-period usage and limits for the key. |

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

```sh
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:

```sh
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](LICENSE).
# flashlearn-mcp