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

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

@@ -0,0 +1,65 @@
+import { diffImpactReports, ImpactReportStore, } from '@shrkcrft/impact-engine';
+/**
+ * Read-only MCP mirror of `shrk impact baseline show`. Returns the
+ * frozen baseline + the most recent run + the delta between them.
+ * When either side is missing the response carries a structured hint
+ * pointing at the command that fills the gap.
+ */
+export const getImpactBaselineTool = {
+    name: 'get_impact_baseline',
+    description: 'Return the impact baseline + latest impact run + delta. Read-only mirror of `shrk impact baseline show`.',
+    cliCommand: 'impact baseline show',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    handler(_input, ctx) {
+        const store = new ImpactReportStore(ctx.inspection.projectRoot);
+        const baseline = store.readBaseline();
+        const last = store.read();
+        if (!baseline && !last) {
+            return {
+                data: {
+                    schema: 'sharkcraft.impact-baseline/v1',
+                    state: 'missing-both',
+                    baseline: null,
+                    last: null,
+                    nextCommands: ['shrk impact --via-graph <target>', 'shrk impact baseline write'],
+                },
+            };
+        }
+        if (!baseline) {
+            return {
+                data: {
+                    schema: 'sharkcraft.impact-baseline/v1',
+                    state: 'missing-baseline',
+                    baseline: null,
+                    last,
+                    nextCommands: ['shrk impact baseline write'],
+                },
+            };
+        }
+        if (!last) {
+            return {
+                data: {
+                    schema: 'sharkcraft.impact-baseline/v1',
+                    state: 'missing-last',
+                    baseline,
+                    last: null,
+                    nextCommands: ['shrk impact --via-graph <target>'],
+                },
+            };
+        }
+        const delta = diffImpactReports(baseline, last);
+        return {
+            data: {
+                schema: 'sharkcraft.impact-baseline/v1',
+                state: 'present',
+                baseline,
+                last,
+                delta,
+            },
+        };
+    },
+};

package/dist/tools/get-intent-benchmark-run.tool.d.ts

@@ -0,0 +1,12 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * Read-only MCP surface for the intent-classifier benchmark. Returns
+ * the latest persisted run + a hint about the source fixture so the
+ * agent can correlate misses against the labelled cases.
+ *
+ * When no run is on disk but a fixture is present, the tool reports
+ * `state: 'fixture-only'` and points at `shrk context benchmark` so
+ * the run can be created without an additional turn of guessing.
+ */
+export declare const getIntentBenchmarkRunTool: IToolDefinition;
+//# sourceMappingURL=get-intent-benchmark-run.tool.d.ts.map

package/dist/tools/get-intent-benchmark-run.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-intent-benchmark-run.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-intent-benchmark-run.tool.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,eA6CvC,CAAC"}

package/dist/tools/get-intent-benchmark-run.tool.js

@@ -0,0 +1,55 @@
+import { loadIntentBenchmark, readBenchmarkRun, } from '@shrkcrft/context-planner';
+/**
+ * Read-only MCP surface for the intent-classifier benchmark. Returns
+ * the latest persisted run + a hint about the source fixture so the
+ * agent can correlate misses against the labelled cases.
+ *
+ * When no run is on disk but a fixture is present, the tool reports
+ * `state: 'fixture-only'` and points at `shrk context benchmark` so
+ * the run can be created without an additional turn of guessing.
+ */
+export const getIntentBenchmarkRunTool = {
+    name: 'get_intent_benchmark_run',
+    description: 'Return the most recent intent-classifier benchmark run. Read-only mirror of `shrk context benchmark`.',
+    cliCommand: 'context benchmark',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    handler(_input, ctx) {
+        const root = ctx.inspection.projectRoot;
+        const fixture = loadIntentBenchmark(root);
+        const run = readBenchmarkRun(root);
+        if (!fixture && !run) {
+            return {
+                data: {
+                    schema: 'sharkcraft.intent-benchmark/v1',
+                    state: 'missing',
+                    fixture: null,
+                    run: null,
+                    nextCommands: ['shrk context benchmark seed', 'shrk context benchmark'],
+                },
+            };
+        }
+        if (!run) {
+            return {
+                data: {
+                    schema: 'sharkcraft.intent-benchmark/v1',
+                    state: 'fixture-only',
+                    fixtureCaseCount: fixture?.cases.length ?? 0,
+                    run: null,
+                    nextCommands: ['shrk context benchmark'],
+                },
+            };
+        }
+        return {
+            data: {
+                schema: 'sharkcraft.intent-benchmark/v1',
+                state: 'present',
+                fixtureCaseCount: fixture?.cases.length ?? run.total,
+                run,
+            },
+        };
+    },
+};

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

