Skip to main content
Glama
Sign In
ctx

ctx

by mhingston
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ctx-mcp

npm version

Local MCP server for decision trace capture and deterministic explanations.

Requirements

  • Node.js 18+

Related MCP server: AgentTrace

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • otel-mcp

      moondef
      A
      license
      A
      quality
      D
      maintenance
      MCP server that gives AI agents access to your application's OpenTelemetry traces for querying, analysis, and debugging.
      5
      17 npm
      2
      MIT

    • AgentTrace

      yashsrivastava16
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for tracing, logging, and debugging multi-agent systems by capturing sessions, spans, and events in a queryable trace tree.
      1
      MIT

    • ContextForge

      srmackey
      A
      license
      B
      quality
      B
      maintenance
      A local MCP server for managing engineering context across Components, Repos, Tasks, and Governance entities. It enables capturing reusable context and composing it per-task with typed relationships and cross-cutting guidelines.
      36
      1
      MIT

    • datalox-gated-runtime

      Oshawott324
      A
      license
      Not graded
      quality
      B
      maintenance
      This MCP server provides a stateful, resettable, verifiable API runtime that gates every tool call, enabling agents to run long workflows against provider-shaped environments without live provider write access. It records decisions, side effects, and outcome evidence for replayable, verifiable benchmark runs.
      Apache 2.0