@shrkcrft/mcp-server 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/tools/get-graph-hubs.tool.js

@@ -0,0 +1,61 @@
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
+import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+const NEXT = 'shrk graph index';
+export const getGraphHubsTool = {
+    name: 'get_graph_hubs',
+    description: 'The most-depended-on code: symbols ranked by how many DISTINCT files reference them, files by how many import them. The "load-bearing code" to change most carefully (biggest blast radius) and understand first when onboarding — the companion to get_graph_impact. Pass `path` (e.g. "packages/foo") to scope to one subsystem. Read-only; needs `shrk graph index`.',
+    cliCommand: 'graph hubs',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: { type: 'number' },
+            path: { type: 'string' },
+            ...FORMAT_INPUT_PROPERTY,
+        },
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const limit = clampLimit(args.limit);
+        const projectRoot = ctx.inspection.projectRoot;
+        const store = new GraphStore(projectRoot);
+        if (!store.exists()) {
+            return {
+                isError: true,
+                error: {
+                    code: 'graph-missing',
+                    message: `Code-intelligence index is missing. Run '${NEXT}'.`,
+                    details: { nextCommand: NEXT },
+                },
+            };
+        }
+        const api = loadGraphApiCached(projectRoot) ?? GraphQueryApi.fromStore(projectRoot);
+        const pathScope = typeof args.path === 'string' && args.path.trim().length > 0 ? args.path.trim() : undefined;
+        const hubs = api.topHubs(limit, pathScope);
+        const row = (h) => ({
+            ...summarise(h.node),
+            inDegree: h.inDegree,
+        });
+        const data = {
+            schema: 'sharkcraft.graph-hubs/v1',
+            ...(pathScope ? { path: pathScope } : {}),
+            symbols: hubs.symbols.map(row),
+            files: hubs.files.map(row),
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};
+function clampLimit(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return 15;
+    return Math.max(1, Math.min(100, Math.floor(raw)));
+}
+function summarise(n) {
+    return {
+        id: n.id,
+        kind: n.kind,
+        label: n.label,
+        ...(n.path ? { path: n.path } : {}),
+        ...(n.line ? { line: n.line } : {}),
+    };
+}

package/dist/tools/get-graph-impact.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-impact.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-impact.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAWpE,eAAO,MAAM,kBAAkB,EAAE,eAmEhC,CAAC"}
+{"version":3,"file":"get-graph-impact.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-impact.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,kBAAkB,EAAE,eA4EhC,CAAC"}

package/dist/tools/get-graph-impact.tool.js

@@ -1,5 +1,6 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { dropDeleted, graphResultStaleness } from "./graph-staleness.js";
 const NEXT = 'shrk graph index';
 export const getGraphImpactTool = {
     name: 'get_graph_impact',
@@ -38,7 +39,7 @@ export const getGraphImpactTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
         const anchor = resolveAnchor(api, target);
         if (!anchor) {
             return {
@@ -50,20 +51,29 @@ export const getGraphImpactTool = {
                 },
             };
         }
-        const closure = reverseClosure(api, anchor.id, maxDepth, limit);
+        const closure = reverseClosure(api, anchor, maxDepth, limit);
         const direct = closure.layer[1] ?? [];
         const transitive = closure.all.filter((id) => id !== anchor.id && !direct.includes(id));
+        const directNodes = direct.map((id) => summarise(api.neighbours(id).node));
+        const transitiveNodes = transitive.slice(0, limit).map((id) => summarise(api.neighbours(id).node));
+        // Targeted staleness over the blast-radius files: drop dependents whose
+        // file was deleted (they can't break), flag those whose content changed —
+        // so a stale index never misroutes which tests/files the agent trusts.
+        const fresh = graphResultStaleness(api, ctx.inspection.projectRoot, [
+            anchor.path,
+            ...directNodes.map((n) => n.path),
+            ...transitiveNodes.map((n) => n.path),
+        ]);
         const data = {
             schema: 'sharkcraft.graph-impact/v1',
             anchor: summarise(anchor),
             maxDepth,
             limit,
             truncated: closure.truncated,
-            directDependents: direct.map((id) => summarise(api.neighbours(id).node)),
-            transitiveDependents: transitive
-                .slice(0, limit)
-                .map((id) => summarise(api.neighbours(id).node)),
+            directDependents: dropDeleted(directNodes, fresh.deletedSet),
+            transitiveDependents: dropDeleted(transitiveNodes, fresh.deletedSet),
             totalReached: closure.all.length - 1,
+            ...(fresh.field ?? {}),
         };
         return { data: formatObjectArrays(data, input) };
     },
