@neonexai/beebole-mcp 1.0.0 → 1.0.2

package/README.md

@@ -59,38 +59,60 @@ Flujo para algo sin tool curada: **search → describe → graphql**.
 
 ---
 
-## Instalación
+## Requisitos en el PC
 
-Requisitos: **Node ≥ 18** y una **API key de Beebole** (`app.beebole.com → Settings → API`).
+- **Node ≥ 18** instalado (para `npx`). No hay que instalar nada más: el server se
+  descarga solo al arrancar con `npx`.
+- Una **API key de Beebole** (`app.beebole.com → Settings → API`).
+- **Conexión a internet**.
+- **NO hace falta tener Beebole abierto ni instalado.** Este MCP habla
+  directamente con la **API web** de Beebole (`app.beebole.com/graphql`) usando la
+  API key; funciona aunque no tengas Beebole abierto en el navegador.
 
-### A) Local en el PC del cliente (recomendado · stdio)
+## Instalación (local · stdio · recomendado)
 
-Se ejecuta directamente desde GitHub con `npx`, sin clonar nada:
+Publicado en npm como **[`@neonexai/beebole-mcp`](https://www.npmjs.com/package/@neonexai/beebole-mcp)**.
+`@latest` trae siempre la última versión.
+
+### Opción 1 — con el comando de Claude Code (si tienes el CLI `claude`)
 
 ```bash
-claude mcp add beebole \
-  --env BEEBOLE_API_KEY=TU_API_KEY \
-  -- npx -y github:NeoNexAI/beebole-mcp
+claude mcp add beebole -s user --env BEEBOLE_API_KEY=TU_API_KEY -- npx -y @neonexai/beebole-mcp@latest
 ```
 
-- `-s user` (scope usuario) lo deja disponible en **todos los proyectos** de ese PC:
-  ```bash
-  claude mcp add beebole -s user --env BEEBOLE_API_KEY=TU_API_KEY -- npx -y github:NeoNexAI/beebole-mcp
-  ```
-- En **Claude Desktop**, añade el bloque equivalente en su `mcp.json`:
-  ```json
-  {
-    "mcpServers": {
-      "beebole": {
-        "command": "npx",
-        "args": ["-y", "github:NeoNexAI/beebole-mcp"],
-        "env": { "BEEBOLE_API_KEY": "TU_API_KEY" }
-      }
+`-s user` lo deja disponible en **todos los proyectos** de ese PC.
+
+### Opción 2 — sin CLI, editando la configuración a mano
+
+Útil si usáis **Claude Desktop** o si el comando `claude` no existe en el equipo.
+Añade el bloque `"beebole"` dentro de `mcpServers` en el archivo de configuración
+y **reinicia la app**:
+
+- **Claude Desktop** → `C:\Users\<usuario>\AppData\Roaming\Claude\claude_desktop_config.json`
+  (en la app: *Settings → Developer → Edit Config*).
+- **Claude Code (config global de usuario)** → `C:\Users\<usuario>\.claude.json`,
+  bajo la clave raíz `mcpServers`.
+
+```json
+{
+  "mcpServers": {
+    "beebole": {
+      "command": "npx",
+      "args": ["-y", "@neonexai/beebole-mcp@latest"],
+      "env": { "BEEBOLE_API_KEY": "TU_API_KEY" }
     }
   }
-  ```
+}
+```
+
+Reinicia la app **del todo** (en Claude Desktop, ciérrala también desde el icono de
+la bandeja del sistema → Quit).
+
+> Si la app **no encuentra `npx`** (PATH), pon la ruta absoluta como `command`
+> (en PowerShell: `where.exe npx`), con barras dobles `\\` en el JSON.
+> Alternativa sin npm (no auto-actualiza, `npx` cachea el clon): `npx -y github:NeoNexAI/beebole-mcp`.
 
-Verifica la key **antes** de añadirlo (debe responder con tu nombre):
+### Verifica la key antes (debe responder con tu nombre)
 
 ```bash
 curl -s -H "apikey: TU_API_KEY" -H "Content-Type: application/json" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neonexai/beebole-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP server para Beebole (control de horas) — NeoNexAI. API GraphQL nueva (app.beebole.com): ~24 tools curadas (proyectos, tareas, personas, fichaje de horas, timesheets, informes) + passthrough GraphQL (search/describe/graphql) para cobertura total (87 queries + 745 mutations). Transportes: stdio (local) + Streamable HTTP (remoto).",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "schema.json"
+    "schema.json",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",
@@ -36,6 +37,18 @@
     "type": "git",
     "url": "git+https://github.com/NeoNexAI/beebole-mcp.git"
   },
+  "homepage": "https://github.com/NeoNexAI/beebole-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/NeoNexAI/beebole-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "beebole",
+    "time-tracking",
+    "graphql",
+    "neonexai"
+  ],
   "publishConfig": {
     "access": "public"
   }

package/skills/beebole-usage/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: beebole-usage
+description: >-
+  Guía para manejar bien el MCP de Beebole (control de horas). Úsala SIEMPRE que
+  el trabajo implique Beebole o cualquier tool `beebole_*` — fichar/consultar
+  horas, proyectos, tareas, personas, timesheets (aprobar/rechazar) o informes de
+  dedicación y rentabilidad. Explica el flujo correcto (curadas → search/describe/
+  graphql) y los gotchas de dominio (duración en MINUTOS, timestamps en
+  MILISEGUNDOS, categoría obligatoria al crear) que, si se ignoran, hacen fallar
+  las llamadas. Aunque el usuario no nombre "Beebole", si habla de fichajes,
+  partes de horas o dedicación por proyecto y el MCP está disponible, aplícala.
+---
+
+# Beebole — cómo usar el MCP bien
+
+El MCP habla con la API **GraphQL** de `app.beebole.com` (auth por cabecera
+`apikey`). Tiene **24 tools curadas** para el flujo normal de un estudio y **3
+genéricas** que cubren el 100% de la API (87 queries + 745 mutations). Tu trabajo
+es resolver la petición con el mínimo de llamadas y sin tropezar con el dominio.
+
+## Regla de oro de selección
+
+1. **¿Hay una tool curada para esto?** Úsala. Cubren lo habitual:
+   - Identidad: `beebole_whoami`
+   - Proyectos: `beebole_list_projects`, `beebole_get_project`, `beebole_add_project`
+   - Tareas: `beebole_list_tasks`, `beebole_get_task`, `beebole_add_task`
+   - Personas: `beebole_list_persons`, `beebole_get_person`, `beebole_add_person`
+   - Horas: `beebole_list_time_records`, `beebole_count_time_records`,
+     `beebole_add_time_record`, `beebole_edit_time_record`,
+     `beebole_delete_time_records`, `beebole_clone_time_records`
+   - Timesheets: `beebole_submit_timesheet`, `beebole_approve_timesheet`, `beebole_reject_timesheet`
+   - Catálogos: `beebole_list_tags`, `beebole_list_absence_types`
+   - Informes: `beebole_list_reports`, `beebole_run_report`, `beebole_planned_vs_real`
+2. **¿No hay tool curada?** Entonces el patrón de descubrimiento:
+   `beebole_search_schema "<palabra clave>"` → `beebole_describe_operation "<nombre>"`
+   (para ver argumentos y tipos exactos) → `beebole_graphql` con la query/mutation.
+   No inventes nombres de operación: descúbrelos siempre con search→describe primero.
+
+## Gotchas de dominio (la causa nº1 de fallos)
+
+Interioriza esto antes de escribir/leer datos; el schema no perdona:
+
+- **Duración de un fichaje = ENTERO en MINUTOS.** 1 h 30 min → `90`. Nunca horas
+  decimales (`1.5`) ni segundos. Si el usuario dice "2 horas", envía `120`.
+- **Timestamps = `BeeboleTimestamp` en MILISEGUNDOS** (epoch · 13 dígitos, `> 1e10`).
+  Una fecha en segundos (10 dígitos) se interpretará mal. Multiplica ×1000.
+- **Crear proyecto o tarea exige categoría:** `beebole_add_project` / `beebole_add_task`
+  requieren `categoryId` (o `parentId` para anidar). Sin ello la API rechaza con
+  `NoCategoryOrParentProvided`. Si no la tienes, descúbrela primero
+  (`search_schema "categor"` → describe → query de categorías) y pásala.
+- **Estados (`status`):** `d`=borrador, `s`=enviado, `a`=aprobado, `r`=rechazado.
+- **Color:** índice de paleta `0–71`. **Ausencias:** unidad `day` o `hour`.
+
+## Patrones frecuentes
+
+- **Fichar horas:** `beebole_add_time_record` con persona, tarea/proyecto, fecha
+  (ms) y `duration` en minutos. Confirma persona y proyecto con un `list_*` si hay duda.
+- **Horas por proyecto / rentabilidad:** primero `beebole_list_reports` para ver
+  los informes definidos; ejecuta con `beebole_run_report`. Para previsto vs. real,
+  `beebole_planned_vs_real`. Estos informes son la vía correcta para analítica, no
+  sumar fichajes a mano.
+- **Aprobar partes:** `submit` → `approve`/`reject`. Comprueba el estado antes.
+- **Borrados:** son destructivos y normalmente sin papelera. Antes de
+  `delete_time_records`, resume al usuario qué se va a borrar y pide confirmación.
+
+## Antes de operar
+
+- Si una llamada devuelve un error de permisos o vacío inesperado, lo más probable
+  es **API key inválida o sin permisos** para ese recurso, no un bug del MCP.
+- Verifica identidad con `beebole_whoami` si dudas de con qué usuario actúas (el
+  MCP actúa siempre como el dueño de la API key configurada).