Vocabit

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

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"      }    }  }}

Tools

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:

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.comexport VOCABIT_AGENT_KEY=...   # must match one of AGENT_API_KEYS on the backendnpx -y vocabit-mcp

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-mcpnpm installnpm run buildnpm test          # tool surface + full loop, plus the HTTP client against a mocked fetchnpm run lint      # eslintnpm run format    # prettier --writenpm 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 modetest/  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