@monoes/monomindcli 2.8.3 → 2.9.1

package/dist/src/mcp-tools/monograph/health-tools.js

@@ -0,0 +1,113 @@
+import { getProjectCwd } from '../types.js';
+import { getDbPath, _isValidDb, text, computeCommitsBehind, triggerBackgroundBuildIfNeeded, STALENESS_THRESHOLD } from './shared.js';
+// ── monograph_stats ─────────────────────────────────────────────────────────
+export const monographStatsTool = {
+    name: 'monograph_stats',
+    description: 'Show node/edge/community counts and index freshness.',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+        const dbPath = getDbPath();
+        if (!_isValidDb(dbPath))
+            return text('Monograph index not built yet. Run monograph_build first.');
+        const { openDb, closeDb, countNodes, countEdges } = await import('@monoes/monograph');
+        const db = openDb(dbPath);
+        try {
+            const nodes = countNodes(db);
+            const edges = countEdges(db);
+            const meta = db.prepare('SELECT key, value FROM index_meta').all();
+            const metaStr = meta.map(m => `  ${m.key}: ${m.value}`).join('\n');
+            return text(`Monograph index stats:\n  nodes: ${nodes}\n  edges: ${edges}\n${metaStr}`);
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_health ────────────────────────────────────────────────────────
+export const monographHealthTool = {
+    name: 'monograph_health',
+    description: 'Check index staleness: compares last indexed git commit vs current HEAD.',
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { execSync } = await import('child_process');
+        const db = openDb(getDbPath());
+        try {
+            // The orchestrator writes the key as 'last_commit_hash' (orchestrator.ts:68).
+            // Fall back to legacy 'lastCommit' for indexes built with older versions.
+            const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get() ?? db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
+            const lastCommit = meta?.value ?? null;
+            if (!lastCommit) {
+                // last_commit_hash can be missing even when the index is populated
+                // (e.g. git rev-parse failed during build). Check actual data before
+                // claiming "never built".
+                const nodeCount = db.prepare('SELECT COUNT(*) AS c FROM nodes').get().c;
+                if (nodeCount > 0) {
+                    const indexedAt = db.prepare("SELECT value FROM index_meta WHERE key = 'indexed_at'").get()?.value;
+                    return text(`Index is built (${nodeCount} nodes${indexedAt ? `, indexed at ${indexedAt}` : ''}) but no commit hash was recorded — staleness tracking unavailable.\n` +
+                        'Run monograph_build to fix commit tracking.');
+                }
+                return text('Index has never been built. Run monograph_build first.');
+            }
+            if (!/^[0-9a-f]{7,40}$/i.test(lastCommit)) {
+                return text('Index metadata is corrupt: invalid commit SHA. Run monograph_build to re-index.');
+            }
+            let commitsBehind = 0;
+            try {
+                const out = execSync(`git rev-list --count ${lastCommit}..HEAD`, {
+                    cwd: getProjectCwd(), encoding: 'utf-8'
+                }).trim();
+                commitsBehind = parseInt(out, 10);
+            }
+            catch {
+                return text('Cannot check staleness: git error');
+            }
+            const status = commitsBehind === 0 ? 'FRESH' : `STALE (${commitsBehind} commits behind)`;
+            return text(`Index status: ${status}\nLast indexed commit: ${lastCommit}`);
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_staleness ─────────────────────────────────────────────────────
+export const monographStalenessTool = {
+    name: 'monograph_staleness',
+    description: 'Git staleness detection: compares the commit hash at last index build against current HEAD. When the index is more than 3 commits behind HEAD it automatically triggers a background rebuild. Returns { commitsBehind, status, triggered }.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Absolute path to the repo (defaults to project cwd)' },
+        },
+    },
+    handler: async (input) => {
+        const repoPath = input.path ?? getProjectCwd();
+        const result = await computeCommitsBehind(repoPath);
+        if (!result) {
+            return text(JSON.stringify({ commitsBehind: 0, status: 'unknown', triggered: false }));
+        }
+        const { commitsBehind } = result;
+        const triggered = triggerBackgroundBuildIfNeeded(repoPath, commitsBehind, STALENESS_THRESHOLD + 1);
+        const status = triggered ? 'building' : commitsBehind === 0 ? 'fresh' : 'stale';
+        return text(JSON.stringify({ commitsBehind, status, triggered }));
+    },
+};
+// ── monograph_doctor ────────────────────────────────────────────────────────
+export const monographDoctorTool = {
+    name: 'monograph_doctor',
+    description: 'Run platform diagnostics — checks Node version, SQLite DB health, node count, disk space.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+    handler: async (_input) => {
+        const { runDoctor } = await import('@monoes/monograph');
+        const repoPath = getProjectCwd();
+        const result = await runDoctor(repoPath);
+        const lines = result.checks.map(c => `${c.status === 'ok' ? '✅' : c.status === 'warn' ? '⚠️' : '❌'} ${c.name}: ${c.message}`);
+        if (!result.healthy)
+            lines.push('\nSome checks failed. Run monograph build to fix.');
+        return text(lines.join('\n'));
+    },
+};
+//# sourceMappingURL=health-tools.js.map

