@prih/mcp-graph-memory 1.0.3

package/dist/api/rest/validation.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachmentFilenameSchema = exports.linkedQuerySchema = exports.graphExportSchema = exports.skillListSchema = exports.skillSearchSchema = exports.createSkillLinkSchema = exports.updateSkillSchema = exports.createSkillSchema = exports.fileListSchema = exports.listQuerySchema = exports.searchQuerySchema = exports.taskListSchema = exports.taskSearchSchema = exports.createTaskLinkSchema = exports.moveTaskSchema = exports.updateTaskSchema = exports.createTaskSchema = exports.noteListSchema = exports.noteSearchSchema = exports.createRelationSchema = exports.updateNoteSchema = exports.createNoteSchema = void 0;
+exports.validateBody = validateBody;
+exports.validateQuery = validateQuery;
+const zod_1 = require("zod");
+function validateBody(schema) {
+    return (req, _res, next) => {
+        req.body = schema.parse(req.body);
+        next();
+    };
+}
+function validateQuery(schema) {
+    return (req, _res, next) => {
+        req.validatedQuery = schema.parse(req.query);
+        next();
+    };
+}
+// ---------------------------------------------------------------------------
+// Knowledge schemas
+// ---------------------------------------------------------------------------
+exports.createNoteSchema = zod_1.z.object({
+    title: zod_1.z.string().min(1).max(500),
+    content: zod_1.z.string().max(1_000_000),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(100).optional().default([]),
+});
+exports.updateNoteSchema = zod_1.z.object({
+    title: zod_1.z.string().min(1).max(500).optional(),
+    content: zod_1.z.string().max(1_000_000).optional(),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(100).optional(),
+    version: zod_1.z.number().int().positive().optional(),
+});
+exports.createRelationSchema = zod_1.z.object({
+    fromId: zod_1.z.string().min(1),
+    toId: zod_1.z.string().min(1),
+    kind: zod_1.z.string().min(1),
+    targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'tasks', 'skills']).optional(),
+    projectId: zod_1.z.string().min(1).optional(),
+});
+exports.noteSearchSchema = zod_1.z.object({
+    q: zod_1.z.string().min(1).max(2000),
+    topK: zod_1.z.coerce.number().int().positive().max(500).optional(),
+    minScore: zod_1.z.coerce.number().min(0).max(1).optional(),
+    searchMode: zod_1.z.enum(['hybrid', 'vector', 'keyword']).optional(),
+});
+exports.noteListSchema = zod_1.z.object({
+    filter: zod_1.z.string().optional(),
+    tag: zod_1.z.string().optional(),
+    limit: zod_1.z.coerce.number().int().positive().optional(),
+});
+// ---------------------------------------------------------------------------
+// Task schemas
+// ---------------------------------------------------------------------------
+exports.createTaskSchema = zod_1.z.object({
+    title: zod_1.z.string().min(1).max(500),
+    description: zod_1.z.string().max(500_000).default(''),
+    status: zod_1.z.enum(['backlog', 'todo', 'in_progress', 'review', 'done', 'cancelled']).default('todo'),
+    priority: zod_1.z.enum(['critical', 'high', 'medium', 'low']).default('medium'),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(100).optional().default([]),
+    dueDate: zod_1.z.number().nullable().optional(),
+    estimate: zod_1.z.number().nullable().optional(),
+});
+exports.updateTaskSchema = zod_1.z.object({
+    title: zod_1.z.string().min(1).max(500).optional(),
+    description: zod_1.z.string().max(500_000).optional(),
+    status: zod_1.z.enum(['backlog', 'todo', 'in_progress', 'review', 'done', 'cancelled']).optional(),
+    priority: zod_1.z.enum(['critical', 'high', 'medium', 'low']).optional(),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(100).optional(),
+    dueDate: zod_1.z.number().nullable().optional(),
+    estimate: zod_1.z.number().nullable().optional(),
+    version: zod_1.z.number().int().positive().optional(),
+});
+exports.moveTaskSchema = zod_1.z.object({
+    status: zod_1.z.enum(['backlog', 'todo', 'in_progress', 'review', 'done', 'cancelled']),
+    version: zod_1.z.number().int().positive().optional(),
+});
+exports.createTaskLinkSchema = zod_1.z.object({
+    fromId: zod_1.z.string().min(1),
+    toId: zod_1.z.string().min(1),
+    kind: zod_1.z.string().min(1),
+    targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'knowledge', 'skills']).optional(),
+    projectId: zod_1.z.string().min(1).optional(),
+});
+exports.taskSearchSchema = zod_1.z.object({
+    q: zod_1.z.string().min(1).max(2000),
+    topK: zod_1.z.coerce.number().int().positive().max(500).optional(),
+    minScore: zod_1.z.coerce.number().min(0).max(1).optional(),
+    searchMode: zod_1.z.enum(['hybrid', 'vector', 'keyword']).optional(),
+});
+exports.taskListSchema = zod_1.z.object({
+    status: zod_1.z.enum(['backlog', 'todo', 'in_progress', 'review', 'done', 'cancelled']).optional(),
+    priority: zod_1.z.enum(['critical', 'high', 'medium', 'low']).optional(),
+    tag: zod_1.z.string().optional(),
+    filter: zod_1.z.string().optional(),
+    limit: zod_1.z.coerce.number().int().positive().optional(),
+});
+// ---------------------------------------------------------------------------
+// Search schemas (docs, code, files)
+// ---------------------------------------------------------------------------
+exports.searchQuerySchema = zod_1.z.object({
+    q: zod_1.z.string().min(1).max(2000),
+    topK: zod_1.z.coerce.number().int().positive().max(500).optional(),
+    minScore: zod_1.z.coerce.number().min(0).max(1).optional(),
+    searchMode: zod_1.z.enum(['hybrid', 'vector', 'keyword']).optional(),
+});
+exports.listQuerySchema = zod_1.z.object({
+    filter: zod_1.z.string().optional(),
+    limit: zod_1.z.coerce.number().int().positive().optional(),
+});
+// ---------------------------------------------------------------------------
+// File index schemas
+// ---------------------------------------------------------------------------
+exports.fileListSchema = zod_1.z.object({
+    directory: zod_1.z.string().optional(),
+    extension: zod_1.z.string().optional(),
+    language: zod_1.z.string().optional(),
+    filter: zod_1.z.string().optional(),
+    limit: zod_1.z.coerce.number().int().positive().optional(),
+});
+// ---------------------------------------------------------------------------
+// Graph export schema
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Skill schemas
+// ---------------------------------------------------------------------------
+exports.createSkillSchema = zod_1.z.object({
+    title: zod_1.z.string().min(1).max(500),
+    description: zod_1.z.string().max(500_000).default(''),
+    steps: zod_1.z.array(zod_1.z.string().max(10_000)).max(100).optional().default([]),
+    triggers: zod_1.z.array(zod_1.z.string().max(500)).max(50).optional().default([]),
+    inputHints: zod_1.z.array(zod_1.z.string().max(500)).max(50).optional().default([]),
+    filePatterns: zod_1.z.array(zod_1.z.string().max(500)).max(50).optional().default([]),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(100).optional().default([]),
+    source: zod_1.z.enum(['user', 'learned']).default('user'),
+    confidence: zod_1.z.number().min(0).max(1).default(1),
+});
+exports.updateSkillSchema = zod_1.z.object({
+    title: zod_1.z.string().min(1).max(500).optional(),
+    description: zod_1.z.string().max(500_000).optional(),
+    steps: zod_1.z.array(zod_1.z.string().max(10_000)).max(100).optional(),
+    triggers: zod_1.z.array(zod_1.z.string().max(500)).max(50).optional(),
+    inputHints: zod_1.z.array(zod_1.z.string().max(500)).max(50).optional(),
+    filePatterns: zod_1.z.array(zod_1.z.string().max(500)).max(50).optional(),
+    tags: zod_1.z.array(zod_1.z.string().max(100)).max(100).optional(),
+    source: zod_1.z.enum(['user', 'learned']).optional(),
+    confidence: zod_1.z.number().min(0).max(1).optional(),
+    version: zod_1.z.number().int().positive().optional(),
+});
+exports.createSkillLinkSchema = zod_1.z.object({
+    fromId: zod_1.z.string().min(1),
+    toId: zod_1.z.string().min(1),
+    kind: zod_1.z.string().min(1),
+    targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'knowledge', 'tasks']).optional(),
+    projectId: zod_1.z.string().min(1).optional(),
+});
+exports.skillSearchSchema = zod_1.z.object({
+    q: zod_1.z.string().min(1).max(2000),
+    topK: zod_1.z.coerce.number().int().positive().max(500).optional(),
+    minScore: zod_1.z.coerce.number().min(0).max(1).optional(),
+    searchMode: zod_1.z.enum(['hybrid', 'vector', 'keyword']).optional(),
+});
+exports.skillListSchema = zod_1.z.object({
+    source: zod_1.z.enum(['user', 'learned']).optional(),
+    tag: zod_1.z.string().optional(),
+    filter: zod_1.z.string().optional(),
+    limit: zod_1.z.coerce.number().int().positive().optional(),
+});
+exports.graphExportSchema = zod_1.z.object({
+    scope: zod_1.z.enum(['all', 'docs', 'code', 'knowledge', 'tasks', 'files', 'skills']).default('all'),
+});
+// ---------------------------------------------------------------------------
+// Attachment schemas
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Linked query schema (cross-graph reverse lookup)
+// ---------------------------------------------------------------------------
+exports.linkedQuerySchema = zod_1.z.object({
+    targetGraph: zod_1.z.enum(['docs', 'code', 'files', 'knowledge', 'tasks', 'skills']),
+    targetNodeId: zod_1.z.string().min(1).max(500),
+    kind: zod_1.z.string().max(100).optional(),
+    projectId: zod_1.z.string().max(200).optional(),
+});
+// ---------------------------------------------------------------------------
+// Attachment schemas
+// ---------------------------------------------------------------------------
+/** Validates an attachment filename (path param). No path separators, no .., no null bytes. */
+exports.attachmentFilenameSchema = zod_1.z.string()
+    .min(1)
+    .refine(s => !/[/\\]/.test(s), 'Filename must not contain path separators')
+    .refine(s => !s.includes('..'), 'Filename must not contain ..')
+    .refine(s => !s.includes('\0'), 'Filename must not contain null bytes');

