Matrix42 MCP

Servidor de Model Context Protocol para Matrix42: permite que los asistentes de IA exploren la API, lean el modelo de datos, busquen en el service desk y actúen sobre tickets. Solo lectura por defecto.

GitHub

Documentación

Servidor MCP de Matrix42

Dale a tu asistente de IA una ventana segura, de solo lectura por defecto, a Matrix42.

Un servidor de Model Context Protocol que permite a un asistente explorar una instancia de Matrix42 como lo haría un consultor experimentado: encontrar el servicio web correcto, leer el modelo de datos real, consultar registros con filtros válidos, buscar en el service desk y — solo si lo activas — actuar sobre tickets.

El servidor guarda las credenciales y habla con Matrix42 en nombre del asistente: realiza el intercambio de tokens de API, establece el encabezado Explicit-Language y gestiona TLS. El asistente nunca ve tus credenciales.

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 es un proyecto comunitario independiente. No está afiliado, respaldado, patrocinado ni soportado por Matrix42 AG. "Matrix42" es una marca comercial de su respectivo propietario y se utiliza aquí solo para describir con qué interoperable este software. El soporte proviene de la comunidad a través de problemas de GitHub — no contactes con el soporte de Matrix42 sobre este proyecto, y no esperes un acuerdo de nivel de servicio de ningún tipo. Se proporciona "tal cual" bajo la licencia MIT.

[!NOTE] Estado: lanzamiento temprano. El servidor es de solo lectura por defecto — las herramientas de escritura ni siquiera se listan a menos que establezcas M42_ALLOW_WRITES=1.

Destacados

Solo lectura por defecto. Las herramientas de escritura están ausentes de la lista de herramientas a menos que se habiliten explícitamente.
Nunca adivina. Cada columna se resuelve contra el esquema en vivo de tu instancia antes de que se ejecute una consulta, por lo que un campo que tu instancia no tiene se informa — no se envía y se convierte en un 500 opaco.
Enseña, luego actúa. Cuatro guías escritas se incluyen con el servidor como recursos MCP, que cubren el modelo de datos, el esquema, el lenguaje de filtros ASQL y las convenciones REST.
Vista previa antes de escribir. Cada escritura devuelve la solicitud exacta que enviaría hasta que pases confirm. La vista previa es el mismo objeto de plan que se ejecuta, por lo que no puede desviarse.
Valores predeterminados seguros donde importa. Los correos de notificación están desactivados, las entradas de diario son internas, y los cierres en cascada son opcionales.
Sin código ni contenido de Matrix42. Cada guía es prosa original que enlaza a la documentación oficial en lugar de reproducirla.

Tabla de contenidos

Entiéndelo

Por qué
Qué puede hacer
- Cómo se ve una conversación

Configúralo

Requisitos
- Creación de un token de API
Configuración
Configuración del cliente
Verificación de la conexión

Úsalo

Herramientas y acciones
Notas de seguridad

Trabaja en ello

Desarrollo
- Cómo encaja
- Estructura
Hoja de ruta
Contribuciones
Soporte
Proyecto
Seguridad
Licencia

Por qué

La superficie de API de Matrix42 es grande (una instancia típica expone ~190 servicios web y ~1,100 operaciones), más un modelo de datos de ~800 definiciones de datos y ~240 elementos de configuración, y un asistente no tiene forma de saber qué existe. Apúntalo a este servidor y podrá buscar el endpoint correcto, leer el contrato exacto y luego escribir código de integración correcto — en lugar de adivinar URLs, autenticación y encabezados.

Qué puede hacer


Descubre la API	~1,100 operaciones con contratos completos de solicitud y respuesta, y si cada una es segura para actualizar
Entiende el modelo	785 definiciones de datos, 237 elementos de configuración, valores de selección, relaciones y cardinalidad
Lee registros	Consultas ASQL con paginación, vistas guardadas, diario, adjuntos y enlaces a la interfaz web
Trabaja en el service desk	Busca siete tipos de tickets por nombre, niveles de servicio, trece dominios curados, o busca en todos a la vez
Actúa sobre tickets	Crear, cerrar, clasificar, asumir, reenviar, pausar, reabrir, establecer plazos, registrar tiempo — cada uno con vista previa primero

Cómo se ve una conversación