@@ -83,13 +93,23 @@ function resolveAnchor(api, target) {
         return syms[0];
     return undefined;
 }
-function reverseClosure(api, startId, maxDepth, limit) {
-    const seen = new Set([startId]);
+function reverseClosure(api, anchor, maxDepth, limit) {
+    const seen = new Set([anchor.id]);
     const layer = {};
-    let frontier = [startId];
-    let depth = 1;
     let truncated = false;
-    while (depth <= maxDepth && frontier.length > 0) {
+    // Layer 1 uses the anchor-kind-aware direct dependents (importersOf alone
+    // returns NOTHING for a symbol anchor — symbols have no import edges).
+    let frontier = directDependents(api, anchor).filter((id) => !seen.has(id));
+    if (frontier.length > limit) {
+        frontier = frontier.slice(0, limit);
+        truncated = true;
+    }
+    for (const id of frontier)
+        seen.add(id);
+    if (frontier.length > 0)
+        layer[1] = frontier;
+    let depth = 2;
+    while (depth <= maxDepth && frontier.length > 0 && !truncated) {
         const next = [];
         for (const id of frontier) {
             for (const imp of api.importersOf(id)) {
@@ -109,11 +129,13 @@ function reverseClosure(api, startId, maxDepth, limit) {
             layer[depth] = next;
         frontier = next;
         depth += 1;
-        if (truncated)
-            break;
     }
     return { all: [...seen], layer, truncated };
 }
+/** Kind-aware direct dependents — the shared `GraphQueryApi` implementation. */
+function directDependents(api, anchor) {
+    return api.directDependentsOf(anchor).map((n) => n.id);
+}
 function summarise(n) {
     return {
         id: n.id,

package/dist/tools/get-graph-path.tool.d.ts

@@ -0,0 +1,3 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+export declare const getGraphPathTool: IToolDefinition;
+//# sourceMappingURL=get-graph-path.tool.d.ts.map

package/dist/tools/get-graph-path.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-graph-path.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-path.tool.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,gBAAgB,EAAE,eAgG9B,CAAC"}

package/dist/tools/get-graph-path.tool.js

@@ -0,0 +1,144 @@
+import { EdgeKind, GraphQueryApi, GraphStore, loadGraphApiCached, NodeKind, } from '@shrkcrft/graph';
+import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+import { callGraphLanguageNote, graphResultStaleness } from "./graph-staleness.js";
+const NEXT = 'shrk graph index';
+export const getGraphPathTool = {
+    name: 'get_graph_path',
+    description: 'Is code A actually wired to code B? Returns the shortest directed CODE path (import/call/reference/declare/re-export/extends/implements edges) from `from` to `to`, hop by hop with edge kind and call-site line — the deterministic answer to "is X wired to Y" that grep cannot give. If A does not reach B it also checks B→A and reports the direction. Each endpoint is a file path or a symbol name. Read-only; needs `shrk graph index`.',
+    cliCommand: 'graph path',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            from: { type: 'string' },
+            to: { type: 'string' },
+            maxDepth: { type: 'number' },
+            ...FORMAT_INPUT_PROPERTY,
+        },
+        required: ['from', 'to'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const fromArg = (args.from ?? '').trim();
+        const toArg = (args.to ?? '').trim();
+        if (!fromArg || !toArg) {
+            return { isError: true, error: { code: 'invalid-input', message: 'from and to are required' } };
+        }
+        const maxDepth = clampDepth(args.maxDepth);
+        const cwd = ctx.inspection.projectRoot;
+        const store = new GraphStore(cwd);
+        if (!store.exists()) {
+            return {
+                isError: true,
+                error: {
+                    code: 'graph-missing',
+                    message: `Code-intelligence index is missing. Run '${NEXT}'.`,
+                    details: { nextCommand: NEXT },
+                },
+            };
+        }
+        const api = loadGraphApiCached(cwd) ?? GraphQueryApi.fromStore(cwd);
+        const from = resolveAnchor(api, fromArg);
+        const to = resolveAnchor(api, toArg);
+        if (!from || !to) {
+            const missing = !from ? fromArg : toArg;
+            return {
+                isError: true,
+                error: { code: 'not-found', message: `No graph node matched "${missing}".`, details: { target: missing } },
+            };
+        }
+        // A symbol has no OUTGOING code edges (references are recorded file→symbol),
+        // so trace from its declaring file. The target may stay a symbol.
+        const fromStart = bfsStartNode(api, from);
+        const toStart = bfsStartNode(api, to);
+        const forward = api.pathBetween(fromStart.id, to.id, { maxDepth });
+        const reverse = forward.found ? null : api.pathBetween(toStart.id, from.id, { maxDepth });
+        const direction = forward.found
+            ? 'forward'
+            : reverse?.found
+                ? 'reverse'
+                : 'none';
+        const chosen = forward.found ? forward : reverse?.found ? reverse : forward;
+        const startEndpoint = direction === 'reverse' ? to : from;
+        const startFile = direction === 'reverse' ? toStart : fromStart;
+        const startNote = direction !== 'none' && startFile.id !== startEndpoint.id && startEndpoint.kind === NodeKind.Symbol
+            ? `\`${startEndpoint.label}\` is declared in ${startFile.path ?? startFile.id}; path traced from that file (per-symbol out-edges are not tracked).`
+            : undefined;
+        const hops = chosen.hops.map((h) => ({
+            from: h.from.path ?? h.from.id,
+            to: h.to.path ?? h.to.id,
+            kind: h.kind,
+            label: h.to.label,
+            ...(h.line ? { line: h.line } : {}),
+        }));
+        const fresh = graphResultStaleness(api, cwd, [
+            from.path,
+            to.path,
+            ...chosen.hops.map((h) => h.from.path),
+            ...chosen.hops.map((h) => h.to.path),
+        ]);
+        // A no-path answer between non-TS endpoints may just be missing call edges.
+        const langNote = direction === 'none' ? callGraphLanguageNote(api, from) ?? callGraphLanguageNote(api, to) : undefined;
+        const data = {
+            schema: 'sharkcraft.graph-path/v1',
+            from: summarise(from),
+            to: summarise(to),
+            found: direction !== 'none',
+            direction,
+            ...(direction !== 'none' && startFile.id !== startEndpoint.id ? { tracedFrom: summarise(startFile) } : {}),
+            hops,
+            hopCount: hops.length,
+            explored: forward.found ? forward.explored : reverse?.explored ?? forward.explored,
+            ...(direction === 'none' && chosen.reason ? { reason: chosen.reason } : {}),
+            ...(startNote ?? langNote ? { note: startNote ?? langNote } : {}),
+            ...(fresh.field ?? {}),
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};
+function clampDepth(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return 16;
+    return Math.max(1, Math.min(32, Math.floor(raw)));
+}
+function resolveAnchor(api, target) {
+    const direct = api.neighbours(target);
+    if (direct)
+        return direct.node;
+    if (target.startsWith('file:') || target.startsWith('symbol:') || target.startsWith('package:')) {
+        return undefined;
+    }
+    const f = api.findFile(target);
+    if (f)
+        return f;
+    const syms = api.findSymbol(target, { exact: true, limit: 1 });
+    if (syms.length > 0)
+        return syms[0];
+    return undefined;
+}
+/** A file is its own BFS start; a symbol resolves to its declaring file. */
+function bfsStartNode(api, node) {
+    if (node.kind !== NodeKind.Symbol)
+        return node;
+    const neighbours = api.neighbours(node.id);
+    if (neighbours) {
+        for (const incoming of neighbours.in) {
+            if (incoming.edge.kind !== EdgeKind.DeclaresSymbol)
+                continue;
+            if ('resolved' in incoming.source)
+                continue;
+            if (incoming.source.kind === NodeKind.File)
+                return incoming.source;
+        }
+    }
+    return (node.path ? api.findFile(node.path) : undefined) ?? node;
+}
+function summarise(n) {
+    return {
+        id: n.id,
+        kind: n.kind,
+        label: n.label,
+        ...(n.path ? { path: n.path } : {}),
+        ...(n.line ? { line: n.line } : {}),
+    };
+}

package/dist/tools/get-graph-search.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-search.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-search.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,kBAAkB,EAAE,eA6DhC,CAAC"}
+{"version":3,"file":"get-graph-search.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-search.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,kBAAkB,EAAE,eA8EhC,CAAC"}

package/dist/tools/get-graph-search.tool.js

@@ -1,4 +1,4 @@
-import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
 import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
 const NEXT = 'shrk graph index';
 export const getGraphSearchTool = {
@@ -38,15 +38,34 @@ export const getGraphSearchTool = {
                 },
             };
         }
-        const api = GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const api = loadGraphApiCached(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const exact = args.exact ?? false;
         const matches = [];
         if (!args.kind || args.kind === 'file') {
             const f = api.findFile(query);
             if (f)
                 matches.push(f);
+            // Fuzzy fallback (mirrors the CLI): substring match on path/basename so a
+            // bare name like `Foo` finds `packages/x/Foo.ts` without the full path —
+            // otherwise the MCP returned an empty list where the CLI found the file.
+            if (!exact && matches.length < limit) {
+                const q = query.toLowerCase();
+                const seen = new Set(matches.map((n) => n.id));
+                for (const node of api.allFiles()) {
+                    if (seen.has(node.id))
+                        continue;
+                    const p = node.path?.toLowerCase() ?? '';
+                    const base = p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p;
+                    if (base.includes(q) || p.includes(q)) {
+                        matches.push(node);
+                        seen.add(node.id);
+                        if (matches.length >= limit)
+                            break;
+                    }
+                }
+            }
         }
         if (!args.kind || args.kind === 'symbol') {
-            const exact = args.exact ?? false;
             for (const s of api.findSymbol(query, { exact, limit }))
                 matches.push(s);
         }

package/dist/tools/get-graph-status.tool.d.ts

@@ -1,9 +1,11 @@
 import type { IToolDefinition } from '../server/tool-definition.js';
 /**
  * Read-only status for the on-disk code graph. Returns
- * { state: 'fresh' | 'corrupt' | 'missing' } and counters.
- * On 'missing', `isError` + `error.details.nextCommand` direct the
- * caller (CLI or human) to refresh.
+ * { state: 'fresh' | 'stale' | 'corrupt' | 'missing' } and counters.
+ * `corrupt` (store self-integrity) and `stale` (files changed on disk since
+ * indexing) are orthogonal — a store can be digest-valid yet stale — so
+ * precedence is corrupt > stale > fresh. On 'missing', `isError` +
+ * `nextCommand` direct the caller to refresh.
  */
 export declare const getGraphStatusTool: IToolDefinition;
 //# sourceMappingURL=get-graph-status.tool.d.ts.map

package/dist/tools/get-graph-status.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-graph-status.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-status.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAKpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAqChC,CAAC"}
+{"version":3,"file":"get-graph-status.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-status.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAKpE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA4ChC,CAAC"}

package/dist/tools/get-graph-status.tool.js

@@ -1,15 +1,17 @@
-import { GraphStore } from '@shrkcrft/graph';
+import { detectGraphFreshness, GraphStore } from '@shrkcrft/graph';
 const NEXT = 'shrk graph index';
 const STALE_HINT = `Code-intelligence index is missing or stale. Run '${NEXT}' to build it.`;
 /**
  * Read-only status for the on-disk code graph. Returns
- * { state: 'fresh' | 'corrupt' | 'missing' } and counters.
- * On 'missing', `isError` + `error.details.nextCommand` direct the
- * caller (CLI or human) to refresh.
+ * { state: 'fresh' | 'stale' | 'corrupt' | 'missing' } and counters.
+ * `corrupt` (store self-integrity) and `stale` (files changed on disk since
+ * indexing) are orthogonal — a store can be digest-valid yet stale — so
+ * precedence is corrupt > stale > fresh. On 'missing', `isError` +
+ * `nextCommand` direct the caller to refresh.
  */
 export const getGraphStatusTool = {
     name: 'get_graph_status',
-    description: 'Read-only status of the SharkCraft code-intelligence graph: file/node/edge counts, schema, last indexed time, digest verification. Returns nextCommand when missing.',
+    description: 'Read-only status of the SharkCraft code-intelligence graph: state (fresh/stale/corrupt/missing), file/node/edge counts, and how many files changed/added/deleted since indexing. Returns nextCommand when stale or missing so the agent knows to refresh before trusting graph answers.',
     cliCommand: 'graph status',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     handler(_input, ctx) {
@@ -26,10 +28,13 @@ export const getGraphStatusTool = {
         }
         const verify = store.verifyDigest();
         const snap = store.loadSnapshot();
+        const fresh = detectGraphFreshness(ctx.inspection.projectRoot);
+        const behind = fresh.modified.length + fresh.added.length + fresh.deleted.length;
+        const state = !verify.ok ? 'corrupt' : behind > 0 ? 'stale' : 'fresh';
         return {
             data: {
                 schema: snap.manifest.schema,
-                state: verify.ok ? 'fresh' : 'corrupt',
+                state,
                 digestOk: verify.ok,
                 fileCount: snap.manifest.filesIndexed,
                 nodeCount: snap.nodes.size,
@@ -39,6 +44,10 @@ export const getGraphStatusTool = {
                 workspacePackages: snap.manifest.workspacePackages,
                 lastIndexedAt: snap.manifest.lastIndexedAt,
                 lastIndexDurationMs: snap.manifest.lastIndexDurationMs,
+                modifiedSinceIndex: fresh.modified.length,
+                newSinceIndex: fresh.added.length,
+                deletedSinceIndex: fresh.deleted.length,
+                ...(behind > 0 ? { nextCommand: 'shrk graph index --changed' } : {}),
                 ...(verify.ok ? {} : { expectedDigest: verify.expected, actualDigest: verify.actual }),
             },
         };

package/dist/tools/get-knowledge-graph.tool.js

@@ -21,7 +21,7 @@ export const getKnowledgeGraphTool = {
                 description: 'json (default): explicit node/edge object arrays. table: columnar encoding (schema hoisted, keys deduped) — fewer tokens for large graphs.',
             },
             maxTokens: {
-                type: 'number',
+                type: 'integer',
                 minimum: 1,
                 description: 'Token budget for the table. When set and the lossless columnar form still exceeds it, falls back to the lossy SmartCrusher row-sampler (representative rows kept; full original cached — retrieve via the returned ccrKey).',
             },

package/dist/tools/graph-staleness.d.ts

@@ -0,0 +1,34 @@
+import { type GraphQueryApi, type INode } from '@shrkcrft/graph';
+/**
+ * A note when a symbol's file language has no call-graph extraction (Go/Python/
+ * Java/…) — only TS/JS build call/reference edges — so an empty caller/usage
+ * result isn't read as "nothing calls it". Returns undefined for TS/JS.
+ */
+export declare function callGraphLanguageNote(api: GraphQueryApi, sym: INode): string | undefined;
+export declare const GRAPH_STALE_HINT = "Result files changed since indexing \u2014 run `shrk graph index --changed` for fresh results.";
+export interface IGraphStaleSurface {
+    /** Result file paths deleted on disk — drop entries whose `path` is in this set. */
+    deletedSet: ReadonlySet<string>;
+    /** Spread into the tool `data` object; null when every result file is fresh. */
+    field: {
+        stale: {
+            modified: readonly string[];
+            deleted: readonly string[];
+        };
+        staleHint: string;
+    } | null;
+}
+/**
+ * Targeted, read-only staleness over a query's result file paths. The graph
+ * MCP tools use it to DROP deleted result files and FLAG modified ones, so a
+ * stale index never silently serves a wrong/dead answer for a file the agent
+ * just edited. Cheap: stats only the handful of result files (mtime+size gate,
+ * sha1 only on mismatch) — never a whole-tree walk.
+ */
+export declare function graphResultStaleness(api: GraphQueryApi, cwd: string, paths: ReadonlyArray<string | undefined>): IGraphStaleSurface;
+/** Filter out result entries whose file path was deleted on disk. */
+export declare function dropDeleted<T extends {
+    id: string;
+    path?: string;
+}>(rows: readonly T[], deletedSet: ReadonlySet<string>): T[];
+//# sourceMappingURL=graph-staleness.d.ts.map

package/dist/tools/graph-staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-staleness.d.ts","sourceRoot":"","sources":["../../src/tools/graph-staleness.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAEzF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAKxF;AAED,eAAO,MAAM,gBAAgB,mGACgE,CAAC;AAE9F,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,gFAAgF;IAChF,KAAK,EACD;QAAE,KAAK,EAAE;YAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;YAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;SAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GACzF,IAAI,CAAC;CACV;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,GACvC,kBAAkB,CAUpB;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACjE,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAC9B,CAAC,EAAE,CAEL"}

package/dist/tools/graph-staleness.js

@@ -0,0 +1,36 @@
+import { hasCallGraphReferences } from '@shrkcrft/graph';
+/**
+ * A note when a symbol's file language has no call-graph extraction (Go/Python/
+ * Java/…) — only TS/JS build call/reference edges — so an empty caller/usage
+ * result isn't read as "nothing calls it". Returns undefined for TS/JS.
+ */
+export function callGraphLanguageNote(api, sym) {
+    const file = sym.path ? api.findFile(sym.path) : undefined;
+    const lang = file?.data?.['language'];
+    if (hasCallGraphReferences(lang))
+        return undefined;
+    return `Call/reference edges are extracted for TS/JS only — \`${sym.label}\` is in a ${lang} file, so callers/usages are not tracked here (an empty result does NOT mean none).`;
+}
+export const GRAPH_STALE_HINT = 'Result files changed since indexing — run `shrk graph index --changed` for fresh results.';
+/**
+ * Targeted, read-only staleness over a query's result file paths. The graph
+ * MCP tools use it to DROP deleted result files and FLAG modified ones, so a
+ * stale index never silently serves a wrong/dead answer for a file the agent
+ * just edited. Cheap: stats only the handful of result files (mtime+size gate,
+ * sha1 only on mismatch) — never a whole-tree walk.
+ */
+export function graphResultStaleness(api, cwd, paths) {
+    const rel = paths.filter((p) => !!p);
+    const stale = api.staleFilesAmong(cwd, rel);
+    const has = stale.modified.length > 0 || stale.deleted.length > 0;
+    return {
+        deletedSet: new Set(stale.deleted),
+        field: has
+            ? { stale: { modified: stale.modified, deleted: stale.deleted }, staleHint: GRAPH_STALE_HINT }
+            : null,
+    };
+}
+/** Filter out result entries whose file path was deleted on disk. */
+export function dropDeleted(rows, deletedSet) {
+    return rows.filter((r) => !r.path || !deletedSet.has(r.path));
+}

package/dist/tools/primary-tools.d.ts

@@ -1,5 +1,5 @@
 /**
- * Primary MCP tools — the ~30 tools advertised to a connected agent
+ * Primary MCP tools — the core set advertised to a connected agent
  * by default. Every tool in {@link ALL_TOOLS} stays callable (so an
  * agent that already knows the name can use it), but `tools/list`
  * only advertises the primary set. Smaller surface = better

package/dist/tools/primary-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primary-tools.d.ts","sourceRoot":"","sources":["../../src/tools/primary-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAiDhD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAGpD"}
+{"version":3,"file":"primary-tools.d.ts","sourceRoot":"","sources":["../../src/tools/primary-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CA4DhD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAGpD"}

package/dist/tools/primary-tools.js

@@ -1,5 +1,5 @@
 /**
- * Primary MCP tools — the ~30 tools advertised to a connected agent
+ * Primary MCP tools — the core set advertised to a connected agent
  * by default. Every tool in {@link ALL_TOOLS} stays callable (so an
  * agent that already knows the name can use it), but `tools/list`
  * only advertises the primary set. Smaller surface = better
@@ -54,6 +54,17 @@ export const PRIMARY_MCP_TOOLS = new Set([
     // Doctor / readiness
     'get_ai_readiness_report',
     'doctor_packs',
+    // Code-intelligence graph — the agent's grep replacement for understanding
+    // existing code: who calls X, where is X used (path:line), what breaks if I
+    // change X, is X wired. Verifiable file:line truth from the indexed graph.
+    'get_graph_callers',
+    'code_find_usages',
+    'get_graph_impact',
+    'get_graph_path',
+    'get_graph_hubs',
+    'graph_why',
+    'get_graph_node',
+    'get_graph_search',
     // Search
     'search_all',
     'search_knowledge',

package/dist/tools/start-here.tool.js

@@ -1,13 +1,13 @@
 import { buildStartHereReport, buildPrimaryCommandsReport, } from '@shrkcrft/inspector';
 export const getStartHereTool = {
     name: 'get_start_here',
-    description: 'Return the SharkCraft start-here flow list (30-second explanation + 5 primary flows + safety pledge). Read-only.',
+    description: 'Return the SharkCraft start-here flow list (30-second explanation + primary flows incl. "investigate existing code" + safety pledge). Read-only.',
     inputSchema: {
         type: 'object',
         properties: {
             flow: {
                 type: 'string',
-                enum: ['onboard', 'brief', 'dev', 'review', 'governance', 'packs', 'release'],
+                enum: ['onboard', 'investigate', 'brief', 'dev', 'review', 'governance', 'packs', 'release'],
             },
         },
         additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/mcp-server",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "description": "SharkCraft MCP server: 25 tools over @modelcontextprotocol/sdk's stdio transport.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -44,32 +44,32 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.16",
-    "@shrkcrft/compress": "^0.1.0-alpha.16",
-    "@shrkcrft/config": "^0.1.0-alpha.16",
-    "@shrkcrft/workspace": "^0.1.0-alpha.16",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.16",
-    "@shrkcrft/context": "^0.1.0-alpha.16",
-    "@shrkcrft/rules": "^0.1.0-alpha.16",
-    "@shrkcrft/paths": "^0.1.0-alpha.16",
-    "@shrkcrft/templates": "^0.1.0-alpha.16",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.16",
-    "@shrkcrft/presets": "^0.1.0-alpha.16",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.16",
-    "@shrkcrft/graph": "^0.1.0-alpha.16",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.16",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.16",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.16",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.16",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.16",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.16",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.16",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.16",
-    "@shrkcrft/migrate": "^0.1.0-alpha.16",
-    "@shrkcrft/packs": "^0.1.0-alpha.16",
-    "@shrkcrft/generator": "^0.1.0-alpha.16",
-    "@shrkcrft/inspector": "^0.1.0-alpha.16",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.16",
+    "@shrkcrft/core": "^0.1.0-alpha.18",
+    "@shrkcrft/compress": "^0.1.0-alpha.18",
+    "@shrkcrft/config": "^0.1.0-alpha.18",
+    "@shrkcrft/workspace": "^0.1.0-alpha.18",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.18",
+    "@shrkcrft/context": "^0.1.0-alpha.18",
+    "@shrkcrft/rules": "^0.1.0-alpha.18",
+    "@shrkcrft/paths": "^0.1.0-alpha.18",
+    "@shrkcrft/templates": "^0.1.0-alpha.18",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.18",
+    "@shrkcrft/presets": "^0.1.0-alpha.18",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.18",
+    "@shrkcrft/graph": "^0.1.0-alpha.18",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.18",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.18",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.18",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.18",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.18",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.18",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.18",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.18",
+    "@shrkcrft/migrate": "^0.1.0-alpha.18",
+    "@shrkcrft/packs": "^0.1.0-alpha.18",
+    "@shrkcrft/generator": "^0.1.0-alpha.18",
+    "@shrkcrft/inspector": "^0.1.0-alpha.18",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.18",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.25.0 || ^4.0.0"
   },