@danielblomma/cortex-mcp 0.4.5 → 1.0.0

package/scaffold/mcp/src/impactPresentation.ts

@@ -0,0 +1,202 @@
+import type { ImpactParams, JsonObject, SearchEntity } from "./types.js";
+
+export type ImpactTraversalStep = {
+  hops: number;
+  via_relation: string;
+  direction: string;
+  via_entity: string;
+  via_note?: string;
+};
+
+function impactEntityLabel(
+  entityId: string,
+  catalog: Map<string, JsonObject>,
+  searchEntities: Map<string, SearchEntity>
+): string {
+  const searchEntity = searchEntities.get(entityId);
+  if (searchEntity?.label) {
+    return searchEntity.label;
+  }
+  const catalogEntry = catalog.get(entityId);
+  return String(catalogEntry?.label ?? entityId);
+}
+
+export function buildImpactPath(
+  targetId: string,
+  seedId: string,
+  visited: Map<string, ImpactTraversalStep>,
+  catalog: Map<string, JsonObject>,
+  searchEntities: Map<string, SearchEntity>
+): { summary: string; entities: string[]; edges: JsonObject[] } {
+  const entities = [targetId];
+  const edges: JsonObject[] = [];
+  let currentId = targetId;
+
+  while (currentId !== seedId) {
+    const metadata = visited.get(currentId);
+    if (!metadata) {
+      break;
+    }
+
+    const from = metadata.direction === "outgoing" ? metadata.via_entity : currentId;
+    const to = metadata.direction === "outgoing" ? currentId : metadata.via_entity;
+    edges.push({
+      from,
+      to,
+      relation: metadata.via_relation,
+      note: metadata.via_note ?? ""
+    });
+    entities.push(metadata.via_entity);
+    currentId = metadata.via_entity;
+  }
+
+  entities.reverse();
+  edges.reverse();
+
+  const labels = entities.map((entityId) => impactEntityLabel(entityId, catalog, searchEntities));
+  const summaryParts = [];
+  for (let index = 0; index < labels.length; index += 1) {
+    summaryParts.push(labels[index]);
+    if (index < edges.length) {
+      const edge = edges[index];
+      const note = edge.note ? `(${String(edge.note)})` : "";
+      summaryParts.push(`-[${String(edge.relation)}${note}]->`);
+    }
+  }
+
+  return {
+    summary: summaryParts.join(" "),
+    entities,
+    edges
+  };
+}
+
+export function buildCompactImpactSummary(
+  entities: string[],
+  edges: JsonObject[],
+  catalog: Map<string, JsonObject>,
+  searchEntities: Map<string, SearchEntity>,
+  maxPathHopsShown: number
+): string {
+  const labels = entities.map((entityId) => impactEntityLabel(entityId, catalog, searchEntities));
+  if (labels.length <= 3 || edges.length <= maxPathHopsShown) {
+    const summaryParts = [];
+    for (let index = 0; index < labels.length; index += 1) {
+      summaryParts.push(labels[index]);
+      if (index < edges.length) {
+        const edge = edges[index];
+        const note = edge.note ? `(${String(edge.note)})` : "";
+        summaryParts.push(`-[${String(edge.relation)}${note}]->`);
+      }
+    }
+    return summaryParts.join(" ");
+  }
+
+  const headEdgeCount = Math.max(1, Math.ceil(maxPathHopsShown / 2));
+  const tailEdgeCount = Math.max(0, Math.floor(maxPathHopsShown / 2));
+  const hiddenHopCount = Math.max(0, edges.length - headEdgeCount - tailEdgeCount);
+  const hiddenText = hiddenHopCount === 1 ? "1 more hop" : `${hiddenHopCount} more hops`;
+  const summaryParts = [labels[0]];
+
+  for (let index = 0; index < headEdgeCount; index += 1) {
+    const edge = edges[index];
+    const note = edge.note ? `(${String(edge.note)})` : "";
+    summaryParts.push(`-[${String(edge.relation)}${note}]->`);
+    summaryParts.push(labels[index + 1]);
+  }
+
+  summaryParts.push(`... ${hiddenText} ...`);
+
+  const tailStart = edges.length - tailEdgeCount;
+  const tailEntityStart = labels.length - tailEdgeCount - 1;
+  for (let index = tailStart; index < edges.length; index += 1) {
+    const edge = edges[index];
+    const note = edge.note ? `(${String(edge.note)})` : "";
+    const labelIndex = tailEntityStart + (index - tailStart);
+    summaryParts.push(`-[${String(edge.relation)}${note}]->`);
+    summaryParts.push(labels[labelIndex + 1]);
+  }
+
+  return summaryParts.join(" ");
+}
+
+function formatImpactRelationLabel(relation: string): string {
+  return relation.toLowerCase().replaceAll("_", " ");
+}
+
+function formatImpactRelationWithNote(edge: JsonObject): string {
+  const relationLabel = formatImpactRelationLabel(String(edge.relation ?? ""));
+  const note = String(edge.note ?? "").trim();
+  if (!note) {
+    return relationLabel;
+  }
+  return `${relationLabel} (${note})`;
+}
+
+export function buildImpactWhy(
+  seedId: string,
+  targetId: string,
+  pathEdges: JsonObject[],
+  hops: number,
+  catalog: Map<string, JsonObject>,
+  searchEntities: Map<string, SearchEntity>
+): string {
+  const seedLabel = impactEntityLabel(seedId, catalog, searchEntities);
+  const targetLabel = impactEntityLabel(targetId, catalog, searchEntities);
+  const relationLabels = [...new Set(pathEdges.map((edge) => formatImpactRelationWithNote(edge)))];
+
+  if (relationLabels.length === 0) {
+    return `${targetLabel} is reachable from ${seedLabel}.`;
+  }
+
+  const relationText =
+    relationLabels.length === 1
+      ? relationLabels[0]
+      : `${relationLabels.slice(0, -1).join(", ")} and ${relationLabels[relationLabels.length - 1]}`;
+  const hopText = hops === 1 ? "1 hop" : `${hops} hops`;
+  return `${targetLabel} is impacted from ${seedLabel} via ${relationText} in ${hopText}.`;
+}
+
+export function buildImpactTopReasons(params: {
+  hops: number;
+  profile: NonNullable<ImpactParams["profile"]>;
+  semanticScore: number;
+  noteScore: number;
+  profileScore: number;
+  impactDomains: string[];
+  pathEdges: JsonObject[];
+}): string[] {
+  const reasons: string[] = [];
+
+  reasons.push(params.hops === 1 ? "1-hop path" : `${params.hops}-hop path`);
+
+  if (params.impactDomains.length > 0) {
+    reasons.push(`domains: ${params.impactDomains.join(", ")}`);
+  }
+
+  if (params.noteScore > 0) {
+    const notedEdges = params.pathEdges
+      .map((edge) => ({
+        relation: formatImpactRelationLabel(String(edge.relation ?? "")),
+        note: String(edge.note ?? "").trim()
+      }))
+      .filter((edge) => edge.note.length > 0)
+      .slice(0, 2)
+      .map((edge) => `${edge.relation} (${edge.note})`);
+    if (notedEdges.length > 0) {
+      reasons.push(`note match: ${notedEdges.join(", ")}`);
+    } else {
+      reasons.push("note match");
+    }
+  }
+
+  if (params.profileScore > 0) {
+    reasons.push(`profile boost: ${params.profile}`);
+  }
+
+  if (params.semanticScore > 0.15) {
+    reasons.push("entity text matched query");
+  }
+
+  return reasons.slice(0, 4);
+}

