@monoes/monomindcli 2.8.4 → 2.9.2

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

@@ -0,0 +1,215 @@
+import { join } from 'path';
+import { execSync } from 'child_process';
+import { statSync } from 'fs';
+import { getProjectCwd } from '../types.js';
+let _cachedDbPath;
+let _cachedCwd;
+// P2: staleness cache for computeCommitsBehind. Keyed by repoPath, TTL 30s.
+// Cuts the per-call git rev-list spawn from "every monograph_* tool call"
+// down to one per 30s per repo — a 50-100ms saving on the hottest path.
+const _stalenessCache = new Map();
+export function _isValidDb(p) {
+    try {
+        return statSync(p).size >= 100;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the monograph DB path for a given repo root (defaults to project cwd).
+ * Falls back to searching up to the git root when the DB isn't directly under
+ * `<cwd>/.monomind` — e.g. when called from a subdirectory of the repo. Only
+ * the no-arg (project cwd) form is cached; explicit `repoPath` overrides are
+ * cheap one-off lookups (staleness checks with a user-supplied path) so caching
+ * them isn't worth the invalidation complexity.
+ */
+export function getDbPath(repoPathOverride) {
+    const cwd = repoPathOverride ?? getProjectCwd();
+    const useCache = repoPathOverride === undefined;
+    // Invalidate cache when project root changes (e.g. MONOMIND_CWD set after initialize)
+    if (useCache && _cachedDbPath && _cachedCwd === cwd)
+        return _cachedDbPath;
+    if (useCache) {
+        _cachedCwd = cwd;
+        _cachedDbPath = undefined;
+    }
+    const direct = join(cwd, '.monomind', 'monograph.db');
+    if (_isValidDb(direct)) {
+        if (useCache)
+            _cachedDbPath = direct;
+        return direct;
+    }
+    try {
+        const root = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf8' }).trim();
+        const candidate = join(root, '.monomind', 'monograph.db');
+        if (_isValidDb(candidate)) {
+            if (useCache)
+                _cachedDbPath = candidate;
+            return candidate;
+        }
+    }
+    catch { /* not in a git repo */ }
+    // Don't cache failures — the DB may be created by a subsequent build
+    return direct;
+}
+export function text(t) {
+    return { content: [{ type: 'text', text: t }] };
+}
+export function applyPprRerank(db, seedNodes, damping, maxResults) {
+    const propagated = new Map();
+    for (const r of seedNodes) {
+        propagated.set(r.id, r.score);
+    }
+    // P3: batched edge lookup — was one SELECT per seed node (N+1 over the
+    // default limit*2=40 seeds). Now a single WHERE source_id IN (?, ?, …)
+    // pulls every neighbor in one round-trip. SQLite parameter limit is 999,
+    // well above the 40-seed default; fall back to chunking if a caller ever
+    // exceeds it.
+    const seedIds = seedNodes.map(r => r.id);
+    const SEED_CHUNK = 500;
+    const sourceToTargets = new Map();
+    for (let i = 0; i < seedIds.length; i += SEED_CHUNK) {
+        const chunk = seedIds.slice(i, i + SEED_CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db.prepare(`SELECT source_id, target_id FROM edges WHERE source_id IN (${placeholders})`).all(...chunk);
+        for (const row of rows) {
+            const arr = sourceToTargets.get(row.source_id) ?? [];
+            arr.push(row.target_id);
+            sourceToTargets.set(row.source_id, arr);
+        }
+    }
+    for (const r of seedNodes) {
+        const neighbors = sourceToTargets.get(r.id) ?? [];
+        for (const n of neighbors) {
+            const boost = r.score * damping;
+            const current = propagated.get(n) ?? 0;
+            propagated.set(n, Math.max(current, boost));
+        }
+    }
+    const seedIdSet = new Set(seedNodes.map(r => r.id));
+    const ranked = seedNodes.map(r => ({
+        ...r,
+        combinedScore: Math.max(r.score, propagated.get(r.id) ?? 0),
+        boostedByNeighbors: false,
+    }));
+    // P3: batched node lookup for non-seed propagated nodes — was one SELECT
+    // per propagated id (~10 per call). Single WHERE id IN (?, ?, …) instead.
+    const nonSeedIds = [...propagated.keys()].filter(id => !seedIdSet.has(id));
+    const nodeById = new Map();
+    for (let i = 0; i < nonSeedIds.length; i += SEED_CHUNK) {
+        const chunk = nonSeedIds.slice(i, i + SEED_CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db.prepare(`SELECT id, name, label, file_path, start_line FROM nodes WHERE id IN (${placeholders})`).all(...chunk);
+        for (const row of rows)
+            nodeById.set(row.id, row);
+    }
+    for (const [id, score] of propagated) {
+        if (!seedIdSet.has(id)) {
+            const node = nodeById.get(id);
+            if (node) {
+                ranked.push({
+                    id: node.id, name: node.name, label: node.label,
+                    filePath: node.file_path, startLine: node.start_line,
+                    score: 0, combinedScore: score, boostedByNeighbors: true,
+                });
+            }
+        }
+    }
+    ranked.sort((a, b) => b.combinedScore - a.combinedScore);
+    return ranked.slice(0, maxResults).map(r => ({
+        id: r.id, name: r.name, label: r.label,
+        filePath: r.filePath, startLine: r.startLine,
+        score: r.combinedScore, boostedByNeighbors: r.boostedByNeighbors,
+    }));
+}
+/** Guard against concurrent background buildAsync calls on the same DB. */
+let _buildInProgress = false;
+/**
+ * Compute how many commits the index is behind HEAD.
+ * Returns { commitsBehind, lastCommit } — or null if the index has never been
+ * built or git is unavailable.
+ */
+export async function computeCommitsBehind(repoPath) {
+    // P2: cache per-repoPath for 30s. computeCommitsBehind fires on every
+    // monograph_query, monograph_suggest, monograph_staleness, and
+    // monograph_health call (4 of the hottest tools) — each one was paying
+    // ~50-100ms for `openDb + git rev-list --count + closeDb`. The result
+    // changes only when the user commits, so a 30s TTL is well inside the
+    // dev cycle and cuts repeated calls to a single git spawn per half-minute.
+    const cached = _stalenessCache.get(repoPath);
+    if (cached && Date.now() - cached.ts < 30_000)
+        return cached.value;
+    const { openDb, closeDb } = await import('@monoes/monograph');
+    const { execSync } = await import('child_process');
+    const dbPath = getDbPath(repoPath);
+    if (!_isValidDb(dbPath))
+        return null;
+    // openDb's fileMustExist option isn't in the currently-published
+    // @monoes/monograph release this CLI depends on — _isValidDb above is the
+    // real guard against openDb silently creating an empty DB at a missing path.
+    const db = openDb(dbPath);
+    try {
+        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 || !/^[0-9a-f]{7,40}$/i.test(lastCommit))
+            return null;
+        try {
+            const out = execSync(`git rev-list --count ${lastCommit}..HEAD`, {
+                cwd: repoPath, encoding: 'utf-8', timeout: 5_000,
+            }).trim();
+            const value = { commitsBehind: parseInt(out, 10), lastCommit };
+            _stalenessCache.set(repoPath, { ts: Date.now(), value });
+            return value;
+        }
+        catch {
+            return null;
+        }
+    }
+    finally {
+        closeDb(db);
+    }
+}
+/**
+ * Shared staleness threshold: both monograph_staleness and monograph_suggest (checkStaleness)
+ * trigger a background rebuild only when the index is more than this many commits behind HEAD.
+ * Using a shared constant prevents conflicting rebuild pressure during active dev sessions.
+ * Was 10 → 3 → 1. Even 3 let routine small commits accumulate stale results
+ * silently. At 1 (rebuild triggers at 2+ behind), staleness rarely persists
+ * across sessions.
+ */
+export const STALENESS_THRESHOLD = 1;
+/**
+ * Fire-and-forget background rebuild. Uses a module-level guard so concurrent
+ * MCP tool calls (e.g. repeated monograph_suggest checkStaleness) don't pile up builds.
+ * threshold: minimum commitsBehind to trigger (default STALENESS_THRESHOLD + 1).
+ */
+export function triggerBackgroundBuildIfNeeded(repoPath, commitsBehind, threshold = STALENESS_THRESHOLD + 1) {
+    if (commitsBehind < threshold)
+        return false;
+    if (_buildInProgress)
+        return false;
+    _buildInProgress = true;
+    void import('@monoes/monograph')
+        .then(({ buildAsync }) => buildAsync(repoPath, { codeOnly: true }))
+        .catch((e) => {
+        if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
+            console.error('[triggerBackgroundBuildIfNeeded] staleness-triggered rebuild failed:', e);
+    })
+        .finally(() => { _buildInProgress = false; });
+    return true;
+}
+/**
+ * BM25 ranks purely on literal keyword overlap, so a doc/concept node whose
+ * prose happens to mention task-related words (e.g. a report mentioning
+ * "retry" constants) can outrank the actual code symbol the task is really
+ * about, which is conceptually related but lexically different (issue #38).
+ * Prefer code-symbol hits (Function/Class/Method/...) over doc-type hits
+ * (Document/Concept/Section/...) when there are any, falling back to the
+ * full hit list so a genuinely doc-only task still gets results.
+ */
+export function preferSymbolHits(hits, symbolLabels) {
+    const symbolHits = hits.filter(h => symbolLabels.has(h.label));
+    return symbolHits.length > 0 ? symbolHits : hits;
+}
+//# sourceMappingURL=shared.js.map

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

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

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

@@ -0,0 +1,10 @@
+import type { MCPTool } from '../types.js';
+export declare const monographVisualizeTool: MCPTool;
+export declare const monographExportTool: MCPTool;
+export declare const monographSnapshotTool: MCPTool;
+export declare const monographDiffTool: MCPTool;
+export declare const monographReportTool: MCPTool;
+export declare const monographWikiTool: MCPTool;
+export declare const monographWikiBuildTool: MCPTool;
+export declare const monographServeTool: MCPTool;
+//# sourceMappingURL=visualize-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visualize-tools.d.ts","sourceRoot":"","sources":["../../../../src/mcp-tools/monograph/visualize-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAY3C,eAAO,MAAM,sBAAsB,EAAE,OA0CpC,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,OA6DjC,CAAC;AAIF,eAAO,MAAM,qBAAqB,EAAE,OA2BnC,CAAC;AAIF,eAAO,MAAM,iBAAiB,EAAE,OAgF/B,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,OAgDjC,CAAC;AAIF,eAAO,MAAM,iBAAiB,EAAE,OAyB/B,CAAC;AAIF,eAAO,MAAM,sBAAsB,EAAE,OA6BpC,CAAC;AAIF,eAAO,MAAM,kBAAkB,EAAE,OAqBhC,CAAC"}

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

@@ -0,0 +1,382 @@
+import { join, resolve, sep } from 'path';
+import { getProjectCwd } from '../types.js';
+import { getDbPath, text } from './shared.js';
+// Columns needed to render/export the graph — deliberately excludes `embedding`,
+// which can be several KB per node (384D vectors) and would otherwise bloat
+// tool-result payloads and written files by many MB.
+const NODE_RENDER_COLUMNS = 'id, label, name, norm_label, file_path, start_line, end_line, community_id, is_exported, language, properties';
+// ── monograph_visualize ───────────────────────────────────────────────────────
+export const monographVisualizeTool = {
+    name: 'monograph_visualize',
+    description: 'Render the knowledge graph as HTML (default), SVG, or JSON. Writes output to a file under .monomind/visualize/ and returns the file path (output can be multi-MB at the max node count, too large to return inline).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            format: { type: 'string', description: 'Output format: html, svg, json (default: html)' },
+            maxNodes: { type: 'number', description: 'Max nodes to include (default 500)' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb, closeDb, toJson, toHtml, toSvg } = await import('@monoes/monograph');
+        const { writeFileSync, mkdirSync } = await import('fs');
+        const db = openDb(getDbPath());
+        try {
+            // 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 ${NODE_RENDER_COLUMNS} FROM nodes LIMIT ?`).all(limit);
+            // Only include edges where both endpoints are in the visible node set
+            const edges = db.prepare(`
+        SELECT e.* FROM edges e
+        WHERE e.source_id IN (SELECT id FROM nodes LIMIT ?)
+          AND e.target_id IN (SELECT id FROM nodes LIMIT ?)
+        LIMIT ?
+      `).all(limit, limit, limit * 3);
+            const fmt = input.format ?? 'html';
+            const rendered = fmt === 'json' ? toJson(nodes, edges)
+                : fmt === 'svg' ? toSvg(nodes, edges)
+                    : toHtml(nodes, edges);
+            const ext = fmt === 'json' ? 'json' : fmt === 'svg' ? 'svg' : 'html';
+            const outDir = resolve(join(getProjectCwd(), '.monomind', 'visualize'));
+            mkdirSync(outDir, { recursive: true });
+            const outPath = join(outDir, `graph-${Date.now()}.${ext}`);
+            writeFileSync(outPath, rendered);
+            return text(`Visualization written to ${outPath} (${nodes.length} nodes, ${edges.length} edges)${ext === 'html' ? '\nNote: HTML uses the vis-network CDN script and requires network access to render.' : ''}`);
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_export ────────────────────────────────────────────────────────
+export const monographExportTool = {
+    name: 'monograph_export',
+    description: 'Export the knowledge graph in various formats: obsidian, canvas, cypher, graphml, svg, json.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            format: { type: 'string', description: 'Format: obsidian, canvas, cypher, graphml, svg, json' },
+            outputPath: { type: 'string', description: 'Output path' },
+        },
+        required: ['format'],
+    },
+    handler: async (input) => {
+        const { openDb, closeDb, toJson, toSvg, toGraphml, toCypher, toObsidian, toCanvas } = await import('@monoes/monograph');
+        const { writeFileSync, mkdirSync } = await import('fs');
+        const db = openDb(getDbPath());
+        try {
+            // Exclude `embedding` — a several-KB-per-node vector column that would
+            // otherwise bloat exported files by many MB for no rendering benefit.
+            const nodes = db.prepare(`SELECT ${NODE_RENDER_COLUMNS} FROM nodes`).all();
+            const edges = db.prepare('SELECT * FROM edges').all();
+            const fmt = input.format;
+            const requestedOut = input.outputPath ?? join(getProjectCwd(), '.monomind', 'export');
+            const outDir = resolve(getProjectCwd(), requestedOut);
+            const allowedRoot = resolve(getProjectCwd());
+            if (outDir !== allowedRoot && !outDir.startsWith(allowedRoot + sep)) {
+                return text(`Error: outputPath must be within the project directory (${allowedRoot})`);
+            }
+            mkdirSync(outDir, { recursive: true });
+            if (fmt === 'json') {
+                const p = join(outDir, 'graph.json');
+                writeFileSync(p, toJson(nodes, edges));
+                return text(`Exported JSON to ${p}`);
+            }
+            if (fmt === 'svg') {
+                const p = join(outDir, 'graph.svg');
+                writeFileSync(p, toSvg(nodes, edges));
+                return text(`Exported SVG to ${p}`);
+            }
+            if (fmt === 'graphml') {
+                const p = join(outDir, 'graph.graphml');
+                writeFileSync(p, toGraphml(nodes, edges));
+                return text(`Exported GraphML to ${p}`);
+            }
+            if (fmt === 'cypher') {
+                const p = join(outDir, 'graph.cypher');
+                writeFileSync(p, toCypher(nodes, edges));
+                return text(`Exported Cypher to ${p}`);
+            }
+            if (fmt === 'obsidian') {
+                toObsidian(nodes, edges, outDir);
+                return text(`Exported Obsidian vault to ${outDir}`);
+            }
+            if (fmt === 'canvas') {
+                const p = join(outDir, 'graph.canvas');
+                writeFileSync(p, toCanvas(nodes, edges));
+                return text(`Exported Canvas to ${p}`);
+            }
+            return text(`Format ${fmt} export written to ${outDir}`);
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_snapshot ──────────────────────────────────────────────────────
+export const monographSnapshotTool = {
+    name: 'monograph_snapshot',
+    description: 'Save current graph state to a named JSON snapshot. Use with monograph_diff to compare before/after changes.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Snapshot name (default: ISO timestamp). Used as the filename.' },
+        },
+    },
+    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 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, `${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}`);
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_diff ──────────────────────────────────────────────────────────
+export const monographDiffTool = {
+    name: 'monograph_diff',
+    description: 'Compare two named graph snapshots (saved via monograph_snapshot). Omit "after" to diff the "before" snapshot against the live graph.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            before: { type: 'string', description: 'Name of the before snapshot (without .json extension)' },
+            after: { type: 'string', description: 'Name of the after snapshot, or omit to compare against the live graph' },
+        },
+        required: ['before'],
+    },
+    handler: async (input) => {
+        const { openDb, closeDb, snapshotFromDb, diffSnapshots } = await import('@monoes/monograph');
+        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 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 {
+            const db = openDb(getDbPath());
+            try {
+                after = snapshotFromDb(db);
+            }
+            finally {
+                closeDb(db);
+            }
+        }
+        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 => `  + ${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);
+    },
+};
+// ── monograph_report ────────────────────────────────────────────────────────
+export const monographReportTool = {
+    name: 'monograph_report',
+    description: 'Generate a GRAPH_REPORT.md summarizing the codebase knowledge graph.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Output path (default: .monomind/GRAPH_REPORT.md)' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb, closeDb, countNodes, countEdges } = await import('@monoes/monograph');
+        const { writeFileSync, mkdirSync } = await import('fs');
+        const db = openDb(getDbPath());
+        try {
+            const nodeCount = countNodes(db);
+            const edgeCount = countEdges(db);
+            const topNodes = db.prepare(`
+        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
+        LEFT JOIN edges e2 ON e2.target_id = n.id
+        WHERE n.label NOT IN ('File','Folder','Community','Concept')
+        GROUP BY n.id ORDER BY degree DESC LIMIT 10
+      `).all();
+            const report = [
+                '# Graph Report\n',
+                `**Generated:** ${new Date().toISOString()}`,
+                `**Nodes:** ${nodeCount}  **Edges:** ${edgeCount}\n`,
+                '## Top 10 Most Connected Entities\n',
+                ...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 rawOutPath = input.path ?? join(getProjectCwd(), '.monomind', 'GRAPH_REPORT.md');
+            const outPath = resolve(getProjectCwd(), rawOutPath);
+            const allowedRoot = resolve(getProjectCwd());
+            if (outPath !== allowedRoot && !outPath.startsWith(allowedRoot + sep)) {
+                return text(`Error: path must be within the project directory (${allowedRoot})`);
+            }
+            mkdirSync(join(outPath, '..'), { recursive: true });
+            writeFileSync(outPath, report);
+            return text(`${report}\n\nReport written to ${outPath}`);
+        }
+        finally {
+            closeDb(db);
+        }
+    },
+};
+// ── monograph_wiki ──────────────────────────────────────────────────────────
+export const monographWikiTool = {
+    name: 'monograph_wiki',
+    description: 'Retrieve LLM-generated wiki pages for code communities. Returns one page by communityId or all pages if no filter provided.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            communityId: { type: 'string', description: 'Community ID to retrieve (omit to list all pages)' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { getWikiToolResult } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        try {
+            const result = getWikiToolResult(db, { communityId: input.communityId });
+            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);
+        }
+    },
+};
+// ── monograph_wiki_build ────────────────────────────────────────────────────
+export const monographWikiBuildTool = {
+    name: 'monograph_wiki_build',
+    description: 'Generate wiki pages for code communities using Claude Code CLI (no API key needed — reuses Claude Code auth).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            communityId: { type: 'string', description: 'Only generate for this community ID (omit for all communities)' },
+            force: { type: 'boolean', description: 'Regenerate even if page already exists (default false)' },
+            model: { type: 'string', description: 'Anthropic model to use (default: claude-haiku-4-5-20251001)' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb, closeDb } = await import('@monoes/monograph');
+        const { runWikiBuildTool } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        try {
+            const result = await runWikiBuildTool(db, {
+                communityId: input.communityId,
+                force: input.force,
+                model: input.model,
+            });
+            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);
+        }
+    },
+};
+// ── monograph_serve ─────────────────────────────────────────────────────────
+export const monographServeTool = {
+    name: 'monograph_serve',
+    description: 'Start a web UI server that visualizes the knowledge graph interactively using Sigma.js. Returns the URL where the dashboard is accessible.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            port: { type: 'number', description: 'Port to listen on (default 7374)' },
+            open: { type: 'boolean', description: 'Open the URL in the default browser after starting (default false)' },
+        },
+    },
+    handler: async (input) => {
+        const { openDb } = await import('@monoes/monograph');
+        const { serveMonograph } = await import('@monoes/monograph');
+        const db = openDb(getDbPath());
+        const result = await serveMonograph({
+            port: input.port ?? 7374,
+            open: input.open ?? false,
+            db,
+        });
+        return text(`Monograph web UI ${result.status === 'already_running' ? 'already running' : 'started'} at ${result.url}`);
+    },
+};
+//# sourceMappingURL=visualize-tools.js.map