Tú: ¿Qué tickets de hardware abiertos siguen sin resolver, y hay alguno que haya superado su nivel de servicio?

El asistente lo resuelve sin que nombres un solo 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.

Observa lo que no sucedió: sin búsquedas de GUID, sin nombres de atributos adivinados, y nada se escribió. Observa también lo que el servidor rechaza: un filtro que Matrix42 acepta pero nunca aplica, por lo que una respuesta sin filtrar nunca se confunde con una filtrada.

Requisitos

Node.js 22.19 o más reciente (requerido por undici, el cliente HTTP)
Una instancia de Matrix42 y ya sea un token de API (recomendado) o credenciales de autenticación básica

Creación de un token de API

En la aplicación de Administración de Matrix42, crea un token de API para la cuenta bajo la que el asistente debe actuar. El servidor lo intercambia automáticamente por un token de acceso de corta duración y lo vuelve a intercambiar antes de que expire.

La autenticación básica es compatible pero no recomendada: muchas instancias aceptan las credenciales pero aún así rechazan el acceso a la API con 403 debido a restricciones de rol/audiencia.

Configuración

Toda la configuración es mediante variables de entorno.

Variable	Requerida	Predeterminado	Descripción
`M42_HOST`	✅	-	URL base de la instancia, p. ej. `https://matrix42.example.com`
`M42_API_TOKEN`	✅¹	-	Token de API; se intercambia por un token de acceso automáticamente
`M42_USERNAME` / `M42_PASSWORD`	✅¹	-	Alternativa de autenticación básica a `M42_API_TOKEN`
`M42_LANGUAGE`		`en-US`	Idioma de respuesta, enviado como `Explicit-Language`
`M42_TOOLS`		todos	IDs de herramientas separados por comas para exponer
`M42_ALLOW_WRITES`		`0`	Establécelo en `1` para exponer herramientas que modifican datos. Las herramientas de escritura no se registran en absoluto a menos que esto esté establecido.
`M42_ALLOW_INSECURE_TLS`		`0`	Establécelo en `1` para omitir la verificación TLS (solo instancias de desarrollo autofirmadas)
`M42_AUDIT_NOTE`		`1`	Marca los tickets creados con una nota interna que dice que se crearon a través de este servidor. Establécelo en `0` para desactivarlo.
`M42_AGENT_LABEL`		`Matrix42 MCP server`	Cómo se nombra al asistente en esa nota
`M42_UI_URL`		descubierto	Origen de la interfaz web, para enlaces profundos. Se descubre de la configuración del shell web de la instancia cuando no se establece.
`M42_TIMEOUT_MS`		`30000`	Tiempo de espera por solicitud

¹ Proporciona ya sea M42_API_TOKEN o ambos M42_USERNAME y M42_PASSWORD.

Configuración del cliente

El servidor se ejecuta sobre stdio: tu cliente MCP lo inicia. No se necesita paso de instalación — npx lo obtiene bajo 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) o .cursor/mcp.json (por proyecto)

{
  "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 — esta forma solicita el token en lugar de almacenarlo en el archivo:

{
  "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}"
      }
    }
  }
}

Otros clientes compatibles con stdio (Windsurf, Cline, Zed, …) usan la misma forma de command / args / env.

Verificación de la conexión

Pide al asistente que llame a server_info, o ejecuta la prueba de humo incluida contra tu instancia:

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

Se conecta como un cliente MCP real y ejercita cada herramienta.

También puedes ejecutar la CLI directamente:

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

Herramientas y acciones

Seis herramientas, cada una agrupando un conjunto de acciones. Todo lo que el servidor puede hacer vive aquí — primero las herramientas de lectura, luego la que escribe.

Herramienta	Qué hace
`server_info`	Informa qué instancia de Matrix42 está conectada y verifica que las credenciales funcionan. Nunca devuelve credenciales.
`webservice_discovery`	Descubre la API REST. Consulta las acciones a continuación.
`schema_discovery`	Explora el modelo de datos: definiciones de datos, elementos de configuración, atributos, relaciones, valores de selección.
`data_query`	Lee registros: consultas ASQL, vistas guardadas, entradas de diario, adjuntos, más una guía y validador ASQL.
`service_desk`	Busca tickets de cualquier tipo, responde preguntas de nivel de servicio y navega por activos, contratos, servicios de catálogo, reservas, artículos de conocimiento, aprobaciones, importaciones e instancias de flujo de trabajo.
`ticket_actions`	Escribe — el ciclo de vida del ticket: crear, cerrar, asumir, reenviar, pausar, reabrir, establecer plazos, registrar tiempo, agregar entradas de diario. Solo presente cuando `M42_ALLOW_WRITES=1`.

