@opencodehub/mcp 0.1.0

package/dist/tools/api-impact.js

@@ -0,0 +1,199 @@
+/**
+ * `api_impact` — score the blast radius of changing a Route's contract.
+ *
+ * For every Route matching the filter (`route` substring, or `file`
+ * substring against Route.filePath) we compute:
+ *   - consumers           = files with outgoing FETCHES → this Route.
+ *   - middleware          = handlers reached via HANDLES_ROUTE (typically
+ *                           File ids; Operation ids when the OpenAPI
+ *                           phase linked a spec).
+ *   - mismatches          = consumer files whose accessed keys are not a
+ *                           subset of Route.responseKeys (delegated to
+ *                           `classifyShape` from shape-check).
+ *   - affectedProcesses   = Process nodes whose PROCESS_STEP edges walk
+ *                           through any of the consumer symbols.
+ *
+ * Risk banding (deterministic):
+ *   LOW      — 0 consumers and 0 mismatches.
+ *   MEDIUM   — 1-4 consumers, 0 mismatches.
+ *   HIGH     — 5-19 consumers OR any mismatch.
+ *   CRITICAL — ≥ 20 consumers.
+ */
+// biome-ignore-all lint/complexity/useLiteralKeys: dot-access disallowed on Record index signatures
+import { z } from "zod";
+import { toolErrorFromUnknown } from "../error-envelope.js";
+import { withNextSteps } from "../next-step-hints.js";
+import { stalenessFromMeta } from "../staleness.js";
+import { classifyShape } from "./shape-check.js";
+import { fromToolResult, repoArgShape, toToolResult, withStore, } from "./shared.js";
+const ApiImpactInput = {
+    ...repoArgShape,
+    route: z.string().optional().describe("Substring match against Route.url."),
+    file: z.string().optional().describe("Substring match against Route.filePath."),
+};
+export async function runApiImpact(ctx, args) {
+    const call = await withStore(ctx, args, async (store, resolved) => {
+        try {
+            const rows = await analyzeApiImpact(store.graph, args.route, args.file);
+            const header = `api_impact — ${rows.length} route(s) for ${resolved.name}${args.route ? ` · url~${args.route}` : ""}${args.file ? ` · filePath~${args.file}` : ""}:`;
+            const body = rows.length === 0
+                ? "(no routes matched — check the filter or re-index with `codehub analyze`)"
+                : rows
+                    .map((r) => `- [${r.risk}] ${r.route.method} ${r.route.url} consumers=${r.consumers.length} mismatches=${r.mismatches.length} processes=${r.affectedProcesses.length}`)
+                    .join("\n");
+            const highest = rows.reduce((acc, r) => worseRisk(acc, r.risk), "LOW");
+            const next = rows.length === 0
+                ? ["call `route_map` to list available routes"]
+                : highest === "CRITICAL" || highest === "HIGH"
+                    ? [
+                        `call \`shape_check\` with route="${rows[0]?.route.url ?? ""}" to see per-consumer mismatches`,
+                        `call \`context\` on a consumer file to plan migration`,
+                    ]
+                    : [
+                        "low blast radius — route change should be safe",
+                        "still verify with `shape_check` before merging",
+                    ];
+            return withNextSteps(`${header}\n${body}`, { routes: rows, highestRisk: highest }, next, stalenessFromMeta(resolved.meta));
+        }
+        catch (err) {
+            return toolErrorFromUnknown(err);
+        }
+    });
+    return toToolResult(call);
+}
+export function registerApiImpactTool(server, ctx) {
+    server.registerTool("api_impact", {
+        title: "Route change blast radius",
+        description: "Score the blast radius of changing a Route's contract. Returns risk (LOW/MEDIUM/HIGH/CRITICAL) plus the consumer files, middleware handlers, shape mismatches, and affected Process flows for every matching Route. Read-only.",
+        inputSchema: ApiImpactInput,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => fromToolResult(await runApiImpact(ctx, args)));
+}
+async function analyzeApiImpact(graph, routeFilter, fileFilter) {
+    const opts = { limit: 500 };
+    if (routeFilter !== undefined && routeFilter.length > 0)
+        opts.pathLike = routeFilter;
+    let routes = await graph.listRoutes(opts);
+    if (fileFilter !== undefined && fileFilter.length > 0) {
+        const sub = fileFilter;
+        routes = routes.filter((r) => r.filePath.includes(sub));
+    }
+    const sorted = [...routes].sort((a, b) => {
+        if (a.url !== b.url)
+            return a.url < b.url ? -1 : 1;
+        const am = a.method ?? "";
+        const bm = b.method ?? "";
+        return am < bm ? -1 : am > bm ? 1 : 0;
+    });
+    const out = [];
+    for (const r of sorted) {
+        const responseKeys = r.responseKeys ?? [];
+        const [consumerSymbolIds, handlers] = await Promise.all([
+            fetchFromIds(graph, r.id, "FETCHES"),
+            fetchFromIds(graph, r.id, "HANDLES_ROUTE"),
+        ]);
+        const consumerFiles = await resolveFiles(graph, consumerSymbolIds);
+        const mismatches = [];
+        for (const file of consumerFiles) {
+            const accessedKeys = await collectAccessedKeys(graph, file);
+            const { status } = classifyShape(accessedKeys, responseKeys);
+            if (status === "MISMATCH")
+                mismatches.push(file);
+        }
+        const affectedProcesses = await fetchAffectedProcesses(graph, consumerSymbolIds);
+        const risk = scoreRisk(consumerFiles.length, mismatches.length);
+        out.push({
+            route: { id: r.id, url: r.url, method: r.method ?? "", filePath: r.filePath },
+            risk,
+            consumers: consumerFiles,
+            middleware: handlers,
+            mismatches,
+            affectedProcesses,
+        });
+    }
+    return out;
+}
+function scoreRisk(consumers, mismatches) {
+    if (consumers >= 20)
+        return "CRITICAL";
+    if (consumers >= 5 || mismatches > 0)
+        return "HIGH";
+    if (consumers >= 1)
+        return "MEDIUM";
+    return "LOW";
+}
+function worseRisk(a, b) {
+    const order = { LOW: 0, MEDIUM: 1, HIGH: 2, CRITICAL: 3 };
+    return order[a] >= order[b] ? a : b;
+}
+async function fetchFromIds(graph, targetId, type) {
+    const edges = await graph.listEdgesByType(type, { toIds: [targetId] });
+    return edges
+        .map((e) => e.from)
+        .filter((s) => s.length > 0)
+        .sort();
+}
+async function resolveFiles(graph, nodeIds) {
+    if (nodeIds.length === 0)
+        return [];
+    const partners = await graph.listNodes({ ids: [...nodeIds] });
+    const set = new Set();
+    for (const n of partners) {
+        if (n.filePath && n.filePath.length > 0)
+            set.add(n.filePath);
+    }
+    return Array.from(set).sort();
+}
+async function collectAccessedKeys(graph, file) {
+    const edges = await graph.listEdgesByType("ACCESSES");
+    if (edges.length === 0)
+        return [];
+    const allIds = new Set();
+    for (const e of edges) {
+        allIds.add(e.from);
+        allIds.add(e.to);
+    }
+    const allNodes = await graph.listNodes({ ids: [...allIds] });
+    const byId = new Map();
+    for (const n of allNodes)
+        byId.set(n.id, n);
+    const names = new Set();
+    for (const e of edges) {
+        const src = byId.get(e.from);
+        if (!src || src.filePath !== file)
+            continue;
+        const target = byId.get(e.to);
+        if (!target || target.kind !== "Property")
+            continue;
+        if (target.name && target.name.length > 0)
+            names.add(target.name);
+    }
+    return Array.from(names).sort();
+}
+async function fetchAffectedProcesses(graph, consumerSymbolIds) {
+    if (consumerSymbolIds.length === 0)
+        return [];
+    const targetSet = new Set(consumerSymbolIds);
+    const edges = await graph.listEdgesByType("PROCESS_STEP");
+    const procIds = new Set();
+    for (const e of edges) {
+        if (!targetSet.has(e.to))
+            continue;
+        procIds.add(e.from);
+    }
+    if (procIds.size === 0)
+        return [];
+    const partners = await graph.listNodes({ ids: [...procIds] });
+    const out = [];
+    for (const n of partners) {
+        if (n.kind === "Process")
+            out.push(n.id);
+    }
+    return out.sort();
+}
+//# sourceMappingURL=api-impact.js.map

package/dist/tools/api-impact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-impact.js","sourceRoot":"","sources":["../../src/tools/api-impact.ts"],"names":[],"mappings":"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"}

package/dist/tools/confidence.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Confidence-breakdown aggregation for MCP edge-based responses.
+ *
+ * Every `context` and `impact` response now carries a `confidenceBreakdown`
+ * summarising the provenance quality of the underlying edges. The three
+ * buckets map directly onto the confidence-demote phase:
+ *
+ *   - `confirmed` — confidence >= 0.95 AND reason starts with a known LSP
+ *     provenance prefix. These are oracle-confirmed by a compiler-grade
+ *     language server (pyright, tsserver, gopls, rust-analyzer).
+ *   - `heuristic` — 0.2 < confidence < 0.95. Tree-sitter / tier-1 / tier-2
+ *     inference that the LSP oracle has not confirmed (either no coverage
+ *     for the language, or the LSP was skipped).
+ *   - `unknown` — confidence <= 0.2. Heuristic edges that the demote phase
+ *     explicitly flagged as contradicted (`+scip-unconfirmed`) or placeholders
+ *     from the parser.
+ *
+ * The breakdown is a pure read-side aggregation — callers feed in the edges
+ * already surfaced by the enclosing tool. It never mutates edges.
+ */
+import type { CodeRelation } from "@opencodehub/core-types";
+export interface ConfidenceBreakdown {
+    readonly confirmed: number;
+    readonly heuristic: number;
+    readonly unknown: number;
+}
+/** Shape we accept from SQL rows without forcing full `CodeRelation` hydration. */
+export interface EdgeConfidenceSource {
+    readonly confidence: number;
+    readonly reason?: string | undefined;
+}
+export declare function computeConfidenceBreakdown(edges: readonly EdgeConfidenceSource[]): ConfidenceBreakdown;
+/**
+ * Convenience overload for callers that already have hydrated `CodeRelation`
+ * instances. Accepts the `CodeRelation` array and re-uses the same aggregation
+ * path by narrowing to the two fields we actually consume.
+ */
+export declare function computeConfidenceBreakdownFromRelations(relations: readonly CodeRelation[]): ConfidenceBreakdown;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/tools/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../../src/tools/confidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAKD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,mBAAmB,CAcrB;AAED;;;;GAIG;AACH,wBAAgB,uCAAuC,CACrD,SAAS,EAAE,SAAS,YAAY,EAAE,GACjC,mBAAmB,CAIrB"}

package/dist/tools/confidence.js

@@ -0,0 +1,58 @@
+/**
+ * Confidence-breakdown aggregation for MCP edge-based responses.
+ *
+ * Every `context` and `impact` response now carries a `confidenceBreakdown`
+ * summarising the provenance quality of the underlying edges. The three
+ * buckets map directly onto the confidence-demote phase:
+ *
+ *   - `confirmed` — confidence >= 0.95 AND reason starts with a known LSP
+ *     provenance prefix. These are oracle-confirmed by a compiler-grade
+ *     language server (pyright, tsserver, gopls, rust-analyzer).
+ *   - `heuristic` — 0.2 < confidence < 0.95. Tree-sitter / tier-1 / tier-2
+ *     inference that the LSP oracle has not confirmed (either no coverage
+ *     for the language, or the LSP was skipped).
+ *   - `unknown` — confidence <= 0.2. Heuristic edges that the demote phase
+ *     explicitly flagged as contradicted (`+scip-unconfirmed`) or placeholders
+ *     from the parser.
+ *
+ * The breakdown is a pure read-side aggregation — callers feed in the edges
+ * already surfaced by the enclosing tool. It never mutates edges.
+ */
+import { SCIP_PROVENANCE_PREFIXES } from "@opencodehub/core-types";
+const CONFIRMED_FLOOR = 0.95;
+const UNKNOWN_CEILING = 0.2;
+export function computeConfidenceBreakdown(edges) {
+    let confirmed = 0;
+    let heuristic = 0;
+    let unknown = 0;
+    for (const e of edges) {
+        if (e.confidence >= CONFIRMED_FLOOR && hasLspProvenance(e.reason)) {
+            confirmed += 1;
+        }
+        else if (e.confidence > UNKNOWN_CEILING) {
+            heuristic += 1;
+        }
+        else {
+            unknown += 1;
+        }
+    }
+    return { confirmed, heuristic, unknown };
+}
+/**
+ * Convenience overload for callers that already have hydrated `CodeRelation`
+ * instances. Accepts the `CodeRelation` array and re-uses the same aggregation
+ * path by narrowing to the two fields we actually consume.
+ */
+export function computeConfidenceBreakdownFromRelations(relations) {
+    return computeConfidenceBreakdown(relations.map((r) => ({ confidence: r.confidence, reason: r.reason })));
+}
+function hasLspProvenance(reason) {
+    if (reason === undefined)
+        return false;
+    for (const prefix of SCIP_PROVENANCE_PREFIXES) {
+        if (reason.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=confidence.js.map

package/dist/tools/confidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.js","sourceRoot":"","sources":["../../src/tools/confidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAcnE,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B,MAAM,UAAU,0BAA0B,CACxC,KAAsC;IAEtC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,UAAU,IAAI,eAAe,IAAI,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;YAClE,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;aAAM,IAAI,CAAC,CAAC,UAAU,GAAG,eAAe,EAAE,CAAC;YAC1C,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uCAAuC,CACrD,SAAkC;IAElC,OAAO,0BAA0B,CAC/B,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CACvE,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,MAA0B;IAClD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvC,KAAK,MAAM,MAAM,IAAI,wBAAwB,EAAE,CAAC;QAC9C,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/tools/context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `context` — 360-degree view of a single symbol.
+ *
+ * Resolution order:
+ *   1. `uid` — direct node-id lookup; no disambiguation, no name match.
+ *   2. `symbol` (or `name` alias) — filtered by optional `kind` and
+ *      `file_path` (snake_case, with `filePath` camelCase alias preserved
+ *      for backward compat). Ambiguous names surface a ranked candidate
+ *      list instead of silently picking one (EC-04 in the PRD).
+ *
+ * Once a single target is resolved we collect:
+ *   - `incoming` — every edge where the target is the `to_id`, bucketed
+ *     by edge type (calls, imports, accesses, has_method, has_property,
+ *     extends, implements, method_overrides, method_implements).
+ *   - `outgoing` — the same bucketing for edges where the target is
+ *     the `from_id`.
+ *   - `processes` — PROCESS_STEP participation (Process-kind partners).
+ *   - `cochanges` — git-history partners for the target's enclosing file.
+ *   - `operations` — OpenAPI `Operation` nodes linked to a Route target via
+ *     `HANDLES_ROUTE` (cross-stack trace from the OpenAPI phase).
+ *   - `confidenceBreakdown` — provenance tally over every edge surfaced.
+ *   - `content` (optional) — the target's indexed source, capped at
+ *     {@link CONTENT_CHAR_CAP} characters. Only returned when
+ *     `include_content` is true.
+ *   - `location` — `{ filePath, startLine, endLine }` for quick jump-to.
+ *
+ * The flat `callers`, `callees`, `members`, and `owner` fields are kept on
+ * the response for backward compat with pre-parity consumers; new callers
+ * should prefer the `incoming` / `outgoing` category buckets.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext, type ToolResult } from "./shared.js";
+interface ContextArgs {
+    readonly symbol?: string | undefined;
+    readonly name?: string | undefined;
+    readonly uid?: string | undefined;
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+    readonly kind?: string | undefined;
+    readonly file_path?: string | undefined;
+    readonly filePath?: string | undefined;
+    readonly include_content?: boolean | undefined;
+}
+export declare function runContext(ctx: ToolContext, args: ContextArgs): Promise<ToolResult>;
+export declare function registerContextTool(server: McpServer, ctx: ToolContext): void;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/tools/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQzE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AA8HrB,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChD;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA2KzF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAiB7E"}