trace-forge

trace-forge-mcp

用于写入结构化跟踪、跨度和决策的 MCP 服务。唯一支持写入的可观测性 MCP——现有的 9 个可观测性 MCP 均为只读。

旨在满足《欧盟 AI 法案》的可追溯性合规要求（第 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

为 Agent 任务开始新的跟踪。

参数	类型	必填	描述
agent_id	string	是	唯一的 Agent 标识符
task_description	string	是	Agent 正在执行的任务
metadata	object	否	可选元数据（模型、部门、优先级）

返回：{ trace_id, started_at }

trace_span

在跟踪中创建跨度。可通过 parent_span_id 嵌套跨度。

参数	类型	必填	描述
trace_id	string	是	要附加到的跟踪
span_name	string	是	跨度名称（例如 "research"、"validation"）
parent_span_id	string	否	用于嵌套的父跨度
metadata	object	否	可选的跨度元数据

返回：{ span_id, trace_id }

trace_tool_call

记录跟踪中的工具调用。根据令牌数自动计算费用估算。

参数	类型	必填	描述
trace_id	string	是	此调用所属的跟踪
span_id	string	否	此调用所属的跨度
tool_name	string	是	调用的工具
args	object	是	传入的参数
result_preview	string	是	结果预览（最多 500 个字符）
tokens_used	number	否	令牌数（用于启用费用估算）
duration_ms	number	是	调用耗时（毫秒）
status	string	是	"success"、"error" 或 "timeout"

返回：{ event_id, logged: true }

trace_decision

记录 Agent 的决策点，包括推理过程和考虑过的备选方案。

参数	类型	必填	描述
trace_id	string	是	此决策所属的跟踪
reasoning	string	是	Agent 做出此决策的原因
alternatives_considered	string[]	是	评估过的其他选项
chosen_action	string	是	做出的决定
confidence	number	是	置信度，范围为 0.0 至 1.0

返回：{ event_id, logged: true }

trace_end

完成跟踪。自动计算总时长、事件数和跨度数。

参数	类型	必填	描述
trace_id	string	是	要完成的跟踪
outcome	string	是	"success"、"failure"、"partial" 或 "timeout"
summary	string	否	可选摘要

返回：{ trace_id, duration_ms, events_count, spans_count, tool_calls_count }

get_trace

获取完整的跟踪树，包含所有跨度、事件、工具调用和决策。

参数	类型	必填	描述
trace_id	string	是	要获取的跟踪 ID

返回：完整的跟踪对象，包含嵌套的跨度树、所有事件及计算得出的总计。

search_traces

按 Agent ID 和/或状态查找跟踪。

参数	类型	默认值	描述
agent_id	string	-	按 Agent 筛选
status	string	-	按状态筛选
limit	number	20	最大结果数（1-100）

返回：按时间由近及远排序的匹配跟踪及摘要统计数据。

资源

URI	描述
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

欧盟《人工智能法案》合规性

欧盟《人工智能法案》第 14 条要求高风险 AI 系统保留决策和操作的可追溯记录。trace-forge-mcp 提供：

• 记录推理过程和备选方案的结构化决策日志
• 包含时间和成本信息的完整工具调用审计跟踪
• 用于复杂多步骤任务的分层跨度树
• Agent 标识和任务归属

许可证

MIT