Matrix42 MCP

Servidor Model Context Protocol para Matrix42 — permite que assistentes de IA explorem a API, leiam o modelo de dados, pesquisem no service desk e atuem em tickets. Somente leitura por padrão.

GitHub

Documentação

Servidor Matrix42 MCP

Dê ao seu assistente de IA uma janela segura, somente leitura por padrão, para o Matrix42.

Um servidor Model Context Protocol que permite a um assistente explorar uma instância Matrix42 da mesma forma que um consultor experiente faria: encontrar o web service certo, ler o modelo de dados real, consultar registros com filtros válidos, pesquisar o service desk e - somente se você ativar - agir em chamados.

O servidor guarda as credenciais e fala com o Matrix42 em nome do assistente: ele realiza a troca do token de API, define o cabeçalho Explicit-Language e lida com TLS. O assistente nunca vê suas credenciais.

You ask an AI assistant; the assistant talks to matrix42-mcp over MCP; matrix42-mcp talks to your Matrix42 instance over REST. Credentials stay in the server and never reach the assistant.

npx matrix42-mcp --help

[!IMPORTANT] Este é um projeto comunitário independente. Ele não é afiliado, endossado, patrocinado ou suportado pela Matrix42 AG. "Matrix42" é uma marca registrada de seu respectivo proprietário e é usada aqui apenas para descrever com o que este software interopera. O suporte vem da comunidade via GitHub issues - não entre em contato com o suporte da Matrix42 sobre este projeto e não espere um acordo de nível de serviço de qualquer tipo. Ele é fornecido "no estado em que se encontra" sob a licença MIT.

[!NOTE] Status: lançamento inicial. O servidor é somente leitura por padrão - as ferramentas de escrita nem sequer são listadas a menos que você defina M42_ALLOW_WRITES=1.

Destaques

Somente leitura por padrão. Ferramentas de escrita estão ausentes da lista de ferramentas, a menos que sejam explicitamente habilitadas.
Nunca adivinha. Cada coluna é resolvida contra o schema ao vivo da sua instância antes de uma consulta ser executada, então um campo que sua instância não possui é reportado - não enviado e transformado em um erro 500 opaco.
Ensina e depois age. Quatro guias escritos acompanham o servidor como recursos MCP, cobrindo o modelo de dados, o schema, a linguagem de filtro ASQL e as convenções REST.
Pré-visualize antes de escrever. Cada escrita retorna a requisição exata que enviaria até você passar confirm. A pré-visualização é o mesmo objeto de plano que é executado, então não pode divergir.
Padrões seguros onde importa. E-mails de notificação estão desativados, entradas de diário são internas e fechamentos em cascata são opcionais.
Sem código ou conteúdo da Matrix42. Cada guia é prosa original que vincula à documentação oficial em vez de reproduzi-la.

Sumário

Entenda

Por quê
O que ele pode fazer
- Como é uma conversa

Configure

Requisitos
- Criando um token de API
Configuração
Configuração do cliente
Verificando a conexão

Use

Ferramentas e ações
Notas de segurança

Trabalhe nele

Desenvolvimento
- Como tudo se encaixa
- Estrutura
Roadmap
Contribuindo
Suporte
Projeto
Segurança
Licença

Por quê

A superfície de API do Matrix42 é grande (uma instância típica expõe ~190 web services e ~1.100 operações), além de um modelo de dados com ~800 definições de dados e ~240 itens de configuração, e um assistente não tem como saber o que existe. Aponte-o para este servidor e ele pode pesquisar o endpoint certo, ler o contrato exato e então escrever código de integração correto - em vez de adivinhar URLs, autenticação e cabeçalhos.

O que ele pode fazer


Descubra a API	~1.100 operações com contratos completos de requisição e retorno, e se cada uma é segura para atualização
Entenda o modelo	785 definições de dados, 237 itens de configuração, valores de pickup, relações e cardinalidade
Leia registros	Consultas ASQL com paginação, visualizações salvas, diário, anexos e links para a interface web
Trabalhe no service desk	Pesquise sete tipos de chamados por nome, níveis de serviço, treze domínios curados ou todos de uma vez
Aja em chamados	Crie, feche, classifique, assuma, encaminhe, pause, reabra, defina prazos, registre tempo - cada um pré-visualizado primeiro

