@shrkcrft/mcp-server 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/tools/get-code-intelligence-state.tool.js

@@ -0,0 +1,60 @@
+import { buildCodeIntelligenceChecks, DoctorSeverity, } from '@shrkcrft/inspector';
+import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+/**
+ * Read-only MCP mirror of `shrk code-intel`. Returns the same 14
+ * code-intelligence doctor findings in one shot — agents can pull
+ * the entire state without iterating `shrk doctor`'s full check list.
+ *
+ * Stable output schema (`sharkcraft.code-intelligence-state/v1`) so
+ * downstream renderers (dashboard, CI bots) can rely on the shape.
+ */
+export const getCodeIntelligenceStateTool = {
+    name: 'get_code_intelligence_state',
+    description: 'Return all code-intelligence doctor findings (graph, rule-graph, api-surface, quality-gate, migrations, architecture, impact, framework, structural-search, context-planner) in one payload. Read-only.',
+    cliCommand: 'code-intel',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            only: { type: 'array', items: { type: 'string' } },
+            checkId: { type: 'string' },
+            ...FORMAT_INPUT_PROPERTY,
+        },
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        let checks = buildCodeIntelligenceChecks(ctx.inspection.projectRoot);
+        if (args.checkId) {
+            checks = checks.filter((c) => c.id === args.checkId);
+        }
+        if (args.only && args.only.length > 0) {
+            const allowed = new Set(args.only.map((s) => s.toLowerCase()));
+            checks = checks.filter((c) => allowed.has(c.severity));
+        }
+        const summary = summarize(checks);
+        const data = {
+            schema: 'sharkcraft.code-intelligence-state/v1',
+            totalChecks: checks.length,
+            summary,
+            checks,
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};
+function summarize(checks) {
+    let ok = 0;
+    let info = 0;
+    let warnings = 0;
+    let errors = 0;
+    for (const c of checks) {
+        if (c.severity === DoctorSeverity.Ok)
+            ok += 1;
+        else if (c.severity === DoctorSeverity.Info)
+            info += 1;
+        else if (c.severity === DoctorSeverity.Warning)
+            warnings += 1;
+        else if (c.severity === DoctorSeverity.Error)
+            errors += 1;
+    }
+    return { ok, info, warnings, errors };
+}

package/dist/tools/get-context-pack.tool.d.ts

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

package/dist/tools/get-context-pack.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-context-pack.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-context-pack.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,kBAAkB,EAAE,eAoChC,CAAC"}

package/dist/tools/get-context-pack.tool.js

@@ -0,0 +1,40 @@
+import { planContext } from '@shrkcrft/context-planner';
+export const getContextPackTool = {
+    name: 'get_context_pack',
+    description: 'Produce a deterministic, token-budgeted context pack (`sharkcraft.context-pack/v1`) for an AI coding agent: ranked relevant files, applicable rules, paths, templates, likely tests, surfaced risks, do-not-touch zones. Read-only.',
+    cliCommand: 'plan-context',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string' },
+            budgetTokens: { type: 'number' },
+            hintedFiles: { type: 'array', items: { type: 'string' } },
+            hintedPackages: { type: 'array', items: { type: 'string' } },
+            maxFiles: { type: 'number' },
+        },
+        required: ['task'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const task = (args.task ?? '').trim();
+        if (!task) {
+            return {
+                isError: true,
+                error: { code: 'invalid-input', message: 'task is required' },
+            };
+        }
+        const pack = planContext({
+            projectRoot: ctx.inspection.projectRoot,
+            task,
+            budgetTokens: clamp(args.budgetTokens ?? 8000, 500, 64000),
+            maxFiles: clamp(args.maxFiles ?? 30, 1, 200),
+            ...(args.hintedFiles ? { hintedFiles: args.hintedFiles } : {}),
+            ...(args.hintedPackages ? { hintedPackages: args.hintedPackages } : {}),
+        });
+        return { data: pack };
+    },
+};
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}

package/dist/tools/get-framework-entities.tool.d.ts

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

package/dist/tools/get-framework-entities.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-framework-entities.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-framework-entities.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAYpE,eAAO,MAAM,wBAAwB,EAAE,eA+DtC,CAAC"}

package/dist/tools/get-framework-entities.tool.js

