trace-forge

trace-forge-mcp

構造化されたトレース、スパン、意思決定を記録する MCP サーバーです。書き込みパスに対応する唯一のオブザーバビリティ MCP です。既存のオブザーバビリティ MCP 9 個はすべて読み取り専用です。

EU AI Act のトレーサビリティ準拠（第 14 条、2026 年 8 月期限）を目的に構築されています。

インストール

npx trace-forge-mcp

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "trace-forge": {
      "command": "npx",
      "args": ["trace-forge-mcp"]
    }
  }
}

ソースから

git clone https://github.com/mdfifty50-boop/trace-forge-mcp.git
cd trace-forge-mcp
npm install
node src/index.js

ツール

trace_start

エージェントのタスクの新しいトレースを開始します。

Param	Type	Required	Description
agent_id	string	yes	一意のエージェント識別子
task_description	string	yes	エージェントが行っていること
metadata	object	no	任意のメタデータ（モデル、部門、優先度）

戻り値：{ trace_id, started_at }

trace_span

トレース内にスパンを作成します。parent_span_id を使ってスパンをネストできます。

Param	Type	Required	Description
trace_id	string	yes	関連付けるトレース
span_name	string	yes	スパン名（例：「research」、「validation」）
parent_span_id	string	no	ネストする親スパン
metadata	object	no	任意のスパンメタデータ

戻り値：{ span_id, trace_id }

trace_tool_call

トレース内のツール呼び出しを記録します。トークン数からコストの推定値を自動計算します。

Param	Type	Required	Description
trace_id	string	yes	この呼び出しが属するトレース
span_id	string	no	この呼び出しが属するスパン
tool_name	string	yes	呼び出されたツール
args	object	yes	渡された引数
result_preview	string	yes	結果のプレビュー（最大 500 文字）
tokens_used	number	no	トークン数（コスト推定が有効になります）
duration_ms	number	yes	呼び出し時間（ミリ秒）
status	string	yes	"success"、"error"、または "timeout"

戻り値：{ event_id, logged: true }

trace_decision

エージェントの意思決定ポイントを、推論と検討した代替案とともに記録します。

Param	Type	Required	Description
trace_id	string	yes	この意思決定が属するトレース
reasoning	string	yes	エージェントがこの決定を行った理由
alternatives_considered	string[]	yes	評価したその他の選択肢
chosen_action	string	yes	決定した内容
confidence	number	yes	確信度（0.0～1.0）

戻り値：{ event_id, logged: true }

trace_end

トレースを完了します。合計時間、イベント数、スパン数を自動計算します。

Param	Type	Required	Description
trace_id	string	yes	完了するトレース
outcome	string	yes	"success"、"failure"、"partial"、または "timeout"
summary	string	no	任意の概要

戻り値：{ trace_id, duration_ms, events_count, spans_count, tool_calls_count }

get_trace

すべてのスパン、イベント、ツール呼び出し、意思決定を含む、完全なトレースツリーを取得します。

Param	Type	Required	Description
trace_id	string	yes	取得するトレース ID

戻り値：ネストされたスパンツリー、すべてのイベント、計算済みの合計値を含む完全なトレースオブジェクトです。

search_traces

エージェント ID やステータスでトレースを検索します。

Param	Type	Default	Description
agent_id	string	-	エージェントで絞り込み
status	string	-	ステータスで絞り込み
limit	number	20	最大結果数（1～100）

戻り値：一致するトレースを新しい順に並べ、概要統計とともに返します。

リソース

URI	Description
traces://recent	直近 20 件のトレースと概要
traces://stats	集計統計（合計、平均時間、成功率）

使用パターン

1. trace_start — when agent begins a task
2. trace_span — create logical work units (research, generation, validation)
3. During execution:
   - trace_tool_call — after each tool invocation
   - trace_decision — at each decision point
4. trace_end — when task completes
5. get_trace — retrieve full audit trail
6. search_traces — find traces by agent or status

EU AI Act への準拠

EU AI Act の第 14 条では、高リスク AI システムに対し、意思決定とアクションの追跡可能性を維持することが求められています。trace-forge-mcp は次の機能を提供します。

• 推論と代替案を含む、構造化された意思決定ログ
• タイミングとコストを含む、完全なツール呼び出し監査証跡
• 複雑な複数ステップのタスクに対応する、階層型スパンツリー
• エージェントの識別とタスクの帰属

ライセンス

MIT