package/scaffold/mcp/src/impactRanking.ts

@@ -0,0 +1,237 @@
+import type { ImpactParams, JsonObject, RelationType, SearchEntity } from "./types.js";
+
+const SQL_ENTITY_KINDS = new Set(["procedure", "view", "function", "table", "trigger"]);
+const SQL_LIKE_EXTENSIONS = [".sql"];
+const CONFIG_LIKE_EXTENSIONS = [".config"];
+const RESOURCE_LIKE_EXTENSIONS = [".resx"];
+const SETTINGS_LIKE_EXTENSIONS = [".settings"];
+const IMPACT_RELATION_TYPE_LIST: RelationType[] = [
+  "CALLS",
+  "CALLS_SQL",
+  "IMPORTS",
+  "USES_CONFIG_KEY",
+  "USES_RESOURCE_KEY",
+  "USES_SETTING_KEY",
+  "USES_CONFIG",
+  "TRANSFORMS_CONFIG",
+  "PART_OF"
+];
+const IMPACT_PROFILE_RELATIONS: Record<
+  NonNullable<ImpactParams["profile"]>,
+  RelationType[]
+> = {
+  all: IMPACT_RELATION_TYPE_LIST,
+  config_only: ["USES_CONFIG_KEY", "USES_RESOURCE_KEY", "USES_SETTING_KEY", "USES_CONFIG", "TRANSFORMS_CONFIG", "PART_OF"],
+  config_to_sql: ["USES_CONFIG_KEY", "USES_RESOURCE_KEY", "USES_SETTING_KEY", "USES_CONFIG", "TRANSFORMS_CONFIG", "CALLS_SQL", "PART_OF"],
+  code_only: ["CALLS", "IMPORTS", "PART_OF"],
+  sql_only: ["CALLS_SQL", "PART_OF"]
+};
+
+function normalizeText(value: string): string {
+  return value.normalize("NFKC").toLowerCase();
+}
+
+function pathHasExtension(pathValue: string, extensions: string[]): boolean {
+  const normalized = normalizeText(pathValue);
+  return extensions.some((extension) => normalized.endsWith(extension));
+}
+
+export function impactBaseScore(hops: number, graphScore: number, trustScore: number, semantic = 0): number {
+  const hopScore = 1 / (1 + Math.max(0, hops));
+  const score = hopScore * 0.55 + graphScore * 0.2 + trustScore * 0.15 + semantic * 0.1;
+  return Number(score.toFixed(4));
+}
+
+export function resolveImpactRelationTypes(parsed: ImpactParams): Set<RelationType> {
+  if (Array.isArray(parsed.relation_types) && parsed.relation_types.length > 0) {
+    return new Set(parsed.relation_types);
+  }
+
+  const profile = parsed.profile ?? "all";
+  return new Set(IMPACT_PROFILE_RELATIONS[profile]);
+}
+
+export function resolveImpactResultDomains(parsed: ImpactParams): Set<string> | null {
+  if (!Array.isArray(parsed.result_domains) || parsed.result_domains.length === 0) {
+    return null;
+  }
+  return new Set(parsed.result_domains.map((domain) => normalizeText(domain)));
+}
+
+export function resolveImpactResultEntityTypes(parsed: ImpactParams): Set<string> | null {
+  if (!Array.isArray(parsed.result_entity_types) || parsed.result_entity_types.length === 0) {
+    return null;
+  }
+  return new Set(parsed.result_entity_types.map((entityType) => normalizeText(entityType)));
+}
+
+export function resolveImpactPathMustInclude(parsed: ImpactParams): Set<string> | null {
+  if (!Array.isArray(parsed.path_must_include) || parsed.path_must_include.length === 0) {
+    return null;
+  }
+  return new Set(parsed.path_must_include.map((relation) => normalizeText(relation)));
+}
+
+export function resolveImpactPathMustExclude(parsed: ImpactParams): Set<string> | null {
+  if (!Array.isArray(parsed.path_must_exclude) || parsed.path_must_exclude.length === 0) {
+    return null;
+  }
+  return new Set(parsed.path_must_exclude.map((relation) => normalizeText(relation)));
+}
+
+export function impactResultComparator(
+  sortBy: NonNullable<ImpactParams["sort_by"]>
+): (a: Record<string, unknown>, b: Record<string, unknown>) => number {
+  return (a, b) => {
+    const aHops = Number(a.hops ?? Number.POSITIVE_INFINITY);
+    const bHops = Number(b.hops ?? Number.POSITIVE_INFINITY);
+    const aImpact = Number(a.impact_score ?? 0);
+    const bImpact = Number(b.impact_score ?? 0);
+    const aSemantic = Number(a.semantic_score ?? 0);
+    const bSemantic = Number(b.semantic_score ?? 0);
+    const aGraph = Number(a.graph_score ?? 0);
+    const bGraph = Number(b.graph_score ?? 0);
+    const aTrust = Number(a.trust_score ?? 0);
+    const bTrust = Number(b.trust_score ?? 0);
+
+    if (sortBy === "shortest_path") {
+      return aHops - bHops || bImpact - aImpact || bSemantic - aSemantic;
+    }
+    if (sortBy === "semantic_score") {
+      return bSemantic - aSemantic || bImpact - aImpact || aHops - bHops;
+    }
+    if (sortBy === "graph_score") {
+      return bGraph - aGraph || bImpact - aImpact || aHops - bHops;
+    }
+    if (sortBy === "trust_score") {
+      return bTrust - aTrust || bImpact - aImpact || aHops - bHops;
+    }
+    return bImpact - aImpact || aHops - bHops || bSemantic - aSemantic;
+  };
+}
+
+export function impactDomainsForEntity(
+  entity: SearchEntity | undefined,
+  catalogEntry: JsonObject | undefined
+): string[] {
+  const domains = new Set<string>();
+  const normalizedKind = normalizeText(entity?.kind ?? "");
+  const normalizedType = normalizeText(entity?.entity_type ?? String(catalogEntry?.type ?? ""));
+  const pathValue = String(entity?.path ?? catalogEntry?.path ?? "");
+
+  if (SQL_ENTITY_KINDS.has(normalizedKind) || pathHasExtension(pathValue, SQL_LIKE_EXTENSIONS)) {
+    domains.add("sql");
+  }
+
+  if (
+    normalizedKind === "connection_string" ||
+    normalizedKind === "database_target" ||
+    normalizedKind === "app_setting" ||
+    pathHasExtension(pathValue, CONFIG_LIKE_EXTENSIONS)
+  ) {
+    domains.add("config");
+  }
+
+  if (normalizedKind === "resource_entry" || pathHasExtension(pathValue, RESOURCE_LIKE_EXTENSIONS)) {
+    domains.add("resource");
+    domains.add("config");
+  }
+
+  if (normalizedKind === "setting_entry" || pathHasExtension(pathValue, SETTINGS_LIKE_EXTENSIONS)) {
+    domains.add("settings");
+    domains.add("config");
+  }
+
+  if (normalizedType === "project") {
+    domains.add("project");
+  }
+
+  if (
+    !domains.has("sql") &&
+    !domains.has("config") &&
+    !domains.has("resource") &&
+    !domains.has("settings") &&
+    (normalizedType === "file" || normalizedType === "chunk" || normalizedType === "module")
+  ) {
+    domains.add("code");
+  }
+
+  return [...domains];
+}
+
+export function impactProfileBoost(
+  profile: NonNullable<ImpactParams["profile"]>,
+  domains: string[],
+  pathEdges: JsonObject[]
+): number {
+  const relationTypes = new Set(pathEdges.map((edge) => String(edge.relation ?? "")));
+  const hasSqlPath = relationTypes.has("CALLS_SQL");
+  const hasConfigKeyPath =
+    relationTypes.has("USES_CONFIG_KEY") ||
+    relationTypes.has("USES_RESOURCE_KEY") ||
+    relationTypes.has("USES_SETTING_KEY") ||
+    relationTypes.has("USES_CONFIG");
+
+  let boost = 0;
+
+  if (profile === "config_to_sql") {
+    if (domains.includes("sql")) {
+      boost += 0.18;
+    }
+    if (domains.includes("config")) {
+      boost += 0.04;
+    }
+    if (hasSqlPath) {
+      boost += 0.08;
+    }
+    if (hasConfigKeyPath && hasSqlPath) {
+      boost += 0.08;
+    }
+  } else if (profile === "config_only") {
+    if (domains.includes("config")) {
+      boost += 0.08;
+    }
+    if (!hasSqlPath && !relationTypes.has("CALLS")) {
+      boost += 0.04;
+    }
+  } else if (profile === "sql_only") {
+    if (domains.includes("sql")) {
+      boost += 0.14;
+    }
+    if (hasSqlPath) {
+      boost += 0.08;
+    }
+  } else if (profile === "code_only") {
+    if (domains.includes("code")) {
+      boost += 0.08;
+    }
+    if (relationTypes.has("CALLS") || relationTypes.has("IMPORTS")) {
+      boost += 0.05;
+    }
+  } else if (domains.includes("sql") && hasSqlPath) {
+    boost += 0.04;
+  }
+
+  return Number(boost.toFixed(4));
+}
+
+export function impactNoteScore(
+  queryTokens: string[],
+  queryPhrase: string,
+  pathEdges: JsonObject[],
+  semanticScorer: (queryTokens: string[], queryPhrase: string, text: string) => number
+): number {
+  if (pathEdges.length === 0 || (queryTokens.length === 0 && !queryPhrase)) {
+    return 0;
+  }
+
+  const noteText = pathEdges
+    .map((edge) => String(edge.note ?? "").trim())
+    .filter(Boolean)
+    .join("\n");
+  if (!noteText) {
+    return 0;
+  }
+
+  return Number(semanticScorer(queryTokens, queryPhrase, noteText).toFixed(4));
+}

