@shrkcrft/mcp-server 0.1.0-alpha.11 → 0.1.0-alpha.13

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

@@ -1 +1 @@
-{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAuUpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EAgR9C,CAAC"}
+{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AA4UpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EAqR9C,CAAC"}

package/dist/tools/all-tools.js

@@ -96,6 +96,11 @@ import { getImportGraphAnalysisTool } from "./import-graph-analysis.tool.js";
 import { getDashboardSummaryTool } from "./dashboard-summary.tool.js";
 import { searchAllTool } from "./search.tool.js";
 import { createAgentBriefTool } from "./agent-brief.tool.js";
+import { smartContextBundleTool } from "./smart-context-bundle.tool.js";
+import { smartContextFeedTool } from "./smart-context-feed.tool.js";
+import { codeFindUsagesTool } from "./code-find-usages.tool.js";
+import { planQualityReviewTool } from "./plan-quality-review.tool.js";
+import { depsAuditTool } from "./deps-audit.tool.js";
 import { getConstructApiTool, getConstructTool, listConstructFacetsTool, listConstructsTool, traceConstructTool, } from "./constructs.tool.js";
 import { getPlaybookTool, listPlaybooksTool, recommendPlaybooksTool, } from "./playbooks.tool.js";
 import { replayBundleApplyTool } from "./bundle-replay.tool.js";
@@ -287,6 +292,11 @@ export const ALL_TOOLS = Object.freeze([
     getDashboardSummaryTool,
     searchAllTool,
     createAgentBriefTool,
+    smartContextBundleTool,
+    smartContextFeedTool,
+    codeFindUsagesTool,
+    planQualityReviewTool,
+    depsAuditTool,
     listConstructsTool,
     getConstructTool,
     traceConstructTool,

package/dist/tools/code-find-usages.tool.d.ts

@@ -0,0 +1,16 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * `code_find_usages` — structured usage finder backed by the
+ * SharkCraft graph (file + symbol nodes + import/declare edges).
+ *
+ * Unlike grep, this distinguishes:
+ *   - the symbol's definition site
+ *   - which files import the declaring file (runtime + type-only
+ *     can't be split without TS-level checks, so we mark them all as
+ *     `import-of-declaring-file` for honesty)
+ *   - which other symbols neighbour the target in the graph
+ *
+ * Read-only. Skips when the graph is missing (returns a hint).
+ */
+export declare const codeFindUsagesTool: IToolDefinition;
+//# sourceMappingURL=code-find-usages.tool.d.ts.map

package/dist/tools/code-find-usages.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-find-usages.tool.d.ts","sourceRoot":"","sources":["../../src/tools/code-find-usages.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA+FhC,CAAC"}

package/dist/tools/code-find-usages.tool.js

@@ -0,0 +1,137 @@
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { EdgeKind, GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
+/**
+ * `code_find_usages` — structured usage finder backed by the
+ * SharkCraft graph (file + symbol nodes + import/declare edges).
+ *
+ * Unlike grep, this distinguishes:
+ *   - the symbol's definition site
+ *   - which files import the declaring file (runtime + type-only
+ *     can't be split without TS-level checks, so we mark them all as
+ *     `import-of-declaring-file` for honesty)
+ *   - which other symbols neighbour the target in the graph
+ *
+ * Read-only. Skips when the graph is missing (returns a hint).
+ */
+export const codeFindUsagesTool = {
+    name: 'code_find_usages',
+    description: 'Find structured usages of a symbol via the SharkCraft graph (file + symbol nodes). Read-only. Distinguishes definition, import-of-declaring-file, and neighbouring symbols.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            symbolName: { type: 'string' },
+            kindHint: { type: 'string' },
+            maxResults: { type: 'number' },
+        },
+        required: ['symbolName'],
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        const symbolName = typeof input['symbolName'] === 'string' ? input['symbolName'].trim() : '';
+        if (symbolName.length === 0) {
+            return { data: { error: 'symbolName is required' } };
+        }
+        const maxResults = clamp(typeof input['maxResults'] === 'number' ? input['maxResults'] : 25, 1, 200);
+        const store = new GraphStore(ctx.cwd);
+        if (!store.exists()) {
+            return {
+                data: {
+                    error: 'no-graph',
+                    message: 'The SharkCraft graph index has not been built yet. Build it with `shrk graph build`.',
+                    nextCommand: 'shrk graph build',
+                },
+            };
+        }
+        const api = GraphQueryApi.fromStore(ctx.cwd);
+        const matches = api.findSymbol(symbolName, { exact: true, limit: maxResults });
+        if (matches.length === 0) {
+            return {
+                data: {
+                    symbol: { name: symbolName, kind: 'unknown' },
+                    definitions: [],
+                    importersOfDeclaringFile: [],
+                    neighbouringSymbols: [],
+                    totalSymbolMatches: 0,
+                    note: 'No exact symbol match in the graph. Try `shrk knowledge search` for fuzzy lookup.',
+                },
+            };
+        }
+        const definitions = [];
+        const importerSet = new Map();
+        const neighbours = [];
+        for (const sym of matches) {
+            const declaringFile = declaringFileOf(api, sym.id);
+            definitions.push({
+                symbolId: sym.id,
+                file: declaringFile?.path ?? null,
+                kind: String(sym.label && sym.label.length > 0 ? sym.label : sym.kind),
+            });
+            if (declaringFile) {
+                for (const importer of api.importersOf(declaringFile.id)) {
+                    if (!importer.path)
+                        continue;
+                    const exists = pathExists(ctx.cwd, importer.path);
+                    if (!exists)
+                        continue;
+                    const key = `${importer.path}::${declaringFile.path}`;
+                    if (!importerSet.has(key)) {
+                        importerSet.set(key, {
+                            file: importer.path,
+                            via: declaringFile.path ?? '',
+                        });
+                    }
+                }
+            }
+            // Sibling symbols declared by the same file.
+            if (declaringFile) {
+                for (const sib of api.symbolsIn(declaringFile.id).slice(0, 6)) {
+                    if (sib.id === sym.id)
+                        continue;
+                    neighbours.push({
+                        name: sib.label,
+                        kind: String(sib.kind),
+                        file: declaringFile.path ?? null,
+                    });
+                }
+            }
+        }
+        return {
+            data: {
+                symbol: { name: symbolName, kind: matches[0]?.kind ?? 'unknown' },
+                definitions,
+                importersOfDeclaringFile: [...importerSet.values()],
+                neighbouringSymbols: neighbours.slice(0, 12),
+                totalSymbolMatches: matches.length,
+                note: 'importersOfDeclaringFile = files that import the declaring file. This is a structural signal — it may include type-only imports and unused references. Pair with `shrk impact` for a tighter blast radius.',
+            },
+        };
+    },
+};
+function declaringFileOf(api, symbolId) {
+    const n = api.neighbours(symbolId);
+    if (!n)
+        return undefined;
+    for (const incoming of n.in) {
+        if (incoming.edge.kind !== EdgeKind.DeclaresSymbol)
+            continue;
+        if ('resolved' in incoming.source)
+            continue;
+        if (incoming.source.kind === NodeKind.File)
+            return incoming.source;
+    }
+    return undefined;
+}
+function pathExists(cwd, path) {
+    try {
+        return existsSync(nodePath.isAbsolute(path) ? path : nodePath.join(cwd, path));
+    }
+    catch {
+        return false;
+    }
+}
+function clamp(n, lo, hi) {
+    if (Number.isNaN(n))
+        return lo;
+    return Math.max(lo, Math.min(hi, Math.floor(n)));
+}

package/dist/tools/deps-audit.tool.d.ts

@@ -0,0 +1,10 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * `deps_audit` — MCP wrapper around `shrk deps-audit`. Pure read-only.
+ * Returns the same shape the CLI's `--json` mode emits.
+ *
+ * NOTE: we re-implement the body here rather than shell out so MCP
+ * tools never spawn subprocesses. Identical logic, identical output.
+ */
+export declare const depsAuditTool: IToolDefinition;
+//# sourceMappingURL=deps-audit.tool.d.ts.map

package/dist/tools/deps-audit.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps-audit.tool.d.ts","sourceRoot":"","sources":["../../src/tools/deps-audit.tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,eAoC3B,CAAC"}

package/dist/tools/deps-audit.tool.js

@@ -0,0 +1,217 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
+/**
+ * `deps_audit` — MCP wrapper around `shrk deps-audit`. Pure read-only.
+ * Returns the same shape the CLI's `--json` mode emits.
+ *
+ * NOTE: we re-implement the body here rather than shell out so MCP
+ * tools never spawn subprocesses. Identical logic, identical output.
+ */
+export const depsAuditTool = {
+    name: 'deps_audit',
+    description: 'Per-package audit of declared dependencies (package.json) vs actually-imported specifiers (graph). Reports missing + unused deps. Read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            package: { type: 'string' },
+        },
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        const onlyPackage = typeof input['package'] === 'string' ? input['package'] : null;
+        const store = new GraphStore(ctx.cwd);
+        if (!store.exists()) {
+            return {
+                data: {
+                    error: 'no-graph',
+                    message: 'The SharkCraft graph index is required for deps-audit.',
+                    nextCommand: 'shrk graph build',
+                },
+            };
+        }
+        const api = GraphQueryApi.fromStore(ctx.cwd);
+        const packages = listWorkspacePackages(ctx.cwd, onlyPackage);
+        const reports = packages.map((p) => buildPackageReport(api, ctx.cwd, p));
+        const totals = reports.reduce((acc, r) => {
+            acc.missing += r.missingDeps.length;
+            acc.unused += r.unusedDeps.length;
+            return acc;
+        }, { missing: 0, unused: 0 });
+        return { data: { totals, packages: reports } };
+    },
+};
+function listWorkspacePackages(cwd, onlyName) {
+    const roots = ['packages', 'libs', 'apps'].map((r) => nodePath.join(cwd, r)).filter((d) => existsSync(d));
+    const out = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const dir = nodePath.join(root, entry);
+            let stat;
+            try {
+                stat = statSync(dir);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isDirectory())
+                continue;
+            const pkgJsonPath = nodePath.join(dir, 'package.json');
+            if (!existsSync(pkgJsonPath))
+                continue;
+            let pkgJson;
+            try {
+                pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            if (!pkgJson.name)
+                continue;
+            if (onlyName !== null && pkgJson.name !== onlyName)
+                continue;
+            out.push({ name: pkgJson.name, dir, pkgJsonPath });
+        }
+    }
+    return out;
+}
+function buildPackageReport(api, cwd, pkg) {
+    const declared = readDeclaredDeps(pkg.pkgJsonPath);
+    const importedSpecifiers = collectImportedSpecifiersForPackage(api, cwd, pkg.dir);
+    const importerCounts = new Map();
+    for (const s of importedSpecifiers)
+        importerCounts.set(s, (importerCounts.get(s) ?? 0) + 1);
+    const distinctImported = new Set(importedSpecifiers);
+    const declaredAll = new Map();
+    for (const [section, map] of [
+        ['dependencies', declared.dependencies],
+        ['devDependencies', declared.devDependencies],
+        ['peerDependencies', declared.peerDependencies],
+        ['optionalDependencies', declared.optionalDependencies],
+    ]) {
+        for (const k of Object.keys(map))
+            declaredAll.set(k, section);
+    }
+    const missingDeps = [];
+    for (const spec of distinctImported) {
+        if (declaredAll.has(spec))
+            continue;
+        if (spec === pkg.name)
+            continue;
+        missingDeps.push({ specifier: spec, importedFromCount: importerCounts.get(spec) ?? 0 });
+    }
+    missingDeps.sort((a, b) => b.importedFromCount - a.importedFromCount);
+    const unusedDeps = [];
+    for (const [spec, section] of declaredAll.entries()) {
+        if (distinctImported.has(spec))
+            continue;
+        unusedDeps.push({ specifier: spec, section });
+    }
+    unusedDeps.sort((a, b) => a.specifier.localeCompare(b.specifier));
+    return {
+        packageName: pkg.name,
+        packageDir: nodePath.relative(cwd, pkg.dir) || '.',
+        importedSpecifiers: [...distinctImported],
+        missingDeps,
+        unusedDeps,
+    };
+}
+function readDeclaredDeps(pkgJsonPath) {
+    try {
+        const body = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+        return {
+            dependencies: asStringMap(body['dependencies']),
+            devDependencies: asStringMap(body['devDependencies']),
+            peerDependencies: asStringMap(body['peerDependencies']),
+            optionalDependencies: asStringMap(body['optionalDependencies']),
+        };
+    }
+    catch {
+        return { dependencies: {}, devDependencies: {}, peerDependencies: {}, optionalDependencies: {} };
+    }
+}
+function asStringMap(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+}
+function collectImportedSpecifiersForPackage(api, cwd, packageDir) {
+    const out = [];
+    const relDir = nodePath.relative(cwd, packageDir).replace(/\\/g, '/');
+    for (const file of api.allFiles()) {
+        if (file.kind !== NodeKind.File)
+            continue;
+        const p = file.path ?? '';
+        if (!p.startsWith(relDir + '/src/') && !p.startsWith(relDir + '/'))
+            continue;
+        const abs = nodePath.isAbsolute(p) ? p : nodePath.join(cwd, p);
+        if (!existsSync(abs))
+            continue;
+        let body;
+        try {
+            body = readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const spec of extractRootSpecifiers(body)) {
+            if (isBuiltinModule(spec))
+                continue;
+            if (spec.startsWith('.') || spec.startsWith('/'))
+                continue;
+            out.push(rootOfSpecifier(spec));
+        }
+    }
+    return out;
+}
+const IMPORT_FROM_RE = /(?:^|\n)\s*(?:import|export)\s+[^;]*?\s+from\s+['"]([^'"]+)['"]/g;
+const REQUIRE_RE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+// `await import('pkg')` / `import('pkg')` — bare dynamic imports.
+// Note: we intentionally match `\bimport\s*\(` not just `import(` so we
+// don't false-trigger on `LocaleImport(...)` etc.
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+function extractRootSpecifiers(body) {
+    const out = [];
+    for (const m of body.matchAll(IMPORT_FROM_RE)) {
+        if (m[1])
+            out.push(m[1]);
+    }
+    for (const m of body.matchAll(REQUIRE_RE)) {
+        if (m[1])
+            out.push(m[1]);
+    }
+    for (const m of body.matchAll(DYNAMIC_IMPORT_RE)) {
+        if (m[1])
+            out.push(m[1]);
+    }
+    return out;
+}
+function rootOfSpecifier(spec) {
+    if (spec.startsWith('@')) {
+        const parts = spec.split('/');
+        return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : spec;
+    }
+    return spec.split('/')[0];
+}
+function isBuiltinModule(spec) {
+    if (spec.startsWith('node:'))
+        return true;
+    return new Set([
+        'fs', 'path', 'os', 'crypto', 'http', 'https', 'url', 'util', 'stream',
+        'events', 'child_process', 'process', 'buffer', 'querystring', 'zlib',
+        'tls', 'net', 'dns', 'dgram', 'cluster', 'worker_threads', 'perf_hooks',
+        'readline', 'tty', 'vm',
+    ]).has(spec);
+}

