ctx-mcp 0.1.0

package/src/graph/graph.ts

@@ -0,0 +1,153 @@
+import type { EdgeRow, NodeRow } from "../storage/queries.js";
+
+export type EdgeRef = {
+  edge_id: string;
+  from: string;
+  to: string;
+  relation_type: string;
+};
+
+export type Graph = {
+  nodes: NodeRow[];
+  edges: EdgeRow[];
+  out: Map<string, EdgeRef[]>;
+  inbound: Map<string, EdgeRef[]>;
+};
+
+export function buildGraph(nodes: NodeRow[], edges: EdgeRow[]): Graph {
+  const out = new Map<string, EdgeRef[]>();
+  const inbound = new Map<string, EdgeRef[]>();
+
+  for (const edge of edges) {
+    const ref: EdgeRef = {
+      edge_id: edge.edge_id,
+      from: edge.from_node_id,
+      to: edge.to_node_id,
+      relation_type: edge.relation_type,
+    };
+
+    const outList = out.get(ref.from) ?? [];
+    outList.push(ref);
+    out.set(ref.from, outList);
+
+    const inList = inbound.get(ref.to) ?? [];
+    inList.push(ref);
+    inbound.set(ref.to, inList);
+  }
+
+  return { nodes, edges, out, inbound };
+}
+
+export type SubgraphOptions = {
+  center: string;
+  depth: number;
+  direction: "in" | "out" | "both";
+  maxNodes: number;
+};
+
+export function extractSubgraph(graph: Graph, options: SubgraphOptions): {
+  nodes: NodeRow[];
+  edges: EdgeRow[];
+} {
+  const included = new Set<string>();
+  const queue: Array<{ id: string; depth: number }> = [{ id: options.center, depth: 0 }];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) continue;
+    if (included.has(current.id)) continue;
+
+    included.add(current.id);
+    if (included.size >= options.maxNodes) break;
+
+    if (current.depth >= options.depth) continue;
+
+    const nextDepth = current.depth + 1;
+    const nextIds: string[] = [];
+
+    if (options.direction === "out" || options.direction === "both") {
+      const edges = graph.out.get(current.id) ?? [];
+      for (const edge of edges) {
+        nextIds.push(edge.to);
+      }
+    }
+
+    if (options.direction === "in" || options.direction === "both") {
+      const edges = graph.inbound.get(current.id) ?? [];
+      for (const edge of edges) {
+        nextIds.push(edge.from);
+      }
+    }
+
+    for (const id of nextIds) {
+      if (!included.has(id)) {
+        queue.push({ id, depth: nextDepth });
+      }
+    }
+  }
+
+  const nodes = graph.nodes.filter((node) => included.has(node.node_id));
+  const nodeSet = new Set(nodes.map((node) => node.node_id));
+  const edges = graph.edges.filter(
+    (edge) => nodeSet.has(edge.from_node_id) && nodeSet.has(edge.to_node_id)
+  );
+
+  return { nodes, edges };
+}
+
+export type Path = {
+  node_ids: string[];
+  edge_ids: string[];
+};
+
+export type PathOptions = {
+  from: string;
+  to: string;
+  maxDepth: number;
+  maxPaths: number;
+  allowRelations?: Set<string>;
+};
+
+export function findPaths(graph: Graph, options: PathOptions): Path[] {
+  const results: Path[] = [];
+
+  const walk = (
+    current: string,
+    target: string,
+    depth: number,
+    visited: Set<string>,
+    nodePath: string[],
+    edgePath: string[]
+  ): void => {
+    if (results.length >= options.maxPaths) return;
+    if (depth > options.maxDepth) return;
+    if (current === target) {
+      results.push({ node_ids: [...nodePath], edge_ids: [...edgePath] });
+      return;
+    }
+
+    const edges = graph.out.get(current) ?? [];
+    for (const edge of edges) {
+      if (options.allowRelations && !options.allowRelations.has(edge.relation_type)) {
+        continue;
+      }
+      if (visited.has(edge.to)) continue;
+
+      visited.add(edge.to);
+      nodePath.push(edge.to);
+      edgePath.push(edge.edge_id);
+
+      walk(edge.to, target, depth + 1, visited, nodePath, edgePath);
+
+      edgePath.pop();
+      nodePath.pop();
+      visited.delete(edge.to);
+
+      if (results.length >= options.maxPaths) return;
+    }
+  };
+
+  walk(options.from, options.to, 0, new Set([options.from]), [options.from], []);
+
+  return results;
+}