@@ -1,3 +1,10 @@
 import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * The knowledge graph is the largest single payload shrk emits — hundreds of
+ * homogeneous node/edge objects. `format:"table"` returns the same data in
+ * columnar form (schema hoisted once, keys deduped) which is still valid JSON
+ * but a fraction of the tokens. `format:"json"` (default) keeps the explicit
+ * node/edge arrays for back-compat.
+ */
 export declare const getKnowledgeGraphTool: IToolDefinition;
 //# sourceMappingURL=get-knowledge-graph.tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"get-knowledge-graph.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-knowledge-graph.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE,eAAO,MAAM,qBAAqB,EAAE,eASnC,CAAC"}
+{"version":3,"file":"get-knowledge-graph.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-knowledge-graph.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,eA8DnC,CAAC"}

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

@@ -1,10 +1,69 @@
 import { buildKnowledgeGraph } from '@shrkcrft/inspector';
+import { compactArrayToColumnar, estimateTokens } from '@shrkcrft/compress';
+import { wantsTable } from "../server/columnar-format.js";
+import { fitArrayToBudget } from "../server/fit-array-to-budget.js";
+/**
+ * The knowledge graph is the largest single payload shrk emits — hundreds of
+ * homogeneous node/edge objects. `format:"table"` returns the same data in
+ * columnar form (schema hoisted once, keys deduped) which is still valid JSON
+ * but a fraction of the tokens. `format:"json"` (default) keeps the explicit
+ * node/edge arrays for back-compat.
+ */
 export const getKnowledgeGraphTool = {
     name: 'get_knowledge_graph',
-    description: 'Return the full SharkCraft knowledge graph: nodes (knowledge/rules/paths/templates/pipelines/presets/packs/boundaries) and edges (related-template, preset-references, pipeline-step-references, …). Read-only.',
-    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-    async handler(_input, ctx) {
+    description: 'Return the full SharkCraft knowledge graph: nodes (knowledge/rules/paths/templates/pipelines/presets/packs/boundaries) and edges (related-template, preset-references, pipeline-step-references, …). Pass `format:"table"` for a token-efficient columnar encoding (still valid JSON) — recommended for large graphs. Read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            format: {
+                type: 'string',
+                enum: ['json', 'table'],
+                description: 'json (default): explicit node/edge object arrays. table: columnar encoding (schema hoisted, keys deduped) — fewer tokens for large graphs.',
+            },
+            maxTokens: {
+                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).',
+            },
+        },
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
         const graph = buildKnowledgeGraph(ctx.inspection);
