ctx-mcp

Local MCP server for decision trace capture and deterministic explanations.

Requirements

• Node.js 18+

Install

npm install

Run (stdio MCP server)

npm run dev

Architecture (high level)

flowchart LR
  Client[MCP client] -->|stdio| Server[ctx MCP server]
  Server --> Tools[Trace tools]
  Tools --> Store[(Trace store)]
  Server --> Resources[trace:// resources]
  Store --> Resources

Usage contract (agents)

• You MUST call trace.start when a user-requested task begins (once intent is clear).
• You MUST call trace.finish when that task is completed, even if the conversation continues, to mark outcome/status for downstream analysis.
• Treat a "task" as a single user goal; if the user pivots to a new goal, start a new trace.
• If a task is completed and the user continues with a new goal, start a new trace (optionally link the prior trace in metadata).

Core tools

• trace.start
• trace.add_node
• trace.add_edge
• trace.attach_artifact
• trace.finish
• trace.query
• trace.get_subgraph
• trace.find_paths
• trace.explain_decision
• trace.similarity
• trace.risk_check

Example tool calls

{
  "tool": "trace.start",
  "input": {
    "intent": "Investigate alert",
    "tags": ["incident", "p1"],
    "metadata": { "ticket": "INC-123" }
  }
}

{
  "tool": "trace.add_node",
  "input": {
    "trace_id": "trace-uuid",
    "type": "Decision",
    "summary": "Roll back release",
    "data": { "reason": "error rate spike" },
    "confidence": 0.8
  }
}

{
  "tool": "trace.add_edge",
  "input": {
    "trace_id": "trace-uuid",
    "from_node_id": "decision-node-id",
    "to_node_id": "action-node-id",
    "relation_type": "causes"
  }
}

{
  "tool": "trace.explain_decision",
  "input": {
    "trace_id": "trace-uuid",
    "decision_node_id": "decision-node-id",
    "depth": 4
  }
}

{
  "tool": "trace.similarity",
  "input": {
    "decision_node_id": "decision-node-id",
    "scope": "all",
    "limit": 5
  }
}

{
  "tool": "trace.risk_check",
  "input": {
    "decision_node_id": "decision-node-id",
    "threshold": 0.6
  }
}

Resources

• trace://{trace_id}
• trace://{trace_id}/timeline
• trace://{trace_id}/graph
• trace://{trace_id}/subgraph?center=...&depth=...&dir=...
• trace://{trace_id}/explain?decision=...&depth=...
• trace://search?text=...&trace_id=...&type=...
• trace://{trace_id}/similarity?decision=...&scope=...&limit=...&depth=...&max_traces=...
• trace://{trace_id}/risk?decision=...&scope=...&limit=...&depth=...&threshold=...&max_traces=...

MCP config example

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

Testing

npm test

Seed a sample trace

npm run seed

CLI examples

npm run risk-check -- decision-node-id

npm run similarity -- decision-node-id