Acciones de `webservice_discovery`

Acción	Parámetros	Devuelve
`api_overview`	-	Convenciones generales de la API de Matrix42: intercambio de tokens, `Explicit-Language`, API Pública vs API de Producto, superficies de datos comunes. Útil antes de escribir código de integración independiente.
`list_operations`	`search?`, `service_id?`, `limit?`	Operaciones como `{id, name, method, path, service, documentation}`. `search` filtra por nombre, documentación y nombre de servicio. Predeterminado a los primeros 200 resultados; pasa `limit: 0` para todos.
`list_services`	-	Cada servicio web con su prefijo de ruta y documentación.
`describe_operation`	`operation_id`	El contrato completo de una operación: método HTTP, ruta, parámetros con tipos y tipo de retorno.

Flujo típico: api_overview una vez → list_operations con un término de búsqueda → describe_operation en el que quieras.

Acciones de `schema_discovery`

Acción	Parámetros	Devuelve
`schema_overview`	-	Cómo encaja el modelo de datos de Matrix42: definiciones de datos vs elementos de configuración, fragmentos y multi-fragmentos, cardinalidad, selecciones y dónde encontrar la documentación oficial.
`list_data_definitions`	`search?`, `include_pickups?`, `limit?`	Definiciones como `{internalName, displayName, description, classType, isPickup, isCustom}`. Las clases de selección se excluyen a menos que se soliciten.
`list_configuration_items`	`search?`, `limit?`	Elementos con su clase principal y definiciones de miembros.
`describe_data_definition`	`name`, `include?`	Atributos con tipos de datos decodificados y enlaces cruzados de selección. Las relaciones se excluyen por defecto (una definición central puede tener 150+) — pasa `include: "relations"` o `"both"`.
`describe_configuration_item`	`name`	Las definiciones de las que se compone un objeto, cada una con su cardinalidad y una bandera `isMultiFragment`.
`get_pickup_values`	`pickup_class` o `name`+`attribute`	Los pares `{value, label}` seleccionables — para que un modelo filtre por valores reales en lugar de adivinar códigos.

Flujo típico: schema_overview → list_* con un término de búsqueda → describe_* → get_pickup_values antes de filtrar por cualquier atributo de selección.

Acciones de `data_query`

Acción	Parámetros	Devuelve
`asql_guide`	-	El lenguaje de expresiones ASQL utilizado por `where` y `columns`: operadores, cadenas de puntos, recogidas, pivotes `T(...)`, subconsultas, `[Expression-ObjectID]`.
`validate_asql`	`class`, `expression`	Si una expresión es válida, con el error exacto (p. ej. "does not contain attribute Nope"). Más barato que una consulta fallida.
`query`	`class`, `columns?`, `where?`, `sort?`, `page_size?`, `page?`	Filas más metadatos de columnas tipadas, con paginación (`hasMore`).
`get_fragment`	`class`, `fragment_id`	Un fragmento completo.
`get_object`	`ci_name`, `object_id`	Un objeto completo (todos los fragmentos de un elemento de configuración).
`list_views` / `run_view`	`search?` / `view_id`	Las consultas de datos guardadas de la instancia: vistas seleccionadas que ya llevan un filtro predefinido. Prefiere una vista coincidente antes que ASQL escrito a mano.
`list_journal`	`object_id`	La línea de tiempo de comentarios/actividad de un objeto.
`list_attachments`	`object_id`	Los archivos adjuntos a un objeto.
`deep_link`	`object_id`, `view_type?`	Una URL a la interfaz web de Matrix42: vista previa, edición, creación o ejecución de una acción. Resuelve el elemento de configuración del objeto en sí, por lo que solo necesitas el id del objeto.

Flujo típico: asql_guide una vez → schema_discovery para encontrar la clase y sus valores de recogida → validate_asql → query. Pasa siempre sort al paginar; de lo contrario, los límites de página son inestables.