+        const asTable = wantsTable(input);
+        const maxTokens = typeof input.maxTokens === 'number' && input.maxTokens > 0 ? Math.floor(input.maxTokens) : undefined;
+        const nodesTable = asTable ? compactArrayToColumnar(graph.nodes) : null;
+        const edgesTable = asTable ? compactArrayToColumnar(graph.edges) : null;
+        // Only advertise `table` when at least one array actually compacted — a tiny
+        // graph (e.g. edges:[]) stays the plain JSON form rather than a mislabelled
+        // "table" whose fields are bare arrays.
+        if (nodesTable || edgesTable) {
+            // P5.2: with no budget, keep the lossless columnar form (unchanged). With
+            // a budget, fit each array — sampling + CCR when it's still over.
+            const nodes = maxTokens
+                ? fitArrayToBudget(graph.nodes, maxTokens, ctx.ccrStore)
+                : { value: nodesTable ?? graph.nodes };
+            const edges = maxTokens
+                ? fitArrayToBudget(graph.edges, maxTokens, ctx.ccrStore)
+                : { value: edgesTable ?? graph.edges };
+            const ccrKeys = [nodes.ccrKey, edges.ccrKey].filter((k) => Boolean(k));
+            const before = estimateTokens(JSON.stringify({ nodes: graph.nodes, edges: graph.edges }));
+            const after = estimateTokens(JSON.stringify({ nodes: nodes.value, edges: edges.value }));
+            return {
+                data: {
+                    format: 'table',
+                    legend: 'Columnar tables: _table.cols are column names; each _table.rows[i] is one record aligned to cols; _table.absent lists [row,col] positions whose key was absent. Reconstruct objects by zipping cols with each row, skipping absent positions. If a column appears in _table.dict, its row cells are integer indices into dict[<col>] (deref to the real value). A field may be a plain array when it was too small to compact. A _table.sample block means rows were dropped to fit a budget — retrieve the full original via ccrKey.',
+                    nodes: nodes.value,
+                    edges: edges.value,
+                    tokenEstimate: { before, after, saved: Math.max(0, before - after) },
+                    ...(ccrKeys.length > 0
+                        ? { ccrKeys, retrieveWith: `retrieve_original { "key": "${ccrKeys[0]}" }` }
+                        : {}),
+                },
+            };
+        }
+        // Default (and tiny-graph) path: the original bare `{ nodes, edges }` shape,
+        // byte-identical to pre-compression clients (no extra `format` key).
         return { data: { nodes: graph.nodes, edges: graph.edges } };
     },
 };

package/dist/tools/get-migrations.tool.d.ts

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

package/dist/tools/get-migrations.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-migrations.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-migrations.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AA0BpE,eAAO,MAAM,iBAAiB,EAAE,eA+D/B,CAAC"}

package/dist/tools/get-migrations.tool.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { findResumePoint } from '@shrkcrft/migrate';
+export const getMigrationsTool = {
+    name: 'get_migrations',
+    description: 'Read-only: list `@shrkcrft/migrate` run state from `.sharkcraft/migrations/*.state.json`. Mirrors the dashboard Migrations panel. Pass `id` to fetch a single run; otherwise returns every saved state newest-first.',
+    cliCommand: 'migrate',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: { type: 'string' },
+        },
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const projectRoot = ctx.inspection.projectRoot;
+        const dir = nodePath.join(projectRoot, '.sharkcraft', 'migrations');
+        if (!existsSync(dir)) {
+            const payload = {
+                schema: 'sharkcraft.mcp-migrations/v1',
+                available: false,
+                total: 0,
+                migrations: [],
+                hint: 'no migrations have been run yet',
+            };
+            return { data: payload };
+        }
+        const rows = [];
+        let entries = [];
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            /* ignore */
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.state.json'))
+                continue;
+            const abs = nodePath.join(dir, entry);
+            try {
+                const report = JSON.parse(readFileSync(abs, 'utf8'));
+                if (args.id && report.migration.id !== args.id)
+                    continue;
+                const resumePoint = findResumePoint(report);
+                rows.push({
+                    id: report.migration.id,
+                    title: report.migration.title,
+                    overall: report.overall,
+                    dryRun: report.dryRun,
+                    startedAt: report.startedAt,
+                    totalDurationMs: report.totalDurationMs,
+                    steps: report.steps,
+                    ...(resumePoint !== undefined ? { resumePoint } : {}),
+                });
+            }
+            catch {
+                /* skip corrupt state */
+            }
+        }
+        rows.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+        const payload = {
+            schema: 'sharkcraft.mcp-migrations/v1',
+            available: true,
+            total: rows.length,
+            migrations: rows,
+        };
+        return { data: payload };
+    },
+};

package/dist/tools/get-pattern-registry.tool.d.ts

