Skip to main content
Glama
mhingston

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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
    7 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
    C
    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