io.github.mdfifty50-boop/trace-forge
Structured execution trace and span logging for AI agents
Installation
Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).
trace-forge-mcpclaude mcp add trace-forge -- npx -y trace-forge-mcp@0.1.1{
"mcpServers": {
"trace-forge": {
"command": "npx",
"args": [
"-y",
"trace-forge-mcp@0.1.1"
]
}
}
}Documentation
Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.
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
npx trace-forge-mcpClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"trace-forge": {
"command": "npx",
"args": ["trace-forge-mcp"]
}
}
}From source
git clone https://github.com/mdfifty50-boop/trace-forge-mcp.git
cd trace-forge-mcp
npm install
node src/index.jsTools
trace_start
Begin a new trace for an agent task.
| Param | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | Unique agent identifier |
task_description | string | yes | What the agent is doing |
metadata | object | no | Optional 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.
| Param | Type | Required | Description |
|---|---|---|---|
trace_id | string | yes | Trace to attach to |
span_name | string | yes | Span name (e.g. "research", "validation") |
parent_span_id | string | no | Parent span for nesting |
metadata | object | no | Optional span metadata |
Returns: { span_id, trace_id }
trace_tool_call
Log a tool call within a trace. Auto-calculates cost estimate from token count.
| Param | Type | Required | Description |
|---|---|---|---|
trace_id | string | yes | Trace this belongs to |
span_id | string | no | Span this belongs to |
tool_name | string | yes | Tool that was called |
args | object | yes | Arguments passed |
result_preview | string | yes | Result preview (max 500 chars) |
tokens_used | number | no | Token count (enables cost estimation) |
duration_ms | number | yes | Call duration in milliseconds |
status | string | yes | "success", "error", or "timeout" |
Returns: { event_id, logged: true }
trace_decision
Log an agent decision point with reasoning and alternatives considered.
| Param | Type | Required | Description |
|---|---|---|---|
trace_id | string | yes | Trace this belongs to |
reasoning | string | yes | Why the agent made this decision |
alternatives_considered | string[] | yes | Other options evaluated |
chosen_action | string | yes | What was decided |
confidence | number | yes | Confidence 0.0 to 1.0 |
Returns: { event_id, logged: true }
trace_end
Complete a trace. Auto-calculates total duration, event counts, and span counts.
| Param | Type | Required | Description |
|---|---|---|---|
trace_id | string | yes | Trace to complete |
outcome | string | yes | "success", "failure", "partial", or "timeout" |
summary | string | no | Optional 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.
| Param | Type | Required | Description |
|---|---|---|---|
trace_id | string | yes | Trace 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.
| Param | Type | Default | Description |
|---|---|---|---|
agent_id | string | - | Filter by agent |
status | string | - | Filter by status |
limit | number | 20 | Max results (1-100) |
Returns: Matching traces sorted by recency with summary stats.
Resources
| URI | Description |
|---|---|
traces://recent | Last 20 traces with summary |
traces://stats | Aggregate statistics (total, avg duration, success rate) |
Usage Pattern
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 statusEU 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
Questions fréquentes
Qu'est-ce que io.github.mdfifty50-boop/trace-forge ?
Structured execution trace and span logging for AI agents
Comment installer io.github.mdfifty50-boop/trace-forge ?
Il s'exécute sur votre machine. Dans Claude Code : claude mcp add trace-forge -- npx -y trace-forge-mcp@0.1.1. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.
Faut-il une clé API pour io.github.mdfifty50-boop/trace-forge ?
Son entrée au registre n'indique aucune clé ni secret obligatoire. Certaines fonctions peuvent tout de même demander un compte auprès du service auquel il se connecte.
io.github.mdfifty50-boop/trace-forge est-il open source ?
Son code est public sur GitHub, mais le dépôt ne déclare pas de licence standard.
Qui maintient io.github.mdfifty50-boop/trace-forge ?
Il est publié par mdfifty50-boop. AI.tn le référence sans le maintenir ni le recommander.
Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.