ctx-mcp 0.1.0

package/tests/graph.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import { buildGraph, extractSubgraph, findPaths } from "../src/graph/graph.js";
+import type { EdgeRow, NodeRow } from "../src/storage/queries.js";
+
+const nodes: NodeRow[] = [
+  {
+    node_id: "a",
+    trace_id: "t1",
+    type: "Intent",
+    summary: "Start",
+    data_json: "{}",
+    confidence: null,
+    metadata_json: "{}",
+    created_at: 1,
+  },
+  {
+    node_id: "b",
+    trace_id: "t1",
+    type: "Decision",
+    summary: "Decide",
+    data_json: "{}",
+    confidence: null,
+    metadata_json: "{}",
+    created_at: 2,
+  },
+  {
+    node_id: "c",
+    trace_id: "t1",
+    type: "Action",
+    summary: "Act",
+    data_json: "{}",
+    confidence: null,
+    metadata_json: "{}",
+    created_at: 3,
+  },
+];
+
+const edges: EdgeRow[] = [
+  {
+    edge_id: "e1",
+    trace_id: "t1",
+    from_node_id: "a",
+    to_node_id: "b",
+    relation_type: "justified_by",
+    data_json: "{}",
+    created_at: 1,
+  },
+  {
+    edge_id: "e2",
+    trace_id: "t1",
+    from_node_id: "b",
+    to_node_id: "c",
+    relation_type: "causes",
+    data_json: "{}",
+    created_at: 2,
+  },
+];
+
+describe("graph", () => {
+  it("extracts a subgraph around a node", () => {
+    const graph = buildGraph(nodes, edges);
+    const subgraph = extractSubgraph(graph, {
+      center: "b",
+      depth: 1,
+      direction: "both",
+      maxNodes: 10,
+    });
+
+    expect(subgraph.nodes.map((n) => n.node_id).sort()).toEqual(["a", "b", "c"]);
+    expect(subgraph.edges).toHaveLength(2);
+  });
+
+  it("finds paths between nodes", () => {
+    const graph = buildGraph(nodes, edges);
+    const paths = findPaths(graph, {
+      from: "a",
+      to: "c",
+      maxDepth: 3,
+      maxPaths: 5,
+    });
+
+    expect(paths).toHaveLength(1);
+    expect(paths[0].node_ids).toEqual(["a", "b", "c"]);
+  });
+});

package/tests/query.test.ts

