ctx-mcp 0.1.0

package/src/schemas.ts

@@ -0,0 +1,238 @@
+import { z } from "zod";
+
+export const nodeTypeEnum = z.enum([
+  "Intent",
+  "Assumption",
+  "Observation",
+  "Option",
+  "Decision",
+  "Action",
+  "Verification",
+  "Outcome",
+  "HumanOverride",
+]);
+
+export const relationTypeEnum = z.enum([
+  "depends_on",
+  "justified_by",
+  "validated_by",
+  "contradicted_by",
+  "causes",
+  "supersedes",
+  "derived_from",
+]);
+
+export const redactionLevelEnum = z.enum(["internal", "scrubbed", "public"]);
+
+const jsonRecord = z.record(z.string(), z.unknown());
+
+export const traceStartInputSchema = z.object({
+  trace_id: z.string().optional(),
+  workflow_id: z.string().optional(),
+  actor: z.string().optional(),
+  intent: z.string(),
+  tags: z.array(z.string()).optional().default([]),
+  metadata: jsonRecord.optional().default({}),
+  started_at: z.number().int().optional(),
+});
+
+export const traceStartOutputSchema = z.object({
+  ok: z.literal(true),
+  trace_id: z.string(),
+});
+
+export const traceAddNodeInputSchema = z.object({
+  trace_id: z.string(),
+  node_id: z.string().optional(),
+  type: nodeTypeEnum,
+  summary: z.string(),
+  data: jsonRecord.optional().default({}),
+  confidence: z.number().min(0).max(1).optional(),
+  metadata: jsonRecord.optional().default({}),
+  created_at: z.number().int().optional(),
+});
+
+export const traceAddNodeOutputSchema = z.object({
+  ok: z.literal(true),
+  node_id: z.string(),
+});
+
+export const traceAddEdgeInputSchema = z.object({
+  trace_id: z.string(),
+  edge_id: z.string().optional(),
+  from_node_id: z.string(),
+  to_node_id: z.string(),
+  relation_type: relationTypeEnum,
+  data: jsonRecord.optional().default({}),
+  created_at: z.number().int().optional(),
+});
+
+export const traceAddEdgeOutputSchema = z.object({
+  ok: z.literal(true),
+  edge_id: z.string(),
+});
+
+export const traceAttachArtifactInputSchema = z.object({
+  trace_id: z.string(),
+  artifact_id: z.string().optional(),
+  node_id: z.string().optional(),
+  artifact_type: z.string(),
+  content: z.string(),
+  redaction_level: redactionLevelEnum.optional().default("internal"),
+  metadata: jsonRecord.optional().default({}),
+  created_at: z.number().int().optional(),
+});
+
+export const traceAttachArtifactOutputSchema = z.object({
+  ok: z.literal(true),
+  artifact_id: z.string(),
+  sha256: z.string(),
+  redaction_level: redactionLevelEnum,
+});
+
+export const traceFinishInputSchema = z.object({
+  trace_id: z.string(),
+  status: z.enum(["success", "fail", "unknown"]).optional(),
+  outcome: jsonRecord.optional(),
+  finished_at: z.number().int().optional(),
+});
+
+export const traceFinishOutputSchema = z.object({
+  ok: z.literal(true),
+  trace_id: z.string(),
+});
+
+export const traceQueryInputSchema = z.object({
+  trace_id: z.string().optional(),
+  type: nodeTypeEnum.optional(),
+  text: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  limit: z.number().int().min(1).max(500).optional().default(50),
+  offset: z.number().int().min(0).optional().default(0),
+});
+
+export const traceQueryOutputSchema = z.object({
+  ok: z.literal(true),
+  nodes: z.array(z.record(z.string(), z.unknown())),
+});
+
+export const traceGetSubgraphInputSchema = z.object({
+  trace_id: z.string(),
+  center: z.string(),
+  depth: z.number().int().min(0).max(10).optional().default(2),
+  direction: z.enum(["in", "out", "both"]).optional().default("both"),
+  max_nodes: z.number().int().min(1).max(2000).optional().default(250),
+});
+
+export const traceGetSubgraphOutputSchema = z.object({
+  ok: z.literal(true),
+  nodes: z.array(z.record(z.string(), z.unknown())),
+  edges: z.array(z.record(z.string(), z.unknown())),
+});
+
+export const traceFindPathsInputSchema = z.object({
+  trace_id: z.string(),
+  from: z.string(),
+  to: z.string(),
+  max_depth: z.number().int().min(1).max(10).optional().default(4),
+  max_paths: z.number().int().min(1).max(50).optional().default(10),
+  allow_relations: z.array(relationTypeEnum).optional(),
+});
+
+export const traceFindPathsOutputSchema = z.object({
+  ok: z.literal(true),
+  paths: z.array(
+    z.object({
+      node_ids: z.array(z.string()),
+      edge_ids: z.array(z.string()),
+    })
+  ),
+});
+
+export const traceExplainDecisionInputSchema = z.object({
+  trace_id: z.string(),
+  decision_node_id: z.string(),
+  depth: z.number().int().min(1).max(10).optional().default(4),
+});
+
+export const traceExplainDecisionOutputSchema = z.object({
+  ok: z.literal(true),
+  explanation: z.record(z.string(), z.unknown()),
+});
+
+export const traceSimilarityInputSchema = z.object({
+  trace_id: z.string().optional(),
+  decision_node_id: z.string(),
+  scope: z.enum(["trace", "all"]).optional().default("all"),
+  limit: z.number().int().min(1).max(50).optional().default(10),
+  depth: z.number().int().min(1).max(10).optional().default(4),
+  max_traces: z.number().int().min(1).max(1000).optional().default(200),
+});
+
+export const traceSimilarityOutputSchema = z.object({
+  ok: z.literal(true),
+  matches: z.array(
+    z.object({
+      node: z.record(z.string(), z.unknown()),
+      trace: z.record(z.string(), z.unknown()),
+      score: z.number(),
+      reasons: z.object({
+        text: z.number(),
+        tags: z.number(),
+        signature: z.boolean(),
+      }),
+    })
+  ),
+});
+
+export const traceRiskCheckInputSchema = z.object({
+  decision_node_id: z.string(),
+  scope: z.enum(["trace", "all"]).optional().default("all"),
+  limit: z.number().int().min(1).max(50).optional().default(10),
+  depth: z.number().int().min(1).max(10).optional().default(4),
+  threshold: z.number().min(0).max(1).optional().default(0.6),
+  max_traces: z.number().int().min(1).max(1000).optional().default(200),
+});
+
+export const traceRiskCheckOutputSchema = z.object({
+  ok: z.literal(true),
+  assessment: z.object({
+    decision: z.record(z.string(), z.unknown()),
+    novelty: z.boolean(),
+    similar_failures: z.array(
+      z.object({
+        node: z.record(z.string(), z.unknown()),
+        trace: z.record(z.string(), z.unknown()),
+        score: z.number(),
+        reasons: z.object({
+          text: z.number(),
+          tags: z.number(),
+          signature: z.boolean(),
+        }),
+      })
+    ),
+    signature_failed_match: z.boolean(),
+    warnings: z.array(z.string()),
+  }),
+});
+
+export const errorOutputSchema = z.object({
+  ok: z.literal(false),
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    details: z.unknown().optional(),
+  }),
+});
+
+export type TraceStartInput = z.infer<typeof traceStartInputSchema>;
+export type TraceAddNodeInput = z.infer<typeof traceAddNodeInputSchema>;
+export type TraceAddEdgeInput = z.infer<typeof traceAddEdgeInputSchema>;
+export type TraceAttachArtifactInput = z.infer<typeof traceAttachArtifactInputSchema>;
+export type TraceFinishInput = z.infer<typeof traceFinishInputSchema>;
+export type TraceQueryInput = z.infer<typeof traceQueryInputSchema>;
+export type TraceGetSubgraphInput = z.infer<typeof traceGetSubgraphInputSchema>;
+export type TraceFindPathsInput = z.infer<typeof traceFindPathsInputSchema>;
+export type TraceExplainDecisionInput = z.infer<typeof traceExplainDecisionInputSchema>;
+export type TraceSimilarityInput = z.infer<typeof traceSimilarityInputSchema>;
+export type TraceRiskCheckInput = z.infer<typeof traceRiskCheckInputSchema>;

