TraceForward
什么是TraceForward？
TraceForward是一个MCP服务器，它将OpenTetry支持的运行时上下文暴露给编码代理。
的问题
编码代理会问一些好问题，但无法查找答案。他们不知道服务依赖于什么，它的行为如何，或者出现了什么错误。TraceForward为编码代理提供了一种直接查询运行时上下文的方法。
运作原理
┌──────────────┐ ┌──────────────┐ ┌─────┐ ┌──────────────┐
│ OTel backend │ ──▶ │ TraceForward │ ──▶ │ MCP │ ──▶ │ Coding Agent │
└──────────────┘ └──────────────┘ └─────┘ └──────────────┘- 您的OpenTetry后端从正在运行的服务中收集跟踪、指标和日志。
- TraceForward连接到该后端，并通过标准适配器接口公开信号数据。
- MCP协议使这些数据成为编码代理可以调用的工具。
- 在编写或修改代码之前，您的代理会查询服务依赖关系、错误率和最近的故障。
快速开始
夹具模式——参考实施
夹具模式是TraceForward的参考实现。它附带了真实、确定的示例数据，因此您可以在不连接到正在运行的后端的情况下开发、测试和评估TraceForward。夹具适配器实现了完整的 SignalAdapter 协议——它不是模拟或演示的快捷方式。
mise run dev这将启动TraceForward stdio 使用夹具适配器。指向你的经纪人，开始提问。
实时模式——连接到您的OTel后端
设置适配器模式并配置后端URL：
export ADAPTER_MODE=otlp
export OTLP_TRACES_URL=http://localhost:4318/v1/traces
export OTLP_METRICS_URL=http://localhost:4318/v1/metrics
export OTLP_LOGS_URL=http://localhost:4318/v1/logs
mise run dev:otlp向您的代理人注册
TraceForward可与任何MCP兼容的代理配合使用。使用MCP配置将代理指向服务器。
克劳德代码 --添加到 ~/.claude/claude.json:
{
"mcpServers": {
"traceforward": {
"command": "mise",
"args": ["run", "dev"],
"cwd": "/path/to/traceforward-mcp"
}
}
}光标 --添加到 .cursor/mcp.json 在项目根目录中：
{
"mcpServers": {
"traceforward": {
"command": "mise",
"args": ["run", "dev"],
"cwd": "/path/to/traceforward-mcp"
}
}
}其他与MCP兼容的代理（Windsurf、Cline等）遵循类似的模式——请参阅您的代理的MCP配置文档。
工具参考
TraceForward展示了一个小工具界面，针对工程师或代理在分流过程中会问的第一个问题。
| 工具 | 它回答了什么问题 |
|---|---|
traceforward_list_services | 在这种环境中存在哪些服务？ |
traceforward_get_service_map | 这项服务依赖于什么，依赖于什么？ |
traceforward_get_traces | 最近对此服务的端到端请求是什么样子的？ |
traceforward_get_metrics | 这项服务的性能如何——延迟、吞吐量、错误率？ |
traceforward_get_errors | 最近这项服务出了什么问题？ |
traceforward_get_logs | 此服务记录了什么？ |
添加后端
要添加后端，请实现 SignalAdapter 协议中 adapters/.
看 adapters/fixture.py 以供参考实施。
示例会话
代理被要求调查支付服务中的结账失败，并在建议修复之前查询TraceForward。
客服电话 traceforward_get_errors(service="payment-service"):
[
{
"operation_name": "process_payment",
"service_name": "payment-service",
"span_id": "span-011",
"timestamp": "2026-03-18T10:05:00.005Z",
"trace_id": "trace-002"
}
]客服电话 traceforward_get_logs(service="payment-service", level="error"):
[
{
"level": "error",
"message": "Payment gateway timeout after 5000ms",
"service_name": "payment-service",
"timestamp": "2026-03-18T10:05:00.300Z",
"trace_id": "trace-002"
},
{
"level": "error",
"message": "Stripe API returned 402: card_declined",
"service_name": "payment-service",
"timestamp": "2026-03-18T10:05:00.350Z",
"trace_id": "trace-002"
}
]现在代理知道了：失败是网关超时和Stripe的卡拒绝，而不是崩溃的进程。重新启动服务不会解决任何问题。代理可以建议调查上游支付网关，而不是建议重新启动。
架构决策
架构决策在实施前记录在ADR中。ADR定义了适配器模型、工具界面、安全边界和整个项目中使用的术语。
请参阅 平均房价指数 查看完整列表。