@@ -0,0 +1,275 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { SqlJsEngine } from "../src/storage/sqljsEngine.js";
+import { insertNode, insertTrace, type NodeRow, type TraceRow } from "../src/storage/queries.js";
+import { registerTools } from "../src/mcp/tools.js";
+
+function makeTempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctx-query-"));
+  return path.join(dir, "trace.db");
+}
+
+describe("trace.query tool", () => {
+  it("filters by tag and text across traces", async () => {
+    const dbPath = makeTempDbPath();
+    const engine = new SqlJsEngine({ dbPath, onLog: () => undefined });
+    await engine.init();
+
+    const traceWithTag: TraceRow = {
+      trace_id: "trace-1",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["alpha", "beta"]),
+      metadata_json: "{}",
+      started_at: Date.now(),
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const traceWithoutTag: TraceRow = {
+      trace_id: "trace-2",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["gamma"]),
+      metadata_json: "{}",
+      started_at: Date.now(),
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const nodeMatch: NodeRow = {
+      node_id: "node-1",
+      trace_id: "trace-1",
+      type: "Observation",
+      summary: "Searchable text",
+      data_json: JSON.stringify({ note: "hit" }),
+      confidence: null,
+      metadata_json: "{}",
+      created_at: Date.now(),
+    };
+
+    const nodeNoMatch: NodeRow = {
+      node_id: "node-2",
+      trace_id: "trace-2",
+      type: "Observation",
+      summary: "Other text",
+      data_json: "{}",
+      confidence: null,
+      metadata_json: "{}",
+      created_at: Date.now(),
+    };
+
+    engine.transaction(() => {
+      insertTrace(engine, traceWithTag);
+      insertTrace(engine, traceWithoutTag);
+      insertNode(engine, nodeMatch);
+      insertNode(engine, nodeNoMatch);
+    });
+
+    const handlers = new Map<string, (input: unknown) => Promise<unknown>>();
+    const fakeServer = {
+      tool: (name: string, _schema: unknown, handler: (input: unknown) => Promise<unknown>) => {
+        handlers.set(name, handler);
+      },
+    } as any;
+
+    registerTools(fakeServer, engine);
+
+    const handler = handlers.get("trace.query");
+    if (!handler) throw new Error("trace.query not registered");
+
+    const result = (await handler({ tags: ["alpha"], text: "Searchable" })) as {
+      ok: boolean;
+      nodes: Array<{ node_id: string; data: Record<string, unknown> }>;
+    };
+
+    expect(result.ok).toBe(true);
+    expect(result.nodes).toHaveLength(1);
+    expect(result.nodes[0].node_id).toBe("node-1");
+    expect(result.nodes[0].data.note).toBe("hit");
+  });
+
+  it("respects tags when trace_id is provided", async () => {
+    const dbPath = makeTempDbPath();
+    const engine = new SqlJsEngine({ dbPath, onLog: () => undefined });
+    await engine.init();
+
+    const traceWithTag: TraceRow = {
+      trace_id: "trace-1",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["alpha"]),
+      metadata_json: "{}",
+      started_at: Date.now(),
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const traceWithoutTag: TraceRow = {
+      trace_id: "trace-2",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["beta"]),
+      metadata_json: "{}",
+      started_at: Date.now(),
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const nodeMatch: NodeRow = {
+      node_id: "node-1",
+      trace_id: "trace-1",
+      type: "Observation",
+      summary: "Searchable text",
+      data_json: JSON.stringify({ note: "hit" }),
+      confidence: null,
+      metadata_json: "{}",
+      created_at: Date.now(),
+    };
+
+    engine.transaction(() => {
+      insertTrace(engine, traceWithTag);
+      insertTrace(engine, traceWithoutTag);
+      insertNode(engine, nodeMatch);
+    });
+
+    const handlers = new Map<string, (input: unknown) => Promise<unknown>>();
+    const fakeServer = {
+      tool: (name: string, _schema: unknown, handler: (input: unknown) => Promise<unknown>) => {
+        handlers.set(name, handler);
+      },
+    } as any;
+
+    registerTools(fakeServer, engine);
+
+    const handler = handlers.get("trace.query");
+    if (!handler) throw new Error("trace.query not registered");
+
+    const matchResult = (await handler({
+      trace_id: "trace-1",
+      tags: ["alpha"],
+    })) as {
+      ok: boolean;
+      nodes: Array<{ node_id: string }>;
+    };
+
+    expect(matchResult.ok).toBe(true);
+    expect(matchResult.nodes).toHaveLength(1);
+    expect(matchResult.nodes[0].node_id).toBe("node-1");
+
+    const noMatchResult = (await handler({
+      trace_id: "trace-1",
+      tags: ["beta"],
+    })) as {
+      ok: boolean;
+      nodes: Array<{ node_id: string }>;
+    };
+
+    expect(noMatchResult.ok).toBe(true);
+    expect(noMatchResult.nodes).toHaveLength(0);
+  });
+
+  it("paginates tag queries across traces with global ordering", async () => {
+    const dbPath = makeTempDbPath();
+    const engine = new SqlJsEngine({ dbPath, onLog: () => undefined });
+    await engine.init();
+
+    const traceA: TraceRow = {
+      trace_id: "trace-a",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["alpha"]),
+      metadata_json: "{}",
+      started_at: 1,
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const traceB: TraceRow = {
+      trace_id: "trace-b",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["alpha"]),
+      metadata_json: "{}",
+      started_at: 2,
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const olderNode: NodeRow = {
+      node_id: "node-old",
+      trace_id: "trace-a",
+      type: "Observation",
+      summary: "Older",
+      data_json: "{}",
+      confidence: null,
+      metadata_json: "{}",
+      created_at: 100,
+    };
+
+    const newerNode: NodeRow = {
+      node_id: "node-new",
+      trace_id: "trace-b",
+      type: "Observation",
+      summary: "Newer",
+      data_json: "{}",
+      confidence: null,
+      metadata_json: "{}",
+      created_at: 200,
+    };
+
+    engine.transaction(() => {
+      insertTrace(engine, traceA);
+      insertTrace(engine, traceB);
+      insertNode(engine, olderNode);
+      insertNode(engine, newerNode);
+    });
+
+    const handlers = new Map<string, (input: unknown) => Promise<unknown>>();
+    const fakeServer = {
+      tool: (name: string, _schema: unknown, handler: (input: unknown) => Promise<unknown>) => {
+        handlers.set(name, handler);
+      },
+    } as any;
+
+    registerTools(fakeServer, engine);
+
+    const handler = handlers.get("trace.query");
+    if (!handler) throw new Error("trace.query not registered");
+
+    const firstPage = (await handler({
+      tags: ["alpha"],
+      limit: 1,
+      offset: 0,
+    })) as { ok: boolean; nodes: Array<{ node_id: string }> };
+
+    const secondPage = (await handler({
+      tags: ["alpha"],
+      limit: 1,
+      offset: 1,
+    })) as { ok: boolean; nodes: Array<{ node_id: string }> };
+
+    expect(firstPage.ok).toBe(true);
+    expect(firstPage.nodes).toHaveLength(1);
+    expect(firstPage.nodes[0].node_id).toBe("node-new");
+
+    expect(secondPage.ok).toBe(true);
+    expect(secondPage.nodes).toHaveLength(1);
+    expect(secondPage.nodes[0].node_id).toBe("node-old");
+  });
+});