package/dist/tools/plan-quality-review.tool.d.ts

@@ -0,0 +1,21 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * `plan_quality_review` — score a plan blob for hallucination,
+ * generic boilerplate, contradictions, and ungrounded commands.
+ *
+ * Inputs:
+ *   - `plan`: either a stringified JSON / Markdown plan body, OR a
+ *     `{ from: { slug } }` reference that resolves to a saved
+ *     `.sharkcraft/smart-context/<slug>.plan.json`.
+ *   - `recommendedCommands` (optional): the set of commands that are
+ *     considered "real" (typically `verificationCommands` from the
+ *     same focused bundle). Anything outside this set in
+ *     `firstCommands`/`validationCommands` gets flagged.
+ *
+ * Output: structured findings + an overall verdict so the calling
+ * agent can decide whether to use, retry, or reject the plan.
+ *
+ * Read-only — does not modify or rewrite the plan.
+ */
+export declare const planQualityReviewTool: IToolDefinition;
+//# sourceMappingURL=plan-quality-review.tool.d.ts.map

package/dist/tools/plan-quality-review.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-quality-review.tool.d.ts","sourceRoot":"","sources":["../../src/tools/plan-quality-review.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,EAAE,eAiFnC,CAAC"}

package/dist/tools/plan-quality-review.tool.js