package/scaffold/mcp/src/impactResponse.ts

@@ -0,0 +1,47 @@
+import type { ImpactParams, RelationType, ToolPayload } from "./types.js";
+
+export function buildImpactResponseMeta(params: {
+  parsed: ImpactParams;
+  responsePreset: "full" | "compact" | "minimal";
+  includeScores: boolean;
+  includeReasons: boolean;
+  verbosePaths: boolean;
+  maxPathHopsShown: number;
+  profile: NonNullable<ImpactParams["profile"]>;
+  sortBy: NonNullable<ImpactParams["sort_by"]>;
+  allowedRelationTypes: Set<RelationType>;
+  contextSource: string;
+}): ToolPayload {
+  return {
+    entity_id: params.parsed.entity_id,
+    query: params.parsed.query,
+    depth: params.parsed.depth,
+    top_k: params.parsed.top_k,
+    response_preset: params.responsePreset,
+    include_scores: params.includeScores,
+    include_reasons: params.includeReasons,
+    verbose_paths: params.verbosePaths,
+    max_path_hops_shown: params.maxPathHopsShown,
+    profile: params.profile,
+    sort_by: params.sortBy,
+    relation_types: [...params.allowedRelationTypes],
+    path_must_include: params.parsed.path_must_include ?? [],
+    path_must_exclude: params.parsed.path_must_exclude ?? [],
+    result_domains: params.parsed.result_domains ?? [],
+    result_entity_types: params.parsed.result_entity_types ?? [],
+    context_source: params.contextSource
+  };
+}
+
+export function buildEmptyImpactResponse(params: {
+  meta: ToolPayload;
+  warning: string;
+}): ToolPayload {
+  return {
+    ...params.meta,
+    warning: params.warning,
+    seed: null,
+    results: [],
+    edges: []
+  };
+}

