Metadata-Version: 2.4
Name: flashcard-jp-mcp
Version: 0.1.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

```bash
# Recommended: ephemeral install per Claude session
uvx flashcard-jp-mcp

# Or install once into the user environment
pipx install flashcard-jp-mcp
```

## Get an API token

1. Open the flashcard-jp web app online.
2. Click **🔑** in the top navbar → **Crea token**.
3. Give it a name (e.g. `claude-desktop`) → copy the `fjp_…` value once.
4. Paste it into the MCP server's environment (see below). The web UI
   keeps only a SHA-256 hash — losing the raw value means you have to
   create a new token.

## Configure Claude Desktop

Add to `~/.claude/settings.json` (or use `claude mcp add flashcard-jp` in
Claude Code):

```jsonc
{
  "mcpServers": {
    "flashcard-jp": {
      "command": "uvx",
      "args": ["flashcard-jp-mcp"],
      "env": {
        "FLASHCARD_API_BASE": "https://flashcard-jp-production.up.railway.app",
        "FLASHCARD_API_TOKEN": "fjp_PASTE_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

Restart Claude. The tools below become available in the chat.

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