Softrack MCP

Servidor Model Context Protocol (MCP) para consultar unidades, veículos, telemetria e catálogos da Softrack. Ele usa transporte Streamable HTTP e expõe tools para consultas ativas, resources para o último resultado em cache e prompts reutilizáveis de contexto.

Requisitos e instalação

• Node.js 20 ou superior
• Credenciais válidas da Softrack enviadas nos headers HTTP

npm.cmd ci
npm.cmd run build

Em ambientes sem bloqueio de scripts do PowerShell, npm pode ser usado no lugar de npm.cmd.

Configuração do cliente MCP

Configure o cliente para acessar o endpoint HTTP e enviar as credenciais em todas as requisições. Nunca grave tokens no repositório ou os imprima em logs.

{
  "mcpServers": {
    "softrack": {
      "url": "https://mcp.seudominio.com/mcp",
      "headers": {
        "Authorization": "Bearer <token-do-usuario>",
        "X-Softrack-Company-Token": "<token-da-empresa>"
      }
    }
  }
}

O header Authorization também pode ser substituído por X-Softrack-Token-User. Os headers precisam ser enviados em todas as requisições ao endpoint. Reinicie ou reconecte o cliente após alterar o código ou a configuração.

O host definido em MCP_PUBLIC_HOST é aceito junto com os aliases locais localhost e 127.0.0.1, permitindo que serviços executados na mesma máquina acessem o MCP pelo endereço de loopback.

Sem MCP_PUBLIC_HOST, o mesmo artefato inicia em modo local stdio e requer SOFTRACK_TOKEN_USER e SOFTRACK_TOKEN_COMPANY. Ao definir MCP_PUBLIC_HOST, o servidor inicia em Streamable HTTP e recebe as credenciais nos headers de cada requisição.

Tools

Todas as tools retornam conteúdo JSON em texto. Em falhas de integração, retornam isError: true.

| Tool | Quando usar | Retorno de sucesso | | --- | --- | --- | | get_units | Descobrir as unidades acessíveis e seus IDs. | { totalCount, units } com Id, Name, Status, Description e Mobile. | | get_users | Listar usuários com filtros opcionais de grupo, nome, e-mail, situação, paginação e ordenação. | { totalCount, users, pagination } com dados cadastrais não sensíveis. | | get_all_vehicle | Listar ou filtrar veículos. Aceita arrays de IDs, situação, frota, série, modelo, ano, paginação e ordenação. | { totalCount, vehicles, pagination } com identificação, unidade, dispositivo, operador, horas, horímetro e status. | | get_vehicle_by_id | Consultar um VehicleId exato já conhecido. | { totalCount, vehicles }. | | get_all_vehicle_model | Listar somente descrições de modelos. | { totalCount, vehicles }, com itens { description }. | | get_config_brands | Obter BrandId antes de filtrar por marca. | { totalCount, configs }. | | get_config_fuels | Obter FuelId antes de filtrar por combustível. | { totalCount, configs }. | | get_welcome_grid | Consultar o estado operacional atual das máquinas, com filtros opcionais de veículo, modelo, unidade, tipo, status e características. | { totalCount, vehicles } com posição, status, alerta e motorista. | | get_telemetry | Consultar a telemetria disponível hoje para um VehicleId. | { totalCount, telemetry }. | | get_telemetry_range | Consultar telemetria por período. Requer VehicleId, StartDate e EndDate. | { totalCount, telemetry }. |

get_telemetry e get_telemetry_range retornam, por item, Telemetry, Events, DataValidation e ImpactValidation. Uma lista vazia indica ausência de dados disponíveis, não valor zero. Para horas diárias, use a entrada de telemetria cujo codigo é Utilização; WorkHours e HourMeter do veículo não representam necessariamente a utilização diária.

Fluxos recomendados

1. Para filtrar por unidade, obtenha Id com get_units e envie UnitId como array: { "UnitId": [1] }.
2. Para uma busca ampla de veículos, peça uma unidade específica ou confirme que a consulta deve abranger todas as unidades acessíveis.
3. Use get_vehicle_by_id apenas para um ID conhecido; use get_all_vehicle para descoberta e filtros.
4. Use get_telemetry para hoje e get_telemetry_range somente quando houver um intervalo explícito.

