vocabit-mcp

Ein MCP-Server für Vocabit, eine Karteikarten-App. Er ermöglicht es einem KI-Assistenten, ein Lernset in eine echte App auf einem echten Telefon zu schreiben und dann auszulesen, wie die lernende Person damit wirklich zurechtgekommen ist.

Die meisten MCP-Server lesen aus einer API. Dieser hier schließt einen Kreis:

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

Das interessanteste Werkzeug ist nicht create_study_set – das kann ohnehin jede Anwendung. Es ist get_set_results: Welche Karten hat die lernende Person als schwer markiert, welche hat sie nie erreicht, wie viele Wiederholungen hat jede Karte gebraucht. Das nächste Lernset entsteht daraus – nicht aus einer Vermutung.

In 30 Sekunden ausprobieren

Kein Backend, kein Konto, kein API-Schlüssel:

npx -y vocabit-mcp --demo

Im Demo-Modus läuft derselbe Server gegen ein In-Memory-Vocabit mit zwei bereits angelegten Sets. Erstelle ein Lernset, frage die Ergebnisse ab, und ein deterministischer Ersatz-Lernender wird es durchgearbeitet haben – in der Antwort als simuliert gekennzeichnet, damit es nie mit echten Daten verwechselt wird.

Zum Herumprobieren mit einer Benutzeroberfläche:

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

Installation

Im MCP Registry ist er als io.github.JohnBilousov/vocabit gelistet, sodass Clients, die das Registry lesen, ihn von selbst finden können.

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

Den env-Block entfernen, um den Server im Demo-Modus zu starten.

Werkzeuge

Außerdem werden bereitgestellt: die Ressource vocabit://set/{setId} (ein Lernset als JSON, aufführlistbar) und ein Prompt study-session, der den gesamten Kreislauf durchläuft.

Kartenstatus

Der Fortschritt stammt aus der Spaced-Repetition-Engine der App, nicht vom Assistenten:

Ein Lernset zeigt completed: true, sobald keine Karte mehr den Status new hat.

Live-Modus

Richte den Server auf ein Vocab-Backend, bei dem die Agent-API aktiviert ist:

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

Setzt man weder URL noch Schlüssel, startet der Server im Demo-Modus. Setzt man genau eines davon, weigert er sich zu starten – eine halbe Konfiguration ist ein Fehler, kein Hinweis.

Design-Notizen

Der Demo-Modus ist erstklassiger Client, kein Stub. HttpDemoClient und DemoVocabitClient implementieren dasselbe VocabitClient-Interface, daher hat kein Werkzeug einen Zweig für „Tun wir gerade bloß so?“. Eine prüfende Person kann den Server starten, bevor sie Zugangsdaten hat, und die Testsuite erprobt die echte Werkzeugoberfläche über echten MCP-Transport, statt das SDK zu mocken.

Fehler sind behebbar, nicht tödlich. Ein fehlgeschlagener Aufruf kommt als isError zurück, mit der eigenen Backend-Nachricht plus einem Hinweis an das Modell – 404 sagt „Ruf list_study_sets auf, um zu sehen, welche Lernsets existieren“, 401 sagt „oder starte mit VOCABIT_DEMO=1“. Sich gegenseitig ausschließende Argumente werden mit einer Erklärung abgelehnt, nicht mit einer Vermutung.

Ausgabeschhemas bleiben an den Rändern lose. Identifizierende Felder sind erforderlich; alles andere ist optional, sodass ein Backend, das ein Feld ergänzt, kein funktionierendes Werkzeug in einen Validierungsfehler verwandelt.

Annotationen sind ehrlich. delete_study_set ist mit destructiveHint markiert, die Lese-Werkzeuge mit readOnlyHint. notify_learner schreibt eine echte Person an, und die Beschreibung rät, es sparsam zu verwenden.

Entwicklung

git clone https://github.com/JohnBilousov/vocabit-mcp && cd vocabit-mcp
npm install
npm run build
npm test          # tool surface + full loop over an in-memory MCP transport
npm run inspect   # demo mode in the MCP Inspector

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

Roadmap

• Streamable HTTP-Transport neben stdio

• Unterstützung für mehrere Lernende ohne Backend-Standard-UID

• Karten mit Audio-Aussprache

• Veröffentlichung im MCP Registry

Lizenz

MIT © Ivan Bilous