MCP de BIMP

Servidor MCP que conecta un cliente de IA (Claude Desktop, Claude Code) directamente con la base de datos de la app (Firestore, el mismo proyecto bimp-platform que usa la app web). Permite hacer preguntas en lenguaje natural sobre proyectos y tareas ("¿cuántas tareas abiertas tenemos?", "¿quién tiene más tareas asignadas?") y también crear/editar/borrar datos sin pasar por un formulario en la app.

Es un proyecto Node separado de la app web (tiene su propio package.json) porque corre como proceso local en la máquina de cada persona, no en el navegador.

Por qué existe

La app todavía no tiene pantallas para editar categorías, clientes, proyectos ni tareas (solo lectura). Mientras esas pantallas no existan, este MCP permite hacer esas operaciones vía un cliente de IA en lugar de construir formularios — ver la sección correspondiente de este README en el repositorio raíz (AGENTS.md) para el contexto completo del proyecto.

Cómo funciona

• Usa firebase-admin con una cuenta de servicio de Firebase (la misma que ya usan scripts/seed-data.mjs y scripts/seed-users.mjs).
• Importante: el Admin SDK de Firebase ignora firestore.rules por completo — tiene acceso total a la base de datos sin las restricciones que aplican en el navegador. Por eso este servidor solo debe correr localmente, en la máquina de alguien ya autorizado a tocar los datos de BIMP, con su propia copia de la credencial (nunca se sube a git ni se publica en el paquete de npm), y cada herramienta valida a mano lo que un formulario validaría (que el proyecto/categoría/persona exista, etc.) antes de escribir.
• Las herramientas están organizadas por colección en src/tools/ (categorias.ts, clientes.ts, proyectos.ts, tareas.ts). src/util.ts tiene las funciones compartidas (buscar por texto parcial, generar ids legibles, mensajes de error).
• Las herramientas de borrado (eliminar_*) exigen un parámetro confirmar: true y bloquean el borrado si hay datos que dependen de eso (ej. no se puede borrar una categoría con proyectos).

Uso dentro de este repo (desarrollo)

npm install
npm run build   # compila TypeScript a dist/

Ya está configurado como servidor MCP del proyecto (.mcp.json en la raíz) — cualquiera que abra el repo con Claude Code lo detecta automáticamente. Sin nada más que configurar: usa por defecto la serviceAccountKey.json de la raíz del repo (ver instrucciones en los comentarios de scripts/seed-data.mjs para generarla) — nunca se sube a git.

Uso instalado desde npm (para el resto del equipo)

Publicado como @bimpsas/platform-mcp. No hace falta clonar el repo ni tener Node instalado más allá de correrlo.

1. Pide una copia de la credencial de Firebase a quien administra la cuenta de BIMP (no se puede generar sola — da acceso total a la base de datos, así que se comparte solo por un canal seguro, nunca por chat público ni se sube a ningún repositorio). Guárdala en tu computador, ej. C:\Users\<tú>\bimp-serviceAccountKey.json.
2. Agrega esto a la configuración de tu cliente MCP (claude_desktop_config.json en Claude Desktop, o claude mcp add en Claude Code), con la ruta a tu copia del archivo:

{
  "mcpServers": {
    "bimp": {
      "command": "npx",
      "args": ["-y", "@bimpsas/platform-mcp"],
      "env": {
        "BIMP_SERVICE_ACCOUNT_KEY": "C:\\Users\\<tú>\\bimp-serviceAccountKey.json"
      }
    }
  }
}

3. Reinicia el cliente. La primera vez, npx descarga el paquete automáticamente.

Cómo hacer cambios: desarrollar → probar en local → publicar

Flujo completo para modificar una herramienta existente o agregar una nueva.

1. Crea una rama desde main (ej. feature/mcp-nombre-del-cambio) — igual que el resto del repo, no se comitea directo a main.
2. Edita el código en mcp-server/src/ (los archivos .ts, nunca los de dist/ — esos se generan solos).
3. Compila para generar dist/:

   cd mcp-server
   npm run build

4. Pruébalo en local antes de publicar nada. Este repo ya tiene el servidor registrado en .mcp.json apuntando a mcp-server/dist/index.js (el que acabas de compilar), así que:
   • Si estás en Claude Code, reinicia la sesión (o la ventana) — vuelve a leer .mcp.json y toma el build nuevo.
   • Si estás en Claude Desktop con la config apuntando a este repo (ruta absoluta a mcp-server/dist/index.js, ver más abajo), reinicia la app.
   • Prueba a mano las herramientas que cambiaste (pregúntale al agente algo que las use) contra datos de prueba — no contra proyectos/tareas reales. El proyecto ZZZ Pruebas MCP existe justo para esto.
5. Cuando quede bien, sube la versión del paquete (usa semver: patch para arreglos, minor para herramientas nuevas o cambios que no rompen nada existente, major si algo deja de funcionar como antes):

   npm version patch   # o minor/major

   Esto actualiza package.json y crea un tag de git con la versión.
6. Publica:

   npm publish

   Requiere sesión iniciada en npm (npm login) con acceso a la organización bimpsas, y va a pedir un código de un solo uso (OTP) por navegador — así que corre este comando tú mismo en tu terminal, no se puede automatizar.
7. Verifica que quedó publicado:

   npm view @bimpsas/platform-mcp

   Debe mostrar la versión nueva en dist-tags: latest.
8. Comitea y sube el cambio (código fuente + el package.json/package-lock.json con la versión nueva + el tag de git que creó npm version), abre el Pull Request y mergéalo a main — mismo flujo que el resto del repo.

Nota para el equipo: todos instalan con npx -y @bimpsas/platform-mcp, que siempre baja la última versión publicada — nadie tiene que actualizar nada manualmente después de un npm publish. Basta con que reinicien su cliente de Claude la próxima vez que lo abran.

Pendiente

• Colección users (equipo): sin herramientas todavía, a propósito.
• Mover una tarea de un proyecto a otro.
• Campo de "última actualización" en las tareas (hoy solo existe completedAt, cuando se completan).