@danielblomma/cortex-mcp 0.4.0

package/scaffold/mcp/src/search.ts

@@ -0,0 +1,412 @@
+import { embedQuery, getEmbeddingRuntimeWarning, loadEmbeddingIndex } from "./embeddings.js";
+import { loadContextData } from "./graph.js";
+import type {
+  ContextData,
+  JsonObject,
+  RelatedParams,
+  RelationRecord,
+  RulesParams,
+  SearchEntity,
+  SearchParams,
+  ToolPayload
+} from "./types.js";
+
+function tokenize(value: string): string[] {
+  return value
+    .toLowerCase()
+    .split(/[^a-z0-9]+/g)
+    .map((part) => part.trim())
+    .filter((part) => part.length >= 2);
+}
+
+function daysSince(isoDate: string): number {
+  const timestamp = Date.parse(isoDate);
+  if (Number.isNaN(timestamp)) {
+    return 3650;
+  }
+
+  const now = Date.now();
+  return Math.max(0, (now - timestamp) / (1000 * 60 * 60 * 24));
+}
+
+function recencyScore(isoDate: string): number {
+  const days = daysSince(isoDate);
+  return 1 / (1 + days / 30);
+}
+
+function semanticScore(query: string, text: string): number {
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) {
+    return 0;
+  }
+
+  const haystack = text.toLowerCase();
+  let matched = 0;
+  for (const token of queryTokens) {
+    if (haystack.includes(token)) {
+      matched += 1;
+    }
+  }
+
+  const overlap = matched / queryTokens.length;
+  const phraseBonus = haystack.includes(query.toLowerCase()) ? 0.25 : 0;
+  return Math.min(1, overlap * 0.85 + phraseBonus);
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length === 0 || b.length === 0 || a.length !== b.length) {
+    return 0;
+  }
+
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    const av = a[index];
+    const bv = b[index];
+    dot += av * bv;
+    normA += av * av;
+    normB += bv * bv;
+  }
+
+  if (normA === 0 || normB === 0) {
+    return 0;
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+function groupRuleLinks(relations: RelationRecord[]): Map<string, string[]> {
+  const links = new Map<string, string[]>();
+  for (const relation of relations) {
+    if (relation.relation !== "CONSTRAINS" && relation.relation !== "IMPLEMENTS") {
+      continue;
+    }
+
+    if (relation.relation === "CONSTRAINS") {
+      const list = links.get(relation.to) ?? [];
+      list.push(relation.from);
+      links.set(relation.to, list);
+    } else {
+      const list = links.get(relation.from) ?? [];
+      list.push(relation.to);
+      links.set(relation.from, list);
+    }
+  }
+  return links;
+}
+
+function buildSearchEntities(data: ContextData, includeContent: boolean): SearchEntity[] {
+  const entities: SearchEntity[] = [];
+  const ruleLinks = groupRuleLinks(data.relations);
+  const adrPathSet = new Set(
+    data.adrs
+      .map((adr) => adr.path.trim().toLowerCase())
+      .filter((adrPath) => adrPath.length > 0)
+  );
+
+  for (const document of data.documents) {
+    const normalizedPath = document.path.trim().toLowerCase();
+    // ADR content is represented by ADR entities below; avoid duplicate results.
+    if (document.kind === "ADR" && adrPathSet.has(normalizedPath)) {
+      continue;
+    }
+
+    entities.push({
+      id: document.id,
+      entity_type: "File",
+      kind: document.kind,
+      label: document.path,
+      path: document.path,
+      text: `${document.path}\n${document.excerpt}\n${document.content}`,
+      status: document.status,
+      source_of_truth: document.source_of_truth,
+      trust_level: document.trust_level,
+      updated_at: document.updated_at,
+      snippet: document.excerpt,
+      matched_rules: ruleLinks.get(document.id) ?? [],
+      content: includeContent ? document.content : undefined
+    });
+  }
+
+  for (const rule of data.rules) {
+    entities.push({
+      id: rule.id,
+      entity_type: "Rule",
+      kind: "RULE",
+      label: rule.title || rule.id,
+      path: "",
+      text: `${rule.id}\n${rule.title}\n${rule.body}`,
+      status: rule.status,
+      source_of_truth: rule.source_of_truth,
+      trust_level: rule.trust_level,
+      updated_at: rule.updated_at,
+      snippet: rule.body.slice(0, 500),
+      matched_rules: [rule.id],
+      content: includeContent ? rule.body : undefined
+    });
+  }
+
+  for (const adr of data.adrs) {
+    entities.push({
+      id: adr.id,
+      entity_type: "ADR",
+      kind: "ADR",
+      label: adr.title || adr.id,
+      path: adr.path,
+      text: `${adr.path}\n${adr.title}\n${adr.body}`,
+      status: adr.status,
+      source_of_truth: adr.source_of_truth,
+      trust_level: adr.trust_level,
+      updated_at: adr.decision_date,
+      snippet: adr.body.slice(0, 500),
+      matched_rules: [],
+      content: includeContent ? adr.body : undefined
+    });
+  }
+
+  return entities;
+}
+
+function relationDegree(relations: RelationRecord[]): Map<string, number> {
+  const degrees = new Map<string, number>();
+
+  for (const relation of relations) {
+    degrees.set(relation.from, (degrees.get(relation.from) ?? 0) + 1);
+    degrees.set(relation.to, (degrees.get(relation.to) ?? 0) + 1);
+  }
+
+  return degrees;
+}
+
+function entityCatalog(data: ContextData): Map<string, JsonObject> {
+  const catalog = new Map<string, JsonObject>();
+
+  for (const file of data.documents) {
+    catalog.set(file.id, {
+      id: file.id,
+      type: "File",
+      label: file.path,
+      status: file.status,
+      source_of_truth: file.source_of_truth
+    });
+  }
+
+  for (const rule of data.rules) {
+    catalog.set(rule.id, {
+      id: rule.id,
+      type: "Rule",
+      label: rule.title,
+      status: rule.status,
+      source_of_truth: rule.source_of_truth
+    });
+  }
+
+  for (const adr of data.adrs) {
+    catalog.set(adr.id, {
+      id: adr.id,
+      type: "ADR",
+      label: adr.title || adr.id,
+      status: adr.status,
+      source_of_truth: adr.source_of_truth
+    });
+  }
+
+  return catalog;
+}
+
+export async function runContextSearch(parsed: SearchParams): Promise<ToolPayload> {
+  const data = await loadContextData();
+  const degreeByEntity = relationDegree(data.relations);
+  const candidates = buildSearchEntities(data, parsed.include_content).filter(
+    (entity) => parsed.include_deprecated || entity.status.toLowerCase() !== "deprecated"
+  );
+  const embeddings = loadEmbeddingIndex();
+  const queryVector =
+    embeddings.model && embeddings.vectors.size > 0
+      ? await embedQuery(parsed.query, embeddings.model)
+      : null;
+
+  const results = candidates
+    .map((entity) => {
+      const lexicalSemantic = semanticScore(parsed.query, entity.text);
+      const entityVector = embeddings.vectors.get(entity.id);
+      const vectorSemantic =
+        queryVector && entityVector
+          ? Math.max(0, Math.min(1, (cosineSimilarity(queryVector, entityVector) + 1) / 2))
+          : 0;
+      const semantic =
+        vectorSemantic > 0 ? vectorSemantic * 0.75 + lexicalSemantic * 0.25 : lexicalSemantic;
+      const graphScore = Math.min(1, (degreeByEntity.get(entity.id) ?? 0) / 4);
+      const trustScore = Math.max(0, Math.min(1, entity.trust_level / 100));
+      const dateScore = recencyScore(entity.updated_at);
+
+      let score = 0;
+      score += data.ranking.semantic * semantic;
+      score += data.ranking.graph * graphScore;
+      score += data.ranking.trust * trustScore;
+      score += data.ranking.recency * dateScore;
+
+      if (entity.source_of_truth) {
+        score += 0.1;
+      }
+
+      return {
+        id: entity.id,
+        entity_type: entity.entity_type,
+        kind: entity.kind,
+        title: entity.label,
+        path: entity.path || undefined,
+        score: Number(score.toFixed(4)),
+        semantic_score: Number(semantic.toFixed(4)),
+        embedding_score: Number(vectorSemantic.toFixed(4)),
+        lexical_score: Number(lexicalSemantic.toFixed(4)),
+        graph_score: Number(graphScore.toFixed(4)),
+        source_of_truth: entity.source_of_truth,
+        status: entity.status,
+        updated_at: entity.updated_at,
+        matched_rules: entity.matched_rules,
+        excerpt: entity.snippet,
+        content: parsed.include_content ? entity.content : undefined
+      };
+    })
+    .filter((result) => result.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, parsed.top_k);
+
+  const warningMessages = [data.warning, embeddings.warning, getEmbeddingRuntimeWarning()].filter(Boolean);
+
+  return {
+    query: parsed.query,
+    top_k: parsed.top_k,
+    ranking: data.ranking,
+    total_candidates: candidates.length,
+    context_source: data.source,
+    warning: warningMessages.length > 0 ? warningMessages.join(" | ") : undefined,
+    semantic_engine:
+      queryVector && embeddings.model ? `embedding+lexical (${embeddings.model})` : "lexical-only",
+    results
+  };
+}
+
+export async function runContextRelated(parsed: RelatedParams): Promise<ToolPayload> {
+  const data = await loadContextData();
+  const catalog = entityCatalog(data);
+
+  if (!catalog.has(parsed.entity_id)) {
+    return {
+      entity_id: parsed.entity_id,
+      depth: parsed.depth,
+      related: [],
+      edges: [],
+      context_source: data.source,
+      warning: "Entity not found in indexed context."
+    };
+  }
+
+  const outgoing = new Map<string, RelationRecord[]>();
+  const incoming = new Map<string, RelationRecord[]>();
+
+  for (const relation of data.relations) {
+    const outList = outgoing.get(relation.from) ?? [];
+    outList.push(relation);
+    outgoing.set(relation.from, outList);
+
+    const inList = incoming.get(relation.to) ?? [];
+    inList.push(relation);
+    incoming.set(relation.to, inList);
+  }
+
+  const seen = new Set<string>([parsed.entity_id]);
+  const queue: Array<{ id: string; hop: number }> = [{ id: parsed.entity_id, hop: 0 }];
+  const related: JsonObject[] = [];
+  const traversedEdges: JsonObject[] = [];
+  const traversedEdgeKeys = new Set<string>();
+
+  while (queue.length > 0) {
+    const current = queue.shift() as { id: string; hop: number };
+    if (current.hop >= parsed.depth) {
+      continue;
+    }
+
+    const neighbors = [
+      ...(outgoing.get(current.id) ?? []).map((edge) => ({
+        edge,
+        next: edge.to,
+        direction: "outgoing"
+      })),
+      ...(incoming.get(current.id) ?? []).map((edge) => ({
+        edge,
+        next: edge.from,
+        direction: "incoming"
+      }))
+    ];
+
+    for (const neighbor of neighbors) {
+      const target = neighbor.next;
+      if (!seen.has(target)) {
+        seen.add(target);
+        queue.push({ id: target, hop: current.hop + 1 });
+
+        const entity = catalog.get(target) ?? {
+          id: target,
+          type: "Unknown",
+          label: target,
+          status: "unknown",
+          source_of_truth: false
+        };
+
+        related.push({
+          ...entity,
+          hops: current.hop + 1,
+          via_relation: neighbor.edge.relation,
+          direction: neighbor.direction
+        });
+      }
+
+      const edgeKey = `${neighbor.edge.from}|${neighbor.edge.relation}|${neighbor.edge.to}|${neighbor.edge.note}`;
+      if (!traversedEdgeKeys.has(edgeKey)) {
+        traversedEdgeKeys.add(edgeKey);
+        traversedEdges.push({
+          from: neighbor.edge.from,
+          to: neighbor.edge.to,
+          relation: neighbor.edge.relation,
+          note: neighbor.edge.note
+        });
+      }
+    }
+  }
+
+  return {
+    entity_id: parsed.entity_id,
+    depth: parsed.depth,
+    context_source: data.source,
+    warning: data.warning,
+    related,
+    edges: parsed.include_edges ? traversedEdges : []
+  };
+}
+
+export async function runContextRules(parsed: RulesParams): Promise<ToolPayload> {
+  const data = await loadContextData();
+
+  const rules = data.rules
+    .filter((rule) => parsed.include_inactive || rule.status === "active")
+    .filter((rule) => !parsed.scope || rule.scope === parsed.scope || rule.scope === "global")
+    .sort((a, b) => b.priority - a.priority)
+    .map((rule) => ({
+      id: rule.id,
+      title: rule.title,
+      description: rule.body,
+      priority: rule.priority,
+      scope: rule.scope,
+      status: rule.status
+    }));
+
+  return {
+    scope: parsed.scope ?? "global",
+    count: rules.length,
+    context_source: data.source,
+    warning: data.warning,
+    rules
+  };
+}

package/scaffold/mcp/src/server.ts

@@ -0,0 +1,98 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { reloadContextGraph } from "./graph.js";
+import { runContextRelated, runContextRules, runContextSearch } from "./search.js";
+
+type ToolPayload = Record<string, unknown>;
+
+const SearchInput = z.object({
+  query: z.string().min(1),
+  top_k: z.number().int().positive().max(20).default(5),
+  include_deprecated: z.boolean().default(false),
+  include_content: z.boolean().default(false)
+});
+
+const RelatedInput = z.object({
+  entity_id: z.string().min(1),
+  depth: z.number().int().positive().max(3).default(1),
+  include_edges: z.boolean().default(true)
+});
+
+const RulesInput = z.object({
+  scope: z.string().optional(),
+  include_inactive: z.boolean().default(false)
+});
+
+const ReloadInput = z.object({
+  force: z.boolean().default(true)
+});
+
+function buildToolResult(data: ToolPayload) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(data, null, 2)
+      }
+    ],
+    structuredContent: data
+  };
+}
+
+function registerTools(server: McpServer): void {
+  server.registerTool(
+    "context.search",
+    {
+      description: "Search ranked context documents and code using semantic, graph and trust weighting.",
+      inputSchema: SearchInput
+    },
+    async (input) => buildToolResult(await runContextSearch(SearchInput.parse(input ?? {})))
+  );
+
+  server.registerTool(
+    "context.get_related",
+    {
+      description: "Return related entities and graph edges for a context entity id.",
+      inputSchema: RelatedInput
+    },
+    async (input) => buildToolResult(await runContextRelated(RelatedInput.parse(input ?? {})))
+  );
+
+  server.registerTool(
+    "context.get_rules",
+    {
+      description: "List indexed rules filtered by scope and active status.",
+      inputSchema: RulesInput.optional()
+    },
+    async (input) => buildToolResult(await runContextRules(RulesInput.parse(input ?? {})))
+  );
+
+  server.registerTool(
+    "context.reload",
+    {
+      description: "Reload RyuGraph connection after graph updates or maintenance.",
+      inputSchema: ReloadInput.optional()
+    },
+    async (input) => {
+      const parsed = ReloadInput.parse(input ?? {});
+      return buildToolResult(await reloadContextGraph(parsed.force));
+    }
+  );
+}
+
+async function main(): Promise<void> {
+  const server = new McpServer({
+    name: "cortex-context",
+    version: "0.1.0"
+  });
+
+  registerTools(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : "Fatal error"}\n`);
+  process.exit(1);
+});

package/scaffold/mcp/src/types.ts

@@ -0,0 +1,109 @@
+export type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];
+export type JsonObject = { [key: string]: JsonValue };
+export type UnknownRow = Record<string, unknown>;
+
+export type DocumentRecord = {
+  id: string;
+  path: string;
+  kind: "DOC" | "CODE" | "ADR";
+  updated_at: string;
+  source_of_truth: boolean;
+  trust_level: number;
+  status: string;
+  excerpt: string;
+  content: string;
+};
+
+export type RuleRecord = {
+  id: string;
+  title: string;
+  body: string;
+  scope: string;
+  updated_at: string;
+  source_of_truth: boolean;
+  trust_level: number;
+  status: string;
+  priority: number;
+};
+
+export type AdrRecord = {
+  id: string;
+  path: string;
+  title: string;
+  body: string;
+  decision_date: string;
+  supersedes_id: string;
+  source_of_truth: boolean;
+  trust_level: number;
+  status: string;
+};
+
+export type RelationRecord = {
+  from: string;
+  to: string;
+  relation: "CONSTRAINS" | "IMPLEMENTS" | "SUPERSEDES";
+  note: string;
+};
+
+export type RankingWeights = {
+  semantic: number;
+  graph: number;
+  trust: number;
+  recency: number;
+};
+
+export type ContextData = {
+  documents: DocumentRecord[];
+  adrs: AdrRecord[];
+  rules: RuleRecord[];
+  relations: RelationRecord[];
+  ranking: RankingWeights;
+  source: "cache" | "ryu";
+  warning?: string;
+};
+
+export type SearchEntity = {
+  id: string;
+  entity_type: "File" | "Rule" | "ADR";
+  kind: string;
+  label: string;
+  path: string;
+  text: string;
+  status: string;
+  source_of_truth: boolean;
+  trust_level: number;
+  updated_at: string;
+  snippet: string;
+  matched_rules: string[];
+  content?: string;
+};
+
+export type EmbeddingIndex = {
+  model: string | null;
+  vectors: Map<string, number[]>;
+  warning?: string;
+};
+
+export type SearchParams = {
+  query: string;
+  top_k: number;
+  include_deprecated: boolean;
+  include_content: boolean;
+};
+
+export type RelatedParams = {
+  entity_id: string;
+  depth: number;
+  include_edges: boolean;
+};
+
+export type RulesParams = {
+  scope?: string;
+  include_inactive: boolean;
+};
+
+export type ReloadParams = {
+  force: boolean;
+};
+
+export type ToolPayload = Record<string, unknown>;

package/scaffold/mcp/tests/server.test.mjs

@@ -0,0 +1,60 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const MCP_DIR = path.resolve(__dirname, "..");
+
+async function withClient(fn) {
+  const transport = new StdioClientTransport({
+    command: "node",
+    args: ["dist/server.js"],
+    cwd: MCP_DIR,
+    stderr: "pipe"
+  });
+
+  const client = new Client({ name: "cortex-test-client", version: "0.1.0" });
+  await client.connect(transport);
+  try {
+    await fn(client);
+  } finally {
+    await client.close();
+  }
+}
+
+test("context.get_rules accepts missing arguments", async () => {
+  await withClient(async (client) => {
+    const result = await client.callTool({ name: "context.get_rules" });
+    assert.notEqual(result.isError, true);
+    assert.ok(result.structuredContent);
+    assert.ok(Array.isArray(result.structuredContent.rules));
+  });
+});
+
+test("context.search returns unified entity types", async () => {
+  await withClient(async (client) => {
+    const result = await client.callTool({
+      name: "context.search",
+      arguments: { query: "rule.source_of_truth", top_k: 10 }
+    });
+    assert.notEqual(result.isError, true);
+    assert.ok(result.structuredContent);
+    assert.ok(Array.isArray(result.structuredContent.results));
+    const types = new Set(result.structuredContent.results.map((item) => item.entity_type));
+    assert.ok(types.has("Rule"));
+  });
+});
+
+test("context.reload returns reload metadata", async () => {
+  await withClient(async (client) => {
+    const result = await client.callTool({ name: "context.reload" });
+    assert.notEqual(result.isError, true);
+    assert.ok(result.structuredContent);
+    assert.equal(typeof result.structuredContent.reloaded, "boolean");
+    assert.ok(["ryu", "cache"].includes(String(result.structuredContent.context_source)));
+  });
+});

package/scaffold/mcp/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}