package/dist/api/rest/websocket.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachWebSocket = attachWebSocket;
+const ws_1 = require("ws");
+/**
+ * Attach a WebSocket server to the HTTP server at /api/ws.
+ * Broadcasts all ProjectManager events to connected clients.
+ * Each event includes projectId — clients filter on their side.
+ */
+function attachWebSocket(httpServer, projectManager) {
+    const wss = new ws_1.WebSocketServer({ noServer: true });
+    // Handle upgrade requests for /api/ws
+    httpServer.on('upgrade', (req, socket, head) => {
+        if (req.url !== '/api/ws') {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit('connection', ws, req);
+        });
+    });
+    // Broadcast helper
+    function broadcast(event) {
+        const msg = JSON.stringify(event);
+        for (const client of wss.clients) {
+            if (client.readyState === ws_1.WebSocket.OPEN) {
+                client.send(msg);
+            }
+        }
+    }
+    // Subscribe to ProjectManager events
+    const events = [
+        'note:created', 'note:updated', 'note:deleted',
+        'note:attachment:added', 'note:attachment:deleted',
+        'task:created', 'task:updated', 'task:deleted', 'task:moved',
+        'task:attachment:added', 'task:attachment:deleted',
+        'skill:created', 'skill:updated', 'skill:deleted',
+        'skill:attachment:added', 'skill:attachment:deleted',
+        'project:indexed',
+    ];
+    for (const eventType of events) {
+        projectManager.on(eventType, (data) => {
+            broadcast({ projectId: data.projectId, type: eventType, data });
+        });
+    }
+    // Debounced graph:updated from indexer
+    let graphUpdateTimer;
+    let pendingGraphUpdates = new Map();
+    projectManager.on('graph:updated', (data) => {
+        const key = data.projectId;
+        if (!pendingGraphUpdates.has(key))
+            pendingGraphUpdates.set(key, []);
+        pendingGraphUpdates.get(key).push(data.file);
+        if (!graphUpdateTimer) {
+            graphUpdateTimer = setTimeout(() => {
+                for (const [projectId, files] of pendingGraphUpdates) {
+                    broadcast({ projectId, type: 'graph:updated', data: { files } });
+                }
+                pendingGraphUpdates = new Map();
+                graphUpdateTimer = undefined;
+            }, 1000);
+        }
+    });
+    return wss;
+}