@@ -0,0 +1,8 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * Read-only MCP mirror of `shrk search-structural registry list`.
+ * Returns the full registry payload — the agent can pick a pattern by
+ * id and reference it in subsequent `get_structural_search` calls.
+ */
+export declare const getPatternRegistryTool: IToolDefinition;
+//# sourceMappingURL=get-pattern-registry.tool.d.ts.map

package/dist/tools/get-pattern-registry.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-pattern-registry.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-pattern-registry.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAkCpC,CAAC"}

package/dist/tools/get-pattern-registry.tool.js

@@ -0,0 +1,40 @@
+import { PatternRegistryStore } from '@shrkcrft/structural-search';
+/**
+ * Read-only MCP mirror of `shrk search-structural registry list`.
+ * Returns the full registry payload — the agent can pick a pattern by
+ * id and reference it in subsequent `get_structural_search` calls.
+ */
+export const getPatternRegistryTool = {
+    name: 'get_pattern_registry',
+    description: 'Return the persistent registry of reusable structural-search patterns. Read-only.',
+    cliCommand: 'search-structural registry list',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+    },
+    handler(_input, ctx) {
+        const store = new PatternRegistryStore(ctx.inspection.projectRoot);
+        if (!store.exists()) {
+            return {
+                data: {
+                    schema: 'sharkcraft.structural-pattern-registry/v1',
+                    present: false,
+                    path: store.absPath,
+                    patterns: [],
+                    nextCommands: ['shrk search-structural registry seed', 'shrk search-structural registry add'],
+                },
+            };
+        }
+        const reg = store.read();
+        return {
+            data: {
+                schema: reg.schema,
+                present: true,
+                path: store.absPath,
+                patterns: reg.patterns,
+                total: reg.patterns.length,
+            },
+        };
+    },
+};

package/dist/tools/get-quality-gate.tool.d.ts

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

package/dist/tools/get-quality-gate.tool.d.ts.map

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

package/dist/tools/get-quality-gate.tool.js

@@ -0,0 +1,27 @@
+import { runQualityGates } from '@shrkcrft/quality-gates';
+export const getQualityGateTool = {
+    name: 'get_quality_gate',
+    description: 'Read-only: run the code-intelligence quality-gate aggregator (graph freshness, architecture, impact since `main`) and return the unified pass/fail report. The CI / pre-merge hook for AI-agent-authored changes.',
+    cliCommand: 'gate',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sinceRef: { type: 'string' },
+            failOn: { type: 'array', items: { type: 'string', enum: ['high', 'critical'] } },
+            disable: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const report = runQualityGates({
+            projectRoot: ctx.inspection.projectRoot,
+            impact: {
+                ...(args.sinceRef ? { sinceRef: args.sinceRef } : {}),
+                ...(args.failOn ? { failOn: args.failOn } : {}),
+            },
+            ...(args.disable ? { disable: args.disable } : {}),
+        });
+        return { data: report };
+    },
+};

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

@@ -1 +1 @@
-{"version":3,"file":"get-relevant-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-relevant-context.tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE,eAAO,MAAM,sBAAsB,EAAE,eAqDpC,CAAC"}
+{"version":3,"file":"get-relevant-context.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-relevant-context.tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAKpE,eAAO,MAAM,sBAAsB,EAAE,eA6EpC,CAAC"}

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

@@ -1,5 +1,6 @@
 import { buildContext } from '@shrkcrft/context';
 import { buildProjectOverview, renderOverviewText } from '@shrkcrft/inspector';
