goalslot-mcp

Un servidor MCP para GoalSlot. Proporciona a un asistente de IA herramientas para objetivos, tareas, la plantilla de horario semanal, el seguimiento del tiempo, el temporizador compartido, informes, notas y el diario, contra tu propia cuenta de GoalSlot.

Se ejecuta sobre stdio, por lo que cualquier host MCP puede lanzarlo. Incluye cuatro habilidades que enseñan a un modelo cómo usar bien las herramientas.

Instalación

Primero necesitas la goalslot CLI con sesión iniciada, porque este servidor lee la credencial que la CLI escribe. Nunca ejecuta un flujo de inicio de sesión por sí mismo.

npm install -g goalslot-cli
goalslot login

Luego añade el servidor MCP a Claude Code:

claude mcp add goalslot -- npx -y goalslot-mcp

Para Claude Desktop, o cualquier host que acepte una configuración JSON:

{
  "mcpServers": {
    "goalslot": {
      "command": "npx",
      "args": ["-y", "goalslot-mcp"]
    }
  }
}

Comprueba que funciona:

npx -y goalslot-mcp --list-tools

Este paquete aún no está publicado en npm. Hasta que lo esté, instálalo desde el código fuente: clona el repositorio, ejecuta npm install && npm run build, y luego apunta el host a node /path/to/goalslot-mcp/dist/cli.js.

Related MCP server: GoHighLevel MCP Server

Cómo funciona la autenticación

No hay flujo de inicio de sesión en este servidor. stdio es el canal de protocolo, por lo que un servidor no puede solicitar nada, y pedir a un modelo que maneje un token sería peor. Lee una credencial que ya existe en la máquina.

Orden de resolución:

1. GOALSLOT_ACCESS_TOKEN del entorno, si está definido y no vacío.

2. $GOALSLOT_CONFIG_DIR/credentials.json.

3. %APPDATA%\goalslot\credentials.json en Windows.

4. $XDG_CONFIG_HOME/goalslot/credentials.json, o si no ~/.config/goalslot/credentials.json.

El archivo lo escribe goalslot login y se comparte con la CLI. Su forma:

{
  "version": 1,
  "apiBaseUrl": "https://api.goalslot.io/api",
  "apiUrl": "https://api.goalslot.io/api",
  "accessToken": "<jwt>",
  "refreshToken": "gsl_rt_...",
  "accessTokenExpiresAt": "2026-08-25T12:00:00.000Z",
  "refreshTokenExpiresAt": "2026-11-23T00:00:00.000Z",
  "tokenId": "<uuid>",
  "scopes": ["full"],
  "user": { "id": "...", "email": "..." },
  "defaultTimezone": "Asia/Karachi",
  "weekStartsOn": 1
}

Tanto apiBaseUrl como apiUrl se leen y se escriben con el mismo valor, para que la CLI y este servidor no se pisen entre sí. Las claves desconocidas sobreviven a una reescritura.

Los tokens de la CLI son JWTs Bearer ordinarios que llevan typ: "cli" y una reclamación cid que nombra la fila de token revocable, y todas las rutas normales de la API los aceptan. Los tokens de acceso duran una hora. Ante un 401, este servidor rota el token de refresco contra POST /api/auth/cli/token/refresh, escribe el nuevo par en disco atómicamente antes de usarlo, y reproduce la solicitud original una vez. La rotación es de un solo vuelo: los tokens de refresco son de un solo uso, y reproducir uno ya rotado revoca toda la credencial, por lo que dos refrescos concurrentes serían un cierre de sesión permanente.

Ningún token, cabecera o línea de Authorization se escribe jamás en ningún registro, en ningún nivel.

Si la credencial falta o está muerta, cada herramienta devuelve un NOT_AUTHENTICATED o SESSION_EXPIRED estructurado que le dice al modelo que tú ejecutes goalslot login. No te pedirá que pegues un token.

Sin interfaz y CI

GOALSLOT_ACCESS_TOKEN anula el archivo por completo. Combínalo con GOALSLOT_REFRESH_TOKEN si quieres que el refresco funcione; sin él, el refresco está deshabilitado y la sesión muere cuando expira el token de acceso de una hora. Para cualquier cosa de larga duración, establece GOALSLOT_CONFIG_DIR en su lugar y deja que el servidor gestione el archivo.

Herramientas

