mcp-tomticket

# mcp-tomticket

[![npm](https://img.shields.io/npm/v/mcp-tomticket.svg)](https://www.npmjs.com/package/mcp-tomticket)
[![MCP Registry](https://img.shields.io/badge/MCP-io.github.glira%2Fmcp-tomticket-blue)](https://registry.modelcontextprotocol.io)
[![Glama](https://glama.ai/mcp/servers/glira/mcp-tomticket/badges/score.svg)](https://glama.ai/mcp/servers/glira/mcp-tomticket)

Servidor [MCP](https://modelcontextprotocol.io) para a [API TomTicket v2](https://tomticket.tomticket.com/kb/api). Lista, responde, lança horário e finaliza chamados e também cobre clientes, organizações, chats, departamentos e base de conhecimento.

Não existe endpoint de login. O Bearer Token é criado no painel: **Administração → Configurações da Conta → API → Novo Token**. Marque **Pode criar e modificar dados** para respostas, horário e finalização.

O token vai só em variável de ambiente. Nunca o commite.

## Requisitos

- Node.js >= 18
- Token de API do TomTicket (conta Premium/Enterprise)

## Instalação

Via npm (recomendado):

```bash
npx mcp-tomticket
```

No Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "tomticket": {
      "command": "npx",
      "args": ["-y", "mcp-tomticket"],
      "env": {
        "TOMTICKET_TOKEN": "cole-o-token-aqui"
      }
    }
  }
}
```

Clone local:

```bash
git clone https://github.com/glira/mcp-tomticket.git
cd mcp-tomticket
npm install
cp .env.example .env
# edite .env e cole o TOMTICKET_TOKEN
npm run build
```

Validação rápida (somente leitura):

```bash
npm run smoke
```

Opcional — cria, comenta, responde e finaliza **um chamado de teste** com assunto `[MCP TESTE]`:

```bash
npx tsx scripts/smoke.ts --write
```

Recarregue os MCPs em **Settings → MCP**. Exemplo local em [`.cursor/mcp.json.example`](.cursor/mcp.json.example).

## Tools principais

| Tool | Ação |
| --- | --- |
| `tomticket_list_open_tickets` | Chamados abertos |
| `tomticket_list_tickets` | Todos, com filtros |
| `tomticket_get_ticket` | Detalhe + respostas + horários |
| `tomticket_reply_ticket` | Resposta do atendente (`start_date`/`end_date` lançam horário) |
| `tomticket_comment_ticket` | Comentário interno |
| `tomticket_finish_ticket` | Finaliza (`time_work` em minutos) |
| `tomticket_start_status` / `tomticket_close_status` | Cronômetro de status |
| `tomticket_create_ticket` | Abre chamado |
| `tomticket_transfer_ticket` / `tomticket_assign_operator` | Transferir / vincular atendente |

Há também tools de clientes, organizações, chats, departamentos, KB e campos personalizados. Operações de escrita avisam que alteram produção. Finalizar um chamado exige atendente vinculado (`tomticket_assign_operator`).

## Rate limit

A API aceita **3 requisições por segundo**. O client aplica intervalo mínimo de 350 ms.

## Variáveis

| Variável | Obrigatória | Descrição |
| --- | --- | --- |
| `TOMTICKET_TOKEN` | sim | Bearer Token do painel |
| `TOMTICKET_BASE_URL` | não | Padrão `https://api.tomticket.com/v2.0` |

## Licença

[MIT](LICENSE)