package/src/server.ts

@@ -0,0 +1,38 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
+
+import { initStorage } from "./storage/db.js";
+import { registerTools } from "./mcp/tools.js";
+import { registerResources } from "./mcp/resources.js";
+
+async function main() {
+  const engine = await initStorage({
+    onLog: (msg) => console.error(`[ctx] ${msg}`),
+  });
+
+  const server = new McpServer({
+    name: "ctx",
+    version: "0.1.0",
+  });
+
+  registerTools(server, engine);
+
+  registerResources(server, engine, {
+    base: new ResourceTemplate("trace://{trace_id}", { list: undefined }),
+    timeline: new ResourceTemplate("trace://{trace_id}/timeline", { list: undefined }),
+    graph: new ResourceTemplate("trace://{trace_id}/graph", { list: undefined }),
+    subgraph: new ResourceTemplate("trace://{trace_id}/subgraph", { list: undefined }),
+    explain: new ResourceTemplate("trace://{trace_id}/explain", { list: undefined }),
+    search: new ResourceTemplate("trace://search", { list: undefined }),
+    similarity: new ResourceTemplate("trace://{trace_id}/similarity", { list: undefined }),
+    risk: new ResourceTemplate("trace://{trace_id}/risk", { list: undefined }),
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("[ctx] Failed to start server", err);
+  process.exit(1);
+});

package/src/similarity/similarity.ts

@@ -0,0 +1,299 @@
+import type { StorageEngine } from "../storage/engine.js";
+import {
+  getAllTraces,
+  getNode,
+  getTrace,
+  getTraceEdges,
+  getTraceNodes,
+  searchNodes,
+  type NodeRow,
+  type TraceRow,
+} from "../storage/queries.js";
+import { explainDecision } from "../explain/explain.js";
+import { sha256 } from "../util/hashing.js";
+
+export type SimilarDecision = {
+  node: NodeRow;
+  trace: TraceRow;
+  score: number;
+  reasons: {
+    text: number;
+    tags: number;
+    signature: boolean;
+  };
+};
+
+export type SimilarityOptions = {
+  scope: "trace" | "all";
+  limit: number;
+  depth: number;
+  maxTraces: number;
+};
+
+export type RiskAssessment = {
+  decision: NodeRow;
+  novelty: boolean;
+  similar_failures: SimilarDecision[];
+  signature_failed_match: boolean;
+  warnings: string[];
+};
+
+type TraceContext = {
+  nodes: NodeRow[];
+  edges: ReturnType<typeof getTraceEdges>;
+  signatureByDecision: Map<string, string>;
+};
+
+export function findSimilarDecisions(
+  engine: StorageEngine,
+  decisionNodeId: string,
+  options: SimilarityOptions
+): SimilarDecision[] {
+  const decision = getNode(engine, decisionNodeId);
+  if (!decision) {
+    throw new Error(`Decision node ${decisionNodeId} not found`);
+  }
+
+  const baseTrace = getTrace(engine, decision.trace_id);
+  if (!baseTrace) {
+    throw new Error(`Trace ${decision.trace_id} not found`);
+  }
+
+  const baseContext = getTraceContext(engine, decision.trace_id, options.depth);
+  const baseSignature = baseContext.signatureByDecision.get(decisionNodeId);
+  if (!baseSignature) {
+    throw new Error(`Signature for ${decisionNodeId} not found`);
+  }
+
+  const baseTokens = tokenize(decision.summary);
+  const baseTags = parseTags(baseTrace.tags_json);
+
+  const candidates = searchNodes(engine, {
+    traceId: options.scope === "trace" ? decision.trace_id : undefined,
+    type: "Decision",
+    text: baseTokens.join(" "),
+    limit: Math.max(options.limit * 3, 30),
+    offset: 0,
+  }).filter((node) => node.node_id !== decisionNodeId);
+
+  const traceMap = new Map<string, TraceRow>();
+  if (options.scope === "all") {
+    const traces = getAllTraces(engine).slice(0, options.maxTraces);
+    for (const trace of traces) {
+      traceMap.set(trace.trace_id, trace);
+    }
+  } else {
+    traceMap.set(baseTrace.trace_id, baseTrace);
+  }
+
+  const scored = candidates
+    .map((node) => {
+      const trace = traceMap.get(node.trace_id) ?? getTrace(engine, node.trace_id);
+      if (!trace) return null;
+
+      const context = getTraceContext(engine, node.trace_id, options.depth);
+
+      const signature = context.signatureByDecision.get(node.node_id);
+      const signatureMatch = signature === baseSignature;
+
+      const textScore = tokenSimilarity(baseTokens, tokenize(node.summary));
+      const tagScore = tagOverlap(baseTags, parseTags(trace.tags_json));
+
+      const score = 0.5 * (signatureMatch ? 1 : 0) + 0.4 * textScore + 0.1 * tagScore;
+
+      return {
+        node,
+        trace,
+        score,
+        reasons: {
+          text: textScore,
+          tags: tagScore,
+          signature: signatureMatch,
+        },
+      } as SimilarDecision;
+    })
+    .filter((item): item is SimilarDecision => Boolean(item));
+
+  return scored.sort((a, b) => b.score - a.score).slice(0, options.limit);
+}
+
+export function assessDecisionRisk(
+  engine: StorageEngine,
+  decisionNodeId: string,
+  options: SimilarityOptions & { threshold: number }
+): RiskAssessment {
+  const decision = getNode(engine, decisionNodeId);
+  if (!decision) {
+    throw new Error(`Decision node ${decisionNodeId} not found`);
+  }
+
+  const similar = findSimilarDecisions(engine, decisionNodeId, options);
+  const matching = similar.filter((item) => item.score >= options.threshold);
+
+  const similarFailures = matching.filter((item) => item.trace.status === "fail");
+
+  const signatureFailedMatch = hasFailedSignatureMatch(
+    engine,
+    decisionNodeId,
+    options.depth,
+    options.maxTraces
+  );
+
+  const novelty = matching.length === 0;
+  const warnings: string[] = [];
+  if (novelty) warnings.push("no_similar_decisions");
+  if (similarFailures.length > 0) warnings.push("similar_decisions_failed");
+  if (signatureFailedMatch) warnings.push("signature_match_failed_trace");
+
+  return {
+    decision,
+    novelty,
+    similar_failures: similarFailures,
+    signature_failed_match: signatureFailedMatch,
+    warnings,
+  };
+}
+
+function loadTraceContext(engine: StorageEngine, traceId: string, depth: number): TraceContext {
+  const nodes = getTraceNodes(engine, traceId);
+  const edges = getTraceEdges(engine, traceId);
+  const signatureByDecision = new Map<string, string>();
+
+  for (const node of nodes) {
+    if (node.type !== "Decision") continue;
+    const signature = computeDecisionSignature(node.node_id, nodes, edges, depth);
+    signatureByDecision.set(node.node_id, signature);
+  }
+
+  return { nodes, edges, signatureByDecision };
+}
+
+const traceContextCache = new WeakMap<StorageEngine, Map<string, Map<number, TraceContext>>>();
+
+export function invalidateTraceContext(engine: StorageEngine, traceId?: string): void {
+  const engineCache = traceContextCache.get(engine);
+  if (!engineCache) return;
+  if (!traceId) {
+    traceContextCache.delete(engine);
+    return;
+  }
+  engineCache.delete(traceId);
+  if (engineCache.size === 0) {
+    traceContextCache.delete(engine);
+  }
+}
+
+function getTraceContext(engine: StorageEngine, traceId: string, depth: number): TraceContext {
+  let engineCache = traceContextCache.get(engine);
+  if (!engineCache) {
+    engineCache = new Map();
+    traceContextCache.set(engine, engineCache);
+  }
+
+  let depthCache = engineCache.get(traceId);
+  if (!depthCache) {
+    depthCache = new Map();
+    engineCache.set(traceId, depthCache);
+  }
+
+  const cached = depthCache.get(depth);
+  if (cached) return cached;
+
+  const context = loadTraceContext(engine, traceId, depth);
+  depthCache.set(depth, context);
+  return context;
+}
+
+function computeDecisionSignature(
+  decisionNodeId: string,
+  nodes: NodeRow[],
+  edges: ReturnType<typeof getTraceEdges>,
+  depth: number
+): string {
+  const explanation = explainDecision(decisionNodeId, nodes, edges, [], depth);
+  const parts = [
+    explanation.decision_node.summary,
+    ...explanation.assumptions.map((node) => node.summary),
+    ...explanation.evidence.map((node) => node.summary),
+    ...explanation.alternatives.map((node) => node.summary),
+    ...explanation.checks.map((node) => node.summary),
+  ]
+    .map(normalizeText)
+    .filter(Boolean)
+    .sort();
+
+  return sha256(parts.join("|"));
+}
+
+function hasFailedSignatureMatch(
+  engine: StorageEngine,
+  decisionNodeId: string,
+  depth: number,
+  maxTraces: number
+): boolean {
+  const decision = getNode(engine, decisionNodeId);
+  if (!decision) return false;
+
+  const baseContext = getTraceContext(engine, decision.trace_id, depth);
+  const baseSignature = baseContext.signatureByDecision.get(decisionNodeId);
+  if (!baseSignature) return false;
+
+  const failedTraces = getAllTraces(engine)
+    .filter((trace) => trace.status === "fail")
+    .slice(0, maxTraces);
+  for (const trace of failedTraces) {
+    const context = getTraceContext(engine, trace.trace_id, depth);
+    for (const signature of context.signatureByDecision.values()) {
+      if (signature === baseSignature) return true;
+    }
+  }
+
+  return false;
+}
+
+function parseTags(tagsJson: string | null): string[] {
+  if (!tagsJson) return [];
+  try {
+    const parsed = JSON.parse(tagsJson);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function tokenize(text: string): string[] {
+  return normalizeText(text)
+    .split(" ")
+    .filter(Boolean);
+}
+
+function normalizeText(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function tokenSimilarity(a: string[], b: string[]): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  const setA = new Set(a);
+  const setB = new Set(b);
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) intersection += 1;
+  }
+  const union = new Set([...setA, ...setB]).size;
+  return union === 0 ? 0 : intersection / union;
+}
+
+function tagOverlap(a: string[], b: string[]): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  const setA = new Set(a);
+  let intersection = 0;
+  for (const tag of b) {
+    if (setA.has(tag)) intersection += 1;
+  }
+  const denom = Math.max(a.length, b.length);
+  return denom === 0 ? 0 : intersection / denom;
+}