package/dist/api/tools/code/get-file-symbols.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('get_file_symbols', {
+        description: 'Return all symbols (functions, classes, types, etc.) declared in a specific file. ' +
+            'Use this to understand the structure of a file before reading individual symbols. ' +
+            'Returns an array of { id, kind, name, signature, startLine, endLine, isExported }. ' +
+            'Pass an id to get_symbol to fetch full content including body and docComment.',
+        inputSchema: {
+            fileId: zod_1.z.string().describe('File path relative to code dir, e.g. "src/lib/graph.ts"'),
+        },
+    }, async ({ fileId }) => {
+        const symbols = mgr.getFileSymbols(fileId);
+        if (symbols.length === 0) {
+            return { content: [{ type: 'text', text: `File not found: ${fileId}` }], isError: true };
+        }
+        const result = symbols.map(s => ({
+            id: s.id,
+            kind: s.kind,
+            name: s.name,
+            signature: s.signature,
+            startLine: s.startLine,
+            endLine: s.endLine,
+            isExported: s.isExported,
+        }));
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/api/tools/code/get-symbol.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('get_symbol', {
+        description: 'Return the full content of a specific code symbol. ' +
+            'Use this after search_code or get_file_symbols to read the full implementation. ' +
+            'Node IDs have the form "fileId::symbolName" or "fileId::ClassName::methodName". ' +
+            'Returns id, fileId, kind, name, signature, docComment, body, startLine, endLine, isExported, and crossLinks (notes/tasks linking to this symbol).',
+        inputSchema: {
+            nodeId: zod_1.z.string().describe('Symbol ID from search_code or get_file_symbols, e.g. "src/lib/graph.ts::updateFile"'),
+        },
+    }, async ({ nodeId }) => {
+        const symbol = mgr.getSymbol(nodeId);
+        if (!symbol) {
+            return { content: [{ type: 'text', text: `Symbol not found: ${nodeId}` }], isError: true };
+        }
+        const { embedding: _embedding, mtime: _mtime, ...rest } = symbol;
+        return { content: [{ type: 'text', text: JSON.stringify(rest, null, 2) }] };
+    });
+}

package/dist/api/tools/code/list-files.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('list_files', {
+        description: 'List indexed source files in the code graph. ' +
+            'Optionally filter by file name substring (case-insensitive) and limit results. ' +
+            'Returns an array of { fileId, symbolCount }. ' +
+            'Pass a fileId to get_file_symbols to see all its declarations.',
+        inputSchema: {
+            filter: zod_1.z.string().optional().describe('Case-insensitive substring to match against file paths, e.g. "graph" or "src/lib"'),
+            limit: zod_1.z.number().optional().describe('Maximum number of results to return (default 20)'),
+        },
+    }, async ({ filter, limit }) => ({
+        content: [{ type: 'text', text: JSON.stringify(mgr.listFiles(filter, limit), null, 2) }],
+    }));
+}

