Matrix42

Matrix42 MCP 服务

为你的 AI 助手提供一个安全的 Matrix42 只读访问入口（默认只读）。

一个 Model Context Protocol 服务，让助手能够像经验丰富的顾问一样探索 Matrix42 实例：找到合适的 Web 服务，读取实际数据模型，使用有效筛选条件查询记录，搜索服务台，以及——只有在你启用后——处理工单。

该服务保管凭据，并代表助手与 Matrix42 通信：执行 API 令牌交换、设置 Explicit-Language 标头并处理 TLS。助手永远看不到你的凭据。

npx matrix42-mcp --help

重要

这是一个独立的社区项目。 它不隶属于 Matrix42 AG，也未获得其认可、赞助或支持。“Matrix42”是其各自所有者的商标，此处仅用于说明本软件可与之互操作。社区通过 GitHub issues 提供支持——请勿就本项目联系 Matrix42 支持团队，也不要期待任何形式的服务级别协议。本项目按MIT 许可证“按原样”提供。

说明

状态：早期版本。 该服务默认只读——除非设置 M42_ALLOW_WRITES=1，否则不会列出写入工具。

亮点

• 默认只读。 除非明确启用，否则工具列表中不会包含写入工具。
• 绝不猜测。 每次查询前，都会根据实例的实时架构解析每一列；如果实例中没有某个字段，系统会报告这一情况，而不会发送该字段并导致不透明的 500 错误。
• 先讲解，再操作。 服务随附四份书面指南，作为 MCP 资源提供，涵盖数据模型、架构、ASQL 筛选语言和 REST 约定。
• 写入前先预览。 在你传入 confirm 之前，每次写入都会返回它将会发送的确切请求。预览与实际执行使用同一个计划对象，因此两者不会出现偏差。
• 关键环节采用安全默认值。 默认关闭通知邮件，日志条目设为内部可见，级联关闭操作则需主动启用。
• 不包含 Matrix42 代码或内容。 所有指南均为原创文字，并链接到官方文档，而非复制其内容。

---

目录

了解它

• 原因
• 它能做什么
  • 对话是什么样的

设置

• 要求
  • 创建 API 令牌
• 配置
• 客户端设置
  • Claude Code
  • Claude Desktop
  • Cursor
  • VS Code（GitHub Copilot）
• 验证连接

使用

• 工具和操作
  • webservice_discovery 操作
  • schema_discovery 操作
  • data_query 操作
    • 指向 Web 界面的链接
  • service_desk 操作
  • ticket_actions 操作（写入数据）
    • 先预览，再确认
  • 提示词
  • 资源
• 安全说明

参与开发

• 开发
  • 整体运作方式
  • 目录结构
• 路线图
• 贡献
• 支持
• 项目
• 安全
• 许可证

---

原因

Matrix42 的 API 范围很广（一个典型实例会公开约 190 个 Web 服务和约 1,100 个操作）， 此外还有约 800 个数据定义和约 240 个配置项组成的数据模型，助手无从得知其中有哪些内容。将它指向此服务后，助手便可以搜索合适的端点、读取准确的契约，进而编写正确的集成代码，而不是猜测 URL、身份验证方式和标头。

---

它能做什么

发现 API	约 1,100 个操作，包含完整的请求和返回契约，以及每个操作是否可安全更新
理解数据模型	785 个数据定义、237 个配置项、可选值、关系和基数
读取记录	支持分页的 ASQL 查询、已保存视图、日志、附件，以及指向 Web 界面的链接
处理服务台事务	按名称、服务级别、13 个精选领域搜索七种工单，也可以一次搜索全部领域
操作工单	创建、关闭、分类、接手、转发、暂停、重新打开、设置截止时间、记录工时——每项操作都会先预览

对话是什么样的

你： 哪些未解决的硬件工单仍处于打开状态？有没有工单已超过服务级别？

助手会自行处理，无需你提供任何 ID：

请注意，没有发生的事情：没有查询 GUID，没有猜测属性名称，也没有写入任何内容。还要注意服务会拒绝什么：Matrix42 接受但实际上不会应用的筛选条件，因此绝不会把未筛选的结果误认为已筛选结果。

---

要求

• Node.js 22.19 或更高版本（undici，即 HTTP 客户端所需）
• 一个 Matrix42 实例，以及 API 令牌（推荐）或基本身份验证凭据

