Simple Support System MCP

simple-support-system-mcp

Servidor MCP local (stdio) para a API REST do add-on Simple Support System para Concrete CMS. Ele permite que um assistente trabalhe em uma fila de suporte como um humano faria: encontrar o ticket, lê-lo com seu histórico, escrever uma resposta, movê-lo para o próximo estado. Projetos, anexos e moderação também são cobertos.

O servidor fala com qualquer site que execute o pacote. Nada é codificado; a URL do site e a chave da API vêm de variáveis de ambiente. Ele fala apenas stdio e nunca abre uma porta.

Instalação

npm install
npm run build

Registre o servidor no 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"

Ou no ~/.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"
      }
    }
  }
}

Ambiente

Variável	Finalidade
SIMPLE_SUPPORT_SYSTEM_BASE_URL	Obrigatória. URL base do site Concrete CMS, por exemplo https://support.example.com. O caminho da API /index.php/api/v1 é anexado automaticamente; uma URL que já termina em /api/v1 é usada como está.
SIMPLE_SUPPORT_SYSTEM_API_KEY	Chave da API da instalação, enviada como cabeçalho X-Api-Key. Sem ela, apenas a parte pública da API é acessível.
SIMPLE_SUPPORT_SYSTEM_API_PATH	Opcional. Substitui o caminho padrão da API para sites que não usam o dispatcher index.php, por exemplo /api/v1.
SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN	Opcional. Token de acesso padrão para projetos privados, usado quando uma chamada de ferramenta não passa token próprio.
SIMPLE_SUPPORT_SYSTEM_TIMEOUT_MS	Opcional. Tempo limite de solicitação em milissegundos, padrão 30000.

A chave da API é gerada quando o pacote é instalado e fica na configuração do site em simple_support_system.api_key. Chamadas sem ela são executadas como visitante anônimo: ler projetos públicos e seus tickets aprovados, criar tickets e escrever comentários ainda funciona; tudo que é administrativo (mudanças de estado, exclusão, aprovação, projetos) não funciona.

Ferramentas

As três ferramentas do dia a dia são list_tickets, get_ticket e reply_to_ticket, além de set_ticket_state para mover um ticket adiante.

Ferramenta	Finalidade
list_tickets	Lista tickets com filtros por projeto, estado, tipo, prioridade, responsável, busca de texto e data de alteração, ordenados e paginados. Resumos compactos por padrão.
get_ticket	Lê um ticket com seus anexos e, a menos que seja desativado, todos os seus comentários.
reply_to_ticket	Publica uma resposta como comentário em um ticket e dispara os e-mails de notificação.
set_ticket_state	Move um ticket para outro estado do fluxo de trabalho e notifica todos os envolvidos.
create_ticket	Cria um ticket em um projeto, por id do projeto ou handle do projeto, opcionalmente com arquivos enviados.
update_ticket	Altera título, conteúdo, tipo, prioridade ou responsável. Apenas os campos informados são alterados.
approve_ticket	Aprova um ticket moderado.
delete_ticket	Exclui um ticket com todos os comentários e links de anexos. Irreversível, requer confirm: true.
list_ticket_comments	Lista os comentários de um ticket.
update_comment	Substitui o texto de um comentário.
approve_comment	Aprova um comentário moderado.
delete_comment	Exclui um comentário. Irreversível, requer confirm: true.
list_projects	Lista os projetos de suporte, com tokens de acesso quando uma chave de API está configurada.
get_project	Lê um projeto por id.
create_project	Cria um projeto; projetos privados recebem um token de acesso gerado.
update_project	Altera nome, handle ou visibilidade de um projeto.
delete_project	Exclui um projeto com todos os tickets e comentários dentro dele. Irreversível, requer confirm: true.
list_ticket_attachments	Lista os arquivos anexados a um ticket.
upload_attachment	Envia um arquivo local para o gerenciador de arquivos e retorna o id do arquivo.
add_ticket_attachments	Vincula ids de arquivos enviados a um ticket.
download_attachment	Resolve a URL de download de um anexo e pode salvá-lo em um caminho local.
delete_attachment	Remove um arquivo de um ticket. Irreversível, requer confirm: true.
get_server_info	Mostra a URL da API configurada, se uma chave está presente e os estados, tipos e prioridades aceitos. A chave em si nunca é retornada.

As ferramentas de leitura são anotadas como somente leitura; as quatro ferramentas delete_ como destrutivas. Todas elas também exigem confirm: true, para que uma exclusão não possa acontecer como efeito colateral de uma instrução vaga. Não há lixeira nem restauração no lado da API; um ticket, comentário ou projeto excluído desaparece.

Trabalhando com um 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 também aceita projectHandle em vez de projectId e o resolve pela lista de projetos primeiro.

Valores que a API aceita

• Estados: new, open, in_progress, on_hold, resolved, duplicate, invalid, wont_fix, closed. set_ticket_state aceita todos eles, exceto new, que só é definido quando um ticket é criado.
• Tipos: bug, enhancement, proposal, task
• Prioridades: trivial, minor, major, critical, blocker
• Tickets no estado closed ou invalid estão bloqueados: a API recusa edições do ticket, de seus comentários e de seus anexos até que o estado mude.

Anexos

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

upload_attachment coloca o arquivo no gerenciador de arquivos do site sem vinculá-lo a nada; a segunda chamada o anexa. create_ticket aceita os mesmos ids em attachmentFileIds.

Projetos privados

Um projeto privado só é acessível com seu token de acesso. Passe-o por chamada como token, ou defina SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN como padrão. Com uma chave de API, o token não é necessário; a chave já concede acesso total.

Notas sobre a API

O pacote responde em vários formatos; o servidor normaliza todos eles para que as ferramentas retornem o recurso puro:

• Coleções vêm como um array simples, tickets e comentários individuais dentro de uma chave ticket ou comment, anexos dentro de data.
• Falhas chegam como {"errors": [...]} ou como um EditResponse do Concrete com um sinalizador error. O segundo pode vir com status 200, então um 200 sozinho não é tratado como sucesso. Todo erro vira um erro de ferramenta com a mensagem que a API enviou.
• create_ticket responde com um envelope de status e não com o novo registro, então o id de um ticket recém-criado precisa ser consultado com list_tickets.
• download_attachment segue o redirecionamento que a API retorna e informa a URL resolvida.

Verificação

npm run build
npm test

Os testes rodam contra uma camada HTTP simulada (stub), nunca tocam um site real e não precisam de credenciais. Eles cobrem a URL e a codificação de formulário que os controladores PHP esperam (incluindo a notação booleana e de array do PHP), os envelopes de resposta, o mapeamento de erros, a filtragem e ordenação de list_tickets, e as proteções das ferramentas destrutivas.

Licença

MIT, veja LICENSE.