vocabit-mcp

Un servidor MCP para Vocabit, una aplicación de tarjetas de estudio (flashcards). Permite que un asistente de IA escriba un set de estudio en una aplicación real, en un teléfono real, y luego lea cómo le ha ido de verdad al estudiante con él.

La mayoría de los servidores MCP leen de una API. Este cierra el ciclo:

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

La herramienta interesante no es create_study_set — cualquiera puede generar tarjetas. Es get_set_results: qué tarjetas marcó el estudiante como difíciles, a cuáles nunca llegó, cuántos repasos necesitó cada una. El siguiente set se construye a partir de eso, no de una suposición.

Pruébalo en 30 segundos

Sin backend, sin cuenta, sin clave de API:

npx -y vocabit-mcp --demo

El modo demo ejecuta el mismo servidor contra un Vocab en memoria con dos sets precargados. Crea un set, pide los resultados y un estudiante sustituto determinista lo habrá trabajado — señalado en la respuesta como simulado, para que nunca se confunda con datos reales.

Para probarlo desde una interfaz gráfica:

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

Instalación

Está listado en el MCP Registry como io.github.JohnBilousov/vocabit-mcp, de modo que los clientes que consultan el registro pueden encontrarlo por sí solos.

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

Elimina el bloque env para ejecutarlo en modo demo.

Herramientas

También se exponen el recurso vocabit://set/{setId} (un set como JSON, listable) y un prompt study-session que recorre todo el ciclo.

Estados de tarjetas

Un set devuelve completed: true cuando no queda ninguna tarjeta en new.

Modo en vivo

Apunta el servidor a un backend de Vocabit con la API de agente habilitada:

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

Si no se define ni la URL ni la clave, el servidor se inicia en modo demo. Si se define exactamente una, se niega a arrancar — media configuración es un error, no una pista.

Notas de diseño

El modo de demostración es un cliente de primera clase, no un stub. HttpVocabitClient y DemoVocabitClient implementan la misma interfaz VocabitClient, así que no hay ninguna herramienta con una rama para “¿estamos simulando?”. Un revisor puede ejecutar el servidor antes de tener credenciales, y la suite de pruebas ejercita la superficie real de las herramientas sobre un transporte MCP real, en lugar de simular el SDK.

Los errores son recuperables, no fatales. Una llamada fallida devuelve isError con el mensaje del propio backend y una pista orientada al modelo — un 404 dice “llama a list_study_sets para ver qué conjuntos existen”, un 401 dice “o ejecuta la guía con VOCABIT_DEMO=1”. Los argumentos mutuamente excluyentes se rechazan con una explicación en lugar de una suposición.

Los esquemas de salida se mantienen flexibles en los bordes. Los campos identificativos son obligatorios; todo el resto es opcional, de modo que un backend que agregue un campo no convierte una herramienta a un error de validación.

Las anotaciones son honestas. delete_study_set está marcado como destructiveHint; las herramientas de lectura, como readOnlyHint. notify_learner envía un mensaje a una persona real, y su descripción dice que se utilice con moderación.

Desarrollo

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

Hoja de ruta

• Transporte Streamable HTTP junto con los gastos de stdio

• Soporte para varios estudiantes sin un UID por defecto en el backend

• Tarjetas con audio de pronunciación

• Publicar en el patrón del MCP Registry

Licencia

MIT © Ivan Bilousov# vocabit-mcp

Un servidor MCP para Vocabit, una aplicación de tarjetas de estudio (flashcards). Permite que un asistente de IA escriba un set de estudio en una aplicación real, en un teléfono real, y luego lea cómo le ha ido realmente al estudiante con él.

La mayoría de los servidores MCP leen de una API. Este cierra el ciclo:

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

La herramienta interesante no es create_study_set — cualquiera puede generar tarjetas. Es get_set_results: qué tarjetas marcó el estudiante como difíciles, a cuáles nunca llegó, cuántos repasos necesitó cada una. El siguiente conjunto se construye a partir de eso, no de una suposición.

Pruébalo en 30 segundos

Sin backend, sin cuenta, sin clave de API:

npx -y vocabit-mcp --demo

El modo demo ejecuta el mismo servidor contra un Vocabit en memoria con dos sets precargados. Crea un set, pide resultados y un estudiante determinista de reemplazo lo habrá trabajado — marcado en la respuesta como simulado, para que nunca se confunda con datos reales.

Para probarlo con una interfaz gráfica:

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

Instalación

Está listado en el MCP Registry como io.github.JohnBilousov/vocabit-mcp, de modo que los clientes que leen del registro pueden encontrarlo por su cuenta.

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

Quita el bloque env para ejecutar en modo demo.

Herramientas

También se exponen: el recurso vocabit://set/{setId} (un set como JSON, listable) y un prompt study-session que recorre todo el ciclo.

Estados de las tarjetas

El progreso proviene del motor de repetición espaciada de la aplicación, no del asistente:

Un set inform de completed: true cuando no queda ninguna tarjeta en new.

Modo en vivo

Apunta el servidor a un backend de Vocabit con la API del agente habilitada:

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

Si no se define ni URL ni clave, el servidor arranca en modo demo. Si se define la exactamente una, se niega a arrancar — dos configuración a medias es un error, no una pista.

Diseño

El modo demo es un cliente de primera clase, no un stub. HttpVocabitClient y DemoVocabitClient implementan la misma interfaz VocabitClient, de modo que ninguna herramienta tiene una rama para “¿estamos fingiendo?”. Un revisor puede ejecutar el servidor antes de tener credenciales, y la suite de pruebas ejercita la superficie real de las herramientas sobre un transporte MCP real, en lugar de simular el SDK.

Los errores son recuperables, no fatales. Una llamada fallida vuelve con isError con el mensaje del propio backend y una pista orientada al modelo — 404 dice “llama a list_study_sets para ver qué sets existen”, 401 dice “o ejecuta con VOCABIT_DEMO=1”. Los argumentos mutuamente excluyentes se rechazan con una explicación en lugar de una suposición.

Los esquemas de salida se mantienen flexibles en los bordes. Los campos de identificación son obligatorios; todo lo demás es opcional, así un backend que añade un campo no convierte una herramienta funcional en un error de validación.

Las anotaciones son honestas. delete_study_set está marcado con destructiveHint; readOnlyHint las herramientas de lectura. notify_learner manda un mensaje a una persona real y su descripción dice que se use con moderación.

Desarrollo

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

Futuro

• Transporte Streamable HTTP junto con un estándar stdio

• Soy voz multi-estudiante sin UID predeterminado del backend

• Tarjetas con pronunciación de audio

• Publicar en el registro MCP

Licoria

MIT © Ivan Bilousov