创建 API 令牌

在 Matrix42 的 Administration 应用中，为助手将要使用的账户创建 API 令牌。服务会自动将其交换为短期访问令牌，并在令牌过期前再次交换。

支持基本身份验证，但不建议使用：许多实例虽然接受凭据，却仍会因角色／受众限制而拒绝 API 访问，并返回 403。

---

配置

所有配置均通过环境变量完成。

变量	必填	默认值	描述
M42_HOST	✅	-	实例的基础 URL，例如 https://matrix42.example.com
M42_API_TOKEN	✅¹	-	API 令牌；会自动交换为访问令牌
M42_USERNAME / M42_PASSWORD	✅¹	-	M42_API_TOKEN 的基本身份验证替代方案
M42_LANGUAGE		en-US	响应语言，通过 Explicit-Language 发送
M42_TOOLS		all	要公开的工具 ID，以逗号分隔
M42_ALLOW_WRITES		0	设置为 1 以公开会修改数据的工具。除非设置此项，否则根本不会注册写入工具。
M42_ALLOW_INSECURE_TLS		0	设置为 1 以跳过 TLS 验证（仅限使用自签名证书的开发实例）
M42_AUDIT_NOTE		1	在创建的工单中添加内部备注，说明工单是通过此服务提交的。设置为 0 可禁用。
M42_AGENT_LABEL		Matrix42 MCP server	备注中助手的名称
M42_UI_URL		discovered	Web 界面的源地址，用于深层链接。未设置时，会从实例的 Web shell 配置中获取。
M42_TIMEOUT_MS		30000	每次请求的超时时间

¹ 请提供 M42_API_TOKEN，或同时提供 M42_USERNAME 和 M42_PASSWORD。

---

客户端设置

此服务通过 stdio 运行：由你的 MCP 客户端启动。无需安装步骤——npx 会按需获取它。

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（全局）或 .cursor/mcp.json（每个项目）

