bluesurf-mcp

Servidor MCP local para que Claude u otros agentes IA lean tickets de BlueSurf, adjunten un archivo, publiquen un comentario y registren tiempo en el daily report. Un solo paquete PyPI incluye el núcleo (bluesurf_client) y el adaptador MCP (bluesurf_mcp).

Instalación

Requiere Python 3.10 o superior. Guía paso a paso (instalación global, login y Cursor): MANUAL_INSTALACION.md en el repositorio.

pip install bluesurf-mcp

En este monorepo, modo editable:

pip install -e ./bluesurf-mcp

Guardar credenciales (login / logout)

La contraseña no tiene que ir en mcp.json. Una vez, en una terminal:

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.

bluesurf-mcp logout

borra lo guardado.

Configuración (variables de entorno)

El entorno gana sobre lo guardado con login. Útil para CI o para sobrescribir sin tocar el almacén.

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 (bluesurf_client) no persiste secretos.

Correr el servidor

bluesurf-mcp

Se comunica por stdio (el transporte estándar para MCP local). Sin argumentos no pide contraseña: usa env o las credenciales de login.

Registrar el MCP en un cliente

Claude Code / Cursor (.mcp.json o config de usuario)

Tras bluesurf-mcp login:

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

Si bluesurf-mcp no está en el PATH, usa la ruta absoluta al ejecutable o python -m bluesurf_mcp.

Las variables BLUESURF_* en env siguen siendo válidas como override; no hace falta poner la contraseña ahí.

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=None) — 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=None) — 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=False) — 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 Python

El paquete de import del núcleo es bluesurf_client:

from bluesurf_client import BlueSurfClient, CredentialsAuth  # o CookieAuth