Los enums numéricos se decodifican por ti (Datatype: 2 → "Int", Cardinality: 3 → "Optional (Multi)"), y las personalizaciones se marcan usando el prefijo personalizado que la propia instancia informa.

Enlaces a la interfaz web

data_query(action='deep_link') construye una URL que un asistente puede entregarte, en el formato que Matrix42 documenta para enlaces profundos:

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

view_type selecciona qué se abre: preview (predeterminado, solo lectura), edit, new para un formulario de creación, o action para un asistente. Solo new funciona sin un id de objeto, y action además necesita un action_id. Nada cambia nunca al abrir un enlace: incluso edit espera a que una persona guarde.

Solo necesitas el id del objeto. Una definición de datos base se reutiliza en muchos elementos de configuración: SPSActivityClassBase por sí solo respalda incidentes, solicitudes de servicio y cambios, por lo que el servidor resuelve el real por ti en lugar de hacerte elegir. Pasa un ci_name incorrecto y lo corrige; pasa un id de fragmento y lo rechaza en lugar de darte un enlace que no abre nada.

Los enlaces apuntan al origen propio de la interfaz web, no al host de la API al que te conectaste. A menudo son diferentes: una instancia accesible por IP suele servir su UUX bajo un nombre real, y el config.json del shell lo indica. Cargar el shell desde el origen incorrecto hace que la aplicación llame a un origen desde el que no fue servida, lo que falla después de que la página ya parezca cargada. El servidor lee ese origen de la instancia y lo informa como webInterface junto al enlace; M42_UI_URL lo anula.

Acciones de `service_desk`

Acción	Parámetros	Devuelve
`data_model`	-	Cómo los módulos de Matrix42 se asignan a un puñado de clases base: dónde viven realmente tickets, activos, licencias, contratos, SLA y elementos de catálogo. Léelo cuando no estés seguro de dónde está algo.
`search_tickets`	`kind`, más `subject`, `category_name` y/o `states`	Tickets coincidentes. `kind` es uno de `ticket`, `incident`, `problem`, `change`, `task`, `service_request`, `kb_article`. Existen otros parámetros de filtro, pero Matrix42 los ignora, por lo que pasar uno es rechazado.
`get_ticket`	`ticket_object_id`	El resumen de un ticket tal como lo ve la mesa de servicio.
`sla_for_ticket`	`ticket_object_id`	Los acuerdos de nivel de servicio aplicables, tal como Matrix42 mismo los calcula.
`sla_times`	`ticket_object_id`	Estado del tiempo de reacción y solución.
`browse`	`domain`, `search?`, `where?`, `limit?`	Filas de un dominio seleccionado, más los campos que esta instancia no tiene.
`find`	`search`, `domains?`, `limit?`	Busca todos los dominios a la vez por un nombre, para cuando no sabes dónde vive algo. Los dominios que fallan (módulo no instalado) se informan, no son fatales.

Cada tipo comparte el mismo contrato, por lo que una sola forma de llamada cubre toda la mesa de servicio. Solo subject, category_name y states realmente lo filtran: Matrix42 acepta initiator_name, ticket_number, asset_id y el resto, luego los ignora y devuelve todos los tickets. Pasar uno es rechazado en lugar de devolver un resultado sin filtrar que leerías como filtrado; el rechazo apunta a data_query con un where ASQL, que sí filtra en esos.

Dominios browse: assets, stock_units, contracts, slas, catalog_services, bookings, kb_articles, approvals, imports, import_runs, workflow_instances, workflow_definitions, applications. Los flujos de trabajo son de solo lectura: este servidor lista definiciones e instancias, pero nunca los inicia, suspende, reanuda o cancela.

Las columnas nunca se adivinan. Antes de cada browse, el servidor lee la lista de atributos real de la definición desde la instancia y conserva solo los campos que existen, informando el resto como unavailableFields. Un módulo que no tienes licenciado produce por tanto una fila más corta, no una llamada fallida. La misma regla se indica en las guías y en las instrucciones del servidor, por lo que un modelo conectado también la sigue.

Todas las herramientas de lectura están anotadas como readOnlyHint: true, para que los clientes puedan distinguirlas de cualquier cosa que cambiaría datos.

Acciones de `ticket_actions` (escritura de datos)