Como é uma conversa

Você: Quais chamados de hardware abertos ainda não foram resolvidos e algum está além do nível de serviço?

O assistente resolve isso sem que você nomeie um único id:

The assistant searches tickets by category and state, checks the service level of each, builds a deep link for the one at risk, and answers - without looking up a single id or writing anything.

Observe o que não aconteceu: sem buscas por GUID, sem nomes de atributos adivinhados e nada foi escrito. Observe também o que o servidor recusa: um filtro que o Matrix42 aceita mas nunca aplica, então uma resposta sem filtro nunca é confundida com uma filtrada.

Requisitos

Node.js 22.19 ou mais recente (exigido pelo undici, o cliente HTTP)
Uma instância Matrix42 e um token de API (recomendado) ou credenciais de autenticação básica

Criando um token de API

No aplicativo Administração do Matrix42, crie um token de API para a conta sob a qual o assistente deve agir. O servidor o troca por um token de acesso de curta duração automaticamente e o re-troca antes que expire.

A autenticação básica é suportada, mas desencorajada: muitas instâncias aceitam as credenciais, mas ainda recusam acesso à API com 403 devido a restrições de função/público.

Configuração

Toda a configuração é feita por variáveis de ambiente.

Variável	Obrigatória	Padrão	Descrição
`M42_HOST`	✅	-	URL base da instância, ex.: `https://matrix42.example.com`
`M42_API_TOKEN`	✅¹	-	Token de API; trocado por um token de acesso automaticamente
`M42_USERNAME` / `M42_PASSWORD`	✅¹	-	Alternativa de autenticação básica ao `M42_API_TOKEN`
`M42_LANGUAGE`		`en-US`	Idioma da resposta, enviado como `Explicit-Language`
`M42_TOOLS`		todos	IDs de ferramentas separados por vírgula a expor
`M42_ALLOW_WRITES`		`0`	Defina como `1` para expor ferramentas que modificam dados. Ferramentas de escrita não são registradas a menos que isso seja definido.
`M42_ALLOW_INSECURE_TLS`		`0`	Defina como `1` para pular a verificação TLS (apenas instâncias de desenvolvimento com certificado autoassinado)
`M42_AUDIT_NOTE`		`1`	Marca chamados criados com uma nota interna dizendo que foram abertos por meio deste servidor. Defina como `0` para desativar.
`M42_AGENT_LABEL`		`Matrix42 MCP server`	Como o assistente é nomeado nessa nota
`M42_UI_URL`		descoberto	Origem da interface web, para links profundos. Descoberto a partir da configuração do web shell da instância quando não definido.
`M42_TIMEOUT_MS`		`30000`	Tempo limite por requisição

¹ Forneça ou M42_API_TOKEN ou ambos M42_USERNAME e M42_PASSWORD.

Configuração do cliente

O servidor roda sobre stdio: seu cliente MCP o inicia. Nenhuma etapa de instalação é necessária - npx o busca sob demanda.

Claude Code

claude mcp add matrix42 \
  --env M42_HOST=https://matrix42.example.com \
  --env M42_API_TOKEN=your-api-token \
  -- npx -y matrix42-mcp

Claude Desktop

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)