+import { compressMarkdown } from '@shrkcrft/compress';
 export const getRelevantContextTool = {
     name: 'get_relevant_context',
     description: 'Build a token-budgeted, AI-ready context for a task — relevant rules/paths/templates/etc. **Prefer `prepare_agent_task` for first task grounding** (it returns this plus action hints + safety + next-command). Use this when you only need the context body. Read-only.',
@@ -17,6 +18,10 @@ export const getRelevantContextTool = {
             includeRules: { type: 'boolean' },
             includePaths: { type: 'boolean' },
             includeDocs: { type: 'boolean' },
+            compact: {
+                type: 'boolean',
+                description: 'When true, the markdown body is run through the deterministic markdown compressor (headers/leads/structure kept, prose thinned). Reversible: the original is cached and a `<<ccr:KEY>>` marker emitted — call retrieve_original to get it back.',
+            },
         },
         required: ['task'],
         additionalProperties: false,
@@ -37,18 +42,37 @@ export const getRelevantContextTool = {
             includeDocs: input.includeDocs,
             projectOverview: renderOverviewText(overview),
         });
+        const sections = result.sections.map((s) => ({
+            title: s.title,
+            tokens: s.tokens,
+            truncated: s.truncated ?? false,
+            entryIds: s.entryIds,
+        }));
+        if (input.compact === true) {
+            const c = compressMarkdown(result.body, ctx.ccrStore ? { store: ctx.ccrStore } : {});
+            return {
+                text: c.compressed,
+                data: {
+                    totalTokens: result.totalTokens,
+                    maxTokens: result.maxTokens,
+                    omittedSections: result.omittedSections,
+                    sections,
+                    compaction: {
+                        strategy: c.strategy,
+                        tokensBefore: c.savings.before,
+                        tokensAfter: c.savings.after,
+                        ccrKey: c.ccrKey ?? null,
+                    },
+                },
+            };
+        }
         return {
             text: result.body,
             data: {
                 totalTokens: result.totalTokens,
                 maxTokens: result.maxTokens,
                 omittedSections: result.omittedSections,
-                sections: result.sections.map((s) => ({
-                    title: s.title,
-                    tokens: s.tokens,
-                    truncated: s.truncated ?? false,
-                    entryIds: s.entryIds,
-                })),
+                sections,
             },
         };
     },

package/dist/tools/get-rules-for-file.tool.d.ts

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

package/dist/tools/get-rules-for-file.tool.d.ts.map

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

package/dist/tools/get-rules-for-file.tool.js