Las herramientas de escritura están ausentes de la lista de herramientas a menos que M42_ALLOW_WRITES=1, por lo que una implementación predeterminada no puede modificar nada incluso si un modelo lo pide. Cuando está habilitado, ticket_actions ofrece:

Acción	Notas
`create_ticket`	Devuelve el nuevo id de objeto, que todas las demás acciones toman directamente.
`close_ticket`	Cierra por id de objeto, con una solución y motivo de cierre opcionales.
`add_journal_entry`	Añade un comentario a cualquier objeto, con plantilla opcional `parameters`.
`classify_ticket`	Solo sugiere un tipo a partir de texto: no cambia nada.
`take_over` / `accept`	Reclama tickets. Necesita `type_name`, el elemento de configuración al que pertenecen.
`forward`	Entrega tickets a un `role_id` o `user_id`, aplicando opcionalmente un OLA.
`pause`	Retiene un ticket, deteniendo opcionalmente el reloj de escalado (`not_escalate_while_paused`).
`reopen`	Revierte un cierre, con un motivo.
`return_to_role`	Devuelve un ticket a su rol responsable.
`set_deadline`	Establece la fecha en que el ticket debe ser gestionado.
`track_working_time`	Registra esfuerzo, opcionalmente tipado (`investigation`, `resolution`, …).
`transform`	Convierte tickets en otro tipo: un incidente en una solicitud de servicio, por ejemplo. Reescribe lo que el registro es; los campos que el tipo de destino no tiene se pierden.

Matrix42 envuelve su máquina de estados en estas operaciones nombradas en lugar de exponer un campo de estado crudo, que es lo que las hace seguras de ofrecer: cada una lleva exactamente los parámetros que su transición necesita.

Vista previa, luego confirmación

Cada acción muestra una vista previa por defecto. Llamada sin confirm: true, una escritura devuelve la solicitud exacta que enviaría (método, ruta, cuerpo), junto con las consecuencias que vale la pena leer, y no cambia 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."
}

Esa vista previa es el mismo objeto de plan que ejecuta la ruta de ejecución, por lo que nunca puede describir una solicitud y enviar otra. Pasa dry_run: true para forzar una vista previa incluso cuando confirm está establecido.

Cada ticket creado también recibe una nota de diario interna que registra que se creó a través de este servidor. Crear a través de la API de otro modo no deja ningún rastro de los que deja la interfaz web, por lo que una persona que recoge el ticket no tiene forma de saber de dónde vino. La nota nunca es visible en el portal, y si no se puede escribir, el ticket aún se informa como creado: perder una línea de auditoría nunca debe parecer una creación fallida. Desactívala con M42_AUDIT_NOTE=0, o nombra al asistente con M42_AGENT_LABEL="Acme Helpdesk Assistant".

Existen otros dos valores predeterminados para evitar los errores más importantes en la gestión de servicios:

Los correos de notificación están desactivados. notify_initiator, notify_users y notify_responsible tienen como valor predeterminado false; cerrar un ticket no envía correo a nadie a menos que lo pidas.
Las entradas de diario son internas. visible_in_portal tiene como valor predeterminado false, por lo que un comentario no se publica en el portal de autoservicio del solicitante por accidente.

close_related_incidents también tiene como valor predeterminado false, ya que se propaga a otros tickets.

Prompts

Plantillas reutilizables que tu cliente puede ofrecer (en Claude Desktop, el menú de prompts). Cada una codifica el orden de operaciones que este servidor recompensa, para que un modelo no tenga que redescubrirlo fallando:

Prompt	Para
`explore_instance`	Orientarse en una instancia desconocida
`build_query`	Convertir una pregunta en una consulta ASQL validada
`triage_ticket`	Trabajar un ticket de principio a fin, sin cambiar nada
`safe_change`	Guiar una escritura a través de vista previa → confirmación
`find_endpoint`	Localizar la operación correcta antes de escribir código de integración

Recursos

Las guías escritas también se publican como recursos MCP, para que un cliente pueda leerlas sin una llamada de herramienta y adjuntar una a una conversación de antemano:

URI	Contenido
`matrix42://guide/data-model`	Matrix42 es un solo grafo, no muchos módulos
`matrix42://guide/schema`	Definiciones de datos, elementos de configuración, fragmentos, recogidas
`matrix42://guide/asql`	El lenguaje de expresiones ASQL
`matrix42://guide/api`	Convenciones de la API REST: autenticación, cabeceras, API Pública vs API de Producto