Essas relações também são publicadas em instructions na inicialização do servidor. Clientes podem incorporá-las ao contexto do modelo; as descrições individuais das tools permanecem a referência para seus parâmetros e retornos.

Prompts e resources

Cada tool expõe um prompt <tool>-context e um resource correspondente. Prompts são templates que o cliente pode listar e invocar; a disponibilidade deles no menu depende do cliente MCP. Resources são dados somente leitura: o cliente decide quando listá-los e lê-los.

| Tool | Resource | | --- | --- | | get_units | units://current | | get_users | users://list/current | | get_all_vehicle | vehicles://list/current | | get_vehicle_by_id | vehicles://by-id/current | | get_all_vehicle_model | vehicles://models/current | | get_config_brands | config://brands/current | | get_config_fuels | config://fuels/current | | get_welcome_grid | telemetry://welcome-grid/current | | get_telemetry | telemetry://current | | get_telemetry_range | telemetry://range/current |

Após a tool correspondente ser chamada, o resource contém o último resultado da sessão com source, cache.valid, cache.cachedAt, cache.ttlMs, parâmetros (quando existirem) e os dados. O TTL é de cinco minutos. O cache é mantido em memória, isolado pelo par de credenciais de usuário e companhia e perdido ao reiniciar o servidor. Leia o resource somente quando cache.valid for true; caso contrário, chame a tool para atualizá-lo.

Softrack MCP

Servidor MCP para consultar dados da Softrack: veículos, unidades, usuários, motoristas, manutenções, telemetria, dados seriais e configurações de frota.

O servidor oferece dois modos de conexão:

• stdio — recomendado para clientes MCP locais, como Claude Desktop e Codex.
• HTTP Streamable — para uso atrás de um proxy reverso, em POST /mcp.

Requisitos

• Node.js 20 ou superior
• Credenciais válidas da Softrack: TokenUser e TokenCompany

Instalação

npm install softrack-mcp

Para executar sem instalação global:

npx softrack-mcp

Uso via stdio

Defina as credenciais no ambiente e execute o binário:

SOFTRACK_TOKEN_USER="seu-token-user" \
SOFTRACK_TOKEN_COMPANY="seu-token-company" \
npx softrack-mcp

No Windows (PowerShell):

$env:SOFTRACK_TOKEN_USER = "seu-token-user"
$env:SOFTRACK_TOKEN_COMPANY = "seu-token-company"
npx softrack-mcp

Exemplo de configuração para um cliente MCP que usa stdio:

{
  "mcpServers": {
    "softrack": {
      "command": "npx",
      "args": ["-y", "softrack-mcp"],
      "env": {
        "SOFTRACK_TOKEN_USER": "seu-token-user",
        "SOFTRACK_TOKEN_COMPANY": "seu-token-company"
      }
    }
  }
}

Uso via HTTP Streamable

Defina MCP_PUBLIC_HOST para iniciar o endpoint HTTP. O processo escuta em 127.0.0.1 na porta indicada por PORT (ou 3000) e expõe POST /mcp. Use um proxy reverso para publicar o serviço.

MCP_PUBLIC_HOST="mcp.exemplo.com" PORT=3000 npx softrack-mcp

Cada requisição deve fornecer as credenciais da Softrack nos headers:

Authorization: Bearer <TokenUser>
X-Softrack-Company-Token: <TokenCompany>

Como alternativa ao header Authorization, use X-Softrack-Token-User: <TokenUser>. O host e a origem são validados; ajuste MCP_PUBLIC_HOST para o domínio público usado pelo proxy.

Nunca exponha os tokens no frontend, em repositórios ou em logs. No modo HTTP, envie-os somente pelo backend ou por um cliente MCP confiável.

Tools