@@ -0,0 +1,54 @@
+import { RuleGraphQueryApi } from '@shrkcrft/rule-graph';
+export const getRulesForFileTool = {
+    name: 'get_rules_for_file',
+    description: 'Read-only bridge query: return rules (boundary), path conventions, and templates that apply to the given file. Requires `shrk graph index` + `shrk rule-graph index`.',
+    cliCommand: 'rule-graph for',
+    inputSchema: {
+        type: 'object',
+        properties: { file: { type: 'string' } },
+        required: ['file'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const file = (input.file ?? '').trim();
+        if (!file) {
+            return {
+                isError: true,
+                error: { code: 'invalid-input', message: 'file is required' },
+            };
+        }
+        const missing = RuleGraphQueryApi.missingDescription(ctx.inspection.projectRoot);
+        if (missing) {
+            const next = missing.includes('rule-graph') ? 'shrk rule-graph index' : 'shrk graph index';
+            return {
+                isError: true,
+                error: {
+                    code: 'bridge-missing',
+                    message: missing,
+                    details: { nextCommand: next },
+                },
+            };
+        }
+        const api = RuleGraphQueryApi.fromStores(ctx.inspection.projectRoot);
+        const r = api.forFile(file);
+        if (!r) {
+            return {
+                isError: true,
+                error: { code: 'not-found', message: `No file node for "${file}".`, details: { file } },
+            };
+        }
+        return {
+            data: {
+                schema: 'sharkcraft.rule-graph-for-file/v1',
+                file: r.path,
+                rules: r.rules.map((h) => ({
+                    id: h.target.id,
+                    label: h.target.label,
+                    severity: h.edge.data?.['severity'] ?? undefined,
+                })),
+                paths: r.paths.map((h) => ({ id: h.target.id, label: h.target.label })),
+                templates: r.templates.map((h) => ({ id: h.target.id, label: h.target.label })),
+            },
+        };
+    },
+};

package/dist/tools/get-structural-rewrite-plan.tool.d.ts

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

package/dist/tools/get-structural-rewrite-plan.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-structural-rewrite-plan.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-structural-rewrite-plan.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAUpE,eAAO,MAAM,4BAA4B,EAAE,eA0C1C,CAAC"}

package/dist/tools/get-structural-rewrite-plan.tool.js

@@ -0,0 +1,46 @@
+import { planRewrite } from '@shrkcrft/structural-search';
+export const getStructuralRewritePlanTool = {
+    // Tool name intentionally uses "codemod" rather than "rewrite" — the
+    // CLI ceremony tests forbid any MCP tool name containing the
+    // substring "write" so a future read of the catalog can't mistake a
+    // preview tool for a write surface. The plan is still read-only
+    // here; apply ceremony happens via `shrk search-structural ... --apply`.
+    name: 'get_structural_codemod_plan',
+    description: 'Preview a structural codemod as a per-file edit plan (`sharkcraft.structural-rewrite-plan/v1`). Read-only — apply ceremony stays on the CLI (`shrk search-structural ... --apply`). Useful for "what would this codemod do?" without touching disk.',
+    cliCommand: 'search-structural',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'object' },
+            recipe: { type: 'object' },
+            files: { type: 'array', items: { type: 'string' } },
+            perFileLimit: { type: 'number' },
+            fileLimit: { type: 'number' },
+        },
+        required: ['pattern', 'recipe'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const pattern = args.pattern;
+        const recipe = args.recipe;
+        if (!pattern || typeof pattern !== 'object' || !pattern.kind) {
+            return { isError: true, error: { code: 'invalid-input', message: 'pattern.kind is required' } };
+        }
+        if (!recipe || typeof recipe !== 'object' || !recipe.kind) {
+            return { isError: true, error: { code: 'invalid-input', message: 'recipe.kind is required' } };
+        }
+        const plan = planRewrite({
+            projectRoot: ctx.inspection.projectRoot,
+            pattern,
+            recipe,
+            ...(args.files ? { files: args.files } : {}),
+            ...(typeof args.perFileLimit === 'number' ? { perFileLimit: clamp(args.perFileLimit, 1, 1000) } : {}),
+            ...(typeof args.fileLimit === 'number' ? { fileLimit: clamp(args.fileLimit, 1, 50000) } : {}),
+        });
+        return { data: plan };
+    },
+};
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}

package/dist/tools/get-structural-search.tool.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-structural-search.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-structural-search.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAOpE,eAAO,MAAM,uBAAuB,EAAE,eA+BrC,CAAC"}

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

@@ -0,0 +1,35 @@
+import { runSearch } from '@shrkcrft/structural-search';
+export const getStructuralSearchTool = {
+    name: 'get_structural_search',
+    description: 'Run a declarative AST pattern over the project and return matches. Patterns are JSON of shape `{ kind: "CallExpression" | "ImportDeclaration" | "ClassDeclaration" | ..., ... }`. No executable predicates, no rewrites. Read-only.',
+    cliCommand: 'search-structural',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'object' },
+            limit: { type: 'number' },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+    },
+    handler(input, ctx) {
+        const args = input;
+        const pat = args.pattern;
+        if (!pat || typeof pat !== 'object' || !pat.kind) {
+            return {
+                isError: true,
+                error: { code: 'invalid-input', message: 'pattern.kind is required' },
+            };
+        }
+        const limit = clamp(args.limit ?? 200, 1, 2000);
+        const result = runSearch({
+            projectRoot: ctx.inspection.projectRoot,
+            pattern: pat,
+            limit,
+        });
+        return { data: result };
+    },
+};
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}

package/dist/tools/get-task-packet.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-task-packet.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-task-packet.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE,eAAO,MAAM,iBAAiB,EAAE,eA8C/B,CAAC"}
+{"version":3,"file":"get-task-packet.tool.d.ts","sourceRoot":"","sources":["../../src/tools/get-task-packet.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,eAAO,MAAM,iBAAiB,EAAE,eAiD/B,CAAC"}