El mismo texto está registrado en docs/ para que sea legible en GitHub sin ejecutar nada: comienza con Matrix42 es un solo grafo, no muchos módulos, que explica por qué no hay una tabla de "Licencias" o "SLAs" y dónde viven realmente esos registros. Esos archivos se generan a partir de los módulos de guía (npm run docs), y una prueba falla si se desvían.

Notas de seguridad

El servidor es un proxy con credenciales. Cualquier cosa que la cuenta configurada pueda leer a través de la API, un asistente conectado puede alcanzarla a través de las herramientas que se le dan. Usa una cuenta limitada a lo que el asistente realmente necesita.
Las credenciales permanecen locales. Se leen del entorno, se usan solo para solicitudes a tu instancia, y nunca se escriben en registros ni se devuelven por ninguna herramienta.
Nunca confirmes .env. Está ignorado por git; usa el bloque env de tu cliente o un prompt secreto.
M42_ALLOW_INSECURE_TLS desactiva la verificación de certificados. Úsalo solo para instancias de desarrollo autofirmadas, nunca contra producción.
Limita la superficie con M42_TOOLS si solo quieres parte de ella.

Desarrollo

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 limita sus escrituras a un solo ticket que crea él mismo, y lo cierra al final; nada preexistente se modifica y nunca se solicita un correo de notificación.

Cómo encaja

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

Dos módulos sustentan las garantías de las que depende el resto del servidor: `columns.ts` significa que nunca se envía una proyección que la instancia no pueda responder, y `write-plan.ts` significa que una vista previa y su solicitud son el mismo objeto.

Diseño

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

Agregar una herramienta implica agregar un módulo bajo src/tools/ y listarlo en src/tools/index.ts; su id entonces funciona en M42_TOOLS automáticamente.

Hoja de ruta

Carga y descarga de archivos adjuntos
Decisiones de aprobación (aprobar / rechazar), que hoy son de solo lectura
Tokens por usuario, para que "mis elementos" pueda referirse a un usuario final en lugar de a la cuenta de servicio

Contribuciones

Las contribuciones son muy bienvenidas: este es un proyecto comunitario y mejora con más instancias detrás. Las implementaciones de Matrix42 varían enormemente, por lo que un informe de error que cite la solicitud exacta y el error exacto vale mucho: a menudo es la única forma de saber que un atributo o una operación se comporta de manera diferente en otro lugar.

Buenas primeras contribuciones:

Un dominio que te importe pero que falte en src/domains.ts.
Una corrección a una guía en src/*-guide.ts / src/*-overview.ts (luego ejecuta npm run docs).
Un caso fallido de tu instancia, con la solicitud y la respuesta, como issue.

Antes de abrir un pull request:

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

Soporte

Solo soporte comunitario, a través de GitHub issues y discussions. No hay SLA, y Matrix42 AG no puede ayudarte con este proyecto; por favor, no abras un ticket con ellos al respecto.

Proyecto


Contribuciones	CONTRIBUTING.md
Código de conducta	CODE_OF_CONDUCT.md
Política de seguridad	SECURITY.md
Registro de cambios	CHANGELOG.md
Lanzamientos	GitHub releases

Los lanzamientos se publican desde CI cuando se publica un GitHub Release, usando npm trusted publishing: no existe ningún token npm de larga duración en ningún lugar, y cada tarball lleva provenance que lo vincula al commit y a la ejecución del workflow que lo construyó.

Seguridad

¿Encontraste una vulnerabilidad? Por favor, repórtala de forma privada en lugar de en un issue público; consulta SECURITY.md.

Licencia

Aviso legal

Este proyecto es una integración independiente y mantenida por la comunidad. No está afiliado, respaldado, patrocinado ni soportado por Matrix42 AG. "Matrix42" y cualquier marca relacionada pertenecen a sus respectivos propietarios y se usan aquí únicamente para identificar el software con el que este proyecto interactúa. No se redistribuye ningún código fuente ni documentación de Matrix42 en este repositorio.

El software se proporciona "tal cual", sin garantía de ningún tipo. Eres responsable de la cuenta con la que lo configures y de cualquier cosa que un asistente haga a través de él; lee Security notes antes de apuntarlo a una instancia de producción.