Skip to main content
Glama

vocabit-mcp

CI npm license

An MCP server for Vocabit, a flashcard app. It lets an AI assistant write a study set into a real app on a real phone, and then read back how the learner actually did with it.

Most MCP servers read from an API. This one closes a loop:

flowchart LR
    A["Assistant<br/>teaches a topic"] --> B["create_study_set"]
    B --> C["Set appears in the<br/>Vocabit app"]
    C --> D["Learner works<br/>through it"]
    D --> E["get_set_results"]
    E -->|weak cards| A

The interesting tool is not create_study_set — anything can generate flashcards. It is get_set_results: which cards the learner marked hard, which they never reached, how many reviews each one took. The next set is built out of that, not out of a guess.

Try it in 30 seconds

No backend, no account, no API key:

npx -y vocabit-mcp --demo

Demo mode runs the same server against an in-memory Vocabit with two seeded sets. Create a set, ask for results, and a deterministic stand-in learner will have worked through it — flagged in the response as simulated, so it is never mistaken for real data.

To poke at it with a UI:

npx @modelcontextprotocol/inspector npx -y vocabit-mcp --demo

Related MCP server: MindDory MCP Server

Install

Listed in the MCP Registry as io.github.JohnBilousov/vocabit-mcp, so clients that read the registry can find it on their own.

claude mcp add vocabit -- npx -y vocabit-mcp
{
  "mcpServers": {
    "vocabit": {
      "command": "npx",
      "args": ["-y", "vocabit-mcp"],
      "env": {
        "VOCABIT_BASE_URL": "https://your-vocabit-backend.example.com",
        "VOCABIT_AGENT_KEY": "your-agent-key"
      }
    }
  }
}

Drop the env block to run in demo mode.

Tools

Tool

What it does

vocabit_health

Check the connection and which mode the server is in.

create_study_set

Publish a set to the learner's app. Returns a deep link that opens it on the device.

list_study_sets

Recent sets, newest first, each with a progress summary.

get_study_set

Full contents of one set, plus the topic and notes the assistant attached.

get_set_results

The feedback half. Per-card status, weakCards, untouchedCards, due cards.

update_study_set

Retitle, retag, or append cards — typically the follow-up after reading results.

notify_learner

Telegram ping that a set is waiting.

delete_study_set

Remove a set from the app. Study history is kept.

Also exposed: the vocabit://set/{setId} resource (a set as JSON, listable) and a study-session prompt that walks the whole loop.

Card states

Progress comes from the app's spaced-repetition engine, not from the assistant:

Status

Meaning

new

Never reviewed.

struggling

Learner marked it hard.

learning

Marked good.

mastered

Marked easy.

A set reports completed: true once no card is left in new.

Live mode

Point the server at a Vocabit backend that has the agent API enabled:

export VOCABIT_BASE_URL=https://your-vocabit-backend.example.com
export VOCABIT_AGENT_KEY=...   # must match one of AGENT_API_KEYS on the backend
npx -y vocabit-mcp

Variable

Purpose

VOCABIT_BASE_URL

Backend base URL.

VOCABIT_AGENT_KEY

Sent as X-Agent-Key.

VOCABIT_USER_ID

Firebase UID of the learner. Optional; the backend has a default.

VOCABIT_TERM_LANGUAGE / VOCABIT_DEFINITION_LANGUAGE

Defaults for new sets, e.g. de / en.

VOCABIT_TELEGRAM_ID

Recipient for notify_learner.

VOCABIT_TIMEOUT_MS

Request timeout, default 20000.

VOCABIT_DEMO

1 forces demo mode.

Set neither URL nor key and the server starts in demo mode. Set exactly one and it refuses to start — half a configuration is a mistake, not a hint.

Design notes

Demo mode is a first-class client, not a stub. HttpVocabitClient and DemoVocabitClient implement the same VocabitClient interface, so no tool has a branch for "are we pretending?". A reviewer can run the server before they have credentials, and the test suite exercises the real tool surface over a real MCP transport rather than mocking the SDK.

Errors are recoverable, not fatal. A failed call comes back as isError with the backend's own message plus a hint aimed at the model — 404 says "call list_study_sets to see which sets exist", 401 says "or run with VOCABIT_DEMO=1". Mutually exclusive arguments are rejected with an explanation instead of a guess.

Output schemas stay loose on the edges. Identifying fields are required; everything else is optional, so a backend that grows a field does not turn a working tool into a validation error.

Annotations are honest. delete_study_set is marked destructiveHint, the read tools readOnlyHint. notify_learner messages a real person, and its description says to use it sparingly.

Development

git clone https://github.com/JohnBilousov/vocabit-mcp && cd vocabit-mcp
npm install
npm run build
npm test          # tool surface + full loop, plus the HTTP client against a mocked fetch
npm run lint      # eslint
npm run format    # prettier --write
npm run inspect   # demo mode in the MCP Inspector

CI runs typecheck, lint, format:check, test, and build on every push and pull request.