@@ -0,0 +1,294 @@
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+/**
+ * `plan_quality_review` — score a plan blob for hallucination,
+ * generic boilerplate, contradictions, and ungrounded commands.
+ *
+ * Inputs:
+ *   - `plan`: either a stringified JSON / Markdown plan body, OR a
+ *     `{ from: { slug } }` reference that resolves to a saved
+ *     `.sharkcraft/smart-context/<slug>.plan.json`.
+ *   - `recommendedCommands` (optional): the set of commands that are
+ *     considered "real" (typically `verificationCommands` from the
+ *     same focused bundle). Anything outside this set in
+ *     `firstCommands`/`validationCommands` gets flagged.
+ *
+ * Output: structured findings + an overall verdict so the calling
+ * agent can decide whether to use, retry, or reject the plan.
+ *
+ * Read-only — does not modify or rewrite the plan.
+ */
+export const planQualityReviewTool = {
+    name: 'plan_quality_review',
+    description: 'Critique a plan (JSON or Markdown) for hallucinated paths, generic boilerplate, contradictions, and ungrounded commands. Read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            plan: { type: 'string' },
+            planFrom: { type: 'object' },
+            recommendedCommands: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        let planText;
+        const planFrom = input['planFrom'];
+        if (typeof input['plan'] === 'string' && input['plan'].length > 0) {
+            planText = input['plan'];
+        }
+        else if (planFrom && typeof planFrom === 'object') {
+            const slug = typeof planFrom['slug'] === 'string'
+                ? planFrom['slug']
+                : '';
+            if (slug.length === 0) {
+                return { data: { error: 'planFrom.slug is required when using planFrom' } };
+            }
+            const path = nodePath.join(ctx.cwd, '.sharkcraft', 'smart-context', `${slug}.plan.json`);
+            if (!existsSync(path)) {
+                return { data: { error: 'no-plan-for-slug', slug, lookedAt: path } };
+            }
+            try {
+                const { readFileSync } = await import('node:fs');
+                planText = readFileSync(path, 'utf8');
+            }
+            catch (e) {
+                return { data: { error: `read failed: ${e.message}` } };
+            }
+        }
+        else {
+            return { data: { error: 'one of `plan` or `planFrom` is required' } };
+        }
+        if (!planText)
+            return { data: { error: 'empty plan' } };
+        const parsed = tryExtractJson(planText);
+        const recommendedCommandsRaw = Array.isArray(input['recommendedCommands'])
+            ? input['recommendedCommands'].filter((c) => typeof c === 'string')
+            : [];
+        const knownCommands = new Set(recommendedCommandsRaw.map(normaliseCommand));
+        const findings = analysePlan({
+            cwd: ctx.cwd,
+            raw: planText,
+            parsed,
+            knownCommands,
+        });
+        const score = scoreFindings(findings);
+        const verdict = score >= 0.85
+            ? 'good'
+            : score >= 0.6
+                ? 'usable-with-review'
+                : score >= 0.35
+                    ? 'weak'
+                    : 'reject';
+        return {
+            data: {
+                verdict,
+                score,
+                parsed: parsed !== null,
+                findings,
+                handoffForClaude: verdict === 'reject'
+                    ? 'Reject this plan — too many ungrounded claims.'
+                    : verdict === 'weak'
+                        ? 'Plan is weak; consider regenerating with --polish or a stronger model.'
+                        : verdict === 'usable-with-review'
+                            ? 'Plan is usable but verify the flagged paths and commands.'
+                            : 'Plan looks well-grounded.',
+            },
+        };
+    },
+};
+function analysePlan(input) {
+    const out = [];
+    // 1. Hallucinated paths — walk the parsed JSON.
+    if (input.parsed) {
+        const seen = new Set();
+        walkPathLeaves(input.parsed, '$', (path, where) => {
+            const id = `${where}:${path}`;
+            if (seen.has(id))
+                return;
+            seen.add(id);
+            if (!looksLikePathRef(path))
+                return;
+            if (!pathExistsInWorkspace(input.cwd, path)) {
+                out.push({
+                    category: 'hallucinated-path',
+                    severity: 'high',
+                    message: `Path "${path}" does not exist in the workspace.`,
+                    where,
+                });
+            }
+        });
+    }
+    // 2. Generic boilerplate (the polish preamble's anti-patterns).
+    const genericPatterns = [
+        { re: /may require additional resources and infrastructure/i, msg: 'Generic "additional resources" boilerplate.' },
+        { re: /may introduce additional complexity/i, msg: 'Generic "additional complexity" boilerplate.' },
+        { re: /may require additional security and privacy considerations/i, msg: 'Generic "security and privacy" boilerplate.' },
+        { re: /can be implemented as a separate tool or as a plugin/i, msg: '"Can be implemented as a separate tool" — useless differentiation.' },
+        { re: /documentation and support level/i, msg: 'Enterprise-boilerplate question about "documentation and support level".' },
+        { re: /\bGET\b.*\b(cli|file|stdout|mcp)/i, msg: 'HTTP verb on a CLI/file/stdout/MCP surface.' },
+    ];
+    for (const p of genericPatterns) {
+        if (p.re.test(input.raw)) {
+            out.push({ category: 'generic-boilerplate', severity: 'medium', message: p.msg });
+        }
+    }
+    // 3. Contradictions: filesToAvoid ∩ likelyFilesToModify.
+    if (input.parsed) {
+        const avoid = collectPathSet(input.parsed['filesToAvoid']);
+        const modify = collectPathSet(input.parsed['likelyFilesToModify']);
+        const overlap = [...avoid].filter((p) => modify.has(p));
+        for (const p of overlap) {
+            out.push({
+                category: 'contradiction',
+                severity: 'high',
+                message: `"${p}" appears in both filesToAvoid and likelyFilesToModify.`,
+            });
+        }
+    }
+    // 4. Ungrounded commands.
+    if (input.parsed && input.knownCommands.size > 0) {
+        const firstCmds = collectStringArrayFromKey(input.parsed['firstCommands'], 'command');
+        const valCmds = collectStringArrayFromKey(input.parsed['validationCommands'], 'command');
+        const plainVal = collectStringArray(input.parsed['validationCommands']);
+        const all = new Set([...firstCmds, ...valCmds, ...plainVal].map(normaliseCommand));
+        for (const c of all) {
+            if (c.length === 0)
+                continue;
+            // Don't flag commands that obviously start with `git` or `bun x tsc` —
+            // those are universal even when the rule registry doesn't list them.
+            if (/^(git|bun\s+x\s+tsc|npm|pnpm|yarn)\b/.test(c))
+                continue;
+            if (!input.knownCommands.has(c)) {
+                out.push({
+                    category: 'ungrounded-command',
+                    severity: 'low',
+                    message: `Command "${c}" is not in the supplied recommendedCommands.`,
+                });
+            }
+        }
+    }
+    // 5. Missing-section heuristic for arch-plan shapes.
+    if (input.parsed) {
+        if ('candidateArchitectures' in input.parsed) {
+            // architecture mode — recommendedMvp + firstSpike are required.
+            if (!input.parsed['recommendedMvp']) {
+                out.push({
+                    category: 'missing-section',
+                    severity: 'medium',
+                    message: 'architecture plan is missing recommendedMvp.',
+                });
+            }
+            if (!input.parsed['firstSpike']) {
+                out.push({
+                    category: 'missing-section',
+                    severity: 'medium',
+                    message: 'architecture plan is missing firstSpike.',
+                });
+            }
+        }
+    }
+    return out;
+}
+function scoreFindings(findings) {
+    if (findings.length === 0)
+        return 1;
+    let penalty = 0;
+    for (const f of findings) {
+        penalty += f.severity === 'high' ? 0.2 : f.severity === 'medium' ? 0.08 : 0.03;
+    }
+    return Math.max(0, 1 - penalty);
+}
+function walkPathLeaves(value, where, visit) {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i += 1)
+            walkPathLeaves(value[i], `${where}[${i}]`, visit);
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    const rec = value;
+    for (const k of Object.keys(rec)) {
+        if (k === 'path' && typeof rec[k] === 'string') {
+            visit(rec[k], `${where}.${k}`);
+            continue;
+        }
+        walkPathLeaves(rec[k], `${where}.${k}`, visit);
+    }
+}
+function collectPathSet(value) {
+    const out = new Set();
+    if (!Array.isArray(value))
+        return out;
+    for (const item of value) {
+        if (item && typeof item === 'object' && typeof item['path'] === 'string') {
+            out.add(item['path'].trim());
+        }
+    }
+    return out;
+}
+function collectStringArrayFromKey(value, key) {
+    const out = [];
+    if (!Array.isArray(value))
+        return out;
+    for (const item of value) {
+        if (item && typeof item === 'object' && typeof item[key] === 'string') {
+            out.push(item[key].trim());
+        }
+    }
+    return out;
+}
+function collectStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((s) => typeof s === 'string');
+}
+function looksLikePathRef(s) {
+    if (s.length === 0)
+        return false;
+    if (/[<>{}]/.test(s))
+        return false;
+    if (s.includes('/'))
+        return true;
+    return /\.(ts|tsx|js|jsx|mjs|cjs|json|md|yml|yaml|css|html)$/.test(s);
+}
+function pathExistsInWorkspace(cwd, candidate) {
+    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
+    const abs = nodePath.isAbsolute(normalised) ? normalised : nodePath.join(cwd, normalised);
+    try {
+        return existsSync(abs);
+    }
+    catch {
+        return false;
+    }
+}
+function normaliseCommand(c) {
+    return c.trim().replace(/\s+/g, ' ');
+}
+function tryExtractJson(text) {
+    const trimmed = text.trim();
+    const fenced = trimmed.match(/```json\s*([\s\S]*?)```/i);
+    const candidate = fenced?.[1]?.trim() ?? trimmed;
+    try {
+        const parsed = JSON.parse(candidate);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Try balanced extraction
+    }
+    const first = candidate.indexOf('{');
+    const last = candidate.lastIndexOf('}');
+    if (first >= 0 && last > first) {
+        try {
+            const parsed = JSON.parse(candidate.slice(first, last + 1));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}

package/dist/tools/smart-context-bundle.tool.d.ts

@@ -0,0 +1,17 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * `smart_context_bundle` — read-only MCP surface for the focused
+ * context bundle that `shrk smart-context --focused` builds.
+ *
+ * The agent calls this with a task string. The tool runs BGE-based
+ * semantic search, declaration extraction, and re-ranking against
+ * the existing on-disk embedding index, then returns the bundle as
+ * JSON plus a hint pointing at the CLI commands the agent should
+ * run next.
+ *
+ * No writes. No LLM calls. If the index has not been built yet the
+ * tool returns a structured error pointing to
+ * `shrk smart-context embeddings-build`.
+ */
+export declare const smartContextBundleTool: IToolDefinition;
+//# sourceMappingURL=smart-context-bundle.tool.d.ts.map

package/dist/tools/smart-context-bundle.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-context-bundle.tool.d.ts","sourceRoot":"","sources":["../../src/tools/smart-context-bundle.tool.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,EAAE,eA6EpC,CAAC"}

package/dist/tools/smart-context-bundle.tool.js

@@ -0,0 +1,108 @@
+import { buildTaskPacket } from '@shrkcrft/inspector';
+import { SemanticIndex, TaskType, buildFocusedContext, classifyTask, parseTaskTypeOverride, } from '@shrkcrft/embeddings';
+/**
+ * `smart_context_bundle` — read-only MCP surface for the focused
+ * context bundle that `shrk smart-context --focused` builds.
+ *
+ * The agent calls this with a task string. The tool runs BGE-based
+ * semantic search, declaration extraction, and re-ranking against
+ * the existing on-disk embedding index, then returns the bundle as
+ * JSON plus a hint pointing at the CLI commands the agent should
+ * run next.
+ *
+ * No writes. No LLM calls. If the index has not been built yet the
+ * tool returns a structured error pointing to
+ * `shrk smart-context embeddings-build`.
+ */
+export const smartContextBundleTool = {
+    name: 'smart_context_bundle',
+    description: 'Build a task-focused context bundle (semantic-ranked code blocks + rules + doc hits + validation commands). Read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            task: { type: 'string' },
+            taskType: { type: 'string' },
+            maxBlocks: { type: 'number' },
+        },
+        required: ['task'],
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        const task = typeof input['task'] === 'string' ? input['task'].trim() : '';
+        if (task.length === 0) {
+            return {
+                data: {
+                    error: 'task is required',
+                },
+            };
+        }
+        const overrideRaw = typeof input['taskType'] === 'string' ? input['taskType'] : undefined;
+        const taskTypeOverride = parseTaskTypeOverride(overrideRaw);
+        const maxBlocks = typeof input['maxBlocks'] === 'number' ? input['maxBlocks'] : 10;
+        const index = await SemanticIndex.tryLoad(ctx.cwd);
+        if (!index) {
+            return {
+                data: {
+                    error: 'no-semantic-index',
+                    message: 'The semantic index has not been built for this workspace yet. The agent should ask the human to run the CLI command below.',
+                    nextCommand: 'shrk smart-context embeddings-build',
+                },
+            };
+        }
+        const classification = taskTypeOverride
+            ? { type: taskTypeOverride, confidence: 1, signals: ['override'], scores: {} }
+            : classifyTask(task);
+        const packet = buildTaskPacket(ctx.inspection, task, { maxTokens: 3500 });
+        const focused = await buildFocusedContext({
+            cwd: ctx.cwd,
+            task,
+            index,
+            rules: packet.relevantRules,
+            verificationCommands: packet.verificationCommands,
+            maxBlocks: Math.max(2, Math.min(20, maxBlocks)),
+        });
+        return {
+            data: {
+                task,
+                taskType: classification.type,
+                classification: {
+                    type: classification.type,
+                    confidence: classification.confidence,
+                    signals: classification.signals.slice(0, 6),
+                },
+                focused: {
+                    model: focused.model,
+                    approxTokens: focused.approxTokens,
+                    files: focused.files,
+                    rules: focused.rules,
+                    docHits: focused.docHits,
+                    verificationCommands: focused.verificationCommands,
+                },
+                nextCommands: nextCommandHints(task, classification.type),
+                notes: [
+                    'This bundle is read-only. To turn the recommended MVP into starter files, the human should run `shrk smart-context "<task>" --focused --plan --save` followed by `shrk spike <slug>`.',
+                ],
+            },
+        };
+    },
+};
+function nextCommandHints(task, taskType) {
+    const quotedTask = JSON.stringify(task);
+    if (taskType === TaskType.Architecture) {
+        return [
+            `shrk smart-context ${quotedTask} --focused --plan --save`,
+            `shrk smart-context list   # find the saved slug`,
+            `shrk spike <slug>          # scaffold the recommended MVP`,
+        ];
+    }
+    if (taskType === TaskType.Investigation) {
+        return [
+            `shrk smart-context ${quotedTask} --focused --save`,
+            `shrk graph why <a> <b>     # trace structural relationships`,
+        ];
+    }
+    return [
+        `shrk smart-context ${quotedTask} --focused --plan --save`,
+        `shrk spike <slug>          # if the plan has a firstSpike`,
+    ];
+}

