vocabit-mcp

MCP-сервер для Vocabit, приложения с карточками для запоминания. Он позволяет ИИ-ассистенту записать учебный набор в настоящее приложение на настоящем телефоне, а затем прочитать, как ученик на самом деле с ним справился.

Большинство MCP-серверов читают данные из API. Но этот замыкает цикл:

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

Интересен не create_study_set — генерировать карточки умеет что угодно. Интересен get_set_results: какие карточки ученик отметил как сложные, до каких так и не добрался, сколько повторений потребовалось каждой. На этих данных строится следующий набор, а не на догадке.

Попробуйте за 30 секунд

Ни бэкенда, ни аккаунта, ни API-ключа:

npx -y vocabit-mcp --demo

Демонстрационный режим запускает тот же сервер на основе Vocabit в памяти, где заранее загружены два набора. Создайте набор, запросите результаты — и детерминированный ученик-симулятор с ним справится. В ответе это помеченное как симуляция, так что такие данные никогда не спутать с настоящими.

Чтобы попробовать его в интерфейсе:

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

Установка

Сервер внесён в MCP Registry как io.github.JohnBilousov/vocabit-mlZero; обычные клиенты, читающие реестр, могут найти его сами.

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

Уберите блок env, чтобы запуститься в демонстрационном режиме.

Инструменты

Также есть ресурс vocabit://set/{setId} (набор как JSON, доступный для перечисления) и промпт study-session, который проводит весь цикл.

Статусы карточек

Прогресс берётся из механизма интервальных повторений приложения, а не строится ассистентом:

Набор возвращает completed: true, когда в new не остаётся ни одной карточки.

Боевой режим

Подключите сервер к бэкенду Vocab, в котором включён agent API.

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

Если не заданы ни URL, ни ключ, сервер запускается в демо-режиме. Если задан только один, он отказывается работать — неполная конфигурация это ошибка, а не намёк.

Дизайн-заметки

Демо-режим — полноценный клиент, а не заглушка. HttpVocabitClient и DemoVocabitClient реализуют один и тот же интерфейс VocabitClient, поэтому ни один инструмент не знает, что он «притворяется». Ревьюер может запустить сервер до получения учётных данных, а тестовая среда проверяет реальную инструментальную поверхность через настоящий MCP-транспорт, а не через мок SDK.

Ошибки восстановимы, а не фатальны. Неудачный вызов возвращается как isError: своё сообщение бэкенда плюс подсказка для модели: 404 говорит «вызовите list_study_sets, чтобы посмотреть, какие наборы существуют», 401 — «или запустите с VOCABIT_DEMO=1». Конфликтующие аргументы отклоняются с объяснением, а не потому что «отгадано».

Схемы вывода остаются свободными по краям. Идентифицирующие поля обязательны, остальные — нет. Поэтому если бэкенд добавит новое поле, рабочий инструмент не превратится в ошибку валидации.

Аннotations честные. delete_study_set помечен как destructiveHint, инструменты чтения — readOnlyHint. notify_learner посылает сообщение реальному человеку, и в описании сказано использовать его экономно.

Разработка

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

Пайплайн

• Потоковый HTTP-транспорт сопровmitting с stdio

• Поддержка нескольких учеников без стандартного UID бэкенда

• Карточки с аудиопроизношением

• Публикация в реестре MCP

LICENSE

MIT © John Belousov

MIT © Ivan Bilousov