package/dist/api/tools/code/search-code.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('search_code', {
+        description: 'Semantic search over the indexed source code. ' +
+            'Finds the most relevant symbols (functions, classes, types) by matching ' +
+            'against their signatures and doc comments using vector similarity, ' +
+            'then expands results by following graph edges (imports, contains, extends). ' +
+            'Returns an array sorted by relevance score (0–1), each with: ' +
+            'id, fileId, kind, name, signature, docComment, startLine, endLine, score. ' +
+            'Pass an id to get_symbol to read the full implementation.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language or code search query, e.g. "function that loads the graph from disk"'),
+            topK: zod_1.z.number().optional().describe('How many top similar symbols to use as seeds (default 5)'),
+            bfsDepth: zod_1.z.number().optional().describe('How many hops to follow graph edges from each seed (default 1; 0 = no expansion)'),
+            maxResults: zod_1.z.number().optional().describe('Maximum number of results to return (default 20)'),
+            minScore: zod_1.z.number().min(0).max(1).optional().describe('Minimum relevance score 0–1; lower values return more results (default 0.5)'),
+            bfsDecay: zod_1.z.number().min(0).max(1).optional().describe('Score multiplier per graph hop (default 0.8)'),
+            searchMode: zod_1.z.enum(['hybrid', 'vector', 'keyword']).optional().describe('Search mode: hybrid (default, BM25 + vector), vector (embedding only), keyword (BM25 only)'),
+        },
+    }, async ({ query, topK, bfsDepth, maxResults, minScore, bfsDecay, searchMode }) => {
+        const results = await mgr.search(query, { topK, bfsDepth, maxResults, minScore, bfsDecay, searchMode });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/code/search-files.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('search_files', {
+        description: 'Semantic search over indexed source code files. ' +
+            'Finds the most relevant files by matching query against file-level embeddings ' +
+            '(file path) using vector similarity. ' +
+            'Returns an array sorted by relevance score (0–1), each with: ' +
+            'fileId, symbolCount, score. ' +
+            'Use this to discover which source files are relevant before diving into symbols with get_file_symbols or search_code.',
+        inputSchema: {
+            query: zod_1.z.string().describe('Natural language or path search query, e.g. "graph persistence" or "search module"'),
+            topK: zod_1.z.number().optional().describe('Maximum number of results to return (default 10)'),
+            minScore: zod_1.z.number().min(0).max(1).optional().describe('Minimum relevance score 0–1 (default 0.3)'),
+        },
+    }, async ({ query, topK, minScore }) => {
+        const results = await mgr.searchFiles(query, { topK, minScore });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}

package/dist/api/tools/context/get-context.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+function register(server, ctx) {
+    server.registerTool('get_context', {
+        description: 'Returns the current project and workspace context. ' +
+            'Use this to discover which project you are connected to, whether it is part of a workspace, ' +
+            'and which other projects are available in the workspace (for cross-graph links with projectId).',
+        inputSchema: {},
+    }, async () => {
+        const result = {
+            projectId: ctx?.projectId ?? null,
+            workspaceId: ctx?.workspaceId ?? null,
+            workspaceProjects: ctx?.workspaceProjects ?? null,
+            hasWorkspace: !!ctx?.workspaceId,
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/api/tools/docs/cross-references.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, docMgr, codeMgr) {
+    const docGraph = docMgr.graph;
+    const codeGraph = codeMgr.graph;
+    server.registerTool('cross_references', {
+        description: 'Find all references to a symbol across both code and documentation graphs. ' +
+            'Returns: definitions (from CodeGraph — where the symbol is defined), ' +
+            'documentation (text sections in docs that contain examples using the symbol), ' +
+            'and examples (code blocks in docs that contain the symbol). ' +
+            'This is the most comprehensive way to understand a symbol — combining source code, docs, and examples.',
+        inputSchema: {
+            symbol: zod_1.z.string().describe('Symbol name to look up, e.g. "createUser", "AuthService"'),
+        },
+    }, async ({ symbol }) => {
+        // 1. Search CodeGraph for definitions
+        const definitions = [];
+        codeGraph.forEachNode((id, attrs) => {
+            if (attrs.name === symbol) {
+                definitions.push({
+                    id,
+                    fileId: attrs.fileId,
+                    kind: attrs.kind,
+                    name: attrs.name,
+                    signature: attrs.signature,
+                    docComment: attrs.docComment,
+                    startLine: attrs.startLine,
+                    endLine: attrs.endLine,
+                });
+            }
+        });
+        // 2. Search DocGraph for code blocks containing the symbol
+        const examples = [];
+        const documentation = [];
+        const seenDocs = new Set();
+        docGraph.forEachNode((id, attrs) => {
+            if (attrs.symbols.length === 0)
+                return;
+            if (!attrs.symbols.includes(symbol))
+                return;
+            examples.push({
+                id,
+                fileId: attrs.fileId,
+                language: attrs.language,
+                symbols: attrs.symbols,
+                content: attrs.content,
+            });
+            // Find parent text section for documentation context
+            for (const neighbor of docGraph.inNeighbors(id)) {
+                if (seenDocs.has(neighbor))
+                    continue;
+                const nAttrs = docGraph.getNodeAttributes(neighbor);
+                if (nAttrs.fileId === attrs.fileId && nAttrs.language === undefined && nAttrs.level < attrs.level) {
+                    seenDocs.add(neighbor);
+                    documentation.push({
+                        id: neighbor,
+                        fileId: nAttrs.fileId,
+                        title: nAttrs.title,
+                        content: nAttrs.content,
+                    });
+                }
+            }
+        });
+        if (definitions.length === 0 && examples.length === 0) {
+            return { content: [{ type: 'text', text: `No references found for symbol: ${symbol}` }] };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ definitions, documentation, examples }, null, 2),
+                }],
+        };
+    });
+}

package/dist/api/tools/docs/explain-symbol.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    const graph = mgr.graph;
+    server.registerTool('explain_symbol', {
+        description: 'Find documentation that explains a specific symbol. ' +
+            'Searches code blocks in docs for the symbol, then returns both the code example ' +
+            'and the surrounding text section that provides context/explanation. ' +
+            'Use this to understand what a function, class, or type does based on documentation.',
+        inputSchema: {
+            symbol: zod_1.z.string().describe('Symbol name to look up, e.g. "createUser", "AuthService"'),
+            limit: zod_1.z.number().optional().describe('Max results to return (default 10)'),
+        },
+    }, async ({ symbol, limit = 10 }) => {
+        const results = [];
+        graph.forEachNode((id, attrs) => {
+            if (results.length >= limit)
+                return;
+            if (attrs.symbols.length === 0)
+                return;
+            if (!attrs.symbols.includes(symbol))
+                return;
+            // Find the parent text section
+            const parent = findParentTextSection(graph, id, attrs);
+            results.push({
+                codeBlock: {
+                    id,
+                    language: attrs.language,
+                    symbols: attrs.symbols,
+                    content: attrs.content,
+                },
+                explanation: parent
+                    ? { id: parent.id, title: parent.title, content: parent.content }
+                    : null,
+                fileId: attrs.fileId,
+            });
+        });
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: `No documentation found for symbol: ${symbol}` }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}
+function findParentTextSection(graph, nodeId, attrs) {
+    // The code block's in-neighbor with same fileId, lower level, and no language = parent text section
+    for (const neighbor of graph.inNeighbors(nodeId)) {
+        const nAttrs = graph.getNodeAttributes(neighbor);
+        if (nAttrs.fileId === attrs.fileId && nAttrs.language === undefined && nAttrs.level < attrs.level) {
+            return { id: neighbor, title: nAttrs.title, content: nAttrs.content };
+        }
+    }
+    return null;
+}

package/dist/api/tools/docs/find-examples.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    const graph = mgr.graph;
+    server.registerTool('find_examples', {
+        description: 'Find code examples in documentation that contain a specific symbol (function, class, interface, etc.). ' +
+            'Searches the `symbols` array extracted from fenced code blocks via AST parsing. ' +
+            'Use this to find usage examples of a known symbol in the docs. ' +
+            'Returns matching code block nodes with id, fileId, language, symbols, content, and the parent section context.',
+        inputSchema: {
+            symbol: zod_1.z.string().describe('Symbol name to search for, e.g. "createUser", "UserService"'),
+            limit: zod_1.z.number().optional().describe('Max results to return (default 20)'),
+        },
+    }, async ({ symbol, limit = 20 }) => {
+        const results = [];
+        graph.forEachNode((id, attrs) => {
+            if (results.length >= limit)
+                return;
+            if (attrs.symbols.length === 0)
+                return;
+            if (!attrs.symbols.includes(symbol))
+                return;
+            // Find parent text section (previous node with lower level and no language)
+            const parentId = findParentSection(graph, id, attrs);
+            results.push({
+                id,
+                fileId: attrs.fileId,
+                language: attrs.language,
+                symbols: attrs.symbols,
+                content: attrs.content,
+                parentId,
+                parentTitle: parentId ? graph.getNodeAttribute(parentId, 'title') : undefined,
+            });
+        });
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: `No code examples found containing symbol: ${symbol}` }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+}
+function findParentSection(graph, nodeId, attrs) {
+    // Walk inNeighbors (sibling edges point forward, so the parent is an inNeighbor)
+    for (const neighbor of graph.inNeighbors(nodeId)) {
+        const nAttrs = graph.getNodeAttributes(neighbor);
+        if (nAttrs.fileId === attrs.fileId && nAttrs.language === undefined && nAttrs.level < attrs.level) {
+            return neighbor;
+        }
+    }
+    return undefined;
+}

package/dist/api/tools/docs/get-node.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('get_node', {
+        description: 'Return the full content of a specific node (file root or section). ' +
+            'Use this after search or get_toc to read the full text of a result. ' +
+            'Node IDs have two forms: ' +
+            '"docs/auth.md" for the file root (intro text before any headings), ' +
+            '"docs/auth.md::Overview" for a named section. ' +
+            'Returns id, fileId, title, content, level, links, mtime, and crossLinks (notes/tasks linking to this node).',
+        inputSchema: {
+            nodeId: zod_1.z.string().describe('Node ID from search results or get_toc, e.g. "docs/auth.md" or "docs/auth.md::Overview"'),
+        },
+    }, async ({ nodeId }) => {
+        const node = mgr.getNode(nodeId);
+        if (!node) {
+            return { content: [{ type: 'text', text: `Node not found: ${nodeId}` }], isError: true };
+        }
+        const { embedding: _embedding, ...rest } = node;
+        return { content: [{ type: 'text', text: JSON.stringify(rest, null, 2) }] };
+    });
+}

package/dist/api/tools/docs/get-toc.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const zod_1 = require("zod");
+function register(server, mgr) {
+    server.registerTool('get_toc', {
+        description: 'Return the table of contents (headings hierarchy) for a specific file. ' +
+            'Use this to understand the structure of a file before deciding which sections to read. ' +
+            'Returns an array of { id, title, level } objects. ' +
+            'The id field is a node ID you can pass directly to get_node to fetch full content.',
+        inputSchema: {
+            fileId: zod_1.z.string().describe('File path relative to docs dir, e.g. "docs/auth.md"'),
+        },
+    }, async ({ fileId }) => {
+        const chunks = mgr.getFileChunks(fileId);
+        if (chunks.length === 0) {
+            return { content: [{ type: 'text', text: `File not found: ${fileId}` }], isError: true };
+        }
+        const toc = chunks.map(c => ({ id: c.id, title: c.title, level: c.level }));
+        return { content: [{ type: 'text', text: JSON.stringify(toc, null, 2) }] };
+    });
+}