package/dist/tools/smart-context-feed.tool.d.ts

@@ -0,0 +1,17 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * `smart_context_feed` — read-only MCP surface for an active
+ * `shrk watch` JSONL feed.
+ *
+ * Two modes:
+ *   - `list`  → returns active watch manifests under .sharkcraft/feed/.
+ *   - `tail`  → returns the JSONL tail of one slug, optionally
+ *               filtered by `since` (emittedAt ISO timestamp) or `tailLines`.
+ *
+ * The agent uses `list` first to discover which watcher is running for
+ * which task, then `tail` to pull new packets since the last call.
+ * Nothing is written; the daemon CLI (`shrk watch`) is the only
+ * producer.
+ */
+export declare const smartContextFeedTool: IToolDefinition;
+//# sourceMappingURL=smart-context-feed.tool.d.ts.map

package/dist/tools/smart-context-feed.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-context-feed.tool.d.ts","sourceRoot":"","sources":["../../src/tools/smart-context-feed.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAKpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAE,eA+BlC,CAAC"}

package/dist/tools/smart-context-feed.tool.js

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import * as nodePath from 'node:path';
+const FEED_DIR = nodePath.join('.sharkcraft', 'feed');
+const MANIFEST_SCHEMA = 'sharkcraft.shrk-watch-manifest/v1';
+/**
+ * `smart_context_feed` — read-only MCP surface for an active
+ * `shrk watch` JSONL feed.
+ *
+ * Two modes:
+ *   - `list`  → returns active watch manifests under .sharkcraft/feed/.
+ *   - `tail`  → returns the JSONL tail of one slug, optionally
+ *               filtered by `since` (emittedAt ISO timestamp) or `tailLines`.
+ *
+ * The agent uses `list` first to discover which watcher is running for
+ * which task, then `tail` to pull new packets since the last call.
+ * Nothing is written; the daemon CLI (`shrk watch`) is the only
+ * producer.
+ */
+export const smartContextFeedTool = {
+    name: 'smart_context_feed',
+    description: 'Poll the JSONL feed of an active `shrk watch` daemon. Read-only. Use mode="list" to discover slugs and mode="tail" to pull packets.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            mode: { type: 'string' },
+            slug: { type: 'string' },
+            since: { type: 'string' },
+            tailLines: { type: 'number' },
+        },
+        additionalProperties: false,
+    },
+    async handler(input, ctx) {
+        const mode = typeof input['mode'] === 'string' ? input['mode'] : 'list';
+        if (mode !== 'list' && mode !== 'tail') {
+            return { data: { error: 'invalid-mode', valid: ['list', 'tail'] } };
+        }
+        const dir = nodePath.join(ctx.cwd, FEED_DIR);
+        if (mode === 'list') {
+            return { data: listFeeds(dir) };
+        }
+        const slug = typeof input['slug'] === 'string' ? input['slug'].trim() : '';
+        if (slug.length === 0) {
+            return { data: { error: 'slug is required for mode=tail' } };
+        }
+        const since = typeof input['since'] === 'string' ? input['since'] : undefined;
+        const tailLines = typeof input['tailLines'] === 'number' ? input['tailLines'] : 50;
+        return { data: tailFeed(dir, slug, { since, tailLines }) };
+    },
+};
+function listFeeds(dir) {
+    if (!existsSync(dir))
+        return { active: [], stale: [] };
+    const active = [];
+    const stale = [];
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return { active: [], stale: [] };
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.pid.json'))
+            continue;
+        const path = nodePath.join(dir, name);
+        let m;
+        try {
+            m = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (m.schema !== MANIFEST_SCHEMA || typeof m.pid !== 'number')
+            continue;
+        const summary = {
+            slug: m.slug ?? '',
+            pid: m.pid,
+            task: m.task ?? '',
+            startedAt: m.startedAt ?? '',
+            feedPath: m.feedPath ?? '',
+            alive: isProcessAlive(m.pid),
+            feedExists: m.feedPath ? existsSync(m.feedPath) : false,
+        };
+        (summary.alive ? active : stale).push(summary);
+    }
+    return { active, stale };
+}
+function tailFeed(dir, slug, options) {
+    const feedPath = nodePath.join(dir, `${slug}.jsonl`);
+    if (!existsSync(feedPath)) {
+        return { slug, feedPath, packets: [], totalLines: 0, filteredOut: 0, feedExists: false };
+    }
+    let body;
+    try {
+        body = readFileSync(feedPath, 'utf8');
+    }
+    catch {
+        return { slug, feedPath, packets: [], totalLines: 0, filteredOut: 0, feedExists: true };
+    }
+    const rawLines = body.split('\n').filter((l) => l.trim().length > 0);
+    const packets = [];
+    let filteredOut = 0;
+    for (const line of rawLines) {
+        try {
+            const p = JSON.parse(line);
+            if (options.since) {
+                const emittedAt = typeof p['emittedAt'] === 'string' ? p['emittedAt'] : '';
+                if (emittedAt && emittedAt <= options.since) {
+                    filteredOut += 1;
+                    continue;
+                }
+            }
+            packets.push(p);
+        }
+        catch {
+            filteredOut += 1;
+        }
+    }
+    // Keep only the trailing N once filtered.
+    const tailed = options.tailLines > 0 ? packets.slice(-options.tailLines) : packets;
+    return {
+        slug,
+        feedPath,
+        packets: tailed,
+        totalLines: rawLines.length,
+        filteredOut,
+        feedExists: true,
+    };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

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