Metadata-Version: 2.4
Name: flashcard-jp-mcp
Version: 0.3.0
Summary: MCP server bridging Claude (Desktop / Code / .ai) to a flashcard-jp deployment.
Project-URL: Homepage, https://github.com/max-crab/flashcard-jp
Project-URL: Issues, https://github.com/max-crab/flashcard-jp/issues
Author-email: Massimo <massimo@myappfree.com>
License-Expression: MIT
Keywords: claude,flashcards,japanese,mcp,srs
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Description-Content-Type: text/markdown

# flashcard-jp-mcp

MCP server that lets Claude (Desktop, Code, or .ai web via Connectors) add
words to a [flashcard-jp](https://github.com/max-crab/flashcard-jp)
deployment. Once installed, you can chat with Claude like:

> *"Aggiungi al mio Test Mazzo: kau (acquistare), matsu (aspettare),
> asobu (giocare). Genera anche le frasi mnemoniche italiane."*

Claude calls `add_cards_bulk` once and the words land in the deck.

## Install (one command)

### Claude Desktop (Mac / Windows / Linux)

```bash
uvx --from flashcard-jp-mcp flashcard-jp-mcp-install-desktop
```

This writes the `flashcard-jp` entry into the Claude Desktop config at
the OS-correct path:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

Restart Claude Desktop. Done.

### Claude Code (CLI)

```bash
claude mcp add flashcard-jp -- uvx flashcard-jp-mcp
```

Restart your Claude Code session.

### Manual (any client)

```jsonc
{
  "mcpServers": {
    "flashcard-jp": {
      "command": "uvx",
      "args": ["flashcard-jp-mcp"]
    }
  }
}
```

The 6 tools below become available in chat.

> **Prereq**: `uv` installed. If `uvx` is missing:
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
> # Windows PowerShell:
> # powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
> ```

## How auth works

The first tool call asks you for an API token via MCP **elicitation** —
Claude pops up a prompt explaining where to mint it. Paste the
`fjp_…` value, the server saves it to `~/.config/flashcard-jp-mcp/config.json`
(perm 600), and you're done. Token resolution order:

1. `FLASHCARD_API_TOKEN` env var (per-deployment override).
2. `~/.config/flashcard-jp-mcp/config.json` (set by the elicit prompt
   or by `flashcard-jp-mcp-setup`).
3. MCP elicitation prompt (only if your client supports it; Claude
   Desktop and recent Claude Code do).
4. Friendly error pointing at the setup recipe.

### Mint the token (when Claude asks, or up-front)

1. Open https://flashcard-jp-production.up.railway.app and log in with Google.
2. Click **🔑** in the top navbar.
3. Click **Crea token**, name it (e.g. `claude-desktop`), copy the
   `fjp_…` value (shown once).

### Out-of-band setup (terminal, no Claude required)

```bash
uvx flashcard-jp-mcp-setup
```

The CLI prints the URL, reads the token from stdin, validates it
against the API, and saves it to the config file. Useful for clients
that don't support elicitation, or if you'd rather not expose the
token through chat.

### Override the API base

If you self-host flashcard-jp on a different URL, set
`FLASHCARD_API_BASE` in the MCP env:

```jsonc
"env": {
  "FLASHCARD_API_BASE": "https://your-flashcard-jp.example.com"
}
```

## Tools

| Tool | What it does |
|---|---|
| `whoami` | Returns the authenticated user's email + last-studied deck id. Quick auth check. |
| `list_decks` | Every deck visible to the user, with progress (`cards_total`, `cards_done`, `cards_left`, `cards_available_today`, `completed`). |
| `get_deck(deck_id)` | A deck's full word list — useful so Claude can dedupe before adding. |
| `create_deck(name)` | Create a private deck owned by the user. |
| `add_card_to_deck(deck_id, romajii, kana, italiano, mnemonic?, emoji?)` | One word → Word + 2 Cards (forward + reverse). |
| `add_cards_bulk(deck_id, cards)` | Several entries in one call, returns `{added: [...], skipped: [...]}`. |

Romajii must be Hepburn, lowercase, ASCII (`ohayoo`, not `ohayō`). Kana
should be the hiragana / katakana reading only — no kanji.

## Environment variables

| Var | Default | Required |
|---|---|---|
| `FLASHCARD_API_BASE` | `https://flashcard-jp-production.up.railway.app` | no |
| `FLASHCARD_API_TOKEN` | — | **yes** |

## Limits

- Starting decks (`is_starting=True`) are **read-only**. Trying to mutate
  one returns 403; the tool surfaces that as an error message Claude can
  show in the chat.
- Token leaks: each token grants full deck-write access for the user it
  belongs to. Revoke from the web UI's 🔑 menu if exposed.

## License

MIT.