package/scaffold/mcp/src/impactResults.ts

@@ -0,0 +1,173 @@
+import {
+  buildCompactImpactSummary,
+  buildImpactPath,
+  buildImpactTopReasons,
+  buildImpactWhy
+} from "./impactPresentation.js";
+import type { ImpactTraversalStep } from "./impactPresentation.js";
+import {
+  impactBaseScore,
+  impactDomainsForEntity,
+  impactNoteScore,
+  impactProfileBoost,
+  impactResultComparator
+} from "./impactRanking.js";
+import type { ImpactParams, JsonObject, SearchEntity } from "./types.js";
+
+function normalizeText(value: string): string {
+  return value.normalize("NFKC").toLowerCase();
+}
+
+function matchesImpactFilters(
+  result: Record<string, unknown>,
+  resultDomains: Set<string> | null,
+  resultEntityTypes: Set<string> | null,
+  pathMustInclude: Set<string> | null,
+  pathMustExclude: Set<string> | null
+): boolean {
+  const pathRelationTypes = new Set(
+    ((result.path_relation_types as string[] | undefined) ?? []).map((relation) => normalizeText(String(relation)))
+  );
+  if (pathMustInclude && pathMustInclude.size > 0) {
+    for (const requiredRelation of pathMustInclude) {
+      if (!pathRelationTypes.has(requiredRelation)) {
+        return false;
+      }
+    }
+  }
+  if (pathMustExclude && pathMustExclude.size > 0) {
+    for (const blockedRelation of pathMustExclude) {
+      if (pathRelationTypes.has(blockedRelation)) {
+        return false;
+      }
+    }
+  }
+  if (!resultDomains || resultDomains.size === 0) {
+    return !resultEntityTypes || resultEntityTypes.has(normalizeText(String(result.entity_type ?? "")));
+  }
+  const impactDomains = Array.isArray(result.impact_domains) ? result.impact_domains : [];
+  const matchesDomain = impactDomains.some((domain) => resultDomains.has(normalizeText(String(domain))));
+  if (!matchesDomain) {
+    return false;
+  }
+  return !resultEntityTypes || resultEntityTypes.has(normalizeText(String(result.entity_type ?? "")));
+}
+
+export function buildImpactResults(params: {
+  visited: Map<string, ImpactTraversalStep>;
+  seedId: string;
+  catalog: Map<string, JsonObject>;
+  searchEntities: Map<string, SearchEntity>;
+  degreeByEntity: Map<string, number>;
+  queryTokens: string[];
+  queryPhrase: string;
+  hasQuery: boolean;
+  profile: NonNullable<ImpactParams["profile"]>;
+  includeReasons: boolean;
+  includeScores: boolean;
+  verbosePaths: boolean;
+  maxPathHopsShown: number;
+  resultDomains: Set<string> | null;
+  resultEntityTypes: Set<string> | null;
+  pathMustInclude: Set<string> | null;
+  pathMustExclude: Set<string> | null;
+  sortBy: NonNullable<ImpactParams["sort_by"]>;
+  topK: number;
+  semanticScorer: (queryTokens: string[], queryPhrase: string, text: string) => number;
+}): Record<string, unknown>[] {
+  return [...params.visited.entries()]
+    .filter(([id]) => id !== params.seedId)
+    .map(([id, metadata]) => {
+      const entity = params.searchEntities.get(id);
+      const catalogEntry = params.catalog.get(id) ?? {
+        id,
+        type: "Unknown",
+        label: id,
+        status: "unknown",
+        source_of_truth: false
+      };
+      const semantic =
+        entity && params.hasQuery ? params.semanticScorer(params.queryTokens, params.queryPhrase, entity.text) : 0;
+      const graphScore = Math.min(1, (params.degreeByEntity.get(id) ?? 0) / 4);
+      const trustScore = entity ? Math.max(0, Math.min(1, entity.trust_level / 100)) : 0.5;
+      const impactPath = buildImpactPath(id, params.seedId, params.visited, params.catalog, params.searchEntities);
+      const impactDomains = impactDomainsForEntity(entity, catalogEntry);
+      const profileScore = impactProfileBoost(params.profile, impactDomains, impactPath.edges);
+      const noteScore = impactNoteScore(
+        params.queryTokens,
+        params.queryPhrase,
+        impactPath.edges,
+        params.semanticScorer
+      );
+      const impactScore = Number(
+        (impactBaseScore(metadata.hops, graphScore, trustScore, semantic) + profileScore + noteScore * 0.12).toFixed(4)
+      );
+      const topReasons = buildImpactTopReasons({
+        hops: metadata.hops,
+        profile: params.profile,
+        semanticScore: semantic,
+        noteScore,
+        profileScore,
+        impactDomains,
+        pathEdges: impactPath.edges
+      });
+
+      return {
+        id,
+        entity_type: entity?.entity_type ?? String(catalogEntry.type ?? "Unknown"),
+        kind: entity?.kind ?? "",
+        title: entity?.label ?? String(catalogEntry.label ?? id),
+        path: entity?.path || catalogEntry.path || undefined,
+        hops: metadata.hops,
+        via_relation: metadata.via_relation,
+        direction: metadata.direction,
+        via_entity: metadata.via_entity,
+        impact_domains: impactDomains,
+        why: buildImpactWhy(params.seedId, id, impactPath.edges, metadata.hops, params.catalog, params.searchEntities),
+        path_summary: impactPath.summary,
+        path_summary_compact: buildCompactImpactSummary(
+          impactPath.entities,
+          impactPath.edges,
+          params.catalog,
+          params.searchEntities,
+          params.maxPathHopsShown
+        ),
+        path_relation_types: impactPath.edges.map((edge) => String(edge.relation ?? "")),
+        excerpt: entity?.snippet ?? "",
+        status: entity?.status ?? String(catalogEntry.status ?? "unknown"),
+        source_of_truth: entity?.source_of_truth ?? Boolean(catalogEntry.source_of_truth),
+        ...(params.includeReasons
+          ? {
+              top_reasons: topReasons
+            }
+          : {}),
+        ...(params.includeScores
+          ? {
+              impact_score: impactScore,
+              profile_score: profileScore,
+              note_score: noteScore,
+              semantic_score: Number(semantic.toFixed(4)),
+              graph_score: Number(graphScore.toFixed(4)),
+              trust_score: Number(trustScore.toFixed(4))
+            }
+          : {}),
+        ...(params.verbosePaths
+          ? {
+              path_entities: impactPath.entities,
+              path_edges: impactPath.edges
+            }
+          : {})
+      };
+    })
+    .filter((result) =>
+      matchesImpactFilters(
+        result,
+        params.resultDomains,
+        params.resultEntityTypes,
+        params.pathMustInclude,
+        params.pathMustExclude
+      )
+    )
+    .sort(impactResultComparator(params.sortBy))
+    .slice(0, params.topK);
+}

package/scaffold/mcp/src/impactSeed.ts

@@ -0,0 +1,33 @@
+import type { ImpactParams, JsonObject, ToolPayload } from "./types.js";
+
+export async function resolveImpactSeed(
+  parsed: ImpactParams,
+  runSearch: (params: {
+    query: string;
+    top_k: number;
+    include_deprecated: boolean;
+    include_content: boolean;
+  }) => Promise<ToolPayload>
+): Promise<{ id: string | null; query_results?: JsonObject[]; warning?: string }> {
+  if (parsed.entity_id) {
+    return { id: parsed.entity_id };
+  }
+
+  if (!parsed.query) {
+    return { id: null, warning: "Either entity_id or query is required." };
+  }
+
+  const searchPayload = await runSearch({
+    query: parsed.query,
+    top_k: Math.max(parsed.top_k, 5),
+    include_deprecated: false,
+    include_content: false
+  });
+  const rawResults = Array.isArray(searchPayload.results) ? searchPayload.results : [];
+  const firstResult = rawResults[0];
+
+  return {
+    id: typeof firstResult?.id === "string" ? firstResult.id : null,
+    query_results: rawResults as JsonObject[]
+  };
+}