package/tests/similarity.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { SqlJsEngine } from "../src/storage/sqljsEngine.js";
+import {
+  insertNode,
+  insertTrace,
+  type NodeRow,
+  type TraceRow,
+} from "../src/storage/queries.js";
+import { assessDecisionRisk, findSimilarDecisions } from "../src/similarity/similarity.js";
+
+function makeTempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctx-similarity-"));
+  return path.join(dir, "trace.db");
+}
+
+function makeEngine(): SqlJsEngine {
+  return new SqlJsEngine({ dbPath: makeTempDbPath(), onLog: () => undefined });
+}
+
+describe("similarity and risk", () => {
+  it("detects similar decisions and failed matches", async () => {
+    const engine = makeEngine();
+    await engine.init();
+
+    const traceA: TraceRow = {
+      trace_id: "trace-a",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["alpha"]),
+      metadata_json: "{}",
+      started_at: Date.now(),
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const traceB: TraceRow = {
+      trace_id: "trace-b",
+      workflow_id: null,
+      actor: "tester",
+      intent: "demo",
+      tags_json: JSON.stringify(["alpha"]),
+      metadata_json: "{}",
+      started_at: Date.now(),
+      finished_at: Date.now(),
+      status: "fail",
+      outcome_json: null,
+    };
+
+    const decisionA: NodeRow = {
+      node_id: "decision-a",
+      trace_id: traceA.trace_id,
+      type: "Decision",
+      summary: "Roll back release",
+      data_json: "{}",
+      confidence: null,
+      metadata_json: "{}",
+      created_at: Date.now(),
+    };
+
+    const decisionB: NodeRow = {
+      node_id: "decision-b",
+      trace_id: traceB.trace_id,
+      type: "Decision",
+      summary: "Roll back release",
+      data_json: "{}",
+      confidence: null,
+      metadata_json: "{}",
+      created_at: Date.now(),
+    };
+
+    engine.transaction(() => {
+      insertTrace(engine, traceA);
+      insertTrace(engine, traceB);
+      insertNode(engine, decisionA);
+      insertNode(engine, decisionB);
+    });
+
+    const similar = findSimilarDecisions(engine, decisionA.node_id, {
+      scope: "all",
+      limit: 5,
+      depth: 2,
+      maxTraces: 50,
+    });
+
+    expect(similar.length).toBeGreaterThan(0);
+
+    const assessment = assessDecisionRisk(engine, decisionA.node_id, {
+      scope: "all",
+      limit: 5,
+      depth: 2,
+      threshold: 0.2,
+      maxTraces: 50,
+    });
+
+    expect(assessment.similar_failures.length).toBeGreaterThan(0);
+    expect(assessment.signature_failed_match).toBe(true);
+  });
+});

package/tests/storage.test.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { SqlJsEngine } from "../src/storage/sqljsEngine.js";
+import {
+  getTrace,
+  insertArtifact,
+  insertEdge,
+  insertNode,
+  insertTrace,
+  type ArtifactRow,
+  type EdgeRow,
+  type NodeRow,
+  type TraceRow,
+} from "../src/storage/queries.js";
+
+function makeTempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctx-test-"));
+  return path.join(dir, "trace.db");
+}
+
+describe("SqlJsEngine", () => {
+  it("persists data across flushes", async () => {
+    const dbPath = makeTempDbPath();
+    const engine = new SqlJsEngine({ dbPath, onLog: () => undefined });
+    await engine.init();
+
+    const trace: TraceRow = {
+      trace_id: "trace-1",
+      workflow_id: null,
+      actor: "tester",
+      intent: "test",
+      tags_json: "[]",
+      metadata_json: "{}",
+      started_at: Date.now(),
+      finished_at: null,
+      status: null,
+      outcome_json: null,
+    };
+
+    const node: NodeRow = {
+      node_id: "node-1",
+      trace_id: trace.trace_id,
+      type: "Decision",
+      summary: "Decide",
+      data_json: "{}",
+      confidence: null,
+      metadata_json: "{}",
+      created_at: Date.now(),
+    };
+
+    const edge: EdgeRow = {
+      edge_id: "edge-1",
+      trace_id: trace.trace_id,
+      from_node_id: "node-1",
+      to_node_id: "node-1",
+      relation_type: "derived_from",
+      data_json: "{}",
+      created_at: Date.now(),
+    };
+
+    const artifact: ArtifactRow = {
+      artifact_id: "artifact-1",
+      trace_id: trace.trace_id,
+      node_id: "node-1",
+      artifact_type: "note",
+      content: "payload",
+      redaction_level: "internal",
+      metadata_json: "{}",
+      sha256: "hash",
+      created_at: Date.now(),
+    };
+
+    engine.transaction(() => {
+      insertTrace(engine, trace);
+      insertNode(engine, node);
+      insertEdge(engine, edge);
+      insertArtifact(engine, artifact);
+    });
+
+    await engine.flushNow();
+
+    const reloaded = new SqlJsEngine({ dbPath, onLog: () => undefined });
+    await reloaded.init();
+
+    const stored = getTrace(reloaded, trace.trace_id);
+    expect(stored?.trace_id).toBe(trace.trace_id);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["src", "tests"],
+  "exclude": ["dist", "node_modules"]
+}