Skip to main content
Glama
bluesurf-mcp-node

bluesurf-mcp-node

by oamilkar

bluesurf-mcp (Node.js)

Servidor MCP local para que Cursor u otros agentes lean tickets de BlueSurf, adjunten un archivo, publiquen un comentario y registren tiempo en el daily report. El CLI es login, logout, y sin argumentos el servidor por stdio.

El kanban se consulta con un POST de filtro. Las escrituras son adjuntar_archivo, agregar_comentario y registrar_tiempo.

Hace falta Node.js 20 o superior.

Instalación

npm install -g bluesurf-mcp
bluesurf-mcp --help

Related MCP server: ticket-triage-mcp

Desarrollo

Desde esta carpeta:

npm install
npm run build
npm test
node dist/bin.js --help

npm test compila y corre la suite (sin red).
npm publish compila antes de empaquetar.

Guardar credenciales (login / logout)

La contraseña no va en mcp.json. Una vez, en una terminal:

bluesurf-mcp login

Si no instalaste el paquete de forma global, el mismo login corre con npx:

npx -y bluesurf-mcp login

Pide usuario y contraseña, valida contra BlueSurf y guarda la contraseña en el almacén del sistema (Credential Manager en Windows, Keychain en macOS, Secret Service en Linux). El username queda en un JSON local, sin la contraseña.

El servicio se llama bluesurf-mcp-node y el usuario vive en:

  • Windows: %LOCALAPPDATA%\bluesurf-mcp-node\config.json

  • macOS / Linux: ~/.config/bluesurf-mcp-node/config.json (o XDG_CONFIG_HOME)

bluesurf-mcp logout

borra lo guardado.

Configuración (variables de entorno)

El entorno gana sobre lo guardado con login.

Claves canónicas BLUESURF_*; se aceptan SURF_* como fallback.

  • BLUESURF_BASE_URL — URL base (opcional; default https://surf.bluepeople.com).

  • BLUESURF_COOKIE — cookie de sesión ya válida → usa CookieAuth.

  • BLUESURF_USERNAME + BLUESURF_PASSWORD — credenciales → usa CredentialsAuth.

Precedencia: cookie en env → usuario/contraseña en env → bluesurf-mcp login.

El núcleo no persiste secretos. La cookie de sesión vive en memoria mientras corre el proceso.

Correr el servidor

bluesurf-mcp

Se comunica por stdio. Sin argumentos no pide contraseña: usa el entorno o las credenciales de login.

Registrar el MCP en Cursor

Con el paquete instalado de forma global:

{
  "mcpServers": {
    "bluesurf": {
      "command": "bluesurf-mcp"
    }
  }
}

npx descarga el paquete y ejecuta su binario:

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

-y evita la pregunta de confirmación de npx. Las variables BLUESURF_* en env siguen siendo válidas como override.

Esa configuración no pide la contraseña. Antes de usarla, guárdala una vez; Cursor reutiliza lo que quede en el almacén del sistema:

npx -y bluesurf-mcp login

Tools expuestas

  • mis_proyectos — proyectos del usuario (id, smallCode, code, name).

  • buscar_mis_tickets(project, include_closed=false) — tickets asignados al usuario.

  • obtener_ticket(code) — detalle de un ticket por su código (p. ej. PROJ-123).

  • listar_adjuntos(code) — archivos de la sección Files del ticket (id, name, is_image), sin descargarlos.

  • descargar_adjuntos(code, destino, archivo_id) — guarda esos archivos en destino. Con archivo_id descarga solo uno; si no, todos. Devuelve id, name, path, content_type y size.

  • adjuntar_archivo(code, ruta) — sube un archivo local a la sección Files. Devuelve id, name e is_image del archivo nuevo.

  • agregar_comentario(code, texto) — publica un comentario. El texto se escapa y se envuelve en un párrafo HTML. Devuelve id, author, body y created_at.

  • proyectos_reporte — proyectos activos para registrar tiempo (id, smallCode, code, name, categoryIds).

  • listar_categorias(proyecto) — subcategorías del usuario. Con proyecto (smallCode) solo las de ese proyecto.

  • mi_reporte_diario(fecha) — daily report de un día (YYYY-MM-DD). cerrado es true cuando status es 2.

  • registrar_tiempo(fecha, lineas, confirmar) — agrega una o más líneas y reenvía el día en un solo guardado. Cada línea lleva horas, categoria y, si aplica, descripcion, proyecto, ticket y pendiente. Sin ticket la descripción es obligatoria. confirmar cierra el día; por defecto guarda un borrador.

Usar el cliente desde Node

npm install bluesurf-mcp
import { BlueSurfClient, CredentialsAuth } from "bluesurf-mcp";

El paquete es solo ESM. El consumidor entrega las credenciales o la cookie. El paquete no las guarda.

Available Tools

5 tools
buscar_mis_ticketsB
Read-only

Lista los tickets asignados al usuario en un proyecto de BlueSurf.

Inputs: project (required), include_closed.

descargar_adjuntosA

Descarga los adjuntos de un ticket a una carpeta local. Con archivo_id descarga solo uno; si no, todos.

Inputs: code (required), destino (required), archivo_id.

listar_adjuntosA
Read-only

Lista los archivos de la sección Files de un ticket, sin descargarlos.

Inputs: code (required).

mis_proyectosA
Read-only

Lista los proyectos del usuario (id, smallCode, code, name). El smallCode (p. ej. "PROJ") es lo que se pasa a buscar_mis_tickets.

Inputs: no named parameters.

obtener_ticketC
Read-only

Devuelve el detalle de un ticket de BlueSurf por su código (p. ej. PROJ-123).

Inputs: code (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: listing projects, listing assigned tickets, retrieving ticket detail, listing attachments, and downloading attachments. The only adjacent pair, listar_adjuntos and descargar_adjuntos, is explicitly differentiated by listing vs downloading.

    Naming Consistency4/5

    The names are consistently snake_case and mostly follow a Spanish verb_noun pattern. The minor deviation is mis_proyectos, which is a noun phrase rather than verb-led, and buscar_mis_tickets includes a possessive but remains understandable.

    Tool Count5/5

    Five tools are well-scoped for a focused BlueSurf project/ticket/attachment workflow. Each tool earns its place without obvious redundancy.

    Completeness4/5

    The set covers the core read path: projects to assigned tickets to ticket detail to attachment listing/download. Minor gaps remain around broader ticket search/filtering and write operations such as creating or updating tickets, but the main browsing workflow is usable.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only MCP access to Tactical RMM, allowing agents to query devices, clients, sites, audit logs, software, and pending actions without any mutating capabilities.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables support agents to look up customer account details and billing or incident information through two read-only MCP tools for triage workflows.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only querying of Jira Server/Data Center projects, issues, comments, transitions, and issue types through MCP tools.
      708 npm
      MIT