package/src/storage/db.ts

@@ -0,0 +1,17 @@
+import { SqlJsEngine, type SqlJsEngineOptions } from "./sqljsEngine.js";
+
+let engine: SqlJsEngine | null = null;
+
+export async function initStorage(opts?: SqlJsEngineOptions): Promise<SqlJsEngine> {
+  if (engine) return engine;
+  engine = new SqlJsEngine(opts);
+  await engine.init();
+  return engine;
+}
+
+export function getStorage(): SqlJsEngine {
+  if (!engine) {
+    throw new Error("Storage engine not initialized");
+  }
+  return engine;
+}

package/src/storage/engine.ts

@@ -0,0 +1,14 @@
+export type TxFn<T> = () => T;
+
+export interface StorageEngine {
+  init(): Promise<void>;
+
+  transaction<T>(fn: TxFn<T>): T;
+
+  exec(sql: string, params?: unknown[]): void;
+  queryAll<T = unknown>(sql: string, params?: unknown[]): T[];
+  queryOne<T = unknown>(sql: string, params?: unknown[]): T | null;
+
+  flushIfDirty(): Promise<void>;
+  flushNow(): Promise<void>;
+}

package/src/storage/migrations.ts

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type Migration = {
+  version: number;
+  sql: string;
+  optional?: boolean;
+};
+
+function readMigrationFile(fileName: string): string {
+  const baseDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../migrations");
+  return fs.readFileSync(path.join(baseDir, fileName), "utf8");
+}
+
+export const defaultMigrations: Migration[] = [
+  { version: 1, sql: readMigrationFile("001_init.sql") },
+  { version: 2, sql: readMigrationFile("002_fts.sql"), optional: true },
+];