Matrix42

Matrix42 MCP サーバー

AI アシスタントに、Matrix42 を安全に、デフォルトでは読み取り専用で利用できるようにします。

Model Context Protocol サーバーです。経験豊富なコンサルタントのように、アシスタントが Matrix42 インスタンスを調べられるようにします。適切な Web サービスを見つけ、実際のデータモデルを読み込み、有効なフィルターでレコードを検索し、サービスデスクを検索できます。そして、有効にした場合に限り、チケットに対して操作を行います。

このサーバーは認証情報を保持し、アシスタントに代わって Matrix42 と通信します。API トークンの交換を実行し、Explicit-Language ヘッダーを設定し、TLS を処理します。アシスタントが認証情報を見ることはありません。

npx matrix42-mcp --help

重要

これは独立したコミュニティプロジェクトです。 Matrix42 AG と提携、推奨、後援、支援のいずれも受けていません。「Matrix42」はそれぞれの所有者の商標であり、このソフトウェアが連携する対象を説明する目的でのみ使用しています。サポートはGitHub の課題を通じてコミュニティから提供されます。**このプロジェクトについて Matrix42 サポートに問い合わせないでください。**また、いかなるサービスレベル契約も期待しないでください。本ソフトウェアはMIT ライセンスに基づき「現状のまま」提供されます。

メモ

ステータス：初期リリース。 このサーバーはデフォルトで読み取り専用です。M42_ALLOW_WRITES=1 を設定しない限り、書き込みツールは一覧にも表示されません。

主な特長

• デフォルトで読み取り専用です。 明示的に有効にしない限り、書き込みツールはツール一覧に表示されません。
• 推測はしません。 クエリの実行前にすべての列をお使いのインスタンスのライブスキーマと照合するため、インスタンスに存在しないフィールドは、不透明な 500 エラーになって送信されるのではなく、報告されます。
• 説明してから操作します。 サーバーには、データモデル、スキーマ、ASQL フィルター言語、REST の規約を扱う 4 つのガイドが MCP リソースとして含まれています。
• 書き込み前にプレビューできます。 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 の構成アイテム、選択肢の値、リレーション、カーディナリティを確認できます
レコードを読む	ページネーション、保存済みビュー、ジャーナル、添付ファイル、Web インターフェースへのリンクに対応した ASQL クエリを実行できます
サービスデスクを操作する	7 種類のチケットを名前、サービスレベル、厳選された 13 のドメインで検索したり、一度にすべてを検索したりできます
チケットを操作する	作成、クローズ、分類、引き継ぎ、転送、一時停止、再開、期限設定、時間の記録を行えます。いずれも事前にプレビューできます

会話の例

あなた： 未解決のままになっている未クローズのハードウェアチケットはどれですか？また、サービスレベルの期限を過ぎているものはありますか？

アシスタントは、ID を 1 つも指定しなくても答えを導き出します。

行われなかったことにも注目してください。GUID の検索も、属性名の推測も、データの書き込みもありません。また、サーバーが拒否するものにも注目してください。Matrix42 が受け付けても適用しないフィルターです。そのため、フィルターなしの回答がフィルター済みの回答と誤認されることはありません。

---

要件

• Node.js 22.19 以降（HTTP クライアントの undici が必要とします）
• 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 の代わりに使用する Basic 認証情報
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	ディープリンク用のウェブインターフェースのオリジンです。未設定の場合は、インスタンスのウェブシェル設定から検出されます。
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

---

ツールとアクション

6 つのツールが、それぞれ一連のアクションをまとめています。サーバーで実行できることはすべてここにあります。まず読み取りツール、次に書き込みツールを紹介します。

ツール	機能
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	1 つのオペレーションの完全な契約：HTTP メソッド、パス、型を含むパラメーター、戻り値の型。