{
  "mcpServers": {
    "matrix42": {
      "command": "npx",
      "args": ["-y", "matrix42-mcp"],
      "env": {
        "M42_HOST": "https://matrix42.example.com",
        "M42_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json (global) ou .cursor/mcp.json (por projeto)

{
  "mcpServers": {
    "matrix42": {
      "command": "npx",
      "args": ["-y", "matrix42-mcp"],
      "env": {
        "M42_HOST": "https://matrix42.example.com",
        "M42_API_TOKEN": "your-api-token"
      }
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json - este formato solicita o token em vez de armazená-lo no arquivo:

{
  "inputs": [
    { "id": "m42-token", "type": "promptString", "description": "Matrix42 API token", "password": true }
  ],
  "servers": {
    "matrix42": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "matrix42-mcp"],
      "env": {
        "M42_HOST": "https://matrix42.example.com",
        "M42_API_TOKEN": "${input:m42-token}"
      }
    }
  }
}

Outros clientes compatíveis com stdio (Windsurf, Cline, Zed, …) usam o mesmo formato command / args / env.

Verificando a conexão

Peça ao assistente para chamar server_info ou execute o teste de fumaça incluído contra sua instância:

git clone https://github.com/sus-tech-gmbh/M42-MCP.git
cd M42-MCP && npm install && npm run build

M42_HOST=https://matrix42.example.com \
M42_API_TOKEN=your-api-token \
node scripts/smoke.mjs

Ele se conecta como um cliente MCP real e exercita todas as ferramentas.

Você também pode executar a CLI diretamente:

npx matrix42-mcp --help    # usage and configuration
npx matrix42-mcp --tools   # available tool ids

Ferramentas e ações

Seis ferramentas, cada uma agrupando um conjunto de ações. Tudo o que o servidor pode fazer está aqui - as ferramentas de leitura primeiro, depois a que escreve.

Ferramenta	O que faz
`server_info`	Informa qual instância Matrix42 está conectada e verifica se as credenciais funcionam. Nunca retorna credenciais.
`webservice_discovery`	Descobre a API REST. Veja as ações abaixo.
`schema_discovery`	Explora o modelo de dados: definições de dados, itens de configuração, atributos, relações, valores de pickup.
`data_query`	Lê registros: consultas ASQL, visualizações salvas, entradas de diário, anexos, além de um guia e validador ASQL.
`service_desk`	Pesquisa chamados de qualquer tipo, responde perguntas sobre nível de serviço e navega por ativos, contratos, serviços de catálogo, reservas, artigos de conhecimento, aprovações, importações e instâncias de fluxo de trabalho.
`ticket_actions`	Escreve - o ciclo de vida do chamado: criar, fechar, assumir, encaminhar, pausar, reabrir, definir prazos, registrar tempo, adicionar entradas de diário. Somente presente quando `M42_ALLOW_WRITES=1`.

Ações de `webservice_discovery`

Ação	Parâmetros	Retorna
`api_overview`	-	Convenções gerais da API Matrix42: troca de token, `Explicit-Language`, API Pública vs API de Produto, superfícies de dados comuns. Útil antes de escrever código de integração independente.
`list_operations`	`search?`, `service_id?`, `limit?`	Operações como `{id, name, method, path, service, documentation}`. `search` filtra por nome, documentação e nome do serviço. Padrão: primeiras 200 correspondências; passe `limit: 0` para todas.
`list_services`	-	Cada web service com seu prefixo de rota e documentação.
`describe_operation`	`operation_id`	Contrato completo de uma operação: método HTTP, caminho, parâmetros com tipos e tipo de retorno.

Fluxo típico: api_overview uma vez → list_operations com um termo de busca → describe_operation na que você deseja.

Ações de `schema_discovery`

Ação	Parâmetros	Retorna
`schema_overview`	-	Como o modelo de dados do Matrix42 se encaixa: definições de dados vs itens de configuração, fragmentos e multi-fragmentos, cardinalidade, pickups e onde encontrar a documentação oficial.
`list_data_definitions`	`search?`, `include_pickups?`, `limit?`	Definições como `{internalName, displayName, description, classType, isPickup, isCustom}`. Classes de pickup são excluídas a menos que solicitadas.
`list_configuration_items`	`search?`, `limit?`	Itens com sua classe principal e definições de membros.
`describe_data_definition`	`name`, `include?`	Atributos com tipos de dados decodificados e links cruzados de pickup. Relações são excluídas por padrão (uma definição central pode ter 150+) - passe `include: "relations"` ou `"both"`.
`describe_configuration_item`	`name`	As definições que compõem um objeto, cada uma com sua cardinalidade e um sinalizador `isMultiFragment`.
`get_pickup_values`	`pickup_class` ou `name`+`attribute`	Os pares `{value, label}` selecionáveis - para que um modelo filtre por valores reais em vez de adivinhar códigos.

Fluxo típico: schema_overview → list_* com um termo de busca → describe_* → get_pickup_values antes de filtrar por qualquer atributo de pickup.

Ações de `data_query`

Ação	Parâmetros	Retornos
`asql_guide`	-	A linguagem de expressão ASQL usada por `where` e `columns`: operadores, cadeias de pontos, pickups, pivôs `T(...)`, subconsultas, `[Expression-ObjectID]`.
`validate_asql`	`class`, `expression`	Se uma expressão é válida, com o erro exato (ex.: "does not contain attribute Nope"). Mais barato que uma consulta com falha.
`query`	`class`, `columns?`, `where?`, `sort?`, `page_size?`, `page?`	Linhas mais metadados de colunas tipadas, com paginação (`hasMore`).
`get_fragment`	`class`, `fragment_id`	Um fragmento completo.
`get_object`	`ci_name`, `object_id`	Um objeto inteiro (todos os fragmentos de um item de configuração).
`list_views` / `run_view`	`search?` / `view_id`	As consultas de dados salvas da instância - visualizações curadas que já carregam um filtro predefinido. Prefira uma visualização correspondente a ASQL escrito à mão.
`list_journal`	`object_id`	A linha do tempo de comentários/atividades de um objeto.
`list_attachments`	`object_id`	Os arquivos anexados a um objeto.
`deep_link`	`object_id`, `view_type?`	Uma URL para a interface web da Matrix42 - visualizar, editar, criar ou executar uma ação. Resolve o item de configuração do objeto em si, então você só precisa do ID do objeto.

Fluxo típico: asql_guide uma vez → schema_discovery para encontrar a classe e seus valores de pickup → validate_asql → query. Sempre passe sort ao paginar; os limites de página são instáveis caso contrário.

Enums numéricos são decodificados para você (Datatype: 2 → "Int", Cardinality: 3 → "Optional (Multi)"), e personalizações são sinalizadas usando o prefixo personalizado que a própria instância relata.

Links para a interface web

data_query(action='deep_link') constrói uma URL que um assistente pode entregar a você, no formato que a Matrix42 documenta para deep linking:

https://your-instance/wm/app-ServiceDesk/?view-options={"type":"SPSActivityTypeTicket",
                                                        "viewType":"preview",
                                                        "objectId":"<object id>"}

view_type seleciona o que abre: preview (padrão, somente leitura), edit, new para um formulário de criação, ou action para um assistente. Apenas new funciona sem um ID de objeto, e action adicionalmente precisa de um action_id. Nada é alterado ao abrir um link - até edit espera que uma pessoa salve.

Você só precisa do ID do objeto. Uma definição de dados base é reutilizada por muitos itens de configuração - SPSActivityClassBase sozinho sustenta incidentes, solicitações de serviço e mudanças - então o servidor resolve o real para você em vez de fazer você escolher. Passe um ci_name errado e ele corrige; passe um ID de fragmento e ele recusa em vez de entregar um link que não abre nada.

Links apontam para a origem da própria interface web, não para o host da API ao qual você se conectou. Esses são frequentemente diferentes: uma instância acessível por um IP geralmente serve sua UUX sob um nome real, e o config.json do shell diz qual. Carregar o shell de uma origem errada deixa o aplicativo chamando uma origem da qual não foi servido, o que falha depois que a página já pareceu carregar. O servidor lê essa origem da instância e a reporta como webInterface junto com o link; M42_UI_URL a substitui.

Ações de `service_desk`

Ação	Parâmetros	Retornos
`data_model`	-	Como os módulos da Matrix42 mapeiam para um punhado de classes base - onde tickets, ativos, licenças, contratos, SLAs e itens de catálogo realmente vivem. Leia quando não tiver certeza de onde algo está.
`search_tickets`	`kind`, mais `subject`, `category_name` e/ou `states`	Tickets correspondentes. `kind` é um de `ticket`, `incident`, `problem`, `change`, `task`, `service_request`, `kb_article`. Outros parâmetros de filtro existem, mas a Matrix42 os ignora, então passar um é recusado.
`get_ticket`	`ticket_object_id`	O resumo de um ticket como o service desk o vê.
`sla_for_ticket`	`ticket_object_id`	Os acordos de nível de serviço que se aplicam, como a própria Matrix42 os calcula.
`sla_times`	`ticket_object_id`	Estado de tempo de reação e solução.
`browse`	`domain`, `search?`, `where?`, `limit?`	Linhas de um domínio curado, mais os campos que esta instância não possui.
`find`	`search`, `domains?`, `limit?`	Pesquisa todos os domínios de uma vez por um nome - para quando você não sabe onde algo vive. Domínios que falham (módulo não instalado) são relatados, não fatais.

Cada tipo compartilha o mesmo contrato, então uma forma de chamada cobre todo o service desk. Apenas subject, category_name e states realmente filtram - a Matrix42 aceita initiator_name, ticket_number, asset_id e o resto, depois os ignora e retorna todos os tickets. Passar um é recusado em vez de devolver um resultado não filtrado que você leria como filtrado; a recusa aponta para data_query com um where ASQL, que filtra nesses.

Domínios browse: assets, stock_units, contracts, slas, catalog_services, bookings, kb_articles, approvals, imports, import_runs, workflow_instances, workflow_definitions, applications. Workflows são somente leitura - este servidor lista definições e instâncias, mas nunca inicia, suspende, retoma ou cancela.

Colunas nunca são adivinhadas. Antes de cada browse, o servidor lê a lista real de atributos da definição da instância e mantém apenas os campos que existem, relatando o resto como unavailableFields. Um módulo que você não licenciou, portanto, produz uma linha mais curta, não uma chamada com falha. A mesma regra é declarada nos guias e nas instruções do servidor, então um modelo conectado também a segue.

Todas as ferramentas de leitura são anotadas com readOnlyHint: true, para que os clientes possam distingui-las de qualquer coisa que alteraria dados.

Ações de `ticket_actions` (escrita de dados)

Ferramentas de escrita estão ausentes da lista de ferramentas a menos que M42_ALLOW_WRITES=1, então uma implantação padrão não pode modificar nada, mesmo que um modelo peça. Quando habilitado, ticket_actions oferece:

Ação	Notas
`create_ticket`	Retorna o novo ID do objeto, que toda outra ação aceita diretamente.
`close_ticket`	Fecha por ID do objeto, com uma solução opcional e motivo de fechamento.
`add_journal_entry`	Adiciona um comentário a qualquer objeto, com template opcional `parameters`.
`classify_ticket`	Apenas sugere um tipo a partir de texto - não altera nada.
`take_over` / `accept`	Reivindica tickets. Precisa de `type_name`, o item de configuração ao qual pertencem.
`forward`	Entrega tickets a um `role_id` ou `user_id`, opcionalmente aplicando um OLA.
`pause`	Segura um ticket, opcionalmente parando o relógio de escalonamento (`not_escalate_while_paused`).
`reopen`	Reverte um fechamento, com um motivo.
`return_to_role`	Devolve um ticket ao seu papel responsável.
`set_deadline`	Define a data em que o ticket deve ser tratado.
`track_working_time`	Registra esforço, opcionalmente tipado (`investigation`, `resolution`, …).
`transform`	Transforma tickets em outro tipo - um incidente em uma solicitação de serviço, por exemplo. Reescreve o que o registro é; campos que o tipo de destino não possui são perdidos.

A Matrix42 envolve sua máquina de estados nessas operações nomeadas em vez de expor um campo de estado bruto, que é o que as torna seguras de oferecer: cada uma carrega exatamente os parâmetros que sua transição precisa.

Visualizar, depois confirmar

Toda ação visualiza por padrão. Chamada sem confirm: true, uma escrita retorna a solicitação exata que enviaria - método, caminho, corpo - junto com as consequências que valem a pena ler, e não altera nada:

{
  "wouldChange": true,
  "applied": false,
  "summary": "Close 1 ticket(s)",
  "request": { "method": "POST", "path": "m42Services/api/ticket/Close", "body": { "…": "…" } },
  "effects": ["No notifications are sent and nothing cascades."],
  "next": "Nothing was changed. Show this to the user, and call again with confirm:true to apply it."
}

Essa visualização é o mesmo objeto de plano que o caminho de execução roda, então nunca pode descrever uma solicitação e enviar outra. Passe dry_run: true para forçar uma visualização mesmo quando confirm está definido.

Todo ticket criado também recebe uma nota de diário interna registrando que foi aberto através deste servidor. Criar pela API de outra forma não deixa nenhum rastro do que a interface web deixa, então um humano que pega o ticket não tem como saber de onde veio. A nota nunca é visível no portal, e se não puder ser escrita, o ticket ainda é relatado como criado - perder uma linha de auditoria nunca deve parecer uma criação com falha. Desative com M42_AUDIT_NOTE=0, ou nomeie o assistente com M42_AGENT_LABEL="Acme Helpdesk Assistant".

Existem mais dois padrões para evitar os erros que mais importam no gerenciamento de serviços:

E-mails de notificação estão desligados. notify_initiator, notify_users e notify_responsible todos usam como padrão false; fechar um ticket não envia e-mail a ninguém a menos que você peça.
Entradas de diário são internas. visible_in_portal usa como padrão false, então um comentário não é publicado no portal de autoatendimento do solicitante por acidente.

close_related_incidents também usa como padrão false, já que ele se propaga para outros tickets.

Prompts

Templates reutilizáveis que seu cliente pode oferecer (no Claude Desktop, o menu de prompts). Cada um codifica a ordem de operações que este servidor recompensa, então um modelo não precisa redescobri-la falhando:

Prompt	Para
`explore_instance`	Se orientar em uma instância desconhecida
`build_query`	Transformar uma pergunta em uma consulta ASQL validada
`triage_ticket`	Trabalhar um ticket de ponta a ponta, sem alterar nada
`safe_change`	Conduzir uma escrita por visualização → confirmação
`find_endpoint`	Localizar a operação certa antes de escrever código de integração

Recursos

Os guias escritos também são publicados como recursos MCP, então um cliente pode lê-los sem uma chamada de ferramenta e anexar um a uma conversa antecipadamente:

URI	Conteúdo
`matrix42://guide/data-model`	Matrix42 é um grafo, não muitos módulos
`matrix42://guide/schema`	Definições de dados, itens de configuração, fragmentos, pickups
`matrix42://guide/asql`	A linguagem de expressão ASQL
`matrix42://guide/api`	Convenções da API REST: autenticação, cabeçalhos, API Pública vs API de Produto

O mesmo texto está versionado em docs/ para ser legível no GitHub sem executar nada - comece com Matrix42 é um grafo, não muitos módulos, que explica por que não há tabela "Licenças" ou "SLAs" e onde esses registros realmente vivem. Esses arquivos são gerados a partir dos módulos de guia (npm run docs), e um teste falha se eles divergirem.

Notas de segurança

O servidor é um proxy com credenciais. Qualquer coisa que a conta configurada possa ler pela API, um assistente conectado pode alcançar pelas ferramentas que recebe. Use uma conta com escopo para o que o assistente realmente precisa.
Credenciais permanecem locais. Elas são lidas do ambiente, usadas apenas para solicitações à sua instância, e nunca escritas em logs ou retornadas por qualquer ferramenta.
Nunca faça commit de .env. Ele é ignorado pelo git; use o bloco env do seu cliente ou um prompt secreto.
M42_ALLOW_INSECURE_TLS desativa a verificação de certificado. Use apenas para instâncias de desenvolvimento com certificado autoassinado, nunca contra produção.
Limite a superfície com M42_TOOLS se você quiser apenas parte dela.

Desenvolvimento

npm install
npm run build        # compile to dist/
npm run typecheck    # tsc --noEmit
npm test             # unit tests (vitest)
npm run docs         # regenerate docs/ from the guide modules
node scripts/smoke.mjs                # end-to-end against a real instance
node scripts/service-desk-smoke.mjs   # service desk, domains and lifecycle verbs

service-desk-smoke.mjs confina suas escritas a um único ticket que ele mesmo cria, e o fecha no final; nada pré-existente é modificado e nenhum e-mail de notificação é solicitado.

Como tudo se encaixa

Layered architecture: the MCP surface sits on domain modules, which sit on the correctness and safety layer, which sits on the authenticated client.

Dois módulos carregam as garantias nas quais o restante do servidor depende: `columns.ts` significa que nenhuma projeção é enviada que a instância não possa responder, e `write-plan.ts` significa que uma pré-visualização e sua solicitação são o mesmo objeto.

Layout

src/
  index.ts           entry point: config → client → MCP stdio server
  config.ts          environment configuration + validation
  m42-client.ts      authenticated HTTP client (token exchange, caching, TLS)
  discovery.ts       fragment queries + projections for services/operations
  schema.ts          schema listings, detail projections, enum decoding, pickup resolution
  api-overview.ts    the static Matrix42 API guide served by api_overview
  schema-overview.ts the static data-model guide served by schema_overview
  data.ts            record queries, paging, result shaping, ASQL validation
  objects.ts         journal, attachments, saved views, current-user identity
  tickets.ts         write operations and their safety defaults
  ticket-verbs.ts    the ticket lifecycle verbs (take over, forward, pause, reopen, …)
  service-desk.ts    the uniform ticket Search contract and the service-level endpoints
  columns.ts         resolves query columns from the live schema instead of assuming them
  domains.ts         the curated domain registry (assets, contracts, catalog, …)
  domain-guide.ts    the "one graph, not many modules" guide
  asql-guide.ts      the static ASQL guide served by asql_guide
  resources.ts       publishes the guides as MCP resources
  prompts.ts         reusable prompt templates
  deep-links.ts      URLs into the Matrix42 web interface (pure string building)
  write-plan.ts      the request a write would send, as a value - the basis of preview/confirm
  tools/             one module per tool, registered from a small registry

Adicionar uma ferramenta significa adicionar um módulo em src/tools/ e listá-lo em src/tools/index.ts; seu id então funciona em M42_TOOLS automaticamente.

Roadmap

Upload e download de anexos
Decisões de aprovação (aprovar / rejeitar), que hoje são somente leitura
Tokens por usuário, para que "meus itens" possam significar um usuário final em vez da conta de serviço

Contribuindo

Contribuições são muito bem-vindas - este é um projeto comunitário e ele melhora com mais instâncias por trás dele. As implantações do Matrix42 diferem enormemente, então um relatório de bug que cita a solicitação exata e o erro exato vale muito: muitas vezes é a única maneira de saber que um atributo ou uma operação se comporta de forma diferente em outro lugar.

Boas primeiras contribuições:

Um domínio que é importante para você, mas que está ausente em src/domains.ts.
Uma correção em um guia em src/*-guide.ts / src/*-overview.ts (depois execute npm run docs).
Um caso de falha da sua instância, com a solicitação e a resposta, como uma issue.

Antes de abrir um pull request:

npm run typecheck && npm test && npm run build

Suporte

Somente suporte comunitário, através de GitHub issues e discussões. Não há SLA, e a Matrix42 AG não pode ajudar você com este projeto - por favor, não abra um ticket com eles sobre isso.

Projeto


Contribuindo	CONTRIBUTING.md
Código de conduta	CODE_OF_CONDUCT.md
Política de segurança	SECURITY.md
Changelog	CHANGELOG.md
Lançamentos	GitHub releases

Os lançamentos são publicados a partir do CI quando um GitHub Release é publicado, usando npm trusted publishing - nenhum token npm de longa duração existe em qualquer lugar, e cada tarball carrega proveniência vinculando-o ao commit e à execução do workflow que o construiu.

Segurança

Encontrou uma vulnerabilidade? Por favor, relate-a de forma privada em vez de em uma issue pública - veja SECURITY.md.

Licença

Aviso legal

Este projeto é uma integração independente, mantida pela comunidade. Ele não é afiliado, endossado, patrocinado ou apoiado pela Matrix42 AG. "Matrix42" e quaisquer marcas relacionadas pertencem aos seus respectivos proprietários e são usadas aqui somente para identificar o software com o qual este projeto interopera. Nenhum código-fonte ou documentação da Matrix42 é redistribuído neste repositório.

O software é fornecido "como está", sem garantia de qualquer tipo. Você é responsável pela conta com a qual o configura e por qualquer coisa que um assistente faça através dele - leia Notas de segurança antes de apontá-lo para uma instância de produção.