@danielblomma/cortex-mcp 2.4.0 → 2.4.1

package/scaffold/mcp/dist/lruCache.js

@@ -0,0 +1,38 @@
+/**
+ * Minimal LRU cache on Map insertion order: reads refresh recency, writes
+ * evict the least-recently-used entry once capacity is reached.
+ */
+export class LruCache {
+    capacity;
+    entries = new Map();
+    constructor(capacity) {
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new Error(`LruCache capacity must be a positive integer, got ${capacity}`);
+        }
+        this.capacity = capacity;
+    }
+    get(key) {
+        if (!this.entries.has(key)) {
+            return undefined;
+        }
+        const value = this.entries.get(key);
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        if (this.entries.has(key)) {
+            this.entries.delete(key);
+        }
+        else if (this.entries.size >= this.capacity) {
+            const oldest = this.entries.keys().next();
+            if (!oldest.done) {
+                this.entries.delete(oldest.value);
+            }
+        }
+        this.entries.set(key, value);
+    }
+    get size() {
+        return this.entries.size;
+    }
+}

package/scaffold/mcp/dist/paths.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function normalizeForWsl(rawPath) {
+    const winMatch = rawPath.match(/^([A-Za-z]):[/\\](.*)/);
+    if (!winMatch)
+        return rawPath;
+    try {
+        const version = fs.readFileSync("/proc/version", "utf8");
+        if (!/microsoft|wsl/i.test(version))
+            return rawPath;
+    }
+    catch {
+        return rawPath;
+    }
+    const drive = winMatch[1].toLowerCase();
+    const rest = winMatch[2].replace(/\\/g, "/").replace(/\/+$/, "");
+    return `/mnt/${drive}/${rest}`;
+}
+const PROJECT_ROOT_OVERRIDE = process.env.CORTEX_PROJECT_ROOT?.trim();
+function hasContextConfig(candidate) {
+    return fs.existsSync(path.join(candidate, ".context", "config.yaml"));
+}
+function resolveFrom(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (hasContextConfig(current)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function resolveRepoRoot() {
+    const candidates = [
+        PROJECT_ROOT_OVERRIDE ? path.resolve(normalizeForWsl(PROJECT_ROOT_OVERRIDE)) : null,
+        process.cwd(),
+        __dirname,
+        process.env.INIT_CWD?.trim() ? path.resolve(normalizeForWsl(process.env.INIT_CWD.trim())) : null
+    ].filter((value) => Boolean(value));
+    for (const candidate of candidates) {
+        const resolved = resolveFrom(candidate);
+        if (resolved) {
+            return resolved;
+        }
+    }
+    return path.resolve(__dirname, "../../..");
+}
+export const REPO_ROOT = resolveRepoRoot();
+export const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
+export const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
+export const DB_PATH = path.join(CONTEXT_DIR, "db", "graph.ryu");
+export const PATHS = {
+    config: path.join(CONTEXT_DIR, "config.yaml"),
+    rulesYaml: path.join(CONTEXT_DIR, "rules.yaml"),
+    graphManifest: path.join(CACHE_DIR, "graph-manifest.json"),
+    embeddingsManifest: path.join(CONTEXT_DIR, "embeddings", "manifest.json"),
+    embeddingsEntities: path.join(CONTEXT_DIR, "embeddings", "entities.jsonl"),
+    embeddingsModelCache: path.join(CONTEXT_DIR, "embeddings", "models"),
+    documents: path.join(CACHE_DIR, "documents.jsonl"),
+    adrEntities: path.join(CACHE_DIR, "entities.adr.jsonl"),
+    ruleEntities: path.join(CACHE_DIR, "entities.rule.jsonl"),
+    chunkEntities: path.join(CACHE_DIR, "entities.chunk.jsonl"),
+    projectEntities: path.join(CACHE_DIR, "entities.project.jsonl"),
+    constrainsRelations: path.join(CACHE_DIR, "relations.constrains.jsonl"),
+    implementsRelations: path.join(CACHE_DIR, "relations.implements.jsonl"),
+    supersedesRelations: path.join(CACHE_DIR, "relations.supersedes.jsonl"),
+    callsRelations: path.join(CACHE_DIR, "relations.calls.jsonl"),
+    callsSqlRelations: path.join(CACHE_DIR, "relations.calls_sql.jsonl"),
+    usesConfigKeyRelations: path.join(CACHE_DIR, "relations.uses_config_key.jsonl"),
+    usesResourceKeyRelations: path.join(CACHE_DIR, "relations.uses_resource_key.jsonl"),
+    usesSettingKeyRelations: path.join(CACHE_DIR, "relations.uses_setting_key.jsonl"),
+    definesRelations: path.join(CACHE_DIR, "relations.defines.jsonl"),
+    importsRelations: path.join(CACHE_DIR, "relations.imports.jsonl"),
+    moduleEntities: path.join(CACHE_DIR, "entities.module.jsonl"),
+    containsRelations: path.join(CACHE_DIR, "relations.contains.jsonl"),
+    containsModuleRelations: path.join(CACHE_DIR, "relations.contains_module.jsonl"),
+    exportsRelations: path.join(CACHE_DIR, "relations.exports.jsonl"),
+    includesFileRelations: path.join(CACHE_DIR, "relations.includes_file.jsonl"),
+    referencesProjectRelations: path.join(CACHE_DIR, "relations.references_project.jsonl"),
+    usesResourceRelations: path.join(CACHE_DIR, "relations.uses_resource.jsonl"),
+    usesSettingRelations: path.join(CACHE_DIR, "relations.uses_setting.jsonl"),
+    usesConfigRelations: path.join(CACHE_DIR, "relations.uses_config.jsonl"),
+    transformsConfigRelations: path.join(CACHE_DIR, "relations.transforms_config.jsonl")
+};
+// Tuned together with the midrank-percentile graph_score in searchResults.ts.
+export const DEFAULT_RANKING = {
+    semantic: 0.4,
+    graph: 0.25,
+    trust: 0.2,
+    recency: 0.15
+};

package/scaffold/mcp/dist/patternEvidence.js

@@ -0,0 +1,272 @@
+import { loadContextData } from "./graph.js";
+import { iterateSearchEntities } from "./contextEntities.js";
+import { embedQuery, loadEmbeddingIndex } from "./embeddings.js";
+import { runContextSearch } from "./search.js";
+const EVIDENCE_TIERS = [
+    { name: "same_file", scope: "Same file as the review target." },
+    { name: "same_module", scope: "Same directory or module as the review target." },
+    { name: "same_feature_area", scope: "Same parent feature area as the review target." },
+    { name: "repo_wide", scope: "Repository-wide fallback evidence." },
+];
+export function normalizeRepoPath(value) {
+    const normalized = value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+    return normalized.replace(/\/{2,}/g, "/").replace(/\/$/, "");
+}
+function dirnameRepoPath(value) {
+    const normalized = normalizeRepoPath(value);
+    const separator = normalized.lastIndexOf("/");
+    return separator === -1 ? "." : normalized.slice(0, separator) || ".";
+}
+function parentRepoPath(value) {
+    const normalized = normalizeRepoPath(value);
+    if (!normalized || normalized === ".") {
+        return null;
+    }
+    const separator = normalized.lastIndexOf("/");
+    return separator === -1 ? "." : normalized.slice(0, separator) || ".";
+}
+function isWithinPath(candidate, directory) {
+    if (!directory || directory === ".") {
+        return false;
+    }
+    return candidate === directory || candidate.startsWith(`${directory}/`);
+}
+function resolvePatternTarget(data, input) {
+    const normalizedInput = normalizeRepoPath(input);
+    const document = data.documents.find((entry) => entry.id === input || normalizeRepoPath(entry.path) === normalizedInput);
+    if (document) {
+        return {
+            input,
+            entity_id: document.id,
+            entity_type: document.kind === "ADR" ? "ADR" : "File",
+            path: normalizeRepoPath(document.path),
+        };
+    }
+    const chunk = data.chunks.find((entry) => entry.id === input);
+    if (chunk) {
+        const owner = data.documents.find((entry) => entry.id === chunk.file_id);
+        if (!owner) {
+            throw new Error(`Pattern target chunk has no indexed owner file: ${input}`);
+        }
+        return {
+            input,
+            entity_id: chunk.id,
+            entity_type: "Chunk",
+            path: normalizeRepoPath(owner.path),
+        };
+    }
+    const adr = data.adrs.find((entry) => entry.id === input);
+    if (adr?.path) {
+        return {
+            input,
+            entity_id: adr.id,
+            entity_type: "ADR",
+            path: normalizeRepoPath(adr.path),
+        };
+    }
+    const knownEntity = [
+        ...data.rules.map((entry) => entry.id),
+        ...data.modules.map((entry) => entry.id),
+        ...data.projects.map((entry) => entry.id),
+    ].includes(input);
+    if (knownEntity) {
+        throw new Error(`Pattern target is not file-backed: ${input}`);
+    }
+    throw new Error(`Pattern target was not found in indexed context: ${input}`);
+}
+function derivePatternQuery(data, target) {
+    if (target.entity_type === "Chunk") {
+        const chunk = data.chunks.find((entry) => entry.id === target.entity_id);
+        if (chunk) {
+            return [chunk.name, chunk.kind, chunk.signature].filter(Boolean).join(" ");
+        }
+    }
+    const document = data.documents.find((entry) => entry.id === target.entity_id);
+    const chunkSignals = data.chunks
+        .filter((entry) => entry.file_id === target.entity_id && !entry.id.includes(":window:"))
+        .slice(0, 12)
+        .flatMap((entry) => [entry.name, entry.kind])
+        .filter(Boolean);
+    const basename = target.path.split("/").at(-1)?.replace(/\.[^.]+$/, "") ?? target.path;
+    return [basename, ...chunkSignals, document?.excerpt ?? ""].filter(Boolean).join(" ").slice(0, 1000);
+}
+function tierForPath(targetPath, candidatePath) {
+    const normalizedTarget = normalizeRepoPath(targetPath);
+    const normalizedCandidate = normalizeRepoPath(candidatePath);
+    if (normalizedCandidate === normalizedTarget) {
+        return "same_file";
+    }
+    const targetModule = dirnameRepoPath(normalizedTarget);
+    if (dirnameRepoPath(normalizedCandidate) === targetModule) {
+        return "same_module";
+    }
+    const featureArea = parentRepoPath(targetModule);
+    if (isWithinPath(normalizedCandidate, featureArea)) {
+        return "same_feature_area";
+    }
+    return "repo_wide";
+}
+function toPatternEvidence(result, chunksById) {
+    const id = typeof result.id === "string" ? result.id : "";
+    const candidatePath = typeof result.path === "string" ? normalizeRepoPath(result.path) : "";
+    if (!id || !candidatePath) {
+        return null;
+    }
+    const chunk = chunksById.get(id);
+    const entityType = typeof result.entity_type === "string" ? result.entity_type : "";
+    if (entityType === "Chunk" && (!chunk || chunk.start_line <= 0 || chunk.end_line < chunk.start_line)) {
+        return null;
+    }
+    const evidence = {
+        id,
+        entity_type: entityType,
+        kind: typeof result.kind === "string" ? result.kind : "",
+        title: typeof result.title === "string" ? result.title : id,
+        path: candidatePath,
+        excerpt: typeof result.excerpt === "string" ? result.excerpt : "",
+    };
+    if (chunk) {
+        evidence.start_line = chunk.start_line;
+        evidence.end_line = chunk.end_line;
+    }
+    if (typeof result.score === "number") {
+        evidence.score = result.score;
+    }
+    if (Array.isArray(result.matched_rules)) {
+        evidence.matched_rules = [...new Set(result.matched_rules)];
+    }
+    return evidence;
+}
+const referenceTimeCache = new WeakMap();
+export function contextReferenceTimeMs(data) {
+    const cached = referenceTimeCache.get(data);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let latest = 0;
+    const consider = (value) => {
+        const timestamp = Date.parse(value);
+        if (Number.isFinite(timestamp) && timestamp > latest) {
+            latest = timestamp;
+        }
+    };
+    for (const entry of data.documents)
+        consider(entry.updated_at);
+    for (const entry of data.rules)
+        consider(entry.updated_at);
+    for (const entry of data.adrs)
+        consider(entry.decision_date);
+    for (const entry of data.chunks)
+        consider(entry.updated_at);
+    for (const entry of data.modules)
+        consider(entry.updated_at);
+    for (const entry of data.projects)
+        consider(entry.updated_at);
+    referenceTimeCache.set(data, latest);
+    return latest;
+}
+export function classifyPatternEvidence(input) {
+    const chunksById = new Map(input.chunks.map((chunk) => [chunk.id, chunk]));
+    const evidenceByTier = new Map(EVIDENCE_TIERS.map((tier) => [tier.name, []]));
+    const seen = new Set();
+    for (const result of input.results) {
+        if (result.id === input.target.entity_id) {
+            continue;
+        }
+        const evidence = toPatternEvidence(result, chunksById);
+        if (!evidence || seen.has(evidence.id)) {
+            continue;
+        }
+        seen.add(evidence.id);
+        const tierName = tierForPath(input.target.path, evidence.path);
+        const tierEvidence = evidenceByTier.get(tierName);
+        if (tierEvidence && tierEvidence.length < input.topK) {
+            tierEvidence.push(evidence);
+        }
+    }
+    const tiers = EVIDENCE_TIERS.map((tier) => ({
+        ...tier,
+        evidence: evidenceByTier.get(tier.name) ?? [],
+    }));
+    const localPatternFound = tiers.slice(0, 3).some((tier) => tier.evidence.length > 0);
+    const fallbackUsed = !localPatternFound && tiers[3].evidence.length > 0;
+    return { tiers, localPatternFound, fallbackUsed };
+}
+export async function runPatternEvidence(parsed, options = {}) {
+    const data = options.data ?? await loadContextData();
+    const target = resolvePatternTarget(data, parsed.target);
+    const explicitQuery = parsed.query?.trim();
+    const query = explicitQuery || derivePatternQuery(data, target);
+    if (!query) {
+        throw new Error(`Could not derive a pattern query for target: ${parsed.target}`);
+    }
+    const referenceTimeMs = contextReferenceTimeMs(data);
+    const embeddingIndex = options.use_embeddings === false
+        ? { model: null, vectors: new Map() }
+        : loadEmbeddingIndex();
+    const queryVector = embeddingIndex.model && embeddingIndex.vectors.size > 0
+        ? await embedQuery(query, embeddingIndex.model)
+        : null;
+    const tierByEntityId = new Map();
+    for (const entity of iterateSearchEntities(data, false)) {
+        if (entity.id !== target.entity_id &&
+            entity.path &&
+            (entity.entity_type === "File" || entity.entity_type === "Chunk" || entity.entity_type === "ADR")) {
+            tierByEntityId.set(entity.id, tierForPath(target.path, entity.path));
+        }
+    }
+    const searchResults = [];
+    const warningParts = [];
+    let contextSource = data.source;
+    let semanticEngine;
+    for (const tier of EVIDENCE_TIERS) {
+        const search = await runContextSearch({
+            query,
+            top_k: parsed.top_k,
+            include_deprecated: parsed.include_deprecated ?? false,
+            response_preset: "full",
+            include_scores: true,
+            include_matched_rules: true,
+        }, {
+            data,
+            reference_time_ms: referenceTimeMs,
+            embedding_index: embeddingIndex,
+            query_vector: queryVector,
+            candidate_filter: (entity) => tierByEntityId.get(entity.id) === tier.name,
+        });
+        if (Array.isArray(search.results)) {
+            searchResults.push(...search.results);
+        }
+        if (typeof search.warning === "string" && !warningParts.includes(search.warning)) {
+            warningParts.push(search.warning);
+        }
+        contextSource = search.context_source ?? contextSource;
+        semanticEngine = search.semantic_engine ?? semanticEngine;
+    }
+    const classified = classifyPatternEvidence({
+        target,
+        results: searchResults,
+        chunks: data.chunks,
+        topK: parsed.top_k,
+    });
+    if (!classified.localPatternFound) {
+        warningParts.push("No applicable file-local, module-local, or feature-local pattern evidence was found.");
+    }
+    return {
+        target,
+        query,
+        query_source: explicitQuery ? "explicit" : "derived_from_target",
+        evidence_order: EVIDENCE_TIERS.map((tier) => tier.name),
+        top_k_per_tier: parsed.top_k,
+        ranking_reference_time: referenceTimeMs > 0 ? new Date(referenceTimeMs).toISOString() : null,
+        local_pattern_found: classified.localPatternFound,
+        fallback_used: classified.fallbackUsed,
+        tiers: classified.tiers,
+        context_source: contextSource,
+        semantic_engine: semanticEngine,
+        warning: warningParts.length > 0 ? warningParts.join(" | ") : undefined,
+    };
+}
+export async function runLocalPatternEvidence(parsed, options = {}) {
+    return runPatternEvidence(parsed, { ...options, use_embeddings: false });
+}

package/scaffold/mcp/dist/plugin.js

@@ -0,0 +1,81 @@
+let loadedEdition = { edition: "community" };
+let toolCallHook = null;
+let sessionEndHook = null;
+let toolEventHook = null;
+let sessionEventHook = null;
+export function getEdition() {
+    return loadedEdition;
+}
+export function getToolCallHook() {
+    return toolCallHook;
+}
+export function getSessionEndHook() {
+    return sessionEndHook;
+}
+export function getToolEventHook() {
+    return toolEventHook;
+}
+export function getSessionEventHook() {
+    return sessionEventHook;
+}
+export async function loadPlugins(server) {
+    // v2.0.0: enterprise is now in-process. We still gate registration on
+    // whether enterprise activation succeeds (license + config), so community
+    // users get a no-op when no api_key is present.
+    try {
+        const enterprise = await import("./enterprise/index.js");
+        const { resolveEnterpriseActivation, loadEnterpriseConfig } = await import("./core/config.js");
+        const path = await import("node:path");
+        const projectRoot = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+        const contextDir = path.join(projectRoot, ".context");
+        const config = loadEnterpriseConfig(contextDir);
+        const activation = resolveEnterpriseActivation(config);
+        if (!activation.active) {
+            // Community mode: no api_key or invalid config. Skip registration.
+            return;
+        }
+        // v2.0.0: validate license against cortex-web before activating.
+        // The verifier uses 24h cache + 7d grace period so transient endpoint
+        // outages don't degrade enterprise users immediately.
+        const { verifyLicense } = await import("./core/license.js");
+        const license = await verifyLicense(contextDir, config.enterprise.endpoint, config.enterprise.api_key, {
+            client_version: process.env.CORTEX_VERSION,
+        });
+        if (!license.valid) {
+            process.stderr.write(`[cortex] Enterprise inactive: license check failed (${license.reason}, source=${license.source})\n`);
+            return;
+        }
+        const [{ matchesEnterpriseHostIdentity }, { enterpriseCredentialId },] = await Promise.all([
+            import("./core/enterprise-host-identity.js"),
+            import("./core/license.js"),
+        ]);
+        if (!matchesEnterpriseHostIdentity(enterpriseCredentialId(config.enterprise.base_url || config.enterprise.endpoint, config.enterprise.api_key))) {
+            process.stderr.write("[cortex] Enterprise inactive: this user profile is enrolled to another endpoint or API key\n");
+            return;
+        }
+        if (typeof enterprise.register === "function") {
+            await enterprise.register(server);
+            loadedEdition = {
+                edition: "enterprise",
+                name: enterprise.name ?? "enterprise",
+                version: enterprise.version ?? "unknown",
+            };
+            if (typeof enterprise.onToolCall === "function") {
+                toolCallHook = enterprise.onToolCall;
+            }
+            if (typeof enterprise.onSessionEnd === "function") {
+                sessionEndHook = enterprise.onSessionEnd;
+            }
+            if (typeof enterprise.onToolEvent === "function") {
+                toolEventHook = enterprise.onToolEvent;
+            }
+            if (typeof enterprise.onSessionEvent === "function") {
+                sessionEventHook = enterprise.onSessionEvent;
+            }
+            process.stderr.write(`[cortex] Enterprise loaded: ${loadedEdition.version}\n`);
+        }
+    }
+    catch (error) {
+        process.stderr.write(`[cortex] Enterprise activation failed: ${error instanceof Error ? error.message : "unknown error"}\n`);
+    }
+}

package/scaffold/mcp/dist/presets.js

@@ -0,0 +1,78 @@
+function resolvePresetOptions(responsePreset, presetDefaultsByMode, explicitOverrides) {
+    const resolvedPreset = responsePreset ?? "full";
+    const presetDefaults = presetDefaultsByMode[resolvedPreset];
+    return {
+        responsePreset: resolvedPreset,
+        ...presetDefaults,
+        ...Object.fromEntries(Object.entries(explicitOverrides).filter(([, value]) => value !== undefined))
+    };
+}
+export function resolveImpactResponsePreset(parsed) {
+    return resolvePresetOptions(parsed.response_preset, {
+        full: {
+            includeScores: true,
+            includeReasons: true,
+            verbosePaths: true,
+            maxPathHopsShown: 2
+        },
+        compact: {
+            includeScores: false,
+            includeReasons: true,
+            verbosePaths: false,
+            maxPathHopsShown: 2
+        },
+        minimal: {
+            includeScores: false,
+            includeReasons: false,
+            verbosePaths: false,
+            maxPathHopsShown: 1
+        }
+    }, {
+        includeScores: parsed.include_scores,
+        includeReasons: parsed.include_reasons,
+        verbosePaths: parsed.verbose_paths,
+        maxPathHopsShown: parsed.max_path_hops_shown
+    });
+}
+export function resolveSearchResponsePreset(parsed) {
+    return resolvePresetOptions(parsed.response_preset, {
+        full: {
+            includeScores: true,
+            includeMatchedRules: true,
+            includeContent: false
+        },
+        compact: {
+            includeScores: false,
+            includeMatchedRules: true,
+            includeContent: false
+        },
+        minimal: {
+            includeScores: false,
+            includeMatchedRules: false,
+            includeContent: false
+        }
+    }, {
+        includeScores: parsed.include_scores,
+        includeMatchedRules: parsed.include_matched_rules,
+        includeContent: parsed.include_content
+    });
+}
+export function resolveRelatedResponsePreset(parsed) {
+    return resolvePresetOptions(parsed.response_preset, {
+        full: {
+            includeEdges: true,
+            includeEntityMetadata: true
+        },
+        compact: {
+            includeEdges: false,
+            includeEntityMetadata: true
+        },
+        minimal: {
+            includeEdges: false,
+            includeEntityMetadata: false
+        }
+    }, {
+        includeEdges: parsed.include_edges,
+        includeEntityMetadata: parsed.include_entity_metadata
+    });
+}

package/scaffold/mcp/dist/relatedResponse.js

@@ -0,0 +1,18 @@
+export function buildRelatedResponseMeta(params) {
+    return {
+        entity_id: params.parsed.entity_id,
+        depth: params.parsed.depth,
+        response_preset: params.responsePreset,
+        include_edges: params.includeEdges,
+        include_entity_metadata: params.includeEntityMetadata,
+        context_source: params.contextSource
+    };
+}
+export function buildEmptyRelatedResponse(params) {
+    return {
+        ...params.meta,
+        related: [],
+        edges: [],
+        warning: params.warning
+    };
+}

package/scaffold/mcp/dist/relatedTraversal.js

@@ -0,0 +1,78 @@
+export function traverseRelatedGraph(params) {
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const relation of params.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([params.entityId]);
+    const queue = [{ id: params.entityId, hop: 0 }];
+    const related = [];
+    const traversedEdges = [];
+    const traversedEdgeKeys = new Set();
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current.hop >= params.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 = params.catalog.get(target) ?? {
+                    id: target,
+                    type: "Unknown",
+                    label: target,
+                    status: "unknown",
+                    source_of_truth: false
+                };
+                related.push(params.includeEntityMetadata
+                    ? {
+                        ...entity,
+                        hops: current.hop + 1,
+                        via_relation: neighbor.edge.relation,
+                        direction: neighbor.direction
+                    }
+                    : {
+                        id: entity.id,
+                        type: entity.type,
+                        label: entity.label,
+                        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 {
+        related,
+        traversedEdges
+    };
+}

package/scaffold/mcp/dist/rules.js

@@ -0,0 +1,23 @@
+import { loadContextData } from "./graph.js";
+export async function runContextRules(parsed) {
+    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
+    };
+}