@monoes/monomindcli 1.11.14 → 1.13.0

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

@@ -22,6 +22,7 @@ const monographBuildTool = {
             path: { type: 'string', description: 'Absolute path to the repo (defaults to project cwd)' },
             codeOnly: { type: 'boolean', description: 'Only index code files (skip docs, config)' },
             force: { type: 'boolean', description: 'Force full rebuild even if index is fresh' },
+            incremental: { type: 'boolean', description: 'Skip rebuild when index already matches HEAD (default false). Use when you want a no-op if the graph is fresh.' },
         },
     },
     handler: async (input) => {
@@ -31,9 +32,12 @@ const monographBuildTool = {
         await buildAsync(repoPath, {
             codeOnly: input.codeOnly ?? false,
             force: input.force ?? false,
+            incremental: input.incremental ?? false,
             onProgress: (p) => { progressLog += `[${p.phase}] ${p.message ?? ''}\n`; },
         });
-        return text(`Monograph build complete for ${repoPath}\n${progressLog}`);
+        const skipped = progressLog.includes('skipping rebuild');
+        const summary = skipped ? `Index was already fresh — no rebuild needed for ${repoPath}` : `Monograph build complete for ${repoPath}`;
+        return text(`${summary}\n${progressLog}`);
     },
 };
 // ── monograph_query ───────────────────────────────────────────────────────────