package/dist/src/mcp-tools/monograph/health-tools.js.map

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

package/dist/src/mcp-tools/monograph/impact-tools.d.ts

@@ -0,0 +1,9 @@
+import type { MCPTool } from '../types.js';
+export declare const monographImpactTool: MCPTool;
+export declare const monographApiImpactTool: MCPTool;
+export declare const monographDeadCodeTool: MCPTool;
+export declare const monographRouteMapTool: MCPTool;
+export declare const monographShapeCheckTool: MCPTool;
+export declare const monographRenameTool: MCPTool;
+export declare const monographToolMapTool: MCPTool;
+//# sourceMappingURL=impact-tools.d.ts.map

package/dist/src/mcp-tools/monograph/impact-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-tools.d.ts","sourceRoot":"","sources":["../../../../src/mcp-tools/monograph/impact-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAM3C,eAAO,MAAM,mBAAmB,EAAE,OAwEjC,CAAC;AAIF,eAAO,MAAM,sBAAsB,EAAE,OA+CpC,CAAC;AAIF,eAAO,MAAM,qBAAqB,EAAE,OAwHnC,CAAC;AAmGF,eAAO,MAAM,qBAAqB,EAAE,OAiCnC,CAAC;AAIF,eAAO,MAAM,uBAAuB,EAAE,OAsDrC,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,OA4CjC,CAAC;AAIF,eAAO,MAAM,oBAAoB,EAAE,OAyBlC,CAAC"}

package/dist/src/mcp-tools/monograph/impact-tools.js