一般的な流れ： api_overview を 1 回実行 → 検索語を指定して 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	式が有効かどうかと、正確なエラー（例："does not contain attribute Nope"）。クエリに失敗してから確認するより低コストです。
query	class, columns?, where?, sort?, page_size?, page?	型付きの列メタデータを含む行と、ページネーション情報（hasMore）。
get_fragment	class, fragment_id	1 つの完全なフラグメント。
get_object	ci_name, object_id	1 つのオブジェクト全体（構成アイテムのすべてのフラグメント）。
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 を 1 回実行 → 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 があります。オブジェクト ID なしで機能するのは new だけで、action にはさらに action_id が必要です。リンクを開いても、データが変更されることはありません。edit でも、ユーザーが保存するまでは変更されません。

必要なのはオブジェクト ID だけです。 基本データ定義は複数の構成アイテムで再利用されています。たとえば SPSActivityClassBase はインシデント、サービスリクエスト、変更をまとめて扱います。そのため、サーバーが実際のクラスを解決するので、ユーザーが選ぶ必要はありません。誤った ci_name を渡すと修正されます。フラグメント ID を渡すと、何も開かないリンクを返すのではなく、リクエストが拒否されます。

リンクの対象は、接続先の API ホストではなく、Web インターフェース自体のオリジンです。 これらは異なる場合がよくあります。IP アドレスでアクセスできるインスタンスでも、UUX は実際の名前で提供されていることが多く、シェルの config.json にその名前が記載されています。誤ったオリジンからシェルを読み込むと、ページが読み込まれたように見えた後、アプリが配信元とは異なるオリジンにアクセスしようとして失敗します。サーバーはインスタンスからそのオリジンを読み取り、リンクとともに 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	サービスデスクから見た、1 件のチケットの概要です。
sla_for_ticket	ticket_object_id	Matrix42 自身が計算した、適用されるサービスレベル契約です。
sla_times	ticket_object_id	反応時間と解決時間の状態です。
browse	domain、search?、where?、limit?	キュレーションされた 1 つのドメインの行と、このインスタンスに存在しないフィールドです。
find	search、domains?、limit?	どこにあるかわからない場合に、名前をすべてのドメインから一括検索します。失敗したドメイン（モジュールがインストールされていない場合）は報告されますが、処理は失敗しません。

すべての種類で同じ仕様が使われるため、1 つの呼び出し形式でサービスデスク全体に対応できます。実際にフィルターとして機能するのは 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."
}

このプレビューは、実行時に使用するものと同じプランオブジェクトを使うため、別のリクエストを示しながら異なるリクエストを送信することはありません。confirm が設定されている場合でもプレビューを強制するには、dry_run: true を指定します。

作成されたチケットにはすべて、このサーバー経由で起票されたことを記録する内部ジャーナルノートも追加されます。API 経由で作成した場合、通常はウェブインターフェースに残る記録が残らないため、チケットを引き継いだ人がどこから起票されたのかを知る手段がありません。このノートはポータルには表示されません。また、書き込みに失敗しても、チケットは作成済みとして報告されます。監査記録が失われたことを、作成失敗と誤認させてはなりません。M42_AUDIT_NOTE=0 で無効にするか、M42_AGENT_LABEL="Acme Helpdesk Assistant" でアシスタント名を指定します。

サービス管理で特に重要なミスを防ぐため、さらに次の 2 つのデフォルト設定があります。

• 通知メールは無効です。 notify_initiator、notify_users、notify_responsible はすべてデフォルトで false です。要求しない限り、チケットをクローズしても誰にもメールは送信されません。
• ジャーナルエントリは内部向けです。 visible_in_portal はデフォルトで false のため、コメントが誤って依頼者のセルフサービスポータルに公開されることはありません。

close_related_incidents もデフォルトで false です。これはほかのチケットにも連鎖して影響するためです。

プロンプト

クライアントが提供できる再利用可能なテンプレートです（Claude Desktop のプロンプトメニューなど）。それぞれに、このサーバーで推奨される操作順が組み込まれているため、モデルが失敗を重ねて手順を探り直す必要はありません。