package/src/mcp/resources.ts

@@ -0,0 +1,234 @@
+import type { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp";
+import { getTrace, getTraceArtifacts, getTraceEdges, getTraceNodes } from "../storage/queries.js";
+import type { StorageEngine } from "../storage/engine.js";
+import { buildGraph, extractSubgraph } from "../graph/graph.js";
+import { explainDecision } from "../explain/explain.js";
+
+function jsonResource(uri: string, payload: unknown) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}
+
+function parseQuery(uri: string): URLSearchParams {
+  return new URL(uri).searchParams;
+}
+
+function parseNumber(value: string | null, fallback: number, min?: number, max?: number): number {
+  const parsed = value ? Number(value) : Number.NaN;
+  let out = Number.isFinite(parsed) ? parsed : fallback;
+  if (min !== undefined) out = Math.max(min, out);
+  if (max !== undefined) out = Math.min(max, out);
+  return out;
+}
+
+function toTraceOutput(trace: ReturnType<typeof getTrace>) {
+  if (!trace) return null;
+  return {
+    ...trace,
+    tags: JSON.parse(trace.tags_json),
+    metadata: JSON.parse(trace.metadata_json),
+    outcome: trace.outcome_json ? JSON.parse(trace.outcome_json) : null,
+  };
+}
+
+function toNodeOutput(node: ReturnType<typeof getTraceNodes>[number]) {
+  return {
+    ...node,
+    data: JSON.parse(node.data_json),
+    metadata: JSON.parse(node.metadata_json),
+  };
+}
+
+function toArtifactOutput(artifact: ReturnType<typeof getTraceArtifacts>[number]) {
+  return {
+    ...artifact,
+    metadata: JSON.parse(artifact.metadata_json),
+  };
+}
+
+export function registerResources(
+  server: McpServer,
+  engine: StorageEngine,
+  templates: {
+    base: ResourceTemplate;
+    timeline: ResourceTemplate;
+    graph: ResourceTemplate;
+    subgraph: ResourceTemplate;
+    explain: ResourceTemplate;
+    search: ResourceTemplate;
+    similarity: ResourceTemplate;
+    risk: ResourceTemplate;
+  }
+): void {
+  server.resource("trace", templates.base, async (uri, { trace_id }) => {
+    const trace = getTrace(engine, trace_id);
+    if (!trace) {
+      return jsonResource(uri, { ok: false, error: "Trace not found" });
+    }
+    const nodes = getTraceNodes(engine, trace_id);
+    const edges = getTraceEdges(engine, trace_id);
+    const artifacts = getTraceArtifacts(engine, trace_id);
+
+    return jsonResource(uri, {
+      trace: toTraceOutput(trace),
+      counts: {
+        nodes: nodes.length,
+        edges: edges.length,
+        artifacts: artifacts.length,
+      },
+    });
+  });
+
+  server.resource("trace.timeline", templates.timeline, async (uri, { trace_id }) => {
+    const nodes = getTraceNodes(engine, trace_id);
+    return jsonResource(uri, { nodes: nodes.map(toNodeOutput) });
+  });
+
+  server.resource("trace.graph", templates.graph, async (uri, { trace_id }) => {
+    const nodes = getTraceNodes(engine, trace_id);
+    const edges = getTraceEdges(engine, trace_id);
+    return jsonResource(uri, { nodes: nodes.map(toNodeOutput), edges });
+  });
+
+  server.resource("trace.subgraph", templates.subgraph, async (uri, { trace_id }) => {
+    const params = parseQuery(uri);
+    const center = params.get("center");
+    if (!center) {
+      return jsonResource(uri, { ok: false, error: "Missing center param" });
+    }
+    const depth = parseNumber(params.get("depth"), 2, 0, 10);
+    const direction = (params.get("dir") ?? "both") as "in" | "out" | "both";
+
+    const nodes = getTraceNodes(engine, trace_id);
+    const edges = getTraceEdges(engine, trace_id);
+    const graph = buildGraph(nodes, edges);
+    const subgraph = extractSubgraph(graph, {
+      center,
+      depth,
+      direction,
+      maxNodes: 250,
+    });
+
+    return jsonResource(uri, {
+      nodes: subgraph.nodes.map(toNodeOutput),
+      edges: subgraph.edges,
+    });
+  });
+
+  server.resource("trace.explain", templates.explain, async (uri, { trace_id }) => {
+    const params = parseQuery(uri);
+    const decision = params.get("decision");
+    if (!decision) {
+      return jsonResource(uri, { ok: false, error: "Missing decision param" });
+    }
+    const depth = parseNumber(params.get("depth"), 4, 1, 10);
+
+    const nodes = getTraceNodes(engine, trace_id);
+    const edges = getTraceEdges(engine, trace_id);
+    const artifacts = getTraceArtifacts(engine, trace_id);
+    const explanation = explainDecision(decision, nodes, edges, artifacts, depth);
+
+    return jsonResource(uri, {
+      ...explanation,
+      decision_node: toNodeOutput(explanation.decision_node),
+      assumptions: explanation.assumptions.map(toNodeOutput),
+      evidence: explanation.evidence.map(toNodeOutput),
+      alternatives: explanation.alternatives.map(toNodeOutput),
+      checks: explanation.checks.map(toNodeOutput),
+      outcome: explanation.outcome ? toNodeOutput(explanation.outcome) : null,
+      artifacts: explanation.artifacts.map(toArtifactOutput),
+    });
+  });
+
+  server.resource("trace.search", templates.search, async (uri) => {
+    const params = parseQuery(uri);
+    const text = params.get("text") ?? undefined;
+    const traceId = params.get("trace_id") ?? undefined;
+    const type = params.get("type") ?? undefined;
+
+    const nodes = engine.queryAll(
+      `SELECT * FROM nodes WHERE
+        (? IS NULL OR trace_id = ?)
+        AND (? IS NULL OR type = ?)
+        AND (? IS NULL OR summary LIKE ?)
+        ORDER BY created_at DESC LIMIT 50;`,
+      [traceId, traceId, type, type, text, text ? `%${text}%` : null]
+    );
+
+    return jsonResource(uri, { nodes: nodes.map(toNodeOutput) });
+  });
+
+  server.resource("trace.similarity", templates.similarity, async (uri, { trace_id }) => {
+    const params = parseQuery(uri);
+    const decision = params.get("decision");
+    if (!decision) {
+      return jsonResource(uri, { ok: false, error: "Missing decision param" });
+    }
+    const scope = (params.get("scope") ?? "all") as "trace" | "all";
+    const limit = parseNumber(params.get("limit"), 10, 1, 50);
+    const depth = parseNumber(params.get("depth"), 4, 1, 10);
+    const maxTraces = parseNumber(params.get("max_traces"), 200, 1, 1000);
+
+    const { findSimilarDecisions } = await import("../similarity/similarity.js");
+    const matches = findSimilarDecisions(engine, decision, {
+      scope,
+      limit,
+      depth,
+      maxTraces,
+    });
+
+    return jsonResource(uri, {
+      trace_id,
+      matches: matches.map((match) => ({
+        node: toNodeOutput(match.node),
+        trace: toTraceOutput(match.trace),
+        score: match.score,
+        reasons: match.reasons,
+      })),
+    });
+  });
+
+  server.resource("trace.risk", templates.risk, async (uri) => {
+    const params = parseQuery(uri);
+    const decision = params.get("decision");
+    if (!decision) {
+      return jsonResource(uri, { ok: false, error: "Missing decision param" });
+    }
+    const scope = (params.get("scope") ?? "all") as "trace" | "all";
+    const limit = parseNumber(params.get("limit"), 10, 1, 50);
+    const depth = parseNumber(params.get("depth"), 4, 1, 10);
+    const threshold = parseNumber(params.get("threshold"), 0.6, 0, 1);
+    const maxTraces = parseNumber(params.get("max_traces"), 200, 1, 1000);
+
+    const { assessDecisionRisk } = await import("../similarity/similarity.js");
+    const assessment = assessDecisionRisk(engine, decision, {
+      scope,
+      limit,
+      depth,
+      threshold,
+      maxTraces,
+    });
+
+    return jsonResource(uri, {
+      assessment: {
+        decision: toNodeOutput(assessment.decision),
+        novelty: assessment.novelty,
+        similar_failures: assessment.similar_failures.map((match) => ({
+          node: toNodeOutput(match.node),
+          trace: toTraceOutput(match.trace),
+          score: match.score,
+          reasons: match.reasons,
+        })),
+        signature_failed_match: assessment.signature_failed_match,
+        warnings: assessment.warnings,
+      },
+    });
+  });
+}