@@ -0,0 +1,532 @@
+import { join } from 'path';
+import { existsSync, readdirSync } from 'fs';
+import { getProjectCwd } from '../types.js';
+import { getDbPath, _isValidDb, text } from './shared.js';
+// ── monograph_impact ──────────────────────────────────────────────────────────
+export const monographImpactTool = {
+    name: 'monograph_impact',
+    description: 'Blast radius analysis: finds all direct and transitive callers of a symbol and computes a risk score.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Symbol name to analyze' },
+            filePath: { type: 'string', description: 'Optional file path to disambiguate' },
+            depth: { type: 'number', description: 'Max BFS depth (default 3, max 6)' },
+        },
+        required: ['name'],
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { getMonographImpact } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        try {
+            // Cap name/filePath; enforce depth ≤ 6 as documented in the schema description.
+            const MAX_IMPACT_NAME_LEN = 512;
+            const MAX_IMPACT_PATH_LEN = 4 * 1024;
+            const rawImpactName = input.name;
+            const impactName = typeof rawImpactName === 'string' && rawImpactName.length > MAX_IMPACT_NAME_LEN
+                ? rawImpactName.slice(0, MAX_IMPACT_NAME_LEN) : rawImpactName;
+            const rawImpactPath = input.filePath;
+            const impactPath = typeof rawImpactPath === 'string' && rawImpactPath.length > MAX_IMPACT_PATH_LEN
+                ? rawImpactPath.slice(0, MAX_IMPACT_PATH_LEN) : rawImpactPath;
+            const rawDepth = input.depth;
+            const depth = rawDepth === undefined
+                ? undefined
+                : (typeof rawDepth === 'number' && Number.isFinite(rawDepth) && rawDepth > 0
+                    ? Math.min(Math.floor(rawDepth), 6) : 3);
+            const result = getMonographImpact(db, {
+                name: impactName,
+                filePath: impactPath,
+                depth,
+            });
+            if (!result || !result.node)
+                return text(`No symbol found: ${impactName}`);
+            // Format impact as structured text for direct LLM consumption
+            const root = result.node;
+            const rootLoc = root.filePath ? (root.startLine != null ? `${root.filePath}:${root.startLine}` : root.filePath) : '';
+            const lines = [
+                `[${root.label ?? '?'}] ${root.name}  ${rootLoc}`,
+                '',
+                `Blast radius: ${result.affectedFiles?.length ?? 0} symbols affected`,
+            ];
+            if (result.riskScore != null) {
+                const riskLabel = result.riskScore >= 0.8 ? 'HIGH' : result.riskScore >= 0.5 ? 'MEDIUM' : 'LOW';
+                lines.push(`Risk score: ${result.riskScore.toFixed(2)} (${riskLabel})`);
+            }
+            lines.push('');
+            const affected = [
+                ...(result.directCallers ?? []),
+                ...(result.transitiveCallers ?? []).flatMap(t => t.nodes ?? []),
+            ];
+            if (affected.length > 0) {
+                lines.push(`Affected callers (${affected.length}):`);
+                for (const sym of affected.slice(0, 20)) {
+                    const fp = sym.filePath ?? sym.file_path ?? '';
+                    const ln = sym.startLine ?? sym.start_line;
+                    const symLoc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    const depth_marker = sym.depth != null ? ` [depth ${sym.depth}]` : '';
+                    lines.push(`  [${sym.label ?? '?'}] ${sym.name ?? sym.id}  ${symLoc}${depth_marker}`);
+                }
+                if (affected.length > 20)
+                    lines.push(`  … ${affected.length - 20} more`);
+            }
+            return text(lines.join('\n').trim());
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_api_impact ──────────────────────────────────────────────────────
+export const monographApiImpactTool = {
+    name: 'monograph_api_impact',
+    description: 'Analyze the blast radius of an API route: finds the handler, performs forward BFS through CALLS edges, and computes a risk score.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            routePath: { type: 'string', description: 'Route path to analyze (e.g. /api/users)' },
+            method: { type: 'string', description: 'Optional HTTP method filter: GET, POST, etc.' },
+        },
+        required: ['routePath'],
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { getMonographApiImpact } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        try {
+            const result = getMonographApiImpact(db, {
+                routePath: input.routePath,
+                method: input.method,
+            });
+            if (!result.route)
+                return text(`Route not found: ${input.routePath}. Run monograph_build or check the path.`);
+            const riskLabel = result.riskScore >= 0.7 ? 'HIGH' : result.riskScore >= 0.4 ? 'MEDIUM' : 'LOW';
+            const lines = [
+                `Route: ${result.route.method} ${result.route.path}  risk=${riskLabel} (${result.riskScore.toFixed(2)})`,
+            ];
+            if (result.handler) {
+                const hLoc = result.handler.filePath
+                    ? (result.handler.startLine != null ? `${result.handler.filePath}:${result.handler.startLine}` : result.handler.filePath)
+                    : '';
+                lines.push(`Handler: ${result.handler.name}${hLoc ? `  ${hLoc}` : ''}`);
+            }
+            if (result.callees.length > 0) {
+                lines.push(`Callees (${result.callees.length}):`);
+                for (const c of result.callees.slice(0, 15)) {
+                    const loc = c.node.filePath
+                        ? (c.node.startLine != null ? `${c.node.filePath}:${c.node.startLine}` : c.node.filePath)
+                        : '';
+                    lines.push(`  ${'  '.repeat(c.depth)}→ ${c.node.name} [${c.node.label}]${loc ? `  ${loc}` : ''}`);
+                }
+                if (result.callees.length > 15)
+                    lines.push(`  … ${result.callees.length - 15} more`);
+            }
+            if (result.affectedProcesses.length > 0) {
+                lines.push(`Affected processes: ${result.affectedProcesses.map(p => p.name).join(', ')}`);
+            }
+            return text(lines.join('\n'));
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_dead_code ──────────────────────────────────────────────────────
+export const monographDeadCodeTool = {
+    name: 'monograph_dead_code',
+    description: 'Detect dead code: exported functions with zero inbound references, files with no importers, and stale dist build artifacts. Returns structured JSON with candidates grouped by category. Always verify candidates with grep before deleting.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Absolute path to the repo (defaults to project cwd)' },
+            categories: {
+                type: 'array',
+                items: { type: 'string', enum: ['dead-functions', 'orphan-files', 'stale-dist'] },
+                description: 'Which categories to check (default: all three)',
+            },
+        },
+    },
+    handler: async (input) => {
+        const { openDb } = await import('@monoes/monograph');
+        const repoPath = input.path ?? getProjectCwd();
+        const cats = input.categories ?? ['dead-functions', 'orphan-files', 'stale-dist'];
+        const result = {};
+        const dbPath = getDbPath(repoPath);
+        // openDb's fileMustExist option isn't in the currently-published
+        // @monoes/monograph release this CLI depends on — check validity
+        // ourselves so a missing DB doesn't get silently auto-created empty.
+        if (!_isValidDb(dbPath)) {
+            return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));
+        }
+        let db = null;
+        try {
+            db = openDb(dbPath);
+            // _isValidDb's size check can't distinguish a real index from an
+            // empty-but-schema-migrated DB (better-sqlite3 auto-creates + migrates
+            // on open, and other unguarded openDb() call sites in this file can
+            // create exactly that as a side effect of an unrelated tool call before
+            // monograph_build ever runs). Verify actual content post-open so this
+            // reports "never built" instead of a misleading "0 dead functions found".
+            const { count } = db.prepare('SELECT COUNT(*) as count FROM nodes').get();
+            if (count === 0) {
+                return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));
+            }
+        }
+        catch {
+            return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));
+        }
+        try {
+            if (cats.includes('dead-functions')) {
+                const { detectDeadCodeNodes } = await import('@monoes/monograph');
+                const { readFileSync } = await import('fs');
+                const nodes = detectDeadCodeNodes(db);
+                // Filter out stale graph nodes: verify the function name actually appears in the source file
+                const verified = nodes.filter(n => {
+                    if (!n.filePath)
+                        return false;
+                    try {
+                        const content = readFileSync(join(repoPath, n.filePath), 'utf-8');
+                        return content.includes(n.name);
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                const staleCount = nodes.length - verified.length;
+                result['dead-functions'] = {
+                    count: verified.length,
+                    candidates: verified.map(n => ({
+                        name: n.name,
+                        location: n.filePath ? (n.startLine ? `${n.filePath}:${n.startLine}` : n.filePath) : null,
+                    })),
+                    ...(staleCount > 0 ? { staleIndexEntries: staleCount, note: 'Some graph entries reference deleted functions. Rebuild the index with monograph_build to clean up.' } : {}),
+                };
+            }
+            if (cats.includes('orphan-files')) {
+                const rows = db.prepare(`
+          SELECT n.name, n.file_path,
+            (SELECT COUNT(*) FROM edges e WHERE e.source_id = n.id AND e.relation = 'IMPORTS') as imports_out,
+            (SELECT COUNT(*) FROM edges e WHERE e.target_id = n.id AND e.relation = 'IMPORTS') as imported_by
+          FROM nodes n
+          WHERE n.label = 'File'
+            AND (SELECT COUNT(*) FROM edges e WHERE e.target_id = n.id AND e.relation = 'IMPORTS') = 0
+            AND n.file_path NOT LIKE '%/test/%'
+            AND n.file_path NOT LIKE '%/tests/%'
+            AND n.file_path NOT LIKE '%.test.%'
+            AND n.file_path NOT LIKE '%__tests__%'
+            AND n.file_path NOT LIKE '%/spec/%'
+            AND n.file_path NOT LIKE '%.spec.%'
+            AND n.file_path NOT LIKE '%/index.%'
+            AND n.file_path NOT LIKE 'bin/%'
+            AND n.file_path NOT LIKE 'scripts/%'
+            AND n.file_path NOT LIKE '%/cli.ts'
+            AND n.file_path NOT LIKE '%/cli.js'
+            AND n.file_path NOT LIKE '%/main.ts'
+            AND n.file_path NOT LIKE '%/main.js'
+            AND n.file_path NOT LIKE '%/dist/%'
+            AND n.file_path NOT LIKE '%node_modules%'
+          ORDER BY n.file_path
+        `).all();
+                const withOutbound = rows.filter((r) => r.imports_out > 0);
+                const isolated = rows.filter((r) => r.imports_out === 0);
+                result['orphan-files'] = {
+                    count: withOutbound.length,
+                    note: 'Files that import other modules but nothing imports them. May be lazy-loaded or dynamically imported — verify with grep.',
+                    candidates: withOutbound.map((r) => ({ file: r.file_path, outboundImports: r.imports_out })),
+                    ...(isolated.length > 0 ? {
+                        isolated: {
+                            count: isolated.length,
+                            note: 'Files with zero edges in either direction — likely standalone scripts or entry points.',
+                            files: isolated.map((r) => r.file_path),
+                        },
+                    } : {}),
+                };
+            }
+            if (cats.includes('stale-dist')) {
+                result['stale-dist'] = findStaleDist(repoPath);
+            }
+            return text(JSON.stringify(result, null, 2));
+        }
+        finally {
+            db.close();
+        }
+    },
+};
+function findStaleDist(repoPath) {
+    const distSrc = join(repoPath, 'dist', 'src');
+    const src = join(repoPath, 'src');
+    // Scan a single package for stale dist artifacts
+    const scanPkg = (pkgPath, pkgName) => {
+        const pkgDistSrc = join(pkgPath, 'dist', 'src');
+        const pkgSrc = join(pkgPath, 'src');
+        if (!existsSync(pkgDistSrc) || !existsSync(pkgSrc))
+            return null;
+        const staleDirs = [];
+        const staleFiles = [];
+        let resourceForks = 0;
+        try {
+            const distDirs = readdirSync(pkgDistSrc, { withFileTypes: true })
+                .filter(d => d.isDirectory() && !d.name.startsWith('.') && !d.name.startsWith('._'));
+            const srcDirs = new Set(readdirSync(pkgSrc, { withFileTypes: true })
+                .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+                .map(d => d.name));
+            for (const d of distDirs) {
+                if (!srcDirs.has(d.name))
+                    staleDirs.push(d.name);
+            }
+        }
+        catch { /* skip */ }
+        try {
+            const distFiles = readdirSync(pkgDistSrc)
+                .filter(f => f.endsWith('.js') && !f.startsWith('.') && !f.startsWith('._'));
+            for (const f of distFiles) {
+                const tsName = f.replace(/\.js$/, '.ts');
+                if (!existsSync(join(pkgSrc, tsName)))
+                    staleFiles.push(f);
+            }
+        }
+        catch { /* skip */ }
+        // Count macOS resource fork files
+        const countRF = (dir) => {
+            try {
+                for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                    if (entry.name.startsWith('._'))
+                        resourceForks++;
+                    else if (entry.isDirectory())
+                        countRF(join(dir, entry.name));
+                }
+            }
+            catch { /* skip */ }
+        };
+        countRF(pkgDistSrc);
+        if (staleDirs.length === 0 && staleFiles.length === 0 && resourceForks === 0)
+            return null;
+        return {
+            package: pkgName,
+            staleDirs,
+            staleFiles,
+            ...(resourceForks > 0 ? { macosResourceForks: resourceForks } : {}),
+        };
+    };
+    // Single-package repo
+    if (existsSync(distSrc) && existsSync(src)) {
+        const finding = scanPkg(repoPath, '.');
+        return {
+            count: finding ? finding.staleDirs.length + finding.staleFiles.length : 0,
+            note: 'Directories/files in dist/src/ with no corresponding source. Fix: rm -rf dist && npm run build.',
+            ...(finding ? { findings: [finding] } : {}),
+        };
+    }
+    // Monorepo: scan all packages
+    const packagesDir = join(repoPath, 'packages');
+    if (!existsSync(packagesDir))
+        return { count: 0, note: 'No dist/src or packages/ found' };
+    const findings = [];
+    try {
+        for (const scope of readdirSync(packagesDir, { withFileTypes: true })) {
+            if (!scope.isDirectory())
+                continue;
+            const scopeDir = join(packagesDir, scope.name);
+            if (scope.name.startsWith('@')) {
+                for (const pkg of readdirSync(scopeDir, { withFileTypes: true })) {
+                    if (!pkg.isDirectory())
+                        continue;
+                    const f = scanPkg(join(scopeDir, pkg.name), `${scope.name}/${pkg.name}`);
+                    if (f)
+                        findings.push(f);
+                }
+            }
+            else {
+                const f = scanPkg(scopeDir, scope.name);
+                if (f)
+                    findings.push(f);
+            }
+        }
+    }
+    catch { /* skip */ }
+    return {
+        count: findings.reduce((s, f) => s + (f.staleDirs?.length ?? 0) + (f.staleFiles?.length ?? 0), 0),
+        note: 'Directories/files in dist/src/ with no corresponding source. Fix: rm -rf dist && npm run build.',
+        findings,
+    };
+}
+// ── monograph_route_map ───────────────────────────────────────────────────────
+export const monographRouteMapTool = {
+    name: 'monograph_route_map',
+    description: 'List all HTTP routes in the codebase with their handler info. Supports filtering by URL prefix or HTTP method.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            prefix: { type: 'string', description: 'Filter routes whose path contains this prefix (e.g. /api)' },
+            method: { type: 'string', description: 'Filter by HTTP method: GET, POST, PUT, DELETE, PATCH, ANY' },
+            includeMiddleware: { type: 'boolean', description: 'Include middleware/use routes (default: false)' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { getMonographRouteMap } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        try {
+            const result = getMonographRouteMap(db, {
+                prefix: input.prefix,
+                method: input.method,
+                includeMiddleware: input.includeMiddleware,
+            });
+            if (result.routes.length === 0)
+                return text('No routes found. Run monograph_build first or adjust your filters.');
+            const lines = [`Routes (${result.total} total):`];
+            for (const r of result.routes) {
+                const loc = r.handlerFile
+                    ? (r.handlerLine != null ? `${r.handlerFile}:${r.handlerLine}` : r.handlerFile)
+                    : '';
+                const mw = r.middlewareChain.length > 0 ? `  middleware: ${r.middlewareChain.join(' → ')}` : '';
+                lines.push(`  ${r.method} ${r.path}${r.handlerName ? ` → ${r.handlerName}` : ''}${loc ? `  (${loc})` : ''}${mw}`);
+            }
+            return text(lines.join('\n'));
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_shape_check ─────────────────────────────────────────────────────
+export const monographShapeCheckTool = {
+    name: 'monograph_shape_check',
+    description: 'Validate API route response shapes: checks that handler return keys match consumer property accesses. Detects shape mismatches between producer and consumer.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            route: { type: 'string', description: 'Filter by route path substring (e.g. /api/users)' },
+            file: { type: 'string', description: 'Filter by source file path substring' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { getShapeCheck } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        const repoPath = getProjectCwd();
+        try {
+            const result = getShapeCheck(db, repoPath, {
+                route: input.route,
+                file: input.file,
+            });
+            // Render as structured text so LLMs can act on it directly without parsing JSON.
+            const lines = [];
+            lines.push(`Shape check: ${result.message}`);
+            if (result.route) {
+                const handlerLoc = result.route.handlerFile
+                    ? `  Handler: ${result.route.handlerName}  [${result.route.handlerFile}]`
+                    : `  Handler: ${result.route.handlerName}`;
+                lines.push(`Route: ${result.route.method} ${result.route.path}`);
+                lines.push(handlerLoc);
+            }
+            if (result.shape.returnedKeys.length > 0) {
+                lines.push(`  Returned keys: ${result.shape.returnedKeys.join(', ')}`);
+            }
+            if (result.shape.accessedKeys.length > 0) {
+                lines.push(`  Accessed keys: ${result.shape.accessedKeys.join(', ')}`);
+            }
+            if (result.shape.mismatches.length > 0) {
+                lines.push(`  Mismatches (accessed but not returned): ${result.shape.mismatches.join(', ')}`);
+            }
+            if (result.shape.extra.length > 0) {
+                lines.push(`  Unused returned keys: ${result.shape.extra.join(', ')}`);
+            }
+            if (result.consumers.length > 0) {
+                lines.push(`  Consumers (${result.consumers.length}):`);
+                for (const c of result.consumers.slice(0, 10)) {
+                    lines.push(`    - ${c.name}  [${c.filePath}]`);
+                }
+                if (result.consumers.length > 10) {
+                    lines.push(`    … ${result.consumers.length - 10} more`);
+                }
+            }
+            return text(lines.join('\n'));
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_rename ──────────────────────────────────────────────────────────
+export const monographRenameTool = {
+    name: 'monograph_rename',
+    description: 'Dry-run multi-file rename: finds all references to a symbol and shows before/after diffs without writing files.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            oldName: { type: 'string', description: 'Current symbol name' },
+            newName: { type: 'string', description: 'New symbol name' },
+            filePath: { type: 'string', description: 'Optional file path to disambiguate the symbol' },
+            dryRun: { type: 'boolean', description: 'Always true — files are never modified (default: true)' },
+        },
+        required: ['oldName', 'newName'],
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { getMonographRename } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        try {
+            const result = getMonographRename(db, {
+                oldName: input.oldName,
+                newName: input.newName,
+                filePath: input.filePath,
+                dryRun: input.dryRun ?? true,
+            });
+            // Format as structured text for direct LLM navigation instead of raw JSON
+            const rn = result;
+            if (!rn)
+                return text(`Symbol not found: ${input.oldName}`);
+            const occurrences = rn.occurrences ?? rn.references ?? [];
+            const lines = [
+                `Rename: ${input.oldName} → ${input.newName}  (dry-run)`,
+                `Occurrences: ${occurrences.length}`,
+                '',
+            ];
+            for (const occ of occurrences.slice(0, 30)) {
+                const fp = occ.filePath ?? occ.file_path ?? '';
+                const ln = occ.line ?? occ.startLine ?? occ.start_line;
+                const loc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                lines.push(`  ${loc || occ}`);
+            }
+            if (occurrences.length > 30)
+                lines.push(`  … ${occurrences.length - 30} more`);
+            return text(lines.join('\n').trim());
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_tool_map ────────────────────────────────────────────────────────
+export const monographToolMapTool = {
+    name: 'monograph_tool_map',
+    description: 'List MCP/RPC tool definitions in the knowledge graph with handler associations. Shows which functions handle each tool.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            tool: { type: 'string', description: 'Filter by tool name substring' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { getToolMap } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        try {
+            const results = getToolMap(db, { tool: input.tool });
+            if (results.length === 0)
+                return text('No tools found. Run monograph_build first.');
+            const lines = results.map(r => {
+                const loc = r.handlerFile
+                    ? (r.handlerLine != null ? `${r.handlerFile}:${r.handlerLine}` : r.handlerFile)
+                    : (r.filePath ?? '');
+                return `${r.name}${r.handlerName ? ` → ${r.handlerName}` : ''}${loc ? `  (${loc})` : ''}`;
+            });
+            return text(`Tools (${results.length}):\n${lines.join('\n')}`);
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+//# sourceMappingURL=impact-tools.js.map