@@ -54,19 +58,38 @@ const monographQueryTool = {
         const { hybridQuery } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const limit = input.limit ?? 20;
+            // Cap limit: passed directly to SQLite queries and hybridQuery; an
+            // unlimited value saturates memory with rows.
+            const MAX_QUERY_LIMIT = 1_000;
+            const rawLimit = input.limit ?? 20;
+            const limit = Number.isFinite(rawLimit) && rawLimit > 0
+                ? Math.min(Math.floor(rawLimit), MAX_QUERY_LIMIT)
+                : 20;
+            // Cap query: passed to FTS5 and hybridQuery; very long queries waste
+            // parse time and can stress the FTS tokenizer.
+            const MAX_MONOGRAPH_QUERY_LEN = 16 * 1024;
+            const rawQuery = input.query;
+            const query = typeof rawQuery === 'string' && rawQuery.length > MAX_MONOGRAPH_QUERY_LEN
+                ? rawQuery.slice(0, MAX_MONOGRAPH_QUERY_LEN)
+                : rawQuery;
             const label = input.label;
             if (process.env['MONOGRAPH_EMBEDDINGS'] === 'true') {
-                const results = await hybridQuery(db, input.query, { limit, label });
+                const results = await hybridQuery(db, query, { limit, label });
                 if (results.length === 0)
                     return text('No results found.');
-                const lines = results.map(r => `[${r.label ?? '?'}] ${r.name ?? r.id}  ${r.filePath ?? ''}  (score: ${r.score.toFixed(4)})`);
+                const lines = results.map(r => {
+                    const loc = r.filePath ? (r.startLine != null ? `${r.filePath}:${r.startLine}` : r.filePath) : '';
+                    return `[${r.label ?? '?'}] ${r.name ?? r.id}  ${loc}  (score: ${r.score.toFixed(4)})`;
+                });
                 return text(lines.join('\n'));
             }
-            const results = ftsSearch(db, input.query, limit, label);
+            const results = ftsSearch(db, query, limit, label);
             if (results.length === 0)
                 return text('No results found.');
-            const lines = results.map(r => `[${r.label}] ${r.name}  ${r.filePath ?? ''}  (score: ${r.rank.toFixed(3)})`);
+            const lines = results.map(r => {
+                const loc = r.filePath ? (r.startLine != null ? `${r.filePath}:${r.startLine}` : r.filePath) : '';
+                return `[${r.label}] ${r.name}  ${loc}  (score: ${r.rank.toFixed(3)})`;
+            });
             return text(lines.join('\n'));
         }
         finally {
@@ -104,7 +127,9 @@ const monographHealthTool = {
         const { execSync } = await import('child_process');
         const db = openDb(getDbPath());
         try {
-            const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
+            // 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)
                 return text('Index has never been built. Run monograph_build first.');
@@ -141,10 +166,15 @@ const monographGodNodesTool = {
         const { openDb, closeDb } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const limit = input.limit ?? 20;
+            // Cap limit: passed directly to the SQL LIMIT clause.
+            const MAX_GOD_NODES_LIMIT = 1_000;
+            const rawGodLimit = input.limit ?? 20;
+            const limit = Number.isFinite(rawGodLimit) && rawGodLimit > 0
+                ? Math.min(Math.floor(rawGodLimit), MAX_GOD_NODES_LIMIT)
+                : 20;
             const excluded = ['File', 'Folder', 'Community', 'Concept'];
             const rows = db.prepare(`
-        SELECT n.id, n.label, n.name, n.file_path,
+        SELECT n.id, n.label, n.name, n.file_path, n.start_line,
                COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) AS degree,
                COUNT(DISTINCT e2.id) AS in_degree,
                COUNT(DISTINCT e1.id) AS out_degree
@@ -157,7 +187,10 @@ const monographGodNodesTool = {
       `).all(...excluded, limit);
             if (rows.length === 0)
                 return text('No god nodes found. Run monograph_build first.');
-            const lines = rows.map(r => `[${r.label}] ${r.name}  degree=${r.degree} (↑${r.out_degree} ↓${r.in_degree})  ${r.file_path ?? ''}`);
+            const lines = rows.map(r => {
+                const loc = r.file_path ? (r.start_line != null ? `${r.file_path}:${r.start_line}` : r.file_path) : '';
+                return `[${r.label}] ${r.name}  degree=${r.degree} (↑${r.out_degree} ↓${r.in_degree})  ${loc}`;
+            });
             return text(lines.join('\n'));
         }
         finally {
@@ -215,7 +248,15 @@ const monographShortestPathTool = {
             const path = getShortestPath(db, input.source, input.target, input.maxDepth ?? 6);
             if (!path)
                 return text(`No path found between ${input.source} and ${input.target}`);
-            return text(`Path (${path.length - 1} hops):\n${path.join(' → ')}`);
+            // Enrich each node ID with file:line for direct LLM navigation
+            const enriched = path.map(nodeId => {
+                const row = db.prepare('SELECT label, name, file_path, start_line FROM nodes WHERE id = ? OR name = ? LIMIT 1').get(nodeId, nodeId);
+                if (!row)
+                    return nodeId;
+                const loc = row.file_path ? (row.start_line != null ? `${row.file_path}:${row.start_line}` : row.file_path) : '';
+                return loc ? `${row.name ?? nodeId}  [${loc}]` : (row.name ?? nodeId);
+            });
+            return text(`Path (${path.length - 1} hops):\n${enriched.join(' → ')}`);
         }
         finally {
             closeDb(db);
@@ -234,13 +275,24 @@ const monographCommunityTool = {
         required: ['id'],
     },
     handler: async (input) => {
+        // Validate community ID — must be a finite integer. parseInt(NaN) or a float
+        // would silently become 0 in SQLite (NaN → NULL → 0 coercion), which would
+        // return all nodes in community 0 instead of an error.
+        const rawId = typeof input.id === 'number' ? input.id : parseInt(String(input.id), 10);
+        if (!Number.isFinite(rawId) || rawId !== Math.floor(rawId)) {
+            return text(`Invalid community ID: ${input.id} (must be an integer)`);
+        }
+        const communityId = rawId;
         const { openDb, closeDb } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const rows = db.prepare('SELECT * FROM nodes WHERE community_id = ?').all(parseInt(input.id, 10));
+            const rows = db.prepare('SELECT id, label, name, file_path, start_line FROM nodes WHERE community_id = ?').all(communityId);
             if (rows.length === 0)
-                return text(`No nodes in community ${input.id}`);
-            return text(rows.map(r => `[${r.label}] ${r.name}  ${r.file_path ?? ''}`).join('\n'));
+                return text(`No nodes in community ${communityId}`);
+            return text(rows.map(r => {
+                const loc = r.file_path ? (r.start_line != null ? `${r.file_path}:${r.start_line}` : r.file_path) : '';
+                return `[${r.label}] ${r.name}  ${loc}`;
+            }).join('\n'));
         }
         finally {
             closeDb(db);
@@ -259,9 +311,16 @@ const monographSurprisesTool = {
         const { openDb, closeDb } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const limit = input.limit ?? 20;
+            // Cap limit: passed directly to the SQL LIMIT clause.
+            const MAX_SURPRISES_LIMIT = 1_000;
+            const rawSurprisesLimit = input.limit ?? 20;
+            const limit = Number.isFinite(rawSurprisesLimit) && rawSurprisesLimit > 0
+                ? Math.min(Math.floor(rawSurprisesLimit), MAX_SURPRISES_LIMIT)
+                : 20;
             const rows = db.prepare(`
-        SELECT e.*, n1.name as src_name, n2.name as tgt_name
+        SELECT e.confidence, e.confidence_score, e.relation,
+               n1.name as src_name, n1.file_path as src_file, n1.start_line as src_line,
+               n2.name as tgt_name, n2.file_path as tgt_file, n2.start_line as tgt_line
         FROM edges e
         JOIN nodes n1 ON n1.id = e.source_id
         JOIN nodes n2 ON n2.id = e.target_id
@@ -270,7 +329,12 @@ const monographSurprisesTool = {
       `).all(limit);
             if (rows.length === 0)
                 return text('No surprising connections found.');
-            return text(rows.map(r => `[${r.confidence}] ${r.src_name} --${r.relation}--> ${r.tgt_name} (score: ${r.confidence_score})`).join('\n'));
+            return text(rows.map(r => {
+                const srcLoc = r.src_file ? (r.src_line != null ? `${r.src_file}:${r.src_line}` : r.src_file) : '';
+                const tgtLoc = r.tgt_file ? (r.tgt_line != null ? `${r.tgt_file}:${r.tgt_line}` : r.tgt_file) : '';
+                const locHint = srcLoc || tgtLoc ? `  [${srcLoc}${tgtLoc ? ` → ${tgtLoc}` : ''}]` : '';
+                return `[${r.confidence}] ${r.src_name} --${r.relation}--> ${r.tgt_name} (score: ${r.confidence_score})${locHint}`;
+            }).join('\n'));
         }
         finally {
             closeDb(db);
@@ -293,8 +357,26 @@ const monographSuggestTool = {
         const { hybridQuery } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const limit = input.limit ?? 10;
-            const task = input.task ?? '';
+            // Cap limit and task: limit is passed directly to SQL LIMIT clause;
+            // task is forwarded to hybridQuery (embedding path) or FTS.
+            const MAX_SUGGEST_LIMIT = 1_000;
+            const MAX_SUGGEST_TASK_LEN = 16 * 1024;
+            const rawSuggestLimit = input.limit ?? 10;
+            const limit = Number.isFinite(rawSuggestLimit) && rawSuggestLimit > 0
+                ? Math.min(Math.floor(rawSuggestLimit), MAX_SUGGEST_LIMIT)
+                : 10;
+            const rawTask = input.task ?? '';
+            const task = typeof rawTask === 'string' && rawTask.length > MAX_SUGGEST_TASK_LEN
+                ? rawTask.slice(0, MAX_SUGGEST_TASK_LEN)
+                : rawTask;
+            // Format a suggestion row as a navigable string for LLM consumption.
+            // Includes file:line references so the LLM can jump directly to the code.
+            const formatSuggestion = (r) => {
+                const srcLoc = r.src_file ? (r.src_line != null ? `${r.src_file}:${r.src_line}` : r.src_file) : '';
+                const tgtLoc = r.tgt_file ? (r.tgt_line != null ? `${r.tgt_file}:${r.tgt_line}` : r.tgt_file) : '';
+                const locHint = srcLoc ? `  [${srcLoc}${tgtLoc ? ` → ${tgtLoc}` : ''}]` : '';
+                return `Why does ${r.src} ${r.relation.toLowerCase()} ${r.tgt}? (${r.confidence})${locHint}`;
+            };
             // When a task is provided and embeddings are enabled, use semantic search
             // to find relevant nodes and surface edge-level questions about them.
             if (task && process.env['MONOGRAPH_EMBEDDINGS'] === 'true') {
@@ -304,7 +386,9 @@ const monographSuggestTool = {
                     return text('No suggestions for this task. Run monograph_build first or try a different query.');
                 }
                 const rows = db.prepare(`
-          SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt, n1.file_path as src_file
+          SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt,
+                 n1.file_path as src_file, n1.start_line as src_line,
+                 n2.file_path as tgt_file, n2.start_line as tgt_line
           FROM edges e
           JOIN nodes n1 ON n1.id = e.source_id
           JOIN nodes n2 ON n2.id = e.target_id
@@ -313,11 +397,13 @@ const monographSuggestTool = {
           AND e.confidence IN ('AMBIGUOUS', 'INFERRED')
           LIMIT 100
         `).all(...[...hitIds], ...[...hitIds]);
-                const questions = rows.map(r => `Why does ${r.src} ${r.relation.toLowerCase()} ${r.tgt}? (${r.confidence})`);
+                const questions = rows.map(formatSuggestion);
                 return text(questions.slice(0, limit).join('\n') || 'No suggestions for this task. Run monograph_build first.');
             }
             const rows = db.prepare(`
-        SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt, n1.file_path as src_file
+        SELECT e.relation, e.confidence, n1.name as src, n2.name as tgt,
+               n1.file_path as src_file, n1.start_line as src_line,
+               n2.file_path as tgt_file, n2.start_line as tgt_line
         FROM edges e
         JOIN nodes n1 ON n1.id = e.source_id
         JOIN nodes n2 ON n2.id = e.target_id
@@ -325,7 +411,7 @@ const monographSuggestTool = {
         LIMIT 100
       `).all();
             let scored = rows.map(r => ({
-                q: `Why does ${r.src} ${r.relation.toLowerCase()} ${r.tgt}? (${r.confidence})`,
+                q: formatSuggestion(r),
                 relevance: task ? taskRelevance(task, r.src + ' ' + r.tgt + ' ' + (r.src_file ?? '')) : 0,
             }));
             if (task)
@@ -357,7 +443,13 @@ const monographVisualizeTool = {
         const { openDb, closeDb, toJson, toHtml, toSvg } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const limit = input.maxNodes ?? 500;
+            // Cap maxNodes: passed to SQL LIMIT clause for both nodes (n) and edges
+            // (n*3).  Without a cap an attacker requests all rows from both tables.
+            const MAX_EXPORT_NODES = 10_000;
+            const rawMaxNodes = input.maxNodes ?? 500;
+            const limit = Number.isFinite(rawMaxNodes) && rawMaxNodes > 0
+                ? Math.min(Math.floor(rawMaxNodes), MAX_EXPORT_NODES)
+                : 500;
             const nodes = db.prepare('SELECT * FROM nodes LIMIT ?').all(limit);
             const edges = db.prepare('SELECT * FROM edges LIMIT ?').all(limit * 3);
             const fmt = input.format ?? 'html';
@@ -420,7 +512,7 @@ const monographReportTool = {
             const nodeCount = countNodes(db);
             const edgeCount = countEdges(db);
             const topNodes = db.prepare(`
-        SELECT n.name, n.label, n.file_path,
+        SELECT n.name, n.label, n.file_path, n.start_line,
                COUNT(DISTINCT e1.id) + COUNT(DISTINCT e2.id) AS degree
         FROM nodes n
         LEFT JOIN edges e1 ON e1.source_id = n.id
@@ -433,7 +525,10 @@ const monographReportTool = {
                 `**Generated:** ${new Date().toISOString()}`,
                 `**Nodes:** ${nodeCount}  **Edges:** ${edgeCount}\n`,
                 '## Top 10 Most Connected Entities\n',
-                ...topNodes.map((n, i) => `${i + 1}. **${n.name}** (${n.label}) — degree ${n.degree}  \`${n.file_path ?? ''}\``),
+                ...topNodes.map((n, i) => {
+                    const loc = n.file_path ? (n.start_line != null ? `${n.file_path}:${n.start_line}` : n.file_path) : '';
+                    return `${i + 1}. **${n.name}** (${n.label}) — degree ${n.degree}${loc ? `  \`${loc}\`` : ''}`;
+                }),
             ].join('\n');
             const outPath = resolve(input.path ?? join(getProjectCwd(), '.monomind', 'GRAPH_REPORT.md'));
             const allowedRoot = resolve(getProjectCwd());
@@ -442,7 +537,7 @@ const monographReportTool = {
             }
             mkdirSync(join(outPath, '..'), { recursive: true });
             writeFileSync(outPath, report);
-            return text(`Report written to ${outPath}`);
+            return text(`${report}\n\nReport written to ${outPath}`);
         }
         finally {
             closeDb(db);
@@ -462,8 +557,24 @@ const monographStalenessTool = {
     handler: async (input) => {
         const { getMonographStaleness } = await import('@monoes/monograph');
         const repoPath = input.path ?? getProjectCwd();
-        const report = await getMonographStaleness(repoPath);
-        return text(JSON.stringify(report, null, 2));
+        const r = await getMonographStaleness(repoPath);
+        if (!r.indexedCommit && !r.currentCommit) {
+            return text('Index has never been built or repo has no git history. Run monograph_build first.');
+        }
+        const statusLine = r.isStale
+            ? `STALE — index at ${r.indexedCommit}, HEAD at ${r.currentCommit}`
+            : `FRESH — index matches HEAD (${r.currentCommit})`;
+        const lines = [`Staleness: ${statusLine}`];
+        if (r.staleSince)
+            lines.push(`Stale since: ${r.staleSince}`);
+        if (r.changedSince.length > 0) {
+            const shown = r.changedSince.slice(0, 10);
+            const more = r.changedSince.length - shown.length;
+            lines.push(`Changed files (${r.changedSince.length}):${shown.map(f => `\n  ${f}`).join('')}${more > 0 ? `\n  … ${more} more` : ''}`);
+        }
+        if (r.isStale)
+            lines.push('Action: run monograph_build to re-index');
+        return text(lines.join('\n'));
     },
 };
 // ── monograph_snapshot ────────────────────────────────────────────────────────
@@ -479,13 +590,19 @@ const monographSnapshotTool = {
     handler: async (input) => {
         const { openDb, closeDb, snapshotFromDb } = await import('@monoes/monograph');
         const { writeFileSync, mkdirSync } = await import('fs');
+        const { resolve: resolvePath } = await import('path');
         const db = openDb(getDbPath());
         try {
             const snapshot = snapshotFromDb(db);
-            const name = input.name ?? new Date().toISOString().replace(/[:.]/g, '-');
-            const snapshotDir = join(getProjectCwd(), '.monomind', 'snapshots');
+            const rawName = input.name ?? new Date().toISOString().replace(/[:.]/g, '-');
+            const SAFE_NAME_RE = /^[a-zA-Z0-9_.\-]+$/;
+            if (!SAFE_NAME_RE.test(rawName))
+                return text(`Invalid snapshot name: ${rawName}`);
+            const snapshotDir = resolvePath(join(getProjectCwd(), '.monomind', 'snapshots'));
             mkdirSync(snapshotDir, { recursive: true });
-            const outPath = join(snapshotDir, `${name}.json`);
+            const outPath = join(snapshotDir, `${rawName}.json`);
+            if (!resolvePath(outPath).startsWith(snapshotDir))
+                return text(`Path traversal detected in snapshot name`);
             writeFileSync(outPath, JSON.stringify(snapshot, null, 2));
             return text(`Snapshot saved: ${outPath}\n  nodes: ${snapshot.nodes.length}  edges: ${snapshot.edges.length}`);
         }
@@ -508,18 +625,37 @@ const monographDiffTool = {
     },
     handler: async (input) => {
         const { openDb, closeDb, snapshotFromDb, diffSnapshots } = await import('@monoes/monograph');
-        const { readFileSync, existsSync } = await import('fs');
-        const snapshotDir = join(getProjectCwd(), '.monomind', 'snapshots');
-        const beforePath = join(snapshotDir, `${input.before}.json`);
+        const { readFileSync, existsSync, statSync: statSyncSnap } = await import('fs');
+        const { resolve: resolvePath } = await import('path');
+        const MAX_SNAPSHOT_BYTES = 100 * 1024 * 1024; // 100 MB
+        const snapshotDir = resolvePath(join(getProjectCwd(), '.monomind', 'snapshots'));
+        // Reject snapshot names containing path separators or traversal sequences
+        const SAFE_SNAPSHOT_NAME = /^[a-zA-Z0-9_.\-]+$/;
+        const beforeName = input.before;
+        if (!SAFE_SNAPSHOT_NAME.test(beforeName))
+            return text(`Invalid snapshot name: ${beforeName}`);
+        const beforePath = join(snapshotDir, `${beforeName}.json`);
+        if (!resolvePath(beforePath).startsWith(snapshotDir))
+            return text(`Path traversal detected in snapshot name`);
         if (!existsSync(beforePath)) {
             return text(`Snapshot not found: ${beforePath}\nCreate one first with monograph_snapshot.`);
         }
+        if (statSyncSnap(beforePath).size > MAX_SNAPSHOT_BYTES) {
+            return text(`Snapshot too large to diff: ${beforePath}`);
+        }
         const before = JSON.parse(readFileSync(beforePath, 'utf-8'));
         let after;
         if (input.after) {
-            const afterPath = join(snapshotDir, `${input.after}.json`);
+            const afterName = input.after;
+            if (!SAFE_SNAPSHOT_NAME.test(afterName))
+                return text(`Invalid snapshot name: ${afterName}`);
+            const afterPath = join(snapshotDir, `${afterName}.json`);
+            if (!resolvePath(afterPath).startsWith(snapshotDir))
+                return text(`Path traversal detected in snapshot name`);
             if (!existsSync(afterPath))
                 return text(`Snapshot not found: ${afterPath}`);
+            if (statSyncSnap(afterPath).size > MAX_SNAPSHOT_BYTES)
+                return text(`Snapshot too large to diff: ${afterPath}`);
             after = JSON.parse(readFileSync(afterPath, 'utf-8'));
         }
         else {
@@ -532,13 +668,33 @@ const monographDiffTool = {
             }
         }
         const diff = diffSnapshots(before, after);
+        const nodeById = new Map();
+        const indexNodes = (nodes) => {
+            for (const n of nodes) {
+                if (n.id)
+                    nodeById.set(n.id, n);
+            }
+        };
+        indexNodes(before.nodes);
+        indexNodes(after.nodes);
+        const resolveEdgeEnd = (id) => {
+            const ref = nodeById.get(id);
+            if (!ref)
+                return id; // fallback to raw id if not found
+            const loc = ref.filePath ? (ref.startLine != null ? `${ref.filePath}:${ref.startLine}` : ref.filePath) : '';
+            return loc ? `${ref.name}  [${loc}]` : ref.name;
+        };
         const section = (label, items) => items.length > 0 ? `\n${label} (${items.length}):\n${items.slice(0, 10).join('\n')}${items.length > 10 ? `\n  … ${items.length - 10} more` : ''}` : '';
+        const formatNode = (n) => {
+            const loc = n.filePath ? (n.startLine != null ? `${n.filePath}:${n.startLine}` : n.filePath) : '';
+            return `  [${n.label ?? '?'}] ${n.name ?? '?'}${loc ? `  ${loc}` : ''}`;
+        };
         const lines = [
             `Diff: ${diff.summary}`,
-            section('New nodes', diff.newNodes.map(n => `  + [${n.label}] ${n.name}  ${n.filePath ?? ''}`)),
-            section('Removed nodes', diff.removedNodes.map(n => `  - [${n.label}] ${n.name}  ${n.filePath ?? ''}`)),
-            section('New edges', diff.newEdges.map(e => `  + ${e.sourceId} --[${e.relation}]--> ${e.targetId}`)),
-            section('Removed edges', diff.removedEdges.map(e => `  - ${e.sourceId} --[${e.relation}]--> ${e.targetId}`)),
+            section('New nodes', diff.newNodes.map(n => `  + ${formatNode(n)}`)),
+            section('Removed nodes', diff.removedNodes.map(n => `  - ${formatNode(n)}`)),
+            section('New edges', diff.newEdges.map(e => `  + ${resolveEdgeEnd(e.sourceId)} --[${e.relation}]--> ${resolveEdgeEnd(e.targetId)}`)),
+            section('Removed edges', diff.removedEdges.map(e => `  - ${resolveEdgeEnd(e.sourceId)} --[${e.relation}]--> ${resolveEdgeEnd(e.targetId)}`)),
         ].join('');
         return text(lines);
     },
@@ -614,11 +770,52 @@ const monographContextTool = {
         const { getMonographContext } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
+            // Cap name and filePath: forwarded to parameterized SQL via getMonographContext.
+            // Very long strings waste memory before the query even executes.
+            const MAX_CTX_NAME_LEN = 512;
+            const MAX_CTX_PATH_LEN = 4 * 1024;
+            const rawCtxName = input.name;
+            const ctxName = typeof rawCtxName === 'string' && rawCtxName.length > MAX_CTX_NAME_LEN
+                ? rawCtxName.slice(0, MAX_CTX_NAME_LEN) : rawCtxName;
+            const rawCtxPath = input.filePath;
+            const ctxPath = typeof rawCtxPath === 'string' && rawCtxPath.length > MAX_CTX_PATH_LEN
+                ? rawCtxPath.slice(0, MAX_CTX_PATH_LEN) : rawCtxPath;
             const result = getMonographContext(db, {
-                name: input.name,
-                filePath: input.filePath,
+                name: ctxName,
+                filePath: ctxPath,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (!result || !result.node)
+                return text(`No symbol found: ${ctxName}`);
+            // Format context as structured text for direct LLM consumption
+            const n = result.node;
+            const loc = n.filePath ? (n.startLine != null ? `${n.filePath}:${n.startLine}` : n.filePath) : '';
+            const lines = [
+                `[${n.label ?? '?'}] ${n.name}  ${loc}`,
+                '',
+            ];
+            const formatNodes = (nodes, label) => {
+                if (!Array.isArray(nodes) || nodes.length === 0)
+                    return;
+                lines.push(`${label} (${nodes.length}):`);
+                for (const node of nodes.slice(0, 20)) {
+                    const fp = node.filePath ?? node.file_path ?? '';
+                    const ln = node.startLine ?? node.start_line;
+                    const nodeLoc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    lines.push(`  [${node.label ?? '?'}] ${node.name ?? node.id}  ${nodeLoc}`);
+                }
+                if (nodes.length > 20)
+                    lines.push(`  … ${nodes.length - 20} more`);
+                lines.push('');
+            };
+            formatNodes(result.callers, 'Callers');
+            formatNodes(result.callees, 'Callees');
+            formatNodes(result.imports, 'Imports');
+            formatNodes(result.importedBy, 'ImportedBy');
+            if (result.community != null)
+                lines.push(`Community: ${result.community}`);
+            if (result.communityName)
+                lines.push(`Community name: ${result.communityName}`);
+            return text(lines.join('\n').trim());
         }
         finally {
             closeDb(db);
@@ -643,12 +840,52 @@ const monographImpactTool = {
         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 = typeof rawDepth === 'number' && Number.isFinite(rawDepth) && rawDepth > 0
+                ? Math.min(Math.floor(rawDepth), 6) : rawDepth;
             const result = getMonographImpact(db, {
-                name: input.name,
-                filePath: input.filePath,
-                depth: input.depth,
+                name: impactName,
+                filePath: impactPath,
+                depth,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (!result || !result.root)
+                return text(`No symbol found: ${impactName}`);
+            // Format impact as structured text for direct LLM consumption
+            const root = result.root;
+            const rootLoc = root.filePath ? (root.startLine != null ? `${root.filePath}:${root.startLine}` : root.filePath) : '';
+            const lines = [
+                `[${root.label ?? '?'}] ${root.name}  ${rootLoc}`,
+                '',
+                `Blast radius: ${result.totalAffected ?? 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.affected ?? result.callers ?? []);
+            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);
@@ -675,7 +912,35 @@ const monographDetectChangesTool = {
                 baseBranch: input.baseBranch,
                 includeTests: input.includeTests,
             }, getProjectCwd());
-            return text(JSON.stringify(result, null, 2));
+            // Format as structured text for direct LLM navigation instead of raw JSON
+            const r = result;
+            if (!r || (!r.changedFiles?.length && !r.affectedSymbols?.length)) {
+                return text('No changed files found relative to the base branch.');
+            }
+            const lines = [];
+            const base = r.baseBranch ?? 'main';
+            const changedFiles = r.changedFiles ?? [];
+            lines.push(`Changed files vs ${base}: ${changedFiles.length}`);
+            if (changedFiles.length > 0) {
+                for (const f of changedFiles.slice(0, 20))
+                    lines.push(`  ${f}`);
+                if (changedFiles.length > 20)
+                    lines.push(`  … ${changedFiles.length - 20} more`);
+            }
+            lines.push('');
+            const affected = r.affectedSymbols ?? r.affected ?? [];
+            if (affected.length > 0) {
+                lines.push(`Affected symbols (${affected.length}):`);
+                for (const sym of affected.slice(0, 30)) {
+                    const fp = sym.filePath ?? sym.file_path ?? '';
+                    const ln = sym.startLine ?? sym.start_line;
+                    const loc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    lines.push(`  [${sym.label ?? '?'}] ${sym.name ?? sym.id}  ${loc}`);
+                }
+                if (affected.length > 30)
+                    lines.push(`  … ${affected.length - 30} more`);
+            }
+            return text(lines.join('\n').trim());
         }
         finally {
             closeDb(db);
@@ -707,7 +972,25 @@ const monographRenameTool = {
                 filePath: input.filePath,
                 dryRun: input.dryRun ?? true,
             });
-            return text(JSON.stringify(result, null, 2));
+            // 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);
@@ -736,7 +1019,17 @@ const monographRouteMapTool = {
                 method: input.method,
                 includeMiddleware: input.includeMiddleware,
             });
-            return text(JSON.stringify(result, null, 2));
+            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);
@@ -764,7 +1057,33 @@ const monographApiImpactTool = {
                 routePath: input.routePath,
                 method: input.method,
             });
-            return text(JSON.stringify(result, null, 2));
+            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);
@@ -818,7 +1137,14 @@ const monographCypherTool = {
         const { getMonographCypher } = await import('@monoes/monograph');
         const db = openDb(getDbPath());
         try {
-            const result = getMonographCypher(db, input.query);
+            // Cap query: forwarded to the Cypher query engine; very long strings
+            // waste parse time and can stress the query compiler.
+            const MAX_CYPHER_QUERY_LEN = 16 * 1024;
+            const rawCypherQuery = input.query;
+            const cypherQuery = typeof rawCypherQuery === 'string' && rawCypherQuery.length > MAX_CYPHER_QUERY_LEN
+                ? rawCypherQuery.slice(0, MAX_CYPHER_QUERY_LEN)
+                : rawCypherQuery;
+            const result = getMonographCypher(db, cypherQuery);
             if (result.error)
                 return text(`Error: ${result.error}`);
             if (result.rows.length === 0)
@@ -846,7 +1172,15 @@ const monographGroupListTool = {
         const { getGroupList } = await import('@monoes/monograph');
         const configPath = input.configPath ?? join(getProjectCwd(), 'group.yaml');
         const result = await getGroupList(configPath);
-        return text(JSON.stringify(result, null, 2));
+        if (!result.repos || result.repos.length === 0) {
+            return text(`Group: ${result.group?.name ?? 'unknown'}\nNo repos configured. Check ${configPath}`);
+        }
+        const lines = [`Group: ${result.group?.name ?? 'unknown'}  (${result.repos.length} repos)`];
+        for (const r of result.repos) {
+            const indexed = r.indexedAt ? r.indexedAt.slice(0, 10) : 'never';
+            lines.push(`  ${r.name}  nodes=${r.nodeCount}  indexed=${indexed}  ${r.path}`);
+        }
+        return text(lines.join('\n'));
     },
 };
 // ── monograph_group_query ─────────────────────────────────────────────────────
@@ -865,7 +1199,18 @@ const monographGroupQueryTool = {
     handler: async (input) => {
         const { runGroupQuery } = await import('@monoes/monograph');
         const configPath = input.configPath ?? join(getProjectCwd(), 'group.yaml');
-        const results = await runGroupQuery(configPath, input.query, input.limit);
+        // Cap query and limit forwarded to runGroupQuery.
+        const MAX_GROUP_QUERY_LEN = 16 * 1024;
+        const MAX_GROUP_LIMIT = 1_000;
+        const rawGroupQuery = input.query;
+        const groupQuery = typeof rawGroupQuery === 'string' && rawGroupQuery.length > MAX_GROUP_QUERY_LEN
+            ? rawGroupQuery.slice(0, MAX_GROUP_QUERY_LEN)
+            : rawGroupQuery;
+        const rawGroupLimit = input.limit;
+        const groupLimit = Number.isFinite(rawGroupLimit) && (rawGroupLimit ?? 0) > 0
+            ? Math.min(Math.floor(rawGroupLimit), MAX_GROUP_LIMIT)
+            : rawGroupLimit;
+        const results = await runGroupQuery(configPath, groupQuery, groupLimit);
         if (results.length === 0)
             return text('No results found.');
         const lines = results.map(r => `[${r.label}] ${r.name}  ${r.filePath ?? ''}  repo:${r.repo}  (score: ${r.score.toFixed(4)})`);
@@ -888,7 +1233,12 @@ const monographWikiTool = {
         const db = openDb(getDbPath());
         try {
             const result = getWikiToolResult(db, { communityId: input.communityId });
-            return text(JSON.stringify(result, null, 2));
+            if (result.pages.length === 0) {
+                return text('No wiki pages found. Run monograph_wiki_build to generate community wiki pages.');
+            }
+            // Return pages as readable prose — content is already LLM-generated markdown.
+            const sections = result.pages.map(p => `--- Community ${p.communityId} ---\n${p.content}`);
+            return text(sections.join('\n\n'));
         }
         finally {
             closeDb(db);
@@ -917,7 +1267,16 @@ const monographWikiBuildTool = {
                 force: input.force,
                 model: input.model,
             });
-            return text(JSON.stringify(result, null, 2));
+            if (result.error)
+                return text(`Wiki build failed: ${result.error}`);
+            const parts = [];
+            if (result.generated != null)
+                parts.push(`${result.generated} page(s) generated`);
+            if (result.skipped != null && result.skipped > 0)
+                parts.push(`${result.skipped} skipped (already exist)`);
+            if (result.errors != null && result.errors > 0)
+                parts.push(`${result.errors} error(s)`);
+            return text(`Wiki build complete: ${parts.join(', ') || 'nothing to do'}. Use monograph_wiki to read the pages.`);
         }
         finally {
             closeDb(db);
@@ -965,7 +1324,13 @@ const monographToolMapTool = {
             const results = getToolMap(db, { tool: input.tool });
             if (results.length === 0)
                 return text('No tools found. Run monograph_build first.');
-            return text(JSON.stringify(results, null, 2));
+            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);
@@ -993,7 +1358,38 @@ const monographShapeCheckTool = {
                 route: input.route,
                 file: input.file,
             });
-            return text(JSON.stringify(result, null, 2));
+            // 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);
@@ -1039,10 +1435,20 @@ const monographAugmentTool = {
     handler: async (input) => {
         const { augmentContext } = await import('@monoes/monograph');
         const repoPath = getProjectCwd();
+        // Cap query (forwarded to FTS/embedding in augmentContext) and topK
+        // (controls how many context nodes are retrieved).
+        const MAX_AUGMENT_QUERY_LEN = 16 * 1024;
+        const MAX_AUGMENT_TOP_K = 100;
+        const rawAugmentQuery = input.query;
+        const augmentQuery = typeof rawAugmentQuery === 'string' && rawAugmentQuery.length > MAX_AUGMENT_QUERY_LEN
+            ? rawAugmentQuery.slice(0, MAX_AUGMENT_QUERY_LEN) : rawAugmentQuery;
+        const rawTopK = input.topK ?? 10;
+        const topK = Number.isFinite(rawTopK) && rawTopK > 0
+            ? Math.min(Math.floor(rawTopK), MAX_AUGMENT_TOP_K) : 10;
         const result = await augmentContext({
-            query: input.query,
+            query: augmentQuery,
             repoPath,
-            topK: input.topK ?? 10,
+            topK,
             format: input.format ?? 'markdown',
         });
         return text(result);
@@ -1308,11 +1714,19 @@ const monographNeighborsTool = {
             });
             if (!result.node)
                 return text(`No node found with name: ${input.name}`);
+            const nodeFilePath = result.node.filePath ?? '';
+            const nodeStartLine = result.node.startLine ?? result.node.start_line;
+            const nodeLoc = nodeFilePath ? (nodeStartLine != null ? `${nodeFilePath}:${nodeStartLine}` : nodeFilePath) : '';
             const lines = [
-                `[${result.node.label}] ${result.node.name}  ${result.node.filePath ?? ''}`,
+                `[${result.node.label}] ${result.node.name}  ${nodeLoc}`,
                 `Neighbors: ${result.neighbors.length}`,
                 '',
-                ...result.neighbors.map(n => `  ${n.direction === 'inbound' ? '←' : '→'} [${n.node.label}] ${n.node.name}  (${n.relation})  ${n.node.filePath ?? ''}`),
+                ...result.neighbors.map(n => {
+                    const fp = n.node.filePath ?? n.node.file_path ?? '';
+                    const ln = n.node.startLine ?? n.node.start_line;
+                    const loc = fp ? (ln != null ? `${fp}:${ln}` : fp) : '';
+                    return `  ${n.direction === 'inbound' ? '←' : '→'} [${n.node.label}] ${n.node.name}  (${n.relation})  ${loc}`;
+                }),
             ];
             return text(lines.join('\n'));
         }