ctx-mcp 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# ctx-mcp
+
+[![npm version](https://img.shields.io/npm/v/ctx-mcp.svg)](https://www.npmjs.com/package/ctx-mcp)
+
+Local MCP server for decision trace capture and deterministic explanations.
+
+## Requirements
+
+- Node.js 18+
+
+## Install
+
+```bash
+npm install
+```
+
+## Run (stdio MCP server)
+
+```bash
+npm run dev
+```
+
+## Architecture (high level)
+
+```mermaid
+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
+
+```json
+{
+  "tool": "trace.start",
+  "input": {
+    "intent": "Investigate alert",
+    "tags": ["incident", "p1"],
+    "metadata": { "ticket": "INC-123" }
+  }
+}
+```
+
+```json
+{
+  "tool": "trace.add_node",
+  "input": {
+    "trace_id": "trace-uuid",
+    "type": "Decision",
+    "summary": "Roll back release",
+    "data": { "reason": "error rate spike" },
+    "confidence": 0.8
+  }
+}
+```
+
+```json
+{
+  "tool": "trace.add_edge",
+  "input": {
+    "trace_id": "trace-uuid",
+    "from_node_id": "decision-node-id",
+    "to_node_id": "action-node-id",
+    "relation_type": "causes"
+  }
+}
+```
+
+```json
+{
+  "tool": "trace.explain_decision",
+  "input": {
+    "trace_id": "trace-uuid",
+    "decision_node_id": "decision-node-id",
+    "depth": 4
+  }
+}
+```
+
+```json
+{
+  "tool": "trace.similarity",
+  "input": {
+    "decision_node_id": "decision-node-id",
+    "scope": "all",
+    "limit": 5
+  }
+}
+```
+
+```json
+{
+  "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
+
+```json
+{
+  "mcpServers": {
+    "ctx": {
+      "command": "npx",
+      "args": ["ctx-mcp"]
+    }
+  }
+}
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Seed a sample trace
+
+```bash
+npm run seed
+```
+
+## CLI examples
+
+```bash
+npm run risk-check -- decision-node-id
+```
+
+```bash
+npm run similarity -- decision-node-id
+```

package/migrations/001_init.sql

@@ -0,0 +1,52 @@
+CREATE TABLE IF NOT EXISTS traces (
+  trace_id TEXT PRIMARY KEY,
+  workflow_id TEXT,
+  actor TEXT,
+  intent TEXT NOT NULL,
+  tags_json TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  started_at INTEGER NOT NULL,
+  finished_at INTEGER,
+  status TEXT,
+  outcome_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id TEXT PRIMARY KEY,
+  trace_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  data_json TEXT NOT NULL,
+  confidence REAL,
+  metadata_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  edge_id TEXT PRIMARY KEY,
+  trace_id TEXT NOT NULL,
+  from_node_id TEXT NOT NULL,
+  to_node_id TEXT NOT NULL,
+  relation_type TEXT NOT NULL,
+  data_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS artifacts (
+  artifact_id TEXT PRIMARY KEY,
+  trace_id TEXT NOT NULL,
+  node_id TEXT,
+  artifact_type TEXT NOT NULL,
+  content TEXT NOT NULL,
+  redaction_level TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  sha256 TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_nodes_trace ON nodes(trace_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_trace_type ON nodes(trace_id, type);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(trace_id, from_node_id);
+CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(trace_id, to_node_id);
+CREATE INDEX IF NOT EXISTS idx_artifacts_trace ON artifacts(trace_id);
+CREATE INDEX IF NOT EXISTS idx_artifacts_node ON artifacts(node_id);

package/migrations/002_fts.sql

@@ -0,0 +1,27 @@
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  node_id,
+  trace_id,
+  type,
+  summary
+);
+
+INSERT INTO nodes_fts(rowid, node_id, trace_id, type, summary)
+  SELECT rowid, node_id, trace_id, type, summary FROM nodes;
+
+CREATE TRIGGER IF NOT EXISTS nodes_ai AFTER INSERT ON nodes BEGIN
+  INSERT INTO nodes_fts(rowid, node_id, trace_id, type, summary)
+  VALUES (new.rowid, new.node_id, new.trace_id, new.type, new.summary);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_ad AFTER DELETE ON nodes BEGIN
+  DELETE FROM nodes_fts WHERE rowid = old.rowid;
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_au AFTER UPDATE ON nodes BEGIN
+  UPDATE nodes_fts SET
+    node_id = new.node_id,
+    trace_id = new.trace_id,
+    type = new.type,
+    summary = new.summary
+  WHERE rowid = old.rowid;
+END;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ctx-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Decision Trace MCP Server",
+  "repository": "https://github.com/mhingston/ctx",
+  "author": "Mark Hingston",
+  "license": "MIT",
+  "main": "dist/server.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/server.ts",
+    "start": "node dist/server.js",
+    "test": "vitest run",
+    "seed": "tsx scripts/seed-trace.ts",
+    "risk-check": "tsx scripts/risk-check.ts",
+    "similarity": "tsx scripts/similarity.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "sql.js": "^1.10.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/risk-check.ts

@@ -0,0 +1,46 @@
+import { initStorage } from "../src/storage/db.js";
+import { assessDecisionRisk, findSimilarDecisions } from "../src/similarity/similarity.js";
+
+function usage(): void {
+  console.log("Usage: npm run risk-check -- <decision_node_id>");
+}
+
+async function main() {
+  const decisionNodeId = process.argv[2];
+  if (!decisionNodeId) {
+    usage();
+    process.exit(1);
+  }
+
+  const engine = await initStorage({
+    onLog: (msg) => console.error(`[ctx] ${msg}`),
+  });
+
+  const matches = findSimilarDecisions(engine, decisionNodeId, {
+    scope: "all",
+    limit: 5,
+    depth: 4,
+    maxTraces: 200,
+  });
+
+  const assessment = assessDecisionRisk(engine, decisionNodeId, {
+    scope: "all",
+    limit: 10,
+    depth: 4,
+    threshold: 0.6,
+    maxTraces: 200,
+  });
+
+  console.log("Top matches:");
+  for (const match of matches) {
+    console.log(`- ${match.node.node_id} (${match.score.toFixed(2)}) ${match.node.summary}`);
+  }
+
+  console.log("Risk assessment:");
+  console.log(JSON.stringify(assessment, null, 2));
+}
+
+main().catch((err) => {
+  console.error("Risk check failed", err);
+  process.exit(1);
+});

package/scripts/seed-trace.ts

@@ -0,0 +1,144 @@
+import { initStorage } from "../src/storage/db.js";
+import {
+  insertArtifact,
+  insertEdge,
+  insertNode,
+  insertTrace,
+  type ArtifactRow,
+  type EdgeRow,
+  type NodeRow,
+  type TraceRow,
+} from "../src/storage/queries.js";
+import { newId } from "../src/util/ids.js";
+import { sha256 } from "../src/util/hashing.js";
+import { redactSecrets } from "../src/util/redact.js";
+
+async function main() {
+  const engine = await initStorage({
+    onLog: (msg) => console.error(`[ctx] ${msg}`),
+  });
+
+  const now = Date.now();
+  const traceId = newId();
+
+  const trace: TraceRow = {
+    trace_id: traceId,
+    workflow_id: "demo",
+    actor: "local-user",
+    intent: "Example trace",
+    tags_json: JSON.stringify(["example", "seed"]),
+    metadata_json: JSON.stringify({ source: "seed-script" }),
+    started_at: now,
+    finished_at: null,
+    status: null,
+    outcome_json: null,
+  };
+
+  const decisionId = newId();
+  const actionId = newId();
+  const observationId = newId();
+  const outcomeId = newId();
+
+  const nodes: NodeRow[] = [
+    {
+      node_id: decisionId,
+      trace_id: traceId,
+      type: "Decision",
+      summary: "Ship with feature flag",
+      data_json: JSON.stringify({ reason: "Reduce rollout risk" }),
+      confidence: 0.7,
+      metadata_json: "{}",
+      created_at: now + 1,
+    },
+    {
+      node_id: actionId,
+      trace_id: traceId,
+      type: "Action",
+      summary: "Deploy with gradual rollout",
+      data_json: JSON.stringify({ percent: 10 }),
+      confidence: null,
+      metadata_json: "{}",
+      created_at: now + 2,
+    },
+    {
+      node_id: observationId,
+      trace_id: traceId,
+      type: "Observation",
+      summary: "No errors in canary",
+      data_json: JSON.stringify({ errorRate: 0 }),
+      confidence: null,
+      metadata_json: "{}",
+      created_at: now + 3,
+    },
+    {
+      node_id: outcomeId,
+      trace_id: traceId,
+      type: "Outcome",
+      summary: "Rollout completed",
+      data_json: JSON.stringify({ status: "success" }),
+      confidence: null,
+      metadata_json: "{}",
+      created_at: now + 4,
+    },
+  ];
+
+  const edges: EdgeRow[] = [
+    {
+      edge_id: newId(),
+      trace_id: traceId,
+      from_node_id: decisionId,
+      to_node_id: actionId,
+      relation_type: "causes",
+      data_json: "{}",
+      created_at: now + 2,
+    },
+    {
+      edge_id: newId(),
+      trace_id: traceId,
+      from_node_id: actionId,
+      to_node_id: observationId,
+      relation_type: "derived_from",
+      data_json: "{}",
+      created_at: now + 3,
+    },
+    {
+      edge_id: newId(),
+      trace_id: traceId,
+      from_node_id: observationId,
+      to_node_id: outcomeId,
+      relation_type: "causes",
+      data_json: "{}",
+      created_at: now + 4,
+    },
+  ];
+
+  const artifactContent = "deploy log: no errors";
+  const redacted = redactSecrets(artifactContent);
+  const artifact: ArtifactRow = {
+    artifact_id: newId(),
+    trace_id: traceId,
+    node_id: observationId,
+    artifact_type: "log",
+    content: redacted.redacted,
+    redaction_level: redacted.wasRedacted ? "scrubbed" : "internal",
+    metadata_json: JSON.stringify({ source: "seed-script" }),
+    sha256: sha256(redacted.redacted),
+    created_at: now + 3,
+  };
+
+  engine.transaction(() => {
+    insertTrace(engine, trace);
+    for (const node of nodes) insertNode(engine, node);
+    for (const edge of edges) insertEdge(engine, edge);
+    insertArtifact(engine, artifact);
+  });
+
+  await engine.flushNow();
+
+  console.log(`Seeded trace ${traceId}`);
+}
+
+main().catch((err) => {
+  console.error("Seed failed", err);
+  process.exit(1);
+});

package/scripts/similarity.ts

@@ -0,0 +1,35 @@
+import { initStorage } from "../src/storage/db.js";
+import { findSimilarDecisions } from "../src/similarity/similarity.js";
+
+function usage(): void {
+  console.log("Usage: npm run similarity -- <decision_node_id>");
+}
+
+async function main() {
+  const decisionNodeId = process.argv[2];
+  if (!decisionNodeId) {
+    usage();
+    process.exit(1);
+  }
+
+  const engine = await initStorage({
+    onLog: (msg) => console.error(`[ctx] ${msg}`),
+  });
+
+  const matches = findSimilarDecisions(engine, decisionNodeId, {
+    scope: "all",
+    limit: 10,
+    depth: 4,
+    maxTraces: 200,
+  });
+
+  console.log("Top matches:");
+  for (const match of matches) {
+    console.log(`- ${match.node.node_id} (${match.score.toFixed(2)}) ${match.node.summary}`);
+  }
+}
+
+main().catch((err) => {
+  console.error("Similarity check failed", err);
+  process.exit(1);
+});

package/src/explain/explain.ts

@@ -0,0 +1,125 @@
+import type { ArtifactRow, EdgeRow, NodeRow } from "../storage/queries.js";
+import { buildGraph } from "../graph/graph.js";
+
+export type Explanation = {
+  decision_node: NodeRow;
+  assumptions: NodeRow[];
+  evidence: NodeRow[];
+  alternatives: NodeRow[];
+  checks: NodeRow[];
+  outcome: NodeRow | null;
+  artifacts: ArtifactRow[];
+};
+
+export function explainDecision(
+  decisionNodeId: string,
+  nodes: NodeRow[],
+  edges: EdgeRow[],
+  artifacts: ArtifactRow[],
+  depth: number
+): Explanation {
+  const graph = buildGraph(nodes, edges);
+  const nodeById = new Map(nodes.map((node) => [node.node_id, node]));
+  const decisionNode = nodeById.get(decisionNodeId);
+  if (!decisionNode) {
+    throw new Error(`Decision node ${decisionNodeId} not found`);
+  }
+
+  const upstream = new Set<string>();
+  const queue: Array<{ id: string; depth: number }> = [{ id: decisionNodeId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+    if (current.depth >= depth) continue;
+
+    const inbound = graph.inbound.get(current.id) ?? [];
+    for (const edge of inbound) {
+      if (upstream.has(edge.from)) continue;
+      upstream.add(edge.from);
+      queue.push({ id: edge.from, depth: current.depth + 1 });
+    }
+  }
+
+  const assumptions: NodeRow[] = [];
+  const evidence: NodeRow[] = [];
+  const alternatives: NodeRow[] = [];
+  const checks: NodeRow[] = [];
+
+  for (const id of upstream) {
+    const node = nodeById.get(id);
+    if (!node) continue;
+    switch (node.type) {
+      case "Assumption":
+        assumptions.push(node);
+        break;
+      case "Observation":
+        evidence.push(node);
+        break;
+      case "Option":
+        alternatives.push(node);
+        break;
+      case "Verification":
+        checks.push(node);
+        break;
+      default:
+        break;
+    }
+  }
+
+  const outcome = findOutcome(decisionNodeId, graph, nodeById, depth);
+
+  const artifactNodeIds = new Set<string>([
+    decisionNodeId,
+    ...assumptions.map((node) => node.node_id),
+    ...evidence.map((node) => node.node_id),
+    ...alternatives.map((node) => node.node_id),
+    ...checks.map((node) => node.node_id),
+    ...(outcome ? [outcome.node_id] : []),
+  ]);
+
+  const linkedArtifacts = artifacts.filter(
+    (artifact) => artifact.node_id && artifactNodeIds.has(artifact.node_id)
+  );
+
+  return {
+    decision_node: decisionNode,
+    assumptions,
+    evidence,
+    alternatives,
+    checks,
+    outcome,
+    artifacts: linkedArtifacts,
+  };
+}
+
+function findOutcome(
+  decisionNodeId: string,
+  graph: ReturnType<typeof buildGraph>,
+  nodeById: Map<string, NodeRow>,
+  depth: number
+): NodeRow | null {
+  const queue: Array<{ id: string; depth: number }> = [{ id: decisionNodeId, depth: 0 }];
+  const visited = new Set<string>([decisionNodeId]);
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+
+    const node = nodeById.get(current.id);
+    if (node && node.type === "Outcome" && current.depth > 0) {
+      return node;
+    }
+
+    if (current.depth >= depth) continue;
+
+    const outbound = graph.out.get(current.id) ?? [];
+    for (const edge of outbound) {
+      if (visited.has(edge.to)) continue;
+      visited.add(edge.to);
+      queue.push({ id: edge.to, depth: current.depth + 1 });
+    }
+  }
+
+  return null;
+}