Trace Forge

io.github.mdfifty50-boop由 GitHub 账号 mdfifty50-boop 发布v0.1.1更新于 Oct 27, 2026

Structured execution trace and span logging for AI agents

已验证STDIO仅桌面安全与监控数据与分析AI 与机器学习

概览

AI 生成的概览

本地 MCP 服务器，让助手为 AI 代理任务记录结构化的执行轨迹、跨度、工具调用与决策，并可检索和查询这些记录。

可以做什么
  • 为代理任务开启和结束轨迹，记录代理标识、任务描述、元数据、结果与摘要
  • 在轨迹内创建可嵌套的跨度，标记逻辑工作单元
  • 记录工具调用，包括参数、结果预览、耗时、状态及可选的基于 token 的成本估算
  • 记录决策点，包括推理过程、考虑过的备选方案、所选动作与置信度
  • 获取完整轨迹树，并按代理标识或状态搜索轨迹
  • 通过资源读取最近轨迹与汇总统计
适用场景
当你需要可审计的代理行为记录时适用，例如复盘多步骤工具调用、比较决策依据，或为高风险 AI 工作流保留可追溯性文档。
运行要求
以本地进程方式运行，可通过 npx（需 Node.js）或从源码 npm install 启动，并在客户端的 MCP 服务器配置中登记。未声明需要账号、API 密钥、环境变量或请求头。
安装前请注意
这是写入型服务：工具参数、结果预览、推理内容和元数据都会被存入轨迹，请避免传入密钥或个人数据。轨迹由该服务器保存在本地，若用于合规记录，应先确认其存储位置与保留期限。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Trace Forge，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

trace-forge-mcp

MCP server for writing structured traces, spans, and decisions. The only write-path observability MCP — all 9 existing observability MCPs are read-only.

Built for EU AI Act traceability compliance (Article 14, due August 2026).

Install

bash
npx trace-forge-mcp

Claude Desktop

Add to claude_desktop_config.json:

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

From source

bash
git clone https://github.com/mdfifty50-boop/trace-forge-mcp.gitcd trace-forge-mcpnpm installnode src/index.js

Tools

trace_start

Begin a new trace for an agent task.

ParamTypeRequiredDescription
agent_idstringyesUnique agent identifier
task_descriptionstringyesWhat the agent is doing
metadataobjectnoOptional metadata (model, department, priority)

Returns: { trace_id, started_at }

trace_span

Create a span within a trace. Spans can be nested via parent_span_id.

ParamTypeRequiredDescription
trace_idstringyesTrace to attach to
span_namestringyesSpan name (e.g. "research", "validation")
parent_span_idstringnoParent span for nesting
metadataobjectnoOptional span metadata

Returns: { span_id, trace_id }

trace_tool_call

Log a tool call within a trace. Auto-calculates cost estimate from token count.

ParamTypeRequiredDescription
trace_idstringyesTrace this belongs to
span_idstringnoSpan this belongs to
tool_namestringyesTool that was called
argsobjectyesArguments passed
result_previewstringyesResult preview (max 500 chars)
tokens_usednumbernoToken count (enables cost estimation)
duration_msnumberyesCall duration in milliseconds
statusstringyes"success", "error", or "timeout"

Returns: { event_id, logged: true }

trace_decision

Log an agent decision point with reasoning and alternatives considered.

ParamTypeRequiredDescription
trace_idstringyesTrace this belongs to
reasoningstringyesWhy the agent made this decision
alternatives_consideredstring[]yesOther options evaluated
chosen_actionstringyesWhat was decided
confidencenumberyesConfidence 0.0 to 1.0

Returns: { event_id, logged: true }

trace_end

Complete a trace. Auto-calculates total duration, event counts, and span counts.

ParamTypeRequiredDescription
trace_idstringyesTrace to complete
outcomestringyes"success", "failure", "partial", or "timeout"
summarystringnoOptional summary

Returns: { trace_id, duration_ms, events_count, spans_count, tool_calls_count }

get_trace

Retrieve a complete trace tree with all spans, events, tool calls, and decisions.

ParamTypeRequiredDescription
trace_idstringyesTrace ID to retrieve

Returns: Full trace object with nested span tree, all events, and computed totals.

search_traces

Find traces by agent ID and/or status.

ParamTypeDefaultDescription
agent_idstring-Filter by agent
statusstring-Filter by status
limitnumber20Max results (1-100)

Returns: Matching traces sorted by recency with summary stats.

Resources

URIDescription
traces://recentLast 20 traces with summary
traces://statsAggregate statistics (total, avg duration, success rate)

Usage Pattern

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

EU AI Act Compliance

Article 14 of the EU AI Act requires high-risk AI systems to maintain traceability of decisions and actions. trace-forge-mcp provides:

  • Structured decision logging with reasoning and alternatives
  • Complete tool call audit trails with timing and cost
  • Hierarchical span trees for complex multi-step tasks
  • Agent identification and task attribution

License

MIT

来源：README.md，提交 b613faf

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.1.1最新Sep 16, 2026

评分

已满足适用检查项的 40%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。