Skip to main content
Glama
oamilkar

bluesurf-mcp-node

by oamilkar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

bluesurf-mcp (Node.js)

Servidor MCP local para que Cursor u otros agentes lean tickets de BlueSurf, adjunten un archivo y publiquen un comentario. 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 y agregar_comentario.

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.

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.

NameRequiredDescriptionDefault
projectYessmallCode del proyecto (p. ej. "PROJ"), prefijo de los códigos de ticket (PROJ-123). Usa mis_proyectos para descubrirlo.
include_closedNoSi es true incluye tickets en estados finales; por defecto solo los abiertos.

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lighter. It adds the implicit filter (only tickets assigned to the calling user, within one project), but says nothing about default open-only scope, ordering, pagination, or result shape beyond what the name implies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the scope (user + project) front-loaded and zero filler. It is not under-specified, but it is too terse to earn a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool with full schema coverage and no output schema, the description is adequate but thin: it omits whether results are paginated, ordered, or capped, which an agent would want before calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (project, include_closed) are already documented, including the default open-only behavior. The description adds no semantics beyond the schema, which is the expected baseline when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Lista") and resource ("tickets asignados al usuario en un proyecto"), so the agent can distinguish it from obtener_ticket (single ticket). It never names a sibling or states the boundary explicitly, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use, when-not-to-use, or alternatives guidance. The only routing hint ("Usa mis_proyectos para descubrirlo") lives in the schema's parameter text, not the description, so the description itself leaves usage to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

descargar_adjuntosA

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

NameRequiredDescriptionDefault
codeYesCódigo del ticket, por ejemplo PROJ-123.
destinoYesDirectorio donde se guardan los archivos. Se crea si no existe.
archivo_idNoSi se indica, descarga solo ese adjunto.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds that files land in a local directory, but says nothing about overwriting existing files, partial failures, or what happens when a ticket has no attachments — notable gaps for a tool with filesystem side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core action first and the mode-switching rule second. Nothing to trim and nothing buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter tool with full schema coverage and no output schema, the description covers the essential action and the optional-parameter behavior. The main omission is the return value (file paths, count, failure reporting), which for a side-effecting download tool would help an agent verify success — but this is a modest gap given the schema richness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented, including the archivo_id semantics and destination auto-creation. The description's restatement of archivo_id adds no information beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: downloading a ticket's attachments to a local folder, with a clear distinction between single-file and all-files modes. It is distinguishable from siblings like listar_adjuntos by the verb 'descarga', though it never explicitly contrasts with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The clause 'Con archivo_id descarga solo uno; si no, todos' tells the agent how to pick between the two modes, which is genuine guidance. However there is no mention of when to prefer this over listar_adjuntos, nor any prerequisite (ticket access, destination writability) stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listar_adjuntosA
Read-only

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

NameRequiredDescriptionDefault
codeYesCódigo del ticket, por ejemplo PROJ-123.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds useful behavioral context beyond the readOnlyHint annotation: it operates on the Files section and does not download files. However, it does not describe the return format (e.g., file names/metadata) or whether pagination applies, and there is no output schema to cover those gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. The key scope and the non-downloading behavior are stated immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool with one fully documented parameter and readOnlyHint annotation, the description covers the essential scope and behavior. Return value details are omitted, but no output schema exists to require them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the 'code' parameter already documented and exemplified. The description itself adds no parameter-specific details, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Lista') and resource ('los archivos de la sección Files de un ticket'), and explicitly distinguishes itself from the sibling 'descargar_adjuntos' by saying 'sin descargarlos'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies the tool is for listing rather than downloading, but does not explicitly say when to use this instead of 'descargar_adjuntos' or 'obtener_ticket'. Usage context is clear but alternatives are not named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint=true already declaring the safety profile, the description adds real value by disclosing the shape of the response (id, smallCode, code, name), which matters because no output schema exists. It does not cover ordering, pagination, or empty-result behavior, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero waste, with the resource and returned fields front-loaded and the cross-tool hint last. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless, read-only list operation with no output schema, the description supplies what an agent needs: what comes back and how to use it downstream. Minor omissions like result ordering or behavior when the user has no projects are low-impact.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing to document beyond the input contract. The description usefully clarifies that smallCode is an output field rather than an input, preventing a misplaced-argument error at the next call. Baseline for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Lista los proyectos del usuario") and enumerates the returned fields (id, smallCode, code, name). The mention of smallCode and its consumer tool separates it cleanly from the ticket-oriented siblings (buscar_mis_tickets, obtener_ticket, listar_adjuntos).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete next step: the smallCode returned here is the value passed to buscar_mis_tickets, establishing this as an upstream discovery call. It stops short of stating when not to use it or what happens if the user has no projects, so it is clear context rather than full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

obtener_ticketC
Read-only

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

NameRequiredDescriptionDefault
codeYesCódigo del ticket, por ejemplo PROJ-123.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add operational detail. It adds none: nothing about whether the ticket must belong to the caller's projects, nothing about not-found or permission-error behavior, and nothing about what the 'detalle' payload contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single well-formed sentence with the verb and resource front-loaded and zero filler. It is tight, though the space it saves is partly reclaimed as a completeness gap elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with annotations and full schema coverage, the definition is minimally viable but thin: an agent still cannot tell whether access is scoped to the caller's own tickets (unlike the mis_* siblings) or what 'detalle' includes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already documents 'code' with the same PROJ-123 example the description gives. The description therefore repeats the schema rather than adding format, validation, or resolution semantics, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (devuelve) plus resource (el detalle de un ticket de BlueSurf) and the lookup key (por su código). It does not explicitly contrast itself with the sibling buscar_mis_tickets, so the boundary between 'fetch by exact code' and 'search' is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus buscar_mis_tickets, no prerequisites, and no mention of what happens if the code is unknown. The 'por su código' phrasing hints at exact-code lookup, but that is inference, not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 5 tool updatesv0.2.0
    • First observedbuscar_mis_tickets
    • First observeddescargar_adjuntos
    • First observedlistar_adjuntos
    • First observedmis_proyectos
    • First observedobtener_ticket
Deploy Server
Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

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 issues

Resources

Related MCP Connectors

Related MCP Servers

  • trmm-mcp

    JohnGilligan2
    A
    license
    Not graded
    quality
    C
    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

  • ticket-triage-mcp

    Mohemed-Amine-Chalhy
    A
    license
    B
    quality
    C
    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

  • jira-mcp

    jabdon00
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only querying of Jira Server/Data Center projects, issues, comments, transitions, and issue types through MCP tools.
    825 npm
    MIT