ai-mind-map 1.1.0

package/dist/tools/evolving-tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AI Mind Map — Self-Evolving MCP Tools
+ *
+ * These tools let the AI TEACH the system new patterns that persist
+ * per-project in SQLite. The system evolves over time on each user's
+ * machine as the AI learns project-specific conventions.
+ *
+ * Tools:
+ *   - mindmap_teach     — AI teaches a new rule (classification, search alias, convention)
+ *   - mindmap_get_learned — View all learned rules
+ *   - mindmap_forget    — Remove a learned rule
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { MindMapConfig } from '../types.js';
+import { KnowledgeGraph } from '../knowledge-graph/graph.js';
+export interface ITokenEstimator {
+    estimate(text: string): number;
+}
+/**
+ * Register self-evolving tools — AI can teach the system new patterns.
+ */
+export declare function registerEvolvingTools(server: McpServer, graph: KnowledgeGraph, config: MindMapConfig, estimator?: ITokenEstimator): void;
+//# sourceMappingURL=evolving-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evolving-tools.d.ts","sourceRoot":"","sources":["../../src/tools/evolving-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAM7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AA0BD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,eAAkC,GAC5C,IAAI,CA4LN"}

package/dist/tools/evolving-tools.js

@@ -0,0 +1,207 @@
+/**
+ * AI Mind Map — Self-Evolving MCP Tools
+ *
+ * These tools let the AI TEACH the system new patterns that persist
+ * per-project in SQLite. The system evolves over time on each user's
+ * machine as the AI learns project-specific conventions.
+ *
+ * Tools:
+ *   - mindmap_teach     — AI teaches a new rule (classification, search alias, convention)
+ *   - mindmap_get_learned — View all learned rules
+ *   - mindmap_forget    — Remove a learned rule
+ */
+import { z } from 'zod';
+const defaultEstimator = {
+    estimate: (text) => Math.ceil(text.length / 4),
+};
+function mcpText(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+}
+function ok(data, estimator) {
+    const serialised = JSON.stringify(data);
+    const tokens = estimator.estimate(serialised);
+    return { success: true, data, tokenCount: tokens, tokensSaved: 0 };
+}
+function fail(message) {
+    return { success: false, data: null, tokenCount: 0, tokensSaved: 0, message };
+}
+// ============================================================
+// Registration
+// ============================================================
+/**
+ * Register self-evolving tools — AI can teach the system new patterns.
+ */
+export function registerEvolvingTools(server, graph, config, estimator = defaultEstimator) {
+    // ── mindmap_teach ────────────────────────────────────────────
+    server.tool('mindmap_teach', 'Teach the AI Mind Map a new rule that persists on this machine. ' +
+        'The rule is saved in the project database and automatically applied ' +
+        'in future sessions. Use this when:\n' +
+        '- A file/pattern is misclassified → teach a classification rule\n' +
+        '- You keep searching for synonyms → teach a search alias\n' +
+        '- You notice a project convention → teach a convention\n' +
+        '- You spot a code pattern → teach a code pattern\n\n' +
+        'Examples:\n' +
+        '  Classification: { type: "classification", name: "bloc_files", layer: "state_update", ' +
+        'source: "path", patterns: ["\\\\.bloc\\\\.dart$"], weight: 3 }\n' +
+        '  Search alias: { type: "search_alias", name: "auth_aliases", term: "auth", ' +
+        'aliases: ["login", "authentication", "session", "jwt"] }\n' +
+        '  Convention: { type: "convention", name: "api_naming", description: "All API methods end with Async" }', {
+        type: z.enum(['classification', 'search_alias', 'code_pattern', 'convention'])
+            .describe('Type of rule to teach'),
+        name: z.string().min(1).max(100)
+            .describe('Unique name for this rule (e.g., "flutter_bloc_pattern", "auth_search_alias")'),
+        description: z.string().min(1)
+            .describe('Human-readable description of what this rule does'),
+        // Classification-specific
+        layer: z.string().optional()
+            .describe('For classification rules: target layer (e.g., "service", "ui_component", "database")'),
+        source: z.enum(['content', 'path', 'directory', 'import', 'symbol_name']).optional()
+            .describe('For classification rules: what to match against'),
+        patterns: z.array(z.string()).optional()
+            .describe('Regex patterns to match (as strings). Example: ["Manager\\\\.cs$", "Service\\\\.cs$"]'),
+        weight: z.number().int().min(1).max(5).optional()
+            .describe('For classification rules: signal weight 1-5 (default 3)'),
+        // Search alias-specific
+        term: z.string().optional()
+            .describe('For search_alias: the search term to create aliases for'),
+        aliases: z.array(z.string()).optional()
+            .describe('For search_alias: alternative terms to also search for'),
+        // Code pattern / convention
+        details: z.record(z.unknown()).optional()
+            .describe('Any additional structured data for the rule'),
+    }, async ({ type, name, description, layer, source, patterns, weight, term, aliases, details }) => {
+        try {
+            // Validate patterns are valid regex
+            if (patterns) {
+                for (const p of patterns) {
+                    try {
+                        new RegExp(p);
+                    }
+                    catch (e) {
+                        return mcpText(fail(`Invalid regex pattern "${p}": ${e}`));
+                    }
+                }
+            }
+            // Build the rule JSON based on type
+            let ruleData = {};
+            switch (type) {
+                case 'classification':
+                    if (!layer)
+                        return mcpText(fail('Classification rules require "layer" (e.g., "service", "database")'));
+                    if (!patterns || patterns.length === 0)
+                        return mcpText(fail('Classification rules require at least one "patterns" regex'));
+                    ruleData = {
+                        layer,
+                        source: source ?? 'path',
+                        patterns,
+                        weight: weight ?? 3,
+                    };
+                    break;
+                case 'search_alias':
+                    if (!term)
+                        return mcpText(fail('Search alias rules require "term" (the term to create aliases for)'));
+                    if (!aliases || aliases.length === 0)
+                        return mcpText(fail('Search alias rules require at least one "aliases" entry'));
+                    ruleData = { term, aliases };
+                    break;
+                case 'code_pattern':
+                case 'convention':
+                    ruleData = {
+                        ...(patterns ? { patterns } : {}),
+                        ...(layer ? { layer } : {}),
+                        ...(details ?? {}),
+                    };
+                    break;
+            }
+            const result = graph.addLearnedRule({
+                type,
+                name,
+                description,
+                rule: ruleData,
+                createdBy: 'ai',
+            });
+            const response = {
+                ...result,
+                name,
+                type,
+                description,
+                rule: ruleData,
+                message: result.created
+                    ? `✅ New ${type} rule "${name}" has been learned and will persist across sessions.`
+                    : `🔄 Updated existing ${type} rule "${name}" with new definition.`,
+                hint: type === 'classification'
+                    ? 'This rule will be automatically used by the classification engine to score files.'
+                    : type === 'search_alias'
+                        ? 'When someone searches for "' + term + '", the system will also search for: ' + (aliases?.join(', ') ?? '')
+                        : 'This rule is stored as project knowledge and can be recalled with mindmap_get_learned.',
+            };
+            return mcpText(ok(response, estimator));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return mcpText(fail(`teach failed: ${msg}`));
+        }
+    });
+    // ── mindmap_get_learned ──────────────────────────────────────
+    server.tool('mindmap_get_learned', 'View all rules the AI has taught this project. Shows classification rules, ' +
+        'search aliases, code patterns, and conventions — sorted by usage count. ' +
+        'Use this at the start of a session to see what the system has already learned.', {
+        type: z.enum(['classification', 'search_alias', 'code_pattern', 'convention', 'all'])
+            .default('all')
+            .describe('Filter by rule type, or "all" for everything'),
+    }, async ({ type }) => {
+        try {
+            const rules = type === 'all'
+                ? graph.getLearnedRules()
+                : graph.getLearnedRules(type);
+            // Group by type for display
+            const grouped = {};
+            for (const rule of rules) {
+                if (!grouped[rule.type])
+                    grouped[rule.type] = [];
+                grouped[rule.type].push(rule);
+            }
+            const result = {
+                totalRules: rules.length,
+                rulesByType: grouped,
+                rules,
+                summary: rules.length > 0
+                    ? `This project has ${rules.length} learned rule(s): ` +
+                        Object.entries(grouped).map(([t, r]) => `${r.length} ${t}`).join(', ')
+                    : 'No rules learned yet. Use mindmap_teach to add project-specific knowledge.',
+            };
+            return mcpText(ok(result, estimator));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return mcpText(fail(`get_learned failed: ${msg}`));
+        }
+    });
+    // ── mindmap_forget ───────────────────────────────────────────
+    server.tool('mindmap_forget', 'Remove a learned rule by its name or ID. Use mindmap_get_learned first ' +
+        'to see all rules and their IDs.', {
+        nameOrId: z.string()
+            .describe('Name or ID of the rule to remove'),
+    }, async ({ nameOrId }) => {
+        try {
+            const deleted = graph.deleteLearnedRule(nameOrId);
+            if (deleted) {
+                return mcpText(ok({
+                    deleted: true,
+                    nameOrId,
+                    message: `✅ Rule "${nameOrId}" has been forgotten.`,
+                }, estimator));
+            }
+            else {
+                return mcpText(fail(`Rule not found: "${nameOrId}". Use mindmap_get_learned to see all rules.`));
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return mcpText(fail(`forget failed: ${msg}`));
+        }
+    });
+}
+//# sourceMappingURL=evolving-tools.js.map

package/dist/tools/evolving-tools.js.map

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

package/dist/tools/flow-tools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AI Mind Map — Flow & Interaction Map MCP Tools
+ *
+ * Tools that let the AI agent understand the BEHAVIORAL flow of the app:
+ *   "What happens when user clicks Save?"
+ *   "What's the pipeline from button to database?"
+ *   "Show me all routes and what they connect to"
+ *   "Which layer does this file belong to?"
+ *
+ * This is the feature that makes the AI NOT waste tokens figuring out
+ * the logic flow — we pre-map it for the agent.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { MindMapConfig } from '../types.js';
+import { KnowledgeGraph } from '../knowledge-graph/graph.js';
+interface ITokenEstimator {
+    estimate(text: string): number;
+}
+/**
+ * Register all flow/interaction map tools on the MCP server.
+ */
+export declare function registerFlowTools(server: McpServer, graph: KnowledgeGraph, config: MindMapConfig, estimator?: ITokenEstimator): void;
+export {};
+//# sourceMappingURL=flow-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow-tools.d.ts","sourceRoot":"","sources":["../../src/tools/flow-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAc,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAQ7D,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AA0BD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,eAAkC,GAC5C,IAAI,CAyMN"}

package/dist/tools/flow-tools.js

@@ -0,0 +1,265 @@
+/**
+ * AI Mind Map — Flow & Interaction Map MCP Tools
+ *
+ * Tools that let the AI agent understand the BEHAVIORAL flow of the app:
+ *   "What happens when user clicks Save?"
+ *   "What's the pipeline from button to database?"
+ *   "Show me all routes and what they connect to"
+ *   "Which layer does this file belong to?"
+ *
+ * This is the feature that makes the AI NOT waste tokens figuring out
+ * the logic flow — we pre-map it for the agent.
+ */
+import { z } from 'zod';
+import { FlowAnalyzer } from '../knowledge-graph/flow-analyzer.js';
+const defaultEstimator = {
+    estimate: (text) => Math.ceil(text.length / 4),
+};
+function mcpText(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+}
+function ok(data, estimator, saved = 0) {
+    const serialised = JSON.stringify(data);
+    const tokens = estimator.estimate(serialised);
+    return { success: true, data, tokenCount: tokens, tokensSaved: saved };
+}
+function fail(message) {
+    return { success: false, data: null, tokenCount: 0, tokensSaved: 0, message };
+}
+// ============================================================
+// Registration
+// ============================================================
+/**
+ * Register all flow/interaction map tools on the MCP server.
+ */
+export function registerFlowTools(server, graph, config, estimator = defaultEstimator) {
+    const analyzer = new FlowAnalyzer(graph, config.projectRoot);
+    // ── mindmap_trace_flow ────────────────────────────────────
+    server.tool('mindmap_trace_flow', `🔗 Trace the FULL PIPELINE from a function/button/event to its final effect.
+Example: "What happens when createNote() is called?" → shows the complete chain:
+  createNote() → validateInput() → notesService.save() → db.insert() → emitEvent()
+Each step shows: which layer (UI/controller/service/DB), which file, which function.
+The AI doesn't need to read any code to understand the flow.`, {
+        symbol: z
+            .string()
+            .describe('Function/method/component name to trace (e.g. "handleSaveClick", "createNote", "POST /api/notes")'),
+        maxDepth: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .default(10)
+            .describe('Max call-chain depth to follow (default 10)'),
+    }, async ({ symbol, maxDepth }) => {
+        try {
+            const flow = analyzer.traceFlow(symbol, maxDepth);
+            if (flow.steps.length === 0) {
+                return mcpText(fail(`Could not trace flow for "${symbol}" — symbol not found or has no call chain.`));
+            }
+            // Build a visual pipeline string
+            const pipeline = flow.steps
+                .map((s, i) => {
+                const indent = '  '.repeat(Math.min(i, 5));
+                const arrow = i === 0 ? '🟢' : '  →';
+                const layerIcon = getLayerIcon(s.layer);
+                return `${indent}${arrow} ${layerIcon} [${s.layer}] ${s.symbolName}() — ${s.filePath}:${s.line}`;
+            })
+                .join('\n');
+            return mcpText(ok({
+                flow: {
+                    name: flow.name,
+                    trigger: flow.trigger,
+                    stepsCount: flow.steps.length,
+                    riskLevel: flow.riskLevel,
+                    sideEffects: flow.sideEffects,
+                    filesInvolved: flow.filesInvolved,
+                },
+                pipeline,
+                steps: flow.steps,
+                tip: `This flow touches ${flow.filesInvolved.length} files and has ${flow.sideEffects.length} side effects. Risk level: ${flow.riskLevel}.`,
+            }, estimator));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return mcpText(fail(`trace_flow failed: ${msg}`));
+        }
+    });
+    // ── mindmap_interaction_map ───────────────────────────────
+    server.tool('mindmap_interaction_map', `🗺️ Get the FULL INTERACTION MAP of the application.
+Shows: all routes → handlers → services → DB calls, all UI events → handlers,
+all components with their actions, state, and data sources.
+Also classifies every file by layer (UI, controller, service, repository, DB, etc.)
+This is the app's behavioral blueprint — the AI reads this ONCE and understands the whole app.`, {}, async () => {
+        try {
+            const map = analyzer.buildInteractionMap();
+            // Build a compact summary
+            const summary = {
+                totalRoutes: map.routes.length,
+                totalEventHandlers: map.eventHandlers.length,
+                totalComponents: map.components.length,
+                layerBreakdown: Object.entries(map.layerSummary)
+                    .filter(([, count]) => count > 0)
+                    .sort(([, a], [, b]) => b - a)
+                    .map(([layer, count]) => `${getLayerIcon(layer)} ${layer}: ${count} symbols`),
+            };
+            // Compact route list
+            const routeSummary = map.routes.slice(0, 15).map((r) => ({
+                name: r.name,
+                trigger: r.trigger,
+                steps: r.steps.length,
+                risk: r.riskLevel,
+                pipeline: r.steps
+                    .map((s) => `${getLayerIcon(s.layer)}${s.symbolName}`)
+                    .join(' → '),
+                sideEffects: r.sideEffects,
+            }));
+            // Compact component list
+            const componentSummary = map.components.slice(0, 15).map((c) => ({
+                name: c.name,
+                file: c.filePath,
+                actions: c.actions.map((a) => a.trigger).join(', ') || 'none',
+                state: c.state.join(', ') || 'none',
+                children: c.children.join(', ') || 'none',
+                dataSources: c.dataSources.join(', ') || 'none',
+            }));
+            return mcpText(ok({
+                summary,
+                routes: routeSummary,
+                eventHandlers: map.eventHandlers.slice(0, 15).map((e) => ({
+                    name: e.name,
+                    trigger: e.trigger,
+                    pipeline: e.steps
+                        .map((s) => `${getLayerIcon(s.layer)}${s.symbolName}`)
+                        .join(' → '),
+                    risk: e.riskLevel,
+                })),
+                components: componentSummary,
+                fileClassification: map.filesByLayer,
+                tip: 'Use mindmap_trace_flow to drill into any specific flow. Use mindmap_classify_file to understand where a file fits.',
+            }, estimator));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return mcpText(fail(`interaction_map failed: ${msg}`));
+        }
+    });
+    // ── mindmap_classify_file ─────────────────────────────────
+    server.tool('mindmap_classify_file', `📂 Classify a file by its architectural layer.
+Returns: whether the file is a UI component, controller, service, repository, 
+database layer, middleware, validator, utility, etc.
+Helps the AI understand WHERE a file fits in the architecture without reading it.`, {
+        filePath: z
+            .string()
+            .describe('File path to classify (relative or absolute)'),
+    }, async ({ filePath }) => {
+        try {
+            const fullPath = filePath.startsWith('/') || filePath.includes(':')
+                ? filePath
+                : `${config.projectRoot}/${filePath}`;
+            const layer = analyzer.classifyFile(fullPath);
+            return mcpText(ok({
+                filePath,
+                layer,
+                icon: getLayerIcon(layer),
+                description: getLayerDescription(layer),
+                typical_contents: getLayerTypicalContents(layer),
+            }, estimator));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return mcpText(fail(`classify_file failed: ${msg}`));
+        }
+    });
+    // ── mindmap_layer_overview ────────────────────────────────
+    server.tool('mindmap_layer_overview', `📊 Show how the app is organized by architectural layers.
+Returns: count of files and symbols per layer (UI, controller, service, DB, etc.)
+with the key files and functions in each layer. 
+One-shot understanding of the app's structure.`, {}, async () => {
+        try {
+            const overview = analyzer.getLayerOverview();
+            if (overview.length === 0) {
+                return mcpText(fail('No indexed files found — run mindmap_reindex first.'));
+            }
+            // Build visual layer diagram
+            const diagram = overview
+                .map((l) => {
+                const icon = getLayerIcon(l.layer);
+                const bar = '█'.repeat(Math.min(Math.ceil(l.symbolCount / 5), 20));
+                return `${icon} ${l.layer.padEnd(15)} │ ${String(l.fileCount).padStart(3)} files │ ${String(l.symbolCount).padStart(4)} symbols │ ${bar}`;
+            })
+                .join('\n');
+            return mcpText(ok({
+                diagram,
+                layers: overview,
+                tip: 'Use mindmap_trace_flow to see how these layers connect. Use mindmap_interaction_map for the full behavioral blueprint.',
+            }, estimator));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return mcpText(fail(`layer_overview failed: ${msg}`));
+        }
+    });
+}
+// ============================================================
+// UI Helpers
+// ============================================================
+function getLayerIcon(layer) {
+    const icons = {
+        ui_event: '🖱️',
+        ui_component: '🧩',
+        event_handler: '⚡',
+        state_update: '🔄',
+        api_call: '🌐',
+        route: '🛣️',
+        controller: '🎮',
+        service: '⚙️',
+        repository: '📦',
+        database: '🗄️',
+        middleware: '🔗',
+        validator: '✅',
+        util: '🔧',
+        unknown: '❓',
+    };
+    return icons[layer] ?? '❓';
+}
+function getLayerDescription(layer) {
+    const descriptions = {
+        ui_event: 'User interaction trigger (click, submit, change)',
+        ui_component: 'UI component that renders visual elements',
+        event_handler: 'Function that handles UI events',
+        state_update: 'State management (React state, Redux, Vuex)',
+        api_call: 'HTTP/API request to external service',
+        route: 'HTTP route/endpoint definition',
+        controller: 'Request handler that orchestrates business logic',
+        service: 'Business logic and domain rules',
+        repository: 'Data access layer (ORM, query builders)',
+        database: 'Direct database operations',
+        middleware: 'Request/response pipeline middleware',
+        validator: 'Input validation and sanitization',
+        util: 'Shared utility functions and helpers',
+        unknown: 'Could not determine the architectural layer',
+    };
+    return descriptions[layer] ?? 'Unknown layer';
+}
+function getLayerTypicalContents(layer) {
+    const contents = {
+        ui_event: 'onClick handlers, form submissions, keyboard shortcuts',
+        ui_component: 'React components, Vue templates, Angular components',
+        event_handler: 'handleClick, handleSubmit, onChange callbacks',
+        state_update: 'useState, useReducer, Redux actions, Vuex mutations',
+        api_call: 'fetch(), axios calls, GraphQL queries',
+        route: 'app.get(), router.post(), @Get() decorators',
+        controller: 'Request parsing, response formatting, error handling',
+        service: 'Business rules, calculations, orchestration',
+        repository: 'Database queries, ORM calls, data transformation',
+        database: 'Raw SQL, MongoDB operations, Redis commands',
+        middleware: 'Auth checks, logging, rate limiting, CORS',
+        validator: 'Schema validation, input sanitization, type checking',
+        util: 'String helpers, date formatting, crypto, file I/O',
+        unknown: 'File purpose could not be determined automatically',
+    };
+    return contents[layer] ?? 'Unknown';
+}
+//# sourceMappingURL=flow-tools.js.map

package/dist/tools/flow-tools.js.map

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

package/dist/tools/graph-tools.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AI Mind Map — Knowledge Graph MCP Tools
+ *
+ * Registers all knowledge-graph-related tools on the MCP server.
+ * Each tool returns structured JSON data wrapped in the standard
+ * MCP text-content envelope.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GraphNode, GraphEdge, NodeType } from '../types.js';
+/**
+ * Minimal interface expected of the Knowledge Graph subsystem.
+ * The concrete implementation lives elsewhere; we depend on the
+ * contract only.
+ */
+export interface IKnowledgeGraph {
+    /** Full-text / name search across all indexed nodes. */
+    search(query: string, type?: NodeType, limit?: number): GraphNode[];
+    /** Get project file tree with top-level symbols per file. */
+    getStructure(depth: number): {
+        files: {
+            path: string;
+            symbols: Pick<GraphNode, 'name' | 'type' | 'signature'>[];
+        }[];
+    };
+    /** Trace dependency chain of a symbol (callers / callees). */
+    traceDependencies(symbolName: string, direction: 'callers' | 'callees' | 'both', depth: number): {
+        root: string;
+        direction: string;
+        depth: number;
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    /** Get the full signature (no body) for a symbol. */
+    getSignature(symbolName: string, filePath?: string): {
+        node: GraphNode;
+        parameters: GraphNode['parameters'];
+        returnType: GraphNode['returnType'];
+        docComment: GraphNode['docComment'];
+    } | null;
+    /** Find every location a symbol is referenced. */
+    findReferences(symbolName: string): {
+        symbol: string;
+        references: {
+            filePath: string;
+            line: number;
+            context: string;
+        }[];
+    };
+    /** Get structural map of all symbols in a single file. */
+    getFileMap(filePath: string): {
+        filePath: string;
+        symbols: Pick<GraphNode, 'name' | 'type' | 'signature' | 'startLine' | 'endLine' | 'visibility' | 'isExported'>[];
+    } | null;
+}
+/**
+ * Minimal interface for estimating token counts.
+ * Used to populate ToolResult.tokenCount / tokensSaved.
+ */
+export interface ITokenEstimator {
+    /** Rough token count for a string (4 chars ≈ 1 token). */
+    estimate(text: string): number;
+}
+/**
+ * Register all Knowledge Graph tools on the given MCP server.
+ *
+ * @param server   The MCP server instance.
+ * @param graph    Concrete knowledge-graph implementation.
+ * @param estimator  Optional token estimator (defaults to 4-char heuristic).
+ */
+export declare function registerGraphTools(server: McpServer, graph: IKnowledgeGraph, estimator?: ITokenEstimator): void;
+//# sourceMappingURL=graph-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph-tools.d.ts","sourceRoot":"","sources":["../../src/tools/graph-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,QAAQ,EAET,MAAM,aAAa,CAAC;AAMrB;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IAEpE,6DAA6D;IAC7D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG;QAC3B,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC,EAAE,CAAA;SAAE,EAAE,CAAC;KACtF,CAAC;IAEF,8DAA8D;IAC9D,iBAAiB,CACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,EACzC,KAAK,EAAE,MAAM,GACZ;QACD,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,SAAS,EAAE,CAAC;QACnB,KAAK,EAAE,SAAS,EAAE,CAAC;KACpB,CAAC;IAEF,qDAAqD;IACrD,YAAY,CACV,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB;QACD,IAAI,EAAE,SAAS,CAAC;QAChB,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;QACpC,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;QACpC,UAAU,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;KACrC,GAAG,IAAI,CAAC;IAET,kDAAkD;IAClD,cAAc,CACZ,UAAU,EAAE,MAAM,GACjB;QACD,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KACnE,CAAC;IAEF,0DAA0D;IAC1D,UAAU,CACR,QAAQ,EAAE,MAAM,GACf;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,YAAY,CAAC,EAAE,CAAC;KACnH,GAAG,IAAI,CAAC;CACV;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAkDD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,eAAe,EACtB,SAAS,GAAE,eAAkC,GAC5C,IAAI,CAyIN"}