Nueve herramientas de lectura y nueve de escritura. Las herramientas de lectura son seguras de llamar libremente y están anotadas con readOnlyHint. La descripción de cada herramienta de escritura comienza con WRITES. y nada de lo expuesto aquí elimina datos del usuario.

Lectura

Escritura

Deliberadamente no son herramientas

Eliminar objetivos, tareas y entradas de tiempo; borrar todo el horario; compartir cualquier cosa públicamente o con otra persona; los endpoints de chat del coach de IA; facturación y ajustes de cuenta; importaciones de plantillas. La destrucción con efectos en cascada y cualquier cosa que publique datos personales pertenece a donde un humano lo escribe, no a donde un agente pueda llamarlo en un bucle. Usa la aplicación GoalSlot o la CLI.

Convenciones que aplican las herramientas

• Las duraciones son minutos enteros, siempre llamadas durationMinutes, nunca una duration simple. Las lecturas también devuelven durationHours como flotante solo para mostrar. El targetHours de un objetivo es la única excepción.

• Las fechas son YYYY-MM-DD y se rechazan en el límite si llevan una hora. "Hoy" se calcula en tu zona horaria, no a partir de una rebanada ISO UTC.

• El horario es una plantilla semanal repetitiva, no eventos con fecha. Cada descripción de herramienta relevante lo dice.

• dayOfWeek es primero el domingo (0 = domingo), que no es el orden de lunes primero que usan los informes semanales. Ambos están etiquetados en línea y cada respuesta lleva un dayName.

• Los cubos semanales se recalculan a partir de las fechas de las entradas en lugar de leer la columna dayOfWeek almacenada de la API, que se deriva en la zona horaria del servidor de la API y puede estar desviada en uno.

Errores

Los fallos vuelven como isError: true con un objeto JSON:

{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "You've reached your FREE plan limit for goals.",
    "httpStatus": 403,
    "retryable": false,
    "remedy": "The account is at its goal limit. Ask the user to pause a goal with update_goal (status PAUSED), delete one from the CLI, or upgrade. Do not retry.",
    "details": { "plan": "FREE", "limitType": "goals" }
  }
}

remedy está escrito en imperativo, para el modelo. Códigos: NOT_AUTHENTICATED, SESSION_EXPIRED, PLAN_LIMIT, FORBIDDEN, SCHEDULE_CONFLICT, INVALID_INPUT, NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, WRITE_BUDGET_EXCEEDED, READ_ONLY_MODE, TIMER_ALREADY_RUNNING, NO_TIMER_RUNNING.

Habilidades

Cuatro habilidades se incluyen en skills/. Llevan el juicio que las descripciones de herramientas no pueden: en qué orden llamar las cosas, qué confirmar antes de escribir y qué no decir.

Instálalas en Claude Code copiando los directorios en tu carpeta de habilidades:

# macOS and Linux
cp -r "$(npm root -g)/goalslot-mcp/skills/"* ~/.claude/skills/

# Windows PowerShell
Copy-Item "$(npm root -g)\goalslot-mcp\skills\*" "$env:USERPROFILE\.claude\skills\" -Recurse

Desde un clon, copia skills/* del repositorio en su lugar. El ámbito de proyecto también funciona: ponlas en .claude/skills/ dentro de un repositorio.

Configuración

Transporte HTTP

Opcional, detrás de una bandera:

npx -y goalslot-mcp --http --port 7801

Sirve el mismo registro de herramientas en http://127.0.0.1:7801/mcp a través del transporte HTTP transmisible, sin estado.

Esto es de un solo usuario y solo local. Cada solicitud se atiende con las credenciales de GoalSlot de esta máquina. No hay autenticación por llamante, ni OAuth ni custodia de tokens, por lo que cualquiera que pueda acceder al puerto puede leer y escribir en la cuenta. Se vincula a loopback y debería permanecer así. No es el servidor MCP multiinquilino alojado que se sigue en goal-slot-api#55; eso requiere un flujo OAuth real y almacenamiento de tokens por usuario, que es un trabajo diferente.

stdio es la vía compatible.

Desarrollo

npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --list-tools

TypeScript estricto, ESM, Node 20 o superior. Las pruebas son vitest con fetch simulado; nada en el conjunto toca una API en vivo. CI ejecuta typecheck, pruebas y compilación en Node 20 y 22 en Ubuntu y Windows.

Licencia

MIT