# vocab-mcp

[![CI](https://github.com/Code-byte404/vocab-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Code-byte404/vocab-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/vocab-mcp.svg)](https://pypi.org/project/vocab-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/vocab-mcp.svg)](https://pypi.org/project/vocab-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A vocabulary-bank MCP server. Use it from Claude Desktop (or any MCP host) to
collect unfamiliar words while you read or chat, organise them into decks,
review them on a spaced-repetition schedule, enrich them with definitions and
examples, and even hear them pronounced — all stored locally on your machine.

## Features

- **Save while you read.** Hand any word to Claude — it saves the spelling,
  definition, phonetic, example, source sentence, and tags.
- **Spaced repetition.** Pure-Python SM-2 algorithm tracks mastery and the
  next review date for each word.
- **Multiple decks.** Group words by topic, exam, language, or project. The
  same word can live in different decks with different definitions.
- **Quizzes that adapt.** Multiple-choice, fill-in-the-blank, and
  definition-match. Claude (the host) writes the questions itself — no API
  key needed.
- **Content enrichment.** `enrich_word` fills in definition / phonetic /
  part-of-speech / synonyms / antonyms. By default Claude does it from its
  own knowledge; opt into the free `dictionaryapi.dev` lookup with
  `use_api=True`.
- **Pronunciation.** `pronounce_word` returns an MP3 audio block via gTTS
  (multilingual, no API key, cached locally).
- **MCP resources & prompts.** Browse decks, due lists, and stats as
  `vocab://...` resources; trigger a daily review or vocab capture from a
  passage with one prompt.

## Install

```bash
pip install vocab-mcp                  # core only
pip install "vocab-mcp[tts]"           # + gTTS pronunciations
pip install "vocab-mcp[enrich]"        # + dictionaryapi.dev lookup
pip install "vocab-mcp[all]"           # everything
```

Python 3.10+. macOS / Linux / Windows.

## Configure Claude Desktop

Edit (or create) `~/Library/Application Support/Claude/claude_desktop_config.json`
on macOS — equivalent paths exist on Windows and Linux:

```json
{
  "mcpServers": {
    "vocab": {
      "command": "vocab-mcp"
    }
  }
}
```

Restart Claude Desktop fully (⌘Q on macOS). The new tools should appear in
the tools panel.

If `vocab-mcp` isn't on your PATH (e.g. you installed into a conda env), use
the absolute path:

```json
{
  "mcpServers": {
    "vocab": {
      "command": "/path/to/python",
      "args": ["-m", "vocab_mcp"]
    }
  }
}
```

## Tool / Resource / Prompt reference

### Tools

| Tool | Purpose |
| --- | --- |
| `save_word` | Save one word into a deck. |
| `save_words_batch` | Save many words at once. |
| `set_word_fields` | Patch existing fields on a word. |
| `enrich_word` | Get definition / phonetic / POS / synonyms / antonyms. |
| `pronounce_word` | Synthesize a pronunciation MP3 (requires `[tts]`). |
| `list_words` / `search_word` / `get_stats` | Browse a deck. |
| `list_decks` / `create_deck` / `delete_deck` | Manage decks. |
| `get_due_words` / `generate_quiz` / `submit_quiz_result` | Review flow. |

### Resources

- `vocab://decks` — index of all decks
- `vocab://decks/{name}` — full contents of a deck
- `vocab://decks/{name}/due` — words due in a deck
- `vocab://decks/{name}/stats` — per-deck stats
- `vocab://stats` — library-wide stats

### Prompts

- `daily_review(deck, limit)` — start a review session
- `capture_vocab(passage, deck)` — extract candidate words from a passage
- `quiz_session(deck, count, quiz_type)` — ad-hoc quiz session

## Multi-deck workflow

```
> "create a deck called gre"
> "I'm reading <passage>. Save any high-utility words to gre."
> "what's due in gre today?"
> "quiz me on 10 gre words"
> "show me library stats"
```

## Data location

Everything lives at `~/.vocab-mcp/`:

```
~/.vocab-mcp/
├── vocab.db           # SQLite database
└── audio/             # cached pronunciation MP3s
```

Override with `VOCAB_DATA_DIR=/some/dir` (or just the database path with
`VOCAB_DB_PATH=/some/file.db`).

The database is **per-user, local, and never uploaded anywhere**. Two users
on the same machine using different OS accounts each get their own DB.

## Development

```bash
git clone https://github.com/Code-byte404/vocab-mcp
cd vocab-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check .
pytest
```

CI runs the same checks across Python 3.10–3.12 on Ubuntu and macOS.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome — please
file an issue before sending large changes.

## License

[MIT](LICENSE).