| Tool | Finalidade | Principais filtros | | --- | --- | --- | | get_units | Lista as unidades disponíveis ao usuário autenticado. | — | | get_all_vehicle | Lista e filtra veículos. | UnitId, VehicleId, FleetNumber, SerialNumber, Model, BrandId, FuelId, MachineTypeId, Active, paginação e ordenação | | get_vehicle_by_id | Busca um veículo por ID exato. | VehicleId | | get_all_vehicle_model | Lista os modelos de veículo disponíveis. | — | | get_config_brands | Lista marcas configuradas e seus IDs. | — | | get_config_fuels | Lista combustíveis configurados e seus IDs. | — | | get_users | Lista usuários visíveis. | GroupId, Name, Email, Active, paginação e ordenação | | get_drivers | Lista motoristas. | UnitId, IButtonId, Name, Validity, Active, LicenseType, paginação e ordenação | | get_maintenances | Lista manutenções de veículos. | período, VehicleId, UnitId, MaintenanceTypeId, Misuse, ShowClosed | | get_welcome_grid | Consulta o estado operacional atual das máquinas. | VehicleId, UnitId, Model, MachineTypeId, Status, características | | get_telemetry | Consulta a telemetria processada do dia atual. | VehicleId | | get_telemetry_range | Consulta a telemetria processada em um período. | VehicleId, StartDate, EndDate | | get_serial_data | Lista dados seriais/pacotes brutos enviados pelo rastreador. | VehicleId, data, horário, FT, Garbage, View, ordenação | | compare_serial_data | Compara dois ou mais registros de dados seriais. | SerialDataId (mínimo de 2) |

Observações de consulta

• Os filtros que recebem IDs, como UnitId e VehicleId em get_all_vehicle, usam arrays numéricos: {"UnitId":[14]}.
• Para filtros de situação, use "S" para ativo e "N" para inativo. Para consultar ambos, informe ["S", "N"].
• Para paginação, informe Page e RecordAmount juntos; Page começa em zero. Para ordenação, use pares de campo e direção, por exemplo {"Sort":["FleetNumber","asc"]}.
• Use get_units para descobrir o UnitId antes de filtrar por unidade.
• Use get_all_vehicle para localizar um veículo por frota ou série. Com o VehicleId exato em mãos, prefira get_vehicle_by_id.
• Telemetria contém leituras já processadas. Para pacotes, frames ou "dados seriais", use get_serial_data; SerialNumber do veículo não é um dado serial de telemetria.
• Uma resposta vazia de get_telemetry significa que não há dados disponíveis para o veículo no dia — não equivale a valor zero.

Recursos e prompts MCP

Após uma consulta, o resultado fica disponível em cache por 1 minuto e pode ser recuperado por resources MCP. Cada tool também registra um prompt <nome-da-tool>-context que orienta o cliente a reutilizar esse cache.

| Consulta | Resource | | --- | --- | | Unidades | units://current | | Veículos | vehicles://list/current | | Veículo por ID | vehicles://by-id/current | | Modelos | vehicles://models/current | | Marcas | config://brands/current | | Combustíveis | config://fuels/current | | Usuários | users://list/current | | Motoristas | drivers://list/current | | Manutenções | maintenances://list/current | | Estado operacional | telemetry://welcome-grid/current | | Telemetria do dia | telemetry://current | | Telemetria por período | telemetry://range/current | | Dados seriais | serial-data://list/current | | Comparação de dados seriais | serial-data://comparison/current |

Desenvolvimento e publicação

npm run typecheck       # valida os tipos
npm run build           # gera um único arquivo minificado e ofuscado
npm pack                # cria o .tgz a partir do dist/ atual

Para criar um pacote protegido, execute os dois comandos nessa ordem:

npm run build && npm pack

Para gerar um pacote de teste com o JavaScript do TypeScript sem bundling nem ofuscação:

npm run pack:plain

O npm pack protegido inclui apenas o bundle distribuível em dist/, sem o diretório src/ ou mapas de fonte. Ainda assim, código JavaScript distribuído nunca é impossível de inspecionar; a minificação e a ofuscação apenas elevam a barreira de engenharia reversa.