src/
  index.ts        CLI entry, stdio transport
  config.ts       env → Config, demo-mode resolution
  server.ts       tool / resource / prompt registration
  schemas.ts      zod input and output shapes
  format.ts       human-readable summaries next to structuredContent
  client/
    types.ts      wire types + VocabitClient contract
    http.ts       live backend
    mock.ts       in-memory backend for demo mode
test/
  server.test.ts       tool surface + full loop — over an in-memory MCP transport
  client/
    http.test.ts       query encoding, error-body parsing, timeouts — against a mocked fetch

Releasing

Publishing uses npm's trusted publishing (OIDC) — no NPM_TOKEN secret, nothing that can leak or expire. One-time setup on npmjs.com, under the package's Settings → Trusted publishing → GitHub Actions: organization JohnBilousov, this repository, workflow filename publish.yml.

To cut a release: bump the version in package.json, server.json, and VERSION in src/server.ts together (a test asserts they can't drift), commit, push, then publish a GitHub Release with a matching vX.Y.Z tag. That triggers .github/workflows/publish.yml, which runs the test suite and publishes to npm with provenance — the package page shows a verified link back to this exact commit and workflow run, not just a name on the registry.

Roadmap

  • Streamable HTTP transport alongside stdio

  • Multi-learner support without a backend default UID

  • Audio pronunciation cards

License

MIT © Ivan Bilousov

Available Tools

8 tools
create_study_setCreate a study setA

Build a flashcard set and publish it to the learner's Vocabit app. Returns a deep link that opens the set on their device. Prefer one focused topic and 8-15 cards per set — long sets get abandoned. Use the notes field for what you want to check afterwards; the learner never sees it.

Inputs: cards (required), title (required), notes, topic, +6 more. Returns: setId, title, userId, deepLink, +4 more

delete_study_setDelete a study setA
DestructiveIdempotent

Remove a set from the learner's app. Study history is kept on the backend, but the set disappears from their device. Ask before calling this.

Inputs: setId (required). Returns: setId, deleted

get_set_resultsGet how the learner didA
Read-only

Read back real study results for a set: which cards the learner marked hard (weakCards), which they never reached (untouchedCards), and per-card review counts. This is the feedback half of the loop — read it before writing the next set, and build the follow-up out of weakCards.

Inputs: setId (required), userId. Returns: cards, notes, setId, title, +7 more

get_study_setGet study set contentsA
Read-only

Read the full contents of a set — every card, plus the topic and notes you attached when you created it.

Inputs: setId (required). Returns: cards, notes, setId, title, +4 more

list_study_setsList study setsA
Read-only

List the sets you created for this learner, newest first, each with a progress summary. Use it to find a setId, or to see at a glance which sets were never opened.

Inputs: limit, topic, userId, includeProgress. Returns: sets, count

notify_learnerPing the learnerA

Send the learner a Telegram message that a set is waiting. Use sparingly — one ping per set, right after you create it.

Inputs: setId (required), text. Returns: setId, notified, telegramId

update_study_setUpdate a study setA
Idempotent

Change a set in place: retitle it, retag it, or add cards. Pass addCards to append (the usual case after reviewing results) or cards to replace the list wholesale — never both. Replacing the cards resets what the learner has already studied.

Inputs: setId (required), cards, notes, title, +4 more. Returns: setId, updated, cardCount

vocabit_healthCheck Vocabit connectionA
Read-only

Verify the server can reach Vocabit and report which mode it is in (live backend or in-memory demo). Call this first if anything else fails.

Inputs: no named parameters. Returns: mode, baseUrl, defaultUserId

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: health check, CRUD for study sets, results feedback, and learner notification. Even get_study_set and get_set_results are unambiguously separated—one retrieves content, the other study metrics. No two tools appear to do the same thing.

    Naming Consistency4/5

    Most tools follow a verb_noun pattern (create_study_set, list_study_sets, update_study_set, delete_study_set, get_study_set, get_set_results). However, vocabit_health deviates from the verb-first style and notify_learner uses a non-set object, so the pattern is not perfectly uniform but remains predictable.

    Tool Count5/5

    8 tools is well within the ideal 3-15 range and each earns its place in the set lifecycle. The count matches the server's scope—managing study sets with health check and notification—without redundancy or unnecessary bulk.

    Completeness5/5

    The tool surface covers the full lifecycle: create, read, update, delete, list, plus results feedback and learner notification. The feedback loop is closed by get_set_results informing update_study_set. Health check aids debugging. No obvious gaps that would cause agent failures.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to search the Inoh dictionary and create, update, or delete vocabulary flashcards in the user's Inoh account through natural language.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI assistant to act as the memory of a personal English-learning app: read progress and words due for review, run short practice conversations, and store sentences, corrections, new words, rubric scores, and checked exercises back to the user's dashboard. Also lets the assistant grow the flashcard deck and adjust word familiarity, which reschedules spaced-repetition reviews.
      MIT