{
  "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——此格式会提示输入令牌，而不是将其存储在文件中：

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

其他支持 stdio 的客户端（Windsurf、Cline、Zed、……）使用相同的 command / args / env 格式。

---

验证连接

让助手调用 server_info，或对你的实例运行随附的冒烟测试：

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

它会以真实 MCP 客户端的身份连接，并测试每个工具。

你也可以直接运行 CLI：

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

---

工具和操作

共有六种工具，每种工具包含一组操作。此服务能执行的所有操作都在这里——先是读取工具，然后是写入工具。

工具	功能
server_info	报告已连接的 Matrix42 实例，并验证凭据是否有效。绝不会返回凭据。
webservice_discovery	发现 REST API。请参阅下方的操作。
schema_discovery	探索数据模型：数据定义、配置项、属性、关系、拾取值。
data_query	读取记录：ASQL 查询、保存的视图、日志条目、附件，以及 ASQL 指南和验证器。
service_desk	搜索任何类型的工单、回答服务级别问题，并浏览资产、合同、目录服务、预订、知识文章、审批、导入和工作流实例。
ticket_actions	写入——工单生命周期操作：创建、关闭、接管、转发、暂停、重新打开、设置截止时间、记录工时、添加日志条目。仅当 M42_ALLOW_WRITES=1 时提供。

webservice_discovery 操作

操作	参数	返回值
api_overview	-	Matrix42 API 的通用约定：令牌交换、Explicit-Language、Public API 与 Product API，以及常见数据面。编写独立集成代码前很有用。
list_operations	search?, service_id?, limit?	操作列表，格式为 {id, name, method, path, service, documentation}。search 会按名称、文档和服务名称筛选。默认返回前 200 个匹配项；传入 limit: 0 可返回全部。
list_services	-	所有 Web 服务及其路由前缀和文档。
describe_operation	operation_id	单个操作的完整契约：HTTP 方法、路径、带类型的参数以及返回类型。

典型流程： 调用一次 api_overview → 使用搜索词调用 list_operations → 对目标操作调用 describe_operation。

schema_discovery 操作

操作	参数	返回值
schema_overview	-	Matrix42 数据模型的构成方式：数据定义与配置项、片段和多片段、基数、选项值，以及官方文档的位置。
list_data_definitions	search?, include_pickups?, limit?	数据定义列表，格式为 {internalName, displayName, description, classType, isPickup, isCustom}。除非特别要求，否则不包括选项值类。
list_configuration_items	search?, limit?	配置项及其主类和成员定义。
describe_data_definition	name, include?	带解码后数据类型的属性及选项值交叉链接。默认不包括关系（一个中心定义可能有 150 多个关系）——传入 include: "relations" 或 "both"。
describe_configuration_item	name	对象的组成定义，每项都带有基数和 isMultiFragment 标志。
get_pickup_values	pickup_class 或 name+attribute	可选的 {value, label} 值对——这样模型可以按实际值筛选，而不必猜测代码。

典型流程： schema_overview → 使用搜索词调用 list_* → 调用 describe_* → 在按任何选项值属性筛选前调用 get_pickup_values。

data_query 操作

操作	参数	返回值
asql_guide	-	where 和 columns 使用的 ASQL 表达式语言：运算符、点链、选项值、T(...) 透视、子查询、[Expression-ObjectID]。
validate_asql	class, expression	表达式是否有效，并提供确切错误（例如 "不包含属性 Nope"）。成本低于执行失败的查询。
query	class, columns?, where?, sort?, page_size?, page?	行数据及带类型的列元数据，并支持分页（hasMore）。
get_fragment	class, fragment_id	一个完整片段。
get_object	ci_name, object_id	一个完整对象（配置项的所有片段）。
list_views / run_view	search? / view_id	实例保存的数据查询——带有预定义筛选条件的精选视图。优先使用匹配的视图，而不是手写 ASQL。
list_journal	object_id	对象的评论／活动时间线。
list_attachments	object_id	附加到对象的文件。
deep_link	object_id, view_type?	指向 Matrix42 Web 界面的 URL——用于预览、编辑、创建或运行操作。会解析对象自身的配置项，因此只需提供对象 ID。

典型流程： 调用一次 asql_guide → 使用 schema_discovery 查找类及其选项值 → 调用 validate_asql → 调用 query。分页时务必传入 sort；否则分页边界不稳定。

数字枚举会自动解码（Datatype: 2 → "Int"，Cardinality: 3 → "Optional (Multi)"），并使用实例自身报告的自定义前缀标记自定义项。

指向 Web 界面的链接

data_query(action='deep_link') 会构建一个助手可以交给你的 URL，格式遵循 Matrix42 文档中的深层链接规范：

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

view_type 用于选择打开的内容：preview（默认，只读）、edit、用于创建表单的 new，或用于向导的 action。只有 new 可以不带对象 ID 使用，而 action 还需要 action_id。打开链接绝不会更改任何内容——即使是 edit，也要等用户保存后才会生效。

你只需要对象 ID。 一个基础数据定义会被许多配置项复用——仅 SPSActivityClassBase 就支撑着事件、服务请求和变更——因此服务会为你解析出实际的对象，而不需要你自行选择。如果传入错误的 ci_name，服务会予以更正；如果传入片段 ID，服务会拒绝请求，而不会交给你一个打开后什么也看不到的链接。

链接指向 Web 界面自身的源，而不是你所连接的 API 主机。 两者通常并不相同：通过 IP 访问的实例通常会使用实际名称提供 UUX，而 shell 的 config.json 会说明该名称。如果从错误的源加载 shell，应用就会调用一个与其提供源不一致的源，导致页面看似加载完成后才出错。服务会从实例读取该源，并在链接旁以 webInterface 的形式报告；M42_UI_URL 可以覆盖此设置。

service_desk 操作

操作	参数	返回值
data_model	-	介绍 Matrix42 的模块如何映射到少数几个基础类——工单、资产、许可证、合同、SLA 和目录项实际存放的位置。不确定某项内容在哪里时，请阅读此说明。
search_tickets	kind，以及 subject、category_name 和／或 states	匹配的工单。kind 可以是 ticket、incident、problem、change、task、service_request、kb_article 之一。其他筛选参数虽存在，但 Matrix42 会忽略它们，因此传入这些参数会被拒绝。
get_ticket	ticket_object_id	服务台所见的单张工单摘要。
sla_for_ticket	ticket_object_id	Matrix42 根据自身计算得出的适用服务级别协议。
sla_times	ticket_object_id	响应和解决时间状态。
browse	domain、search?、where?、limit?	一个经过筛选的域中的行，以及此实例不具备的字段。
find	search、domains?、limit?	同时搜索所有域以查找名称，适用于不知道内容存放位置的情况。搜索失败的域（未安装模块）会报告出来，但不会导致操作失败。

所有类型都遵循相同的约定，因此一种调用形式就能覆盖整个服务台。只有 subject、category_name 和 states 会实际参与筛选——Matrix42 会接受 initiator_name、ticket_number、asset_id 等参数，却忽略它们并返回所有工单。传入这些参数会被拒绝，以免返回未筛选的结果却让你误以为它已筛选；拒绝信息会指向使用 ASQL where 的 data_query，后者确实会按这些字段筛选。

browse 域：assets、stock_units、contracts、slas、catalog_services、bookings、kb_articles、approvals、imports、import_runs、workflow_instances、workflow_definitions、applications。工作流为只读——此服务会列出定义和实例，但绝不会启动、挂起、恢复或取消工作流。

绝不猜测列名。 每次执行 browse 前，服务都会从实例读取定义中的实际属性列表，并且只保留确实存在的字段；其余字段会作为 unavailableFields 报告。对于你未获许可使用的模块，返回的行会更短，而不会导致调用失败。指南和服务说明中也都明确了这一规则，因此已连接的模型也会遵循。

所有读取工具均标注为 readOnlyHint: true，以便客户端将它们与任何可能更改数据的工具区分开来。

ticket_actions 操作（写入数据）

除非设置 M42_ALLOW_WRITES=1，否则工具列表中不会包含写入工具，因此默认部署无法修改任何内容，即使模型提出请求也是如此。启用后，ticket_actions 提供：

操作	说明
create_ticket	返回新的对象 ID，其他每项操作都会直接使用该 ID。
close_ticket	按对象 ID 关闭，可选填写解决方案和关闭原因。
add_journal_entry	向任意对象添加评论，可选填写模板 parameters。
classify_ticket	仅根据文本建议类型，不会更改任何内容。
take_over / accept	接管工单。需要提供工单所属配置项 type_name。
forward	将工单转交给 role_id 或 user_id，可选应用 OLA。
pause	暂停工单，可选停止升级计时（not_escalate_while_paused）。
reopen	撤销关闭状态，并说明原因。
return_to_role	将工单退回给负责该工单的角色。
set_deadline	设置必须处理该工单的日期。
track_working_time	登记工作量，可选指定类型（investigation、resolution 等）。
transform	将工单转换为另一种类型，例如将事件转换为服务请求。这会重写记录的类型；目标类型不具备的字段将丢失。

Matrix42 将状态机封装为这些命名操作，而不是暴露原始状态字段，因此可以安全地提供这些操作：每项操作都恰好携带其状态转换所需的参数。

先预览，再确认

默认情况下，每项操作都会先预览。调用时不传入 confirm: true，写入操作就会返回将要发送的确切请求——方法、路径、正文——以及值得留意的后果，并且不会进行任何更改：

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

该预览与执行路径运行的是同一个计划对象，因此它描述的请求绝不会与实际发送的请求不同。设置 dry_run: true，即可在 confirm 已设置时仍强制预览。

每张创建的工单还会附带一条内部日志备注，记录该工单是通过此服务提交的。通过 API 创建工单不会留下网页界面会留下的任何痕迹，因此人工接手工单时无法判断其来源。该备注不会显示在门户中；如果无法写入，仍会报告工单已创建——丢失审计记录绝不能让人误以为创建失败。设置 M42_AUDIT_NOTE=0 可关闭此功能，也可以通过 M42_AGENT_LABEL="Acme Helpdesk Assistant" 指定助手名称。

为避免服务管理中最重要的错误，还有两个默认设置：

• 默认关闭通知邮件。 notify_initiator、notify_users 和 notify_responsible 均默认为 false；除非明确要求，否则关闭工单不会向任何人发送邮件。
• 日志条目默认为内部。 visible_in_portal 默认为 false，因此评论不会意外发布到请求者的自助服务门户。

close_related_incidents 也默认为 false，因为它会连带关闭其他工单。

提示词

客户端可提供的可复用模板（例如 Claude Desktop 中的提示词菜单）。每个模板都体现了此服务所采用的操作顺序，因此模型不必通过失败来重新摸索：

提示词	用途
explore_instance	熟悉不熟悉的实例
build_query	将问题转换为经过验证的 ASQL 查询
triage_ticket	端到端处理一张工单，不做任何更改
safe_change	按“预览 → 确认”的流程进行写入
find_endpoint	在编写集成代码前找到合适的操作

资源

书面指南也作为 MCP 资源发布，因此客户端无需调用工具即可阅读，并可预先将其附加到对话中：

URI	内容
matrix42://guide/data-model	Matrix42 是一个图，而不是许多模块
matrix42://guide/schema	数据定义、配置项、片段、拾取项
matrix42://guide/asql	ASQL 表达式语言
matrix42://guide/api	REST API 约定：身份验证、标头、Public API 与 Product API

相同文本也已提交到 docs/，因此无需运行任何内容即可在 GitHub 上阅读——请从 Matrix42 是一个图，而不是许多模块 开始，其中说明了为什么没有“Licenses”或“SLAs”表，以及这些记录实际位于何处。 这些文件由指南模块生成（npm run docs），如果内容不一致，测试就会失败。

---

安全说明

• 此服务是一个带凭据的代理。 配置的账户可以通过 API 读取的任何内容，连接的助手都可以通过提供给它的工具访问。请使用权限范围符合助手实际需求的账户。
• 凭据保留在本地。 凭据从环境中读取，仅用于向你的实例发送请求，不会写入日志，也不会由任何工具返回。
• 切勿提交 .env。 该文件已被 git 忽略；请使用客户端的 env 块或机密提示词。
• M42_ALLOW_INSECURE_TLS 会禁用证书验证。 仅用于自签名的开发实例，切勿用于生产环境。
• 如果只需要其中一部分，请使用 M42_TOOLS 限制可用范围。

---

开发

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 将写入操作限制在它自行创建的单个工单上，并在结束时将其关闭；不会修改任何已有内容，也绝不会请求发送通知邮件。

工作原理

两个模块为服务器其余部分提供保障：columns.ts 确保发送的投影始终是实例能够响应的内容，而 write-plan.ts 确保预览与请求是同一个对象。

目录结构

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

添加工具时，只需在 src/tools/ 下添加一个模块，并将其列入 src/tools/index.ts；之后便可自动通过 M42_TOOLS 使用其 ID。

---

路线图

• 上传和下载附件
• 审批决定（批准 / 拒绝），目前仅支持读取
• 按用户区分的令牌，这样“我的项目”就可以指最终用户，而不是服务账户

---

贡献

非常欢迎大家贡献——这是一个社区项目，随着更多实例的加入，它会变得更好。Matrix42 的部署差异很大，因此如果错误报告中附上准确的请求和准确的错误信息，将非常有帮助：这往往是了解某个属性或操作在其他环境中行为不同的唯一方式。

适合作为首次贡献的内容：

• 在 src/domains.ts 中补充对你有用但目前缺失的领域。
• 修正 src/*-guide.ts / src/*-overview.ts 中的指南（然后运行 npm run docs）。
• 将你实例中的失败案例连同请求和响应作为问题报告。

创建拉取请求前：

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

支持

仅提供社区支持，请通过 GitHub 问题和 讨论区联系。此项目不提供 SLA，且 Matrix42 AG 无法为你提供此项目的帮助——请不要就此向他们提交工单。

项目

贡献指南	CONTRIBUTING.md
行为准则	CODE_OF_CONDUCT.md
安全策略	SECURITY.md
更新日志	CHANGELOG.md
发行版	GitHub 发行版

GitHub Release 发布后，CI 会使用 npm 可信发布 发布发行版——任何地方都不会存放长期有效的 npm 令牌，并且每个 tarball 都带有来源证明，可追溯到构建它的提交和工作流运行。

安全

发现漏洞？请私下报告，而不要在公开 issue 中披露——请参阅 SECURITY.md。

许可证

MIT © 2026 S&S Technologies GmbH

---

免责声明

本项目是一个独立、由社区维护的集成项目。它与 Matrix42 AG 无关联，也未获得其认可、赞助或支持。“Matrix42”及任何相关标志均归其各自所有者所有，在此仅用于标识本项目进行互操作的软件。本仓库不再分发任何 Matrix42 源代码或文档。

本软件按“原样”提供，不提供任何形式的担保。您需对配置的账户以及助手通过该账户执行的任何操作负责——在将其连接到生产实例之前，请阅读安全说明。