プロンプト	用途
explore_instance	不慣れなインスタンスの概要を把握する
build_query	質問を検証済みの ASQL クエリに変換する
triage_ticket	変更を加えずに、1 件のチケットに最初から最後まで対応する
safe_change	プレビュー → 確定の手順に沿って書き込みを進める
find_endpoint	統合コードを書く前に、適切な操作を特定する

リソース

文章形式のガイドは MCP リソースとしても公開されているため、クライアントはツールを呼び出さずに読み込み、会話の冒頭で添付できます。

URI	内容
matrix42://guide/data-model	Matrix42 は多数のモジュールではなく、1 つのグラフです
matrix42://guide/schema	データ定義、構成アイテム、フラグメント、ピックアップ
matrix42://guide/asql	ASQL 式言語
matrix42://guide/api	REST API の規約：認証、ヘッダー、Public API と Product API

同じテキストは docs/ にもチェックインされているため、何も実行せずに GitHub 上で読むことができます。まずは Matrix42 は多数のモジュールではなく、1 つのグラフです をご覧ください。「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 は、自身で作成した単一のチケットに書き込みを限定し、最後にそのチケットをクローズします。既存のデータは変更されず、通知メールが要求されることもありません。

構成の概要

サーバーのほかの部分が依存する保証を担うモジュールは 2 つあります。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 に登録します。追加した ID は自動的に M42_TOOLS で使用できるようになります。

---

ロードマップ

• 添付ファイルのアップロードとダウンロード
• 現在は読み取り専用となっている承認の決定（承認／却下）
• ユーザーごとのトークン。「自分のアイテム」をサービスアカウントではなくエンドユーザーの視点で扱えるようにする機能

---

貢献

貢献を心より歓迎します。これはコミュニティプロジェクトであり、対応するインスタンスが増えるほど改善されていきます。Matrix42 のデプロイ環境には大きな違いがあるため、正確なリクエストとエラーを記載したバグ報告は非常に役立ちます。別の環境では属性や操作の挙動が異なることを知る唯一の手がかりとなることもよくあります。

最初の貢献におすすめの内容：

• src/domains.ts に不足している、自分にとって重要なドメイン。
• src/*-guide.ts／src/*-overview.ts にあるガイドの修正（その後、npm run docs を実行してください）。
• リクエストとレスポンスを添えた、お使いのインスタンスで発生した失敗事例の issue。

プルリクエストを作成する前に：

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

サポート

コミュニティによるサポートのみです。GitHub の issue と ディスカッションをご利用ください。SLA はなく、Matrix42 AG はこのプロジェクトのサポートを提供できません。このプロジェクトについて Matrix42 AG にチケットを作成しないでください。

プロジェクト

コントリビューション	CONTRIBUTING.md
行動規範	CODE_OF_CONDUCT.md
セキュリティポリシー	SECURITY.md
変更履歴	CHANGELOG.md
リリース	GitHub のリリース

リリースは、GitHub Release の公開時に CI から npm trusted publishing を使用して公開されます。長期間有効な npm トークンはどこにも存在せず、すべての tarball には、ビルドに使用したコミットとワークフロー実行にひも付ける provenance が含まれています。

セキュリティ

脆弱性を発見しましたか？公開 issue ではなく、非公開で報告してください。詳しくは SECURITY.md をご覧ください。

ライセンス

MIT © 2026 S&S Technologies GmbH

---

免責事項

このプロジェクトは、独立してコミュニティが保守する統合機能です。Matrix42 AG とは提携、推奨、後援、サポートのいずれの関係もありません。「Matrix42」および関連する標章はそれぞれの所有者に帰属し、このプロジェクトが連携するソフトウェアを特定する目的でのみ使用しています。このリポジトリでは、Matrix42 のソースコードやドキュメントを再配布していません。

このソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。設定するアカウント、およびアシスタントがこのソフトウェアを通じて行うすべてのことについて、利用者が責任を負います。本番環境のインスタンスに接続する前に、セキュリティに関する注意事項をお読みください。