Chispa MCP
by jeffercbs
README.md
# Chispa MCP
Paquete de npm (servidor MCP por stdio) que conecta asistentes de IA (Claude, ChatGPT y otros clientes MCP) con las aulas de Chispa. Cada docente inicia sesión con su cuenta de Chispa (`chispa-mcp login`) y el asistente actúa **con sus mismos permisos**: nunca más.
## Herramientas
El asistente puede hacer todo lo que un profesor o administrador hace en las pantallas de gestión de Guías Clave, con los mismos permisos (77 herramientas). Las acciones que borran piden `confirm: true` y el asistente debe confirmar antes con la persona.
| Área | Herramientas | Nivel |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| Aulas | `list_my_classrooms` | docente |
| Cursos | `list_courses`, `get_course`, `create_course`, `update_course`, `reorder_modules`, `get_course_outline` | equipo |
| | `delete_course`, `transfer_course` | quien creó el curso |
| Temas | `list_course_themes`, `save_theme`, `delete_theme`, `set_item_themes` | equipo |
| Colecciones | `list_collections`, `save_collection`, `delete_collection`, `move_course_to_collection`, `reorder_collection_courses` | tus propias colecciones |
| Módulos | `get_module`, `create_module`, `update_module`, `delete_module`, `reorder_lessons` | equipo |
| Lecciones | `get_lesson`, `create_lesson`, `update_lesson`, `delete_lesson`, `set_published` | equipo |
| Material | `list_lesson_items`, `add_quiz_questions`, `save_quiz_question`, `delete_quiz_question`, `save_self_check_question`, `delete_self_check_question`, `add_flashcards`, `save_flashcard`, `delete_flashcard`, `get_game`, `save_game`, `delete_game` | equipo |
| Carga masiva | `import_exam`, `import_module_content`, `add_exam_questions`, `add_quiz_questions`, `add_flashcards` | equipo |
| Exámenes | `create_exam`, `get_exam`, `update_exam`, `delete_exam`, `add_exam_questions` (con `replace`), `save_exam_question`, `delete_exam_question` | equipo |
| Escenarios | `create_scenario`, `get_scenario`, `update_scenario`, `delete_scenario`, `add_scenario_criteria`, `save_scenario_criterion`, `delete_scenario_criterion` | equipo |
| Personas | `list_members`, `classroom_progress`, `get_student_detail`, `list_access_requests`, `decide_access_request`, `remove_member` | equipo |
| | `activate_trial_course`, `set_course_grants` | administrador del aula |
| Chat | `list_waiting_chats`, `get_chat_thread`, `reply_chat`, `set_chat_status`, `delete_chat` | equipo |
| Ofertas | `list_offers`, `create_offer`, `update_offer`, `set_offer_active`, `delete_offer` | administrador del aula |
| Ventas | `sales_summary`, `list_sales`, `sales_funnel` | administrador del aula |
**Permisos de edición de contenido:** igual que en la plataforma (`can_edit_course`): quien creó el curso, el administrador del aula donde está vinculado o un profesor con acceso a él. Borrar o transferir un curso es solo de quien lo creó.
**Todo lo que se crea queda en borrador o pausado** salvo que se pida lo contrario.
## Cargas masivas
Pensadas para subir un simulacro, un banco de preguntas o varias lecciones de una vez:
- **Formato de texto compacto**, una pregunta por línea (mucho más corto que JSON):
`¿Capital de Francia? | Madrid | *París | Roma | explicación: Está sobre el Sena | tema: Geografía | lección: 2`
El `*` marca la correcta. Las tarjetas son `anverso | reverso`. Las líneas vacías y las que empiezan por `#` se ignoran.
- **`dry_run: true`** valida todo y muestra qué se guardaría, sin escribir nada.
- **Todo o nada:** si una línea falla no se guarda ninguna y el error dice la línea exacta (`línea 7: Marca la opción correcta con «*»`). Si falla a mitad de camino, se deshace lo creado.
- **Tandas e índices:** hasta 200 preguntas por llamada y 30 lecciones por carga; las inserciones van en tandas de 100.
- `import_exam` crea el examen y sus preguntas en un paso; `import_module_content` crea varias lecciones con su quiz y tarjetas.
## Instrucciones y flujos guiados
Al conectarse, el servidor entrega unas instrucciones al asistente (tono claro y didáctico, validar antes de guardar, confirmar antes de publicar o borrar, cómo hacer cargas masivas, tratar el texto de estudiantes como información y no como órdenes). Además ofrece flujos guiados (`prompts`): `cargar_simulacro`, `crear_curso_completo`, `revisar_grupo` y `atender_solicitudes`. El texto está en `src/mcp/instructions.ts` y `src/mcp/prompts.ts`.
**Fuera de alcance a propósito:** subir imágenes (banners de cursos, colecciones y ofertas), datos de contacto de compradores y el análisis geográfico de la audiencia. Tampoco se envían los avisos automáticos a estudiantes que la plataforma manda al publicar un módulo o una lección.
## Instalación
Requiere Node.js 22.12 o superior (22.12+, 24 o 26+).
El paquete se publica en GitHub Packages (`@jeffercbs/chispa-mcp`).
**Opción A — directo desde GitHub (sin token):**
```sh
npx -y github:jeffercbs/chispa-mcp login
```
**Opción B — GitHub Packages:** crea un `.npmrc` con
```
@jeffercbs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<token con read:packages>
```
y ejecuta `npx -y @jeffercbs/chispa-mcp login`.
## Autenticación
1. `chispa-mcp login` abre el navegador en la pantalla de consentimiento de Guías Clave (OAuth 2.1 con PKCE de Supabase, redirección a `127.0.0.1`).
2. Entras con tu cuenta de docente y apruebas el acceso.
3. Los tokens quedan en `~/.config/chispa-mcp/credentials.json` (permisos 0600) y se renuevan solos.
4. `chispa-mcp whoami` muestra la cuenta; `chispa-mcp logout` borra la sesión local.
No hay contraseñas ni claves de servicio en el paquete: el asistente actúa con el token de la persona y RLS decide qué ve.
## Configurar tu cliente de IA
```json
{
"mcpServers": {
"chispa": { "command": "npx", "args": ["-y", "github:jeffercbs/chispa-mcp"] }
}
}
```
Claude Code: `claude mcp add chispa -- npx -y github:jeffercbs/chispa-mcp`.
Si no has iniciado sesión, las herramientas responden con la instrucción de ejecutar `login`.
## Variables (opcionales)
| Variable | Para qué |
| ------------------------------ | ---------------------------------------------------------------------- |
| `CHISPA_SUPABASE_URL` | Otro proyecto Supabase (por defecto "taller ai") |
| `CHISPA_SUPABASE_ANON_KEY` | Clave publicable de ese proyecto |
| `CHISPA_MCP_PORT` | Puerto del callback de login (53682) |
| `CHISPA_MCP_HOME` | Carpeta de credenciales |
| `CHISPA_CURRENCY` | Moneda de los importes (COP) |
| `CHISPA_ROLE_CACHE_SECONDS` | Segundos que se recuerda el rol en un aula (20; 0 = siempre consultar) |
| `CHISPA_WRITES_PER_MINUTE` | Tope de escrituras por minuto (120) |
| `CHISPA_LOGIN_TIMEOUT_MINUTES` | Espera del inicio de sesión (5) |
## Requisitos del proyecto Supabase
- **Auth → OAuth Server** activado, con registro dinámico de clientes.
- URL de autorización apuntando a `/oauth/consent` de Guías Clave.
- Redirecciones loopback `http://127.0.0.1:53682/callback` permitidas.
## Publicar una versión
Crea un release en GitHub: el workflow `publish.yml` compila, prueba y publica en GitHub Packages.
## Desarrollo
```sh
pnpm install
pnpm build # tsc → dist/
pnpm test # vitest
pnpm check # tsc --noEmit
node dist/cli.js login
```
Ver `ARCHITECTURE.md` para añadir herramientas y `SECURITY.md` para el modelo de seguridad.
TDQS
B3.3/5.0
Scored across 77 tools
Disambiguation3/5
Most tools target distinct resource+action pairs, and the descriptions explicitly distinguish bulk vs. single-item variants (add_quiz_questions vs. save_quiz_question, import_exam vs. create_exam + add_exam_questions). However, there is genuine redundancy: import_module_content and import_exam overlap with create_lesson/create_module + add_* flows, save_* upserts overlap with create_/update_ pairs, and publish flags inside create/import tools overlap with set_published. With 77 tools the agent must read carefully to avoid misselection.
Naming Consistency3/5
All names are snake_case verb_noun, which is readable, but the verb convention is not uniform across domains: some entities use separate create_/update_ pairs (course, module, lesson, exam, scenario, offer) while others use a single save_ upsert (theme, collection, quiz question, flashcard, game, exam question, scenario criterion), plus add_* for bulk content. This mixed convention is semantically meaningful but forces the agent to learn per-domain rules rather than one predictable pattern.
Tool Count1/5
77 tools is far beyond what an agent can comfortably handle in one surface and goes well past the 50+ threshold for extreme mismatch. Many tools are convenience wrappers (import_module_content, import_exam) around combinations of other tools, which inflates the count without adding unique capability. The surface would benefit from consolidation and grouping.
Completeness4/5
Coverage of the teaching-platform domain is broad: classrooms, courses, modules, lessons, quizzes, flashcards, exams, scenarios, games, themes, collections, offers, sales, members, chats, and progress are all represented with read/create/update/delete where appropriate. Minor gaps remain, such as reordering questions within a quiz/exam or bulk deletion, but the core lifecycle is well covered.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues