Simple Support System MCP

simple-support-system-mcp

Servidor MCP local (stdio) para la API REST del complemento Simple Support System para Concrete CMS. Permite que un asistente gestione una cola de soporte como lo haría una persona: encontrar el ticket, leerlo con su historial, escribir una respuesta, moverlo al siguiente estado. También se cubren proyectos, archivos adjuntos y moderación.

El servidor se comunica con cualquier sitio que ejecute el paquete. Nada está codificado de forma fija; la URL del sitio y la clave de API provienen de variables de entorno. Solo habla stdio y nunca abre un puerto.

Instalación

npm install
npm run build

Registra el servidor en Claude Code:

claude mcp add simple-support-system \
  -e SIMPLE_SUPPORT_SYSTEM_BASE_URL=https://support.example.com \
  -e SIMPLE_SUPPORT_SYSTEM_API_KEY=your-api-key \
  -- node "/absolute/path/to/simple-support-system-mcp/dist/src/index.js"

O en ~/.claude.json / claude_desktop_config.json:

{
  "mcpServers": {
    "simple-support-system": {
      "command": "node",
      "args": ["/absolute/path/to/simple-support-system-mcp/dist/src/index.js"],
      "env": {
        "SIMPLE_SUPPORT_SYSTEM_BASE_URL": "https://support.example.com",
        "SIMPLE_SUPPORT_SYSTEM_API_KEY": "your-api-key"
      }
    }
  }
}

Entorno

Variable	Propósito
SIMPLE_SUPPORT_SYSTEM_BASE_URL	Obligatoria. URL base del sitio Concrete CMS, por ejemplo https://support.example.com. La ruta de API /index.php/api/v1 se añade automáticamente; una URL que ya termine en /api/v1 se usa tal cual.
SIMPLE_SUPPORT_SYSTEM_API_KEY	Clave de API de la instalación, enviada como cabecera X-Api-Key. Sin ella solo se alcanza la parte pública de la API.
SIMPLE_SUPPORT_SYSTEM_API_PATH	Opcional. Sobrescribe la ruta de API predeterminada para sitios que no usan el despachador index.php, por ejemplo /api/v1.
SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN	Opcional. Token de acceso predeterminado para proyectos privados, usado cuando una llamada de herramienta no pasa ningún token propio.
SIMPLE_SUPPORT_SYSTEM_TIMEOUT_MS	Opcional. Tiempo de espera de solicitud en milisegundos, predeterminado 30000.

La clave de API se genera al instalar el paquete y reside en la configuración del sitio bajo simple_support_system.api_key. Las llamadas sin ella se ejecutan como visitante anónimo: leer proyectos públicos y sus tickets aprobados, crear tickets y escribir comentarios sigue funcionando; todo lo administrativo (cambios de estado, eliminación, aprobación, proyectos) no.

Herramientas

Las tres herramientas cotidianas son list_tickets, get_ticket y reply_to_ticket, además de set_ticket_state para mover un ticket a lo largo del flujo.

Herramienta	Propósito
list_tickets	Lista tickets con filtros por proyecto, estado, tipo, prioridad, asignado, búsqueda de texto y fecha de cambio, ordenados y paginados. Resúmenes compactos por defecto.
get_ticket	Lee un ticket con sus archivos adjuntos y, a menos que se desactive, todos sus comentarios.
reply_to_ticket	Publica una respuesta como comentario en un ticket y dispara los correos de notificación.
set_ticket_state	Mueve un ticket a otro estado del flujo de trabajo y notifica a todos los implicados.
create_ticket	Crea un ticket en un proyecto, por id de proyecto o por handle de proyecto, opcionalmente con archivos subidos.
update_ticket	Cambia título, contenido, tipo, prioridad o asignado. Solo se tocan los campos indicados.
approve_ticket	Aprueba un ticket moderado.
delete_ticket	Elimina un ticket con todos sus comentarios y enlaces de archivos adjuntos. Irreversible, requiere confirm: true.
list_ticket_comments	Lista los comentarios de un ticket.
update_comment	Reemplaza el texto de un comentario.
approve_comment	Aprueba un comentario moderado.
delete_comment	Elimina un comentario. Irreversible, requiere confirm: true.
list_projects	Lista los proyectos de soporte, con tokens de acceso cuando hay una clave de API configurada.
get_project	Lee un proyecto por id.
create_project	Crea un proyecto; los proyectos privados reciben un token de acceso generado.
update_project	Cambia nombre, handle o visibilidad de un proyecto.
delete_project	Elimina un proyecto con todos los tickets y comentarios que contiene. Irreversible, requiere confirm: true.
list_ticket_attachments	Lista los archivos adjuntos a un ticket.
upload_attachment	Sube un archivo local al gestor de archivos y devuelve su id de archivo.
add_ticket_attachments	Vincula ids de archivo subidos a un ticket.
download_attachment	Resuelve la URL de descarga de un archivo adjunto y puede guardarlo en una ruta local.
delete_attachment	Elimina un archivo de un ticket. Irreversible, requiere confirm: true.
get_server_info	Muestra la URL de API configurada, si hay una clave presente y los estados, tipos y prioridades aceptados. La clave en sí nunca se devuelve.

Las herramientas de lectura están anotadas como de solo lectura; las cuatro herramientas delete_ como destructivas. Todas requieren además confirm: true, de modo que una eliminación no puede ocurrir como efecto secundario de una instrucción vaga. No hay papelera ni restauración en el lado de la API; un ticket, comentario o proyecto eliminado desaparece.

Trabajar con un ticket

list_tickets   { "state": "open", "sortBy": "updatedAt" }
get_ticket     { "ticketId": 42 }
reply_to_ticket{ "ticketId": 42, "comment": "Thanks for the report, we are on it." }
set_ticket_state { "ticketId": 42, "state": "in_progress" }

list_tickets también acepta projectHandle en lugar de projectId y lo resuelve a través de la lista de proyectos primero.

Valores que acepta la API

• Estados: new, open, in_progress, on_hold, resolved, duplicate, invalid, wont_fix, closed. set_ticket_state acepta todos excepto new, que solo se establece al crear un ticket.
• Tipos: bug, enhancement, proposal, task
• Prioridades: trivial, minor, major, critical, blocker
• Los tickets en el estado closed o invalid están bloqueados: la API rechaza ediciones del ticket, sus comentarios y sus archivos adjuntos hasta que cambie el estado.

Archivos adjuntos

upload_attachment      { "filePath": "/tmp/screenshot.png" }      -> fileId
add_ticket_attachments { "ticketId": 42, "fileIds": [123] }

upload_attachment coloca el archivo en el gestor de archivos del sitio sin vincularlo a ningún lugar; la segunda llamada lo adjunta. create_ticket acepta los mismos ids en attachmentFileIds.

Proyectos privados

Un proyecto privado solo es accesible con su token de acceso. Pásalo por llamada como token, o establece SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN como predeterminado. Con una clave de API no se necesita el token; la clave ya otorga acceso completo.

Notas sobre la API

El paquete responde en varias formas; el servidor las normaliza todas para que las herramientas devuelvan el recurso desnudo:

• Las colecciones vuelven como un array simple, tickets individuales y comentarios dentro de una clave ticket o comment, archivos adjuntos dentro de data.
• Los fallos llegan ya sea como {"errors": [...]} o como un EditResponse de Concrete con un indicador error. El segundo puede venir con estado 200, por lo que un 200 solo no se trata como éxito. Cada error se convierte en un error de herramienta con el mensaje que envió la API.
• create_ticket responde con un envoltorio de estado y no con el nuevo registro, por lo que el id de un ticket recién creado debe buscarse con list_tickets.
• download_attachment sigue la redirección que devuelve la API e informa de la URL resuelta.

Verificación

npm run build
npm test

Las pruebas se ejecutan contra una capa HTTP simulada; nunca tocan un sitio en vivo y no necesitan credenciales. Cubren la codificación de URL y formulario que esperan los controladores PHP (incluida la notación booleana y de arrays de PHP), los envoltorios de respuesta, el mapeo de errores, el filtrado y ordenamiento de list_tickets, y las salvaguardas de las herramientas destructivas.

Licencia

MIT, ver LICENSE.