@@ -0,0 +1,68 @@
+import { FrameworkQueryApi } from '@shrkcrft/framework-scanners';
+const NEXT = 'shrk framework index';
+export const getFrameworkEntitiesTool = {
+    name: 'get_framework_entities',
+    description: 'Read-only: list framework entities discovered by the extractors (NestJS controllers/modules/providers/routes, React components/hook usages). Filters: framework, subtype, file. Pass `routes: true` for the NestJS route table.',
+    cliCommand: 'framework list',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            framework: { type: 'string' },
+            subtype: { type: 'string' },
+            file: { type: 'string' },
+            limit: { type: 'number' },
+            routes: { type: 'boolean' },
+        },
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const missing = FrameworkQueryApi.missingDescription(ctx.inspection.projectRoot);
+        if (missing) {
+            return {
+                isError: true,
+                error: { code: 'framework-missing', message: missing, details: { nextCommand: NEXT } },
+            };
+        }
+        const api = FrameworkQueryApi.fromStore(ctx.inspection.projectRoot);
+        if (args.routes) {
+            const routes = api.routes();
+            return {
+                data: {
+                    schema: 'sharkcraft.framework-routes/v1',
+                    total: routes.length,
+                    routes,
+                },
+            };
+        }
+        const limit = clamp(args.limit ?? 100, 1, 2000);
+        const entities = api.list({
+            ...(args.framework ? { framework: args.framework } : {}),
+            ...(args.subtype ? { subtype: args.subtype } : {}),
+            ...(args.file ? { file: args.file } : {}),
+            limit,
+        });
+        return {
+            data: {
+                schema: 'sharkcraft.framework-list/v1',
+                filters: {
+                    framework: args.framework ?? null,
+                    subtype: args.subtype ?? null,
+                    file: args.file ?? null,
+                },
+                total: entities.length,
+                entities: entities.map((n) => ({
+                    id: n.id,
+                    label: n.label,
+                    path: n.path,
+                    framework: n.data?.['framework'] ?? null,
+                    subtype: n.data?.['subtype'] ?? null,
+                    data: n.data,
+                })),
+            },
+        };
+    },
+};
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}

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

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

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

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

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

@@ -0,0 +1,94 @@
+import { GraphQueryApi, GraphStore, loadGraphApiCached } 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 getGraphCallersTool = {
+    name: 'get_graph_callers',
+    description: 'Find who calls/references a symbol (use this instead of grep before changing a function/type). Returns each caller as path:line of the first call site. Mode "call" → calls-symbol edges; mode "reference" → both references-symbol and calls-symbol. Read-only; needs `shrk graph index`.',
+    cliCommand: 'graph callers',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            symbol: { type: 'string' },
+            mode: { type: 'string', enum: ['call', 'reference'] },
+            ...FORMAT_INPUT_PROPERTY,
+        },
+        required: ['symbol'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const target = (args.symbol ?? '').trim();
+        if (!target) {
+            return {
+                isError: true,
+                error: { code: 'invalid-input', message: 'symbol is required' },
+            };
+        }
+        const mode = args.mode ?? 'call';
+        const store = new GraphStore(ctx.inspection.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(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const sym = resolveSymbol(api, target);
+        if (!sym) {
+            return {
+                isError: true,
+                error: {
+                    code: 'not-found',
+                    message: `No symbol matched "${target}".`,
+                    details: { target },
+                },
+            };
+        }
+        const cwd = ctx.inspection.projectRoot;
+        const sites = mode === 'reference' ? api.referenceSitesOf(sym.id) : api.callerSitesOf(sym.id);
+        // Targeted staleness over the result files: drop callers whose file was
+        // deleted on disk, flag those whose content changed since indexing — so a
+        // stale index never silently serves a wrong/dead caller. Read-only.
+        const fresh = graphResultStaleness(api, cwd, [sym.path, ...sites.map((s) => s.node.path)]);
+        const live = sites.filter((s) => !s.node.path || !fresh.deletedSet.has(s.node.path));
+        const note = callGraphLanguageNote(api, sym);
+        const data = {
+            schema: 'sharkcraft.graph-callers/v1',
+            symbol: summarise(sym),
+            mode,
+            total: live.length,
+            callers: live.slice(0, 200).map((s) => ({
+                ...summarise(s.node),
+                ...(s.line ? { line: s.line } : {}),
+            })),
+            ...(note ? { note } : {}),
+            ...(fresh.field ?? {}),
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};
+function resolveSymbol(api, target) {
+    if (target.startsWith('symbol:'))
+        return api.neighbours(target)?.node;
+    const syms = api.findSymbol(target, { exact: true, limit: 5 });
+    if (syms.length === 0)
+        return undefined;
+    if (syms.length === 1)
+        return syms[0];
+    const exported = syms.find((s) => (s.data?.['isExported'] ?? false) === true);
+    return exported ?? syms[0];
+}
+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-context.tool.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-graph-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-context.tool.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,mBAAmB,EAAE,eAsGjC,CAAC"}

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

@@ -0,0 +1,125 @@
+import { GraphQueryApi, GraphStore, NodeKind, 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 getGraphContextTool = {
+    name: 'get_graph_context',
+    description: 'Return graph context for a file or symbol: declared symbols, files this imports, files that import it. Read-only.',
+    cliCommand: 'graph context',
+    inputSchema: {
+        type: 'object',
+        properties: { target: { type: 'string' }, ...FORMAT_INPUT_PROPERTY },
+        required: ['target'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const target = (args.target ?? '').trim();
+        if (!target) {
+            return {
+                isError: true,
+                error: { code: 'invalid-input', message: 'target is required' },
+            };
+        }
+        const store = new GraphStore(ctx.inspection.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(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const anchor = resolveAnchor(api, target);
+        if (!anchor) {
+            return {
+                isError: true,
+                error: {
+                    code: 'not-found',
+                    message: `No graph node matched "${target}".`,
+                    details: { target },
+                },
+            };
+        }
+        // A SYMBOL has no imports-file edges (those are file→file), so its import
+        // context is the DECLARING FILE's imports — compute neighbours on that file
+        // (mirrors the CLI; otherwise importsFrom/importedBy are wrongly empty).
+        const declaringFile = anchor.kind === NodeKind.Symbol
+            ? api.declaringFileOf(anchor.id) ?? (anchor.path ? api.findFile(anchor.path) : undefined)
+            : undefined;
+        const subjectId = anchor.kind === NodeKind.File ? anchor.id : declaringFile?.id ?? anchor.id;
+        const neighbours = api.neighbours(subjectId);
+        const symbols = anchor.kind === NodeKind.File ? api.symbolsIn(anchor.id) : [];
+        // Who uses this symbol — references + calls (the CLI provides these; the MCP
+        // previously omitted them, returning a confidently-wrong "nothing uses this").
+        const referencedBy = anchor.kind === NodeKind.Symbol ? api.referencesOf(anchor.id) : [];
+        const calledBy = anchor.kind === NodeKind.Symbol ? api.callersOf(anchor.id) : [];
+        // Typed subtype/supertype edges (extends / implements) — the precise
+        // "who implements this interface" answer for a symbol anchor.
+        const subtypes = anchor.kind === NodeKind.Symbol ? api.subtypesOf(anchor.id) : [];
+        const supertypes = anchor.kind === NodeKind.Symbol ? api.supertypesOf(anchor.id) : [];
+        const importsFrom = neighbours.out
+            .filter((o) => o.edge.kind === 'imports-file')
+            .slice(0, 50)
+            .map((o) => 'resolved' in o.target
+            ? { id: o.target.id, resolved: false }
+            : { ...summarise(o.target), resolved: true });
+        const importedBy = neighbours.in
+            .filter((i) => i.edge.kind === 'imports-file')
+            .slice(0, 50)
+            .map((i) => 'resolved' in i.source
+            ? { id: i.source.id, resolved: false }
+            : { ...summarise(i.source), resolved: true });
+        const referencedByRows = referencedBy.slice(0, 50).map(summarise);
+        const calledByRows = calledBy.slice(0, 50).map(summarise);
+        // Drop imports/refs to/from files deleted on disk; flag the rest if changed.
+        const fresh = graphResultStaleness(api, ctx.inspection.projectRoot, [
+            anchor.path,
+            ...importsFrom.map((x) => ('path' in x ? x.path : undefined)),
+            ...importedBy.map((x) => ('path' in x ? x.path : undefined)),
+            ...referencedByRows.map((x) => x.path),
+            ...calledByRows.map((x) => x.path),
+        ]);
+        const data = {
+            schema: 'sharkcraft.graph-context/v1',
+            anchor: summarise(anchor),
+            ...(declaringFile ? { declaredIn: summarise(declaringFile) } : {}),
+            importsFrom: dropDeleted(importsFrom, fresh.deletedSet),
+            importedBy: dropDeleted(importedBy, fresh.deletedSet),
+            symbols: symbols.slice(0, 50).map(summarise),
+            ...(referencedByRows.length > 0 ? { referencedBy: dropDeleted(referencedByRows, fresh.deletedSet) } : {}),
+            ...(calledByRows.length > 0 ? { calledBy: dropDeleted(calledByRows, fresh.deletedSet) } : {}),
+            ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, 50).map(summarise) } : {}),
+            ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, 50).map(summarise) } : {}),
+            ...(fresh.field ?? {}),
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};
+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;
+}
+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-cycles.tool.d.ts

@@ -0,0 +1,10 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * Read-only MCP mirror of `shrk graph cycles`. Returns the full SCC
+ * list (sorted by size desc) so agents can answer "show me every
+ * import cycle in this repo" in a single tool call. Mirrors the safety
+ * contract: read-only, structured error with nextCommand when state
+ * is missing.
+ */
+export declare const getGraphCyclesTool: IToolDefinition;
+//# sourceMappingURL=get-graph-cycles.tool.d.ts.map

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

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

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

@@ -0,0 +1,58 @@
+import { GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
+import { FORMAT_INPUT_PROPERTY, formatObjectArrays } from "../server/columnar-format.js";
+const NEXT = 'shrk graph index';
+/**
+ * Read-only MCP mirror of `shrk graph cycles`. Returns the full SCC
+ * list (sorted by size desc) so agents can answer "show me every
+ * import cycle in this repo" in a single tool call. Mirrors the safety
+ * contract: read-only, structured error with nextCommand when state
+ * is missing.
+ */
+export const getGraphCyclesTool = {
+    name: 'get_graph_cycles',
+    description: 'Return every import cycle in the code graph (strongly-connected components of size ≥ 2 over `imports-file` edges). Sorted by size desc. Read-only.',
+    cliCommand: 'graph cycles',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            limit: { type: 'number' },
+            minSize: { type: 'number' },
+            ...FORMAT_INPUT_PROPERTY,
+        },
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const rawLimit = typeof args.limit === 'number' && Number.isFinite(args.limit) && args.limit > 0
+            ? args.limit
+            : 50;
+        const minSize = typeof args.minSize === 'number' && Number.isFinite(args.minSize) && args.minSize >= 2
+            ? args.minSize
+            : 2;
+        const store = new GraphStore(ctx.inspection.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(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const all = api.cycles();
+        const filtered = all.filter((c) => c.size >= minSize);
+        const limited = filtered.slice(0, rawLimit);
+        const data = {
+            schema: 'sharkcraft.graph-cycles/v1',
+            total: filtered.length,
+            truncated: filtered.length > rawLimit,
+            cycles: limited.map((c) => ({
+                size: c.size,
+                paths: c.paths ?? c.nodeIds.map((id) => id.replace(/^file:/, '')),
+            })),
+        };
+        return { data: formatObjectArrays(data, input) };
+    },
+};

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

@@ -0,0 +1,12 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * Read-only MCP mirror of `shrk graph deps`. Returns the workspace
+ * package's outbound (`depends on`) and inbound (`depended on by`)
+ * `package-depends-on` edges from the persisted code graph.
+ *
+ * Mirrors the safety contract: structured `graph-missing` error when
+ * the index isn't built; `not-found` when no `package:<name>` node
+ * exists.
+ */
+export declare const getGraphDepsTool: IToolDefinition;
+//# sourceMappingURL=get-graph-deps.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-graph-deps.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-graph-deps.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AASpE;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAmE9B,CAAC"}

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

@@ -0,0 +1,80 @@
+import { EdgeKind, GraphQueryApi, GraphStore, loadGraphApiCached } from '@shrkcrft/graph';
+const NEXT = 'shrk graph index';
+/**
+ * Read-only MCP mirror of `shrk graph deps`. Returns the workspace
+ * package's outbound (`depends on`) and inbound (`depended on by`)
+ * `package-depends-on` edges from the persisted code graph.
+ *
+ * Mirrors the safety contract: structured `graph-missing` error when
+ * the index isn't built; `not-found` when no `package:<name>` node
+ * exists.
+ */
+export const getGraphDepsTool = {
+    name: 'get_graph_deps',
+    description: 'Return inbound + outbound `package-depends-on` edges for a workspace package. Read-only.',
+    cliCommand: 'graph deps',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            package: { type: 'string' },
+        },
+        required: ['package'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const target = (args.package ?? '').trim();
+        if (!target) {
+            return {
+                isError: true,
+                error: { code: 'invalid-input', message: 'package is required' },
+            };
+        }
+        const store = new GraphStore(ctx.inspection.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(ctx.inspection.projectRoot) ?? GraphQueryApi.fromStore(ctx.inspection.projectRoot);
+        const pkgId = `package:${target}`;
+        const pkgNode = api.neighbours(pkgId)?.node;
+        if (!pkgNode) {
+            return {
+                isError: true,
+                error: {
+                    code: 'not-found',
+                    message: `No workspace package node "${target}" in the graph.`,
+                    details: { target },
+                },
+            };
+        }
+        const dependsOn = api
+            .packageDeps(target)
+            .map((n) => n.id.replace(/^package:/, ''))
+            .sort();
+        const dependedOnBy = [];
+        for (const p of api.allPackages()) {
+            const name = p.id.replace(/^package:/, '');
+            if (name === target)
+                continue;
+            if (api.packageDeps(name).some((n) => n.id === pkgId))
+                dependedOnBy.push(name);
+        }
+        dependedOnBy.sort();
+        void EdgeKind;
+        return {
+            data: {
+                schema: 'sharkcraft.graph-deps/v1',
+                package: target,
+                dependsOn,
+                dependedOnBy,
+            },
+        };
+    },
+};

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

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

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

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

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 } : {}),
+    };
+}