@danielblomma/cortex-mcp 2.4.0 → 2.4.2

package/scaffold/mcp/dist/searchResults.js

@@ -0,0 +1,230 @@
+function isWindowChunkId(id) {
+    return id.includes(":window:");
+}
+function baseChunkId(id) {
+    const markerIndex = id.indexOf(":window:");
+    return markerIndex === -1 ? id : id.slice(0, markerIndex);
+}
+function baseChunkLabel(label) {
+    const markerIndex = label.indexOf("#window");
+    return markerIndex === -1 ? label : label.slice(0, markerIndex);
+}
+export function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function rankedResultKey(ranked) {
+    return `${String(ranked.result.id ?? "")}\u0000${String(ranked.result.path ?? "")}`;
+}
+function compareRankedResults(a, b) {
+    return b.rankScore - a.rankScore || compareText(rankedResultKey(a), rankedResultKey(b));
+}
+function pruneRankedResults(bestById, limit) {
+    if (bestById.size <= limit) {
+        return;
+    }
+    const retained = [...bestById.entries()]
+        .sort(([, a], [, b]) => compareRankedResults(a, b))
+        .slice(0, limit);
+    bestById.clear();
+    for (const [id, result] of retained) {
+        bestById.set(id, result);
+    }
+}
+function secondarySignalScale(semantic) {
+    return Math.min(1, 0.15 + Math.max(0, semantic) * 0.85);
+}
+function isTestEvidenceEntity(entity) {
+    return /(^|\/)(tests?|__tests__)\//u.test(entity.path) || /\.(test|spec)\.[^.]+$/u.test(entity.path);
+}
+function testEvidenceBoost(entity, semantic, lexicalSemantic) {
+    if (!isTestEvidenceEntity(entity)) {
+        return 0;
+    }
+    if (semantic >= 0.5 && lexicalSemantic >= 0.4) {
+        return 0.07;
+    }
+    if (semantic >= 0.4 && lexicalSemantic >= 0.25) {
+        return 0.04;
+    }
+    return 0;
+}
+function resultPathKey(result) {
+    const path = typeof result.path === "string" ? result.path : "";
+    return path || String(result.id ?? "");
+}
+function selectDiverseResults(rankedResults, topK) {
+    const remaining = rankedResults
+        .map((ranked) => ({ ranked }))
+        .sort((a, b) => compareRankedResults(a.ranked, b.ranked));
+    const selected = [];
+    const selectedByPath = new Map();
+    while (selected.length < topK && remaining.length > 0) {
+        let bestIndex = 0;
+        let bestAdjustedScore = Number.NEGATIVE_INFINITY;
+        let bestRankScore = Number.NEGATIVE_INFINITY;
+        let bestKey = "";
+        for (let index = 0; index < remaining.length; index += 1) {
+            const candidate = remaining[index].ranked;
+            const pathCount = selectedByPath.get(resultPathKey(candidate.result)) ?? 0;
+            const samePathPenalty = pathCount === 0 ? 0 : Math.min(0.12, pathCount * 0.04);
+            const adjustedScore = candidate.rankScore - samePathPenalty;
+            const candidateKey = rankedResultKey(candidate);
+            if (adjustedScore > bestAdjustedScore ||
+                (adjustedScore === bestAdjustedScore && candidate.rankScore > bestRankScore) ||
+                (adjustedScore === bestAdjustedScore && candidate.rankScore === bestRankScore && candidateKey < bestKey)) {
+                bestIndex = index;
+                bestAdjustedScore = adjustedScore;
+                bestRankScore = candidate.rankScore;
+                bestKey = candidateKey;
+            }
+        }
+        const [picked] = remaining.splice(bestIndex, 1);
+        selected.push(picked.ranked);
+        const pathKey = resultPathKey(picked.ranked.result);
+        selectedByPath.set(pathKey, (selectedByPath.get(pathKey) ?? 0) + 1);
+    }
+    return selected;
+}
+function candidatesFrom(source) {
+    return typeof source === "function" ? source() : source;
+}
+export function buildSearchResultsWithStats(params) {
+    if (params.topK <= 0) {
+        return { results: [], totalCandidates: 0 };
+    }
+    // Graph score = midrank percentile of relation degree within the entity's
+    // own type. The previous min(1, degree/4) saturated at degree >= 4, which
+    // nearly every entity exceeds, making the graph weight a constant. Per-type
+    // percentiles discriminate by connectivity while staying type-neutral
+    // (every type averages ~0.5), so hub-heavy types like rules cannot drown
+    // out leaf code files or doc sections.
+    const sortedDegreesByType = new Map();
+    const chunkCandidatesById = new Map();
+    let totalCandidates = 0;
+    for (const entity of candidatesFrom(params.candidates)) {
+        totalCandidates += 1;
+        const degree = params.degreeByEntity.get(entity.id) ?? 0;
+        const list = sortedDegreesByType.get(entity.entity_type);
+        if (list) {
+            list.push(degree);
+        }
+        else {
+            sortedDegreesByType.set(entity.entity_type, [degree]);
+        }
+        if (entity.entity_type === "Chunk" && !isWindowChunkId(entity.id)) {
+            chunkCandidatesById.set(entity.id, {
+                label: entity.label,
+                path: entity.path
+            });
+        }
+    }
+    for (const list of sortedDegreesByType.values()) {
+        list.sort((a, b) => a - b);
+    }
+    const midrankPercentile = (sorted, value) => {
+        let lo = 0;
+        let hi = sorted.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (sorted[mid] < value)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        let upper = lo;
+        while (upper < sorted.length && sorted[upper] === value)
+            upper += 1;
+        return sorted.length > 0 ? (lo + upper) / (2 * sorted.length) : 0;
+    };
+    const resultLimit = Math.max(1, params.topK);
+    const diversityPoolLimit = Math.max(resultLimit * 3, resultLimit);
+    const pruneThreshold = Math.max(diversityPoolLimit * 2, 64);
+    const bestById = new Map();
+    for (const entity of candidatesFrom(params.candidates)) {
+        const lexicalSemantic = params.semanticScorer(params.queryTokens, params.queryPhrase, entity.text);
+        const entityVector = params.embeddingVectors.get(entity.id);
+        const vectorSemantic = params.queryVector && entityVector
+            ? Math.max(0, Math.min(1, params.vectorScorer(params.queryVector, entityVector)))
+            : 0;
+        const hasRelevanceSignal = lexicalSemantic >= params.minLexicalRelevance || vectorSemantic >= params.minVectorRelevance;
+        if (!hasRelevanceSignal) {
+            continue;
+        }
+        const semantic = vectorSemantic > 0 ? vectorSemantic * 0.75 + lexicalSemantic * 0.25 : lexicalSemantic;
+        const degree = params.degreeByEntity.get(entity.id) ?? 0;
+        const graphScore = midrankPercentile(sortedDegreesByType.get(entity.entity_type) ?? [], degree);
+        const trustScore = Math.max(0, Math.min(1, entity.trust_level / 100));
+        const dateScore = params.recencyScorer(entity.updated_at);
+        const structuralBoost = params.structuralSearchBooster?.(entity, params.queryTokens, params.queryPhrase) ?? 0;
+        const evidenceBoost = testEvidenceBoost(entity, semantic, lexicalSemantic);
+        const secondaryScale = secondarySignalScale(Math.max(semantic, structuralBoost));
+        let score = 0;
+        score += params.ranking.semantic * semantic;
+        score += params.ranking.graph * graphScore * secondaryScale;
+        score += params.ranking.trust * trustScore * secondaryScale;
+        score += params.ranking.recency * dateScore * secondaryScale;
+        score += structuralBoost;
+        score += evidenceBoost;
+        score += params.legacyDataAccessBooster(entity, params.queryTokens, params.queryPhrase);
+        if (entity.source_of_truth) {
+            score += 0.1 * semantic;
+        }
+        const result = {
+            id: entity.id,
+            entity_type: entity.entity_type,
+            kind: entity.kind,
+            title: entity.label,
+            path: entity.path || undefined,
+            source_of_truth: entity.source_of_truth,
+            status: entity.status,
+            updated_at: entity.updated_at,
+            excerpt: entity.snippet,
+            ...(params.includeScores
+                ? {
+                    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))
+                }
+                : {}),
+            ...(params.includeMatchedRules
+                ? {
+                    matched_rules: entity.matched_rules
+                }
+                : {}),
+            ...(params.includeContent
+                ? {
+                    content: entity.content
+                }
+                : {})
+        };
+        if (entity.entity_type === "Chunk" && isWindowChunkId(entity.id)) {
+            const canonicalId = baseChunkId(entity.id);
+            const baseChunk = chunkCandidatesById.get(canonicalId);
+            if (baseChunk) {
+                result.id = canonicalId;
+                result.title = baseChunkLabel(baseChunk.label);
+                result.path = baseChunk.path || undefined;
+            }
+        }
+        const resultId = String(result.id);
+        const existing = bestById.get(resultId);
+        if (!existing || score > existing.rankScore) {
+            bestById.set(resultId, { result, rankScore: score });
+        }
+        if (bestById.size > pruneThreshold) {
+            pruneRankedResults(bestById, diversityPoolLimit);
+        }
+    }
+    const rankedResults = [...bestById.values()]
+        .sort(compareRankedResults)
+        .slice(0, diversityPoolLimit);
+    const results = selectDiverseResults(rankedResults, params.topK)
+        .sort(compareRankedResults)
+        .map((ranked) => ranked.result);
+    return { results, totalCandidates };
+}
+export function buildSearchResults(params) {
+    return buildSearchResultsWithStats(params).results;
+}

package/scaffold/mcp/dist/server.js

@@ -0,0 +1,317 @@
+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 { runContextRules } from "./rules.js";
+import { runContextImpact, runContextRelated, runContextSearch } from "./search.js";
+import { getToolCallHook, getToolEventHook, getSessionEndHook, getSessionEventHook, loadPlugins, } from "./plugin.js";
+const ESTIMATED_TOKENS_SAVED_PER_RESULT = 400;
+const MAX_SESSION_CALLS = 1000;
+const SHUTDOWN_TIMEOUT_MS = 3000;
+const sessionCalls = [];
+const sessionStartedAt = Date.now();
+let successfulToolCalls = 0;
+let failedToolCalls = 0;
+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),
+    response_preset: z.enum(["full", "compact", "minimal"]).optional(),
+    include_scores: z.boolean().optional(),
+    include_matched_rules: z.boolean().optional(),
+    include_content: z.boolean().optional()
+});
+const RelatedInput = z.object({
+    entity_id: z.string().min(1),
+    depth: z.number().int().positive().max(3).default(1),
+    include_edges: z.boolean().optional(),
+    response_preset: z.enum(["full", "compact", "minimal"]).optional(),
+    include_entity_metadata: z.boolean().optional()
+});
+const ImpactInput = z
+    .object({
+    entity_id: z.string().min(1).optional(),
+    query: z.string().min(1).optional(),
+    depth: z.number().int().positive().max(4).default(2),
+    top_k: z.number().int().positive().max(20).default(8),
+    include_edges: z.boolean().default(true),
+    response_preset: z.enum(["full", "compact", "minimal"]).optional(),
+    include_scores: z.boolean().optional(),
+    include_reasons: z.boolean().optional(),
+    verbose_paths: z.boolean().optional(),
+    max_path_hops_shown: z.number().int().positive().max(8).optional(),
+    profile: z.enum(["all", "config_only", "config_to_sql", "code_only", "sql_only"]).default("all"),
+    sort_by: z
+        .enum(["impact_score", "shortest_path", "semantic_score", "graph_score", "trust_score"])
+        .default("impact_score"),
+    relation_types: z
+        .array(z.enum([
+        "CALLS",
+        "CALLS_SQL",
+        "IMPORTS",
+        "USES_CONFIG_KEY",
+        "USES_RESOURCE_KEY",
+        "USES_SETTING_KEY",
+        "USES_CONFIG",
+        "TRANSFORMS_CONFIG",
+        "PART_OF"
+    ]))
+        .max(9)
+        .optional(),
+    path_must_include: z
+        .array(z.enum([
+        "CALLS",
+        "CALLS_SQL",
+        "IMPORTS",
+        "USES_CONFIG_KEY",
+        "USES_RESOURCE_KEY",
+        "USES_SETTING_KEY",
+        "USES_CONFIG",
+        "TRANSFORMS_CONFIG",
+        "PART_OF"
+    ]))
+        .max(9)
+        .optional(),
+    path_must_exclude: z
+        .array(z.enum([
+        "CALLS",
+        "CALLS_SQL",
+        "IMPORTS",
+        "USES_CONFIG_KEY",
+        "USES_RESOURCE_KEY",
+        "USES_SETTING_KEY",
+        "USES_CONFIG",
+        "TRANSFORMS_CONFIG",
+        "PART_OF"
+    ]))
+        .max(9)
+        .optional(),
+    result_domains: z
+        .array(z.enum(["code", "config", "resource", "settings", "sql", "project"]))
+        .max(6)
+        .optional(),
+    result_entity_types: z
+        .array(z.enum(["File", "Chunk", "Module", "Project", "ADR", "Rule"]))
+        .max(6)
+        .optional()
+})
+    .refine((value) => Boolean(value.entity_id || value.query), {
+    message: "Either entity_id or query is required."
+});
+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) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2)
+            }
+        ],
+        structuredContent: data
+    };
+}
+function extractQuery(input) {
+    if (input && typeof input === "object" && "query" in input) {
+        const q = input.query;
+        if (typeof q === "string")
+            return q;
+    }
+    return undefined;
+}
+function notifyToolStart(toolName, input) {
+    const timestamp = new Date().toISOString();
+    const eventHook = getToolEventHook();
+    if (eventHook) {
+        const query = extractQuery(input);
+        void eventHook({
+            phase: "start",
+            tool: toolName,
+            timestamp,
+            input: (input ?? {}),
+            query,
+            query_length: query?.length,
+        });
+    }
+    return timestamp;
+}
+function notifyToolCall(toolName, input, result, durationMs, startedAtIso) {
+    const resultCount = Array.isArray(result.results)
+        ? (result.results).length
+        : 0;
+    const query = extractQuery(input);
+    if (sessionCalls.length < MAX_SESSION_CALLS) {
+        sessionCalls.push({
+            tool: toolName,
+            query,
+            resultCount,
+            time: startedAtIso,
+            outcome: "success",
+            duration_ms: durationMs,
+        });
+    }
+    successfulToolCalls++;
+    const eventHook = getToolEventHook();
+    const hook = getToolCallHook();
+    if (!eventHook && hook) {
+        hook(toolName, resultCount, resultCount * ESTIMATED_TOKENS_SAVED_PER_RESULT);
+    }
+    if (eventHook) {
+        void eventHook({
+            phase: "success",
+            tool: toolName,
+            timestamp: new Date().toISOString(),
+            input: (input ?? {}),
+            query,
+            query_length: query?.length,
+            result_count: resultCount,
+            estimated_tokens_saved: resultCount * ESTIMATED_TOKENS_SAVED_PER_RESULT,
+            duration_ms: durationMs,
+        });
+    }
+}
+function notifyToolError(toolName, input, error, durationMs, startedAtIso) {
+    const query = extractQuery(input);
+    if (sessionCalls.length < MAX_SESSION_CALLS) {
+        sessionCalls.push({
+            tool: toolName,
+            query,
+            resultCount: 0,
+            time: startedAtIso,
+            outcome: "error",
+            duration_ms: durationMs,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    failedToolCalls++;
+    const eventHook = getToolEventHook();
+    if (eventHook) {
+        void eventHook({
+            phase: "error",
+            tool: toolName,
+            timestamp: new Date().toISOString(),
+            input: (input ?? {}),
+            query,
+            query_length: query?.length,
+            duration_ms: durationMs,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+async function executeInstrumentedTool(toolName, input, run) {
+    const startedAt = Date.now();
+    const startedAtIso = notifyToolStart(toolName, input);
+    try {
+        const result = await run();
+        notifyToolCall(toolName, input, result, Date.now() - startedAt, startedAtIso);
+        return buildToolResult(result);
+    }
+    catch (error) {
+        notifyToolError(toolName, input, error, Date.now() - startedAt, startedAtIso);
+        throw error;
+    }
+}
+function registerTools(server) {
+    server.registerTool("context.search", {
+        description: "Search ranked context documents and code using semantic, graph and trust weighting.",
+        inputSchema: SearchInput
+    }, async (input) => executeInstrumentedTool("context.search", input, async () => 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) => executeInstrumentedTool("context.get_related", input, async () => runContextRelated(RelatedInput.parse(input ?? {}))));
+    server.registerTool("context.impact", {
+        description: "Traverse likely impact paths across config, code and SQL starting from an entity id or query.",
+        inputSchema: ImpactInput
+    }, async (input) => executeInstrumentedTool("context.impact", input, async () => runContextImpact(ImpactInput.parse(input ?? {}))));
+    server.registerTool("context.get_rules", {
+        description: "List indexed rules filtered by scope and active status.",
+        inputSchema: RulesInput.optional()
+    }, async (input) => executeInstrumentedTool("context.get_rules", input, async () => runContextRules(RulesInput.parse(input ?? {}))));
+    server.registerTool("context.reload", {
+        description: "Reload RyuGraph connection after graph updates or maintenance.",
+        inputSchema: ReloadInput.optional()
+    }, async (input) => executeInstrumentedTool("context.reload", input, async () => {
+        const parsed = ReloadInput.parse(input ?? {});
+        return reloadContextGraph(parsed.force);
+    }));
+    // Note: cortex.workflow.* tools (the Cortex Harness) are enterprise-only
+    // and registered by enterprise/index.ts::register() once the license has
+    // verified. They intentionally do not appear here so community-mode MCP
+    // servers do not surface them at all.
+}
+let shutdownCalled = false;
+async function onShutdown() {
+    if (shutdownCalled)
+        return;
+    shutdownCalled = true;
+    const sessionEventHook = getSessionEventHook();
+    if (sessionEventHook) {
+        try {
+            await Promise.race([
+                Promise.resolve(sessionEventHook({
+                    phase: "end",
+                    timestamp: new Date().toISOString(),
+                    duration_ms: Date.now() - sessionStartedAt,
+                    tool_calls: sessionCalls.length,
+                    successful_tool_calls: successfulToolCalls,
+                    failed_tool_calls: failedToolCalls,
+                    calls: [...sessionCalls],
+                })),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("session event hook timeout")), SHUTDOWN_TIMEOUT_MS))
+            ]);
+        }
+        catch {
+            // Best effort — don't block shutdown
+        }
+    }
+    const hook = getSessionEndHook();
+    if (hook) {
+        try {
+            await Promise.race([
+                hook([...sessionCalls]),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("shutdown hook timeout")), SHUTDOWN_TIMEOUT_MS))
+            ]);
+        }
+        catch {
+            // Best effort — don't block shutdown
+        }
+    }
+}
+async function main() {
+    const server = new McpServer({
+        name: "cortex-context",
+        version: "0.1.0"
+    });
+    registerTools(server);
+    // v2.0.0: load enterprise plugin in-process if .context/enterprise.yml
+    // is present and license validates. Community-mode is a no-op.
+    await loadPlugins(server);
+    // Notify session start to enterprise (if active).
+    const sessionEventHook = getSessionEventHook();
+    if (sessionEventHook) {
+        void sessionEventHook({
+            phase: "start",
+            timestamp: new Date(sessionStartedAt).toISOString(),
+        });
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const cleanup = () => {
+        void onShutdown().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    process.on("beforeExit", () => {
+        void onShutdown();
+    });
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : "Fatal error"}\n`);
+    process.exit(1);
+});

package/scaffold/mcp/dist/types.js

@@ -0,0 +1 @@
+export {};