@rpcajr/smart-graph-indexer 1.0.0

package/.agents/rules/antigravity-rtk-rules.md

@@ -0,0 +1,32 @@
+# RTK - Rust Token Killer (Google Antigravity)
+
+**Usage**: Token-optimized CLI proxy for shell commands.
+
+## Rule
+
+Always prefix shell commands with `rtk` to minimize token consumption.
+
+Examples:
+
+```bash
+rtk git status
+rtk cargo test
+rtk ls src/
+rtk grep "pattern" src/
+rtk find "*.rs" .
+rtk docker ps
+rtk gh pr list
+```
+
+## Meta Commands
+
+```bash
+rtk gain              # Show token savings
+rtk gain --history    # Command history with savings
+rtk discover          # Find missed RTK opportunities
+rtk proxy <cmd>       # Run raw (no filtering, for debugging)
+```
+
+## Why
+
+RTK filters and compresses command output before it reaches the LLM context, saving 60-90% tokens on common operations. Always use `rtk <cmd>` instead of raw commands.

package/README.md

@@ -0,0 +1,116 @@
+# smart-graph-indexer 🚀
+
+A fast, language-agnostic, syntax-aware structural code indexer and **Model Context Protocol (MCP)** server. 
+
+It indexes project structure, extracts AST signature skeletons, computes file-to-file dependency graphs, and provides local hybrid search (semantic vector embeddings + exact substring search) for **9 major programming languages**:
+*TypeScript/JavaScript, Python, C#, Java, Go, Rust, Ruby, C, and C++.*
+
+Additionally, it tracks **Token Savings (RTK Token Killer)** and session logs, giving you a detailed breakdown of how much context (and API cost) you are saving when utilizing AI assistants with this MCP server.
+
+---
+
+## Key Features
+
+1. **Syntax-Aware Structural Parsing (AST Skeletons)**:
+   Extracts public class, method, function signatures, and docstrings using Tree-Sitter WASM grammars. Internal logic blocks are discarded, creating a lightweight "skeleton" map of your project.
+
+2. **Dynamic Workspace Discovery**:
+   Uses the MCP `roots/list` protocol handshake to dynamically query the IDE for the active project path. Zero configuration needed for CWD path variations across different IDE hosts.
+
+3. **Local Hybrid Search**:
+   Performs fast cosine-similarity search using a local ONNX embedding model (`all-MiniLM-L6-v2` via `@xenova/transformers`) running entirely on your CPU, blended with substring lexical fallback.
+
+4. **Interactive Dependency Graph (`graph-indexer view`)**:
+   Generates a visually stunning Vis.js network visualization (`.graph-indexer/graph.html`) of your file imports. Use the `--watch` flag to auto-update the visualization as you save code.
+
+5. **Dormant Mode by Default**:
+   To prevent overhead when opening arbitrary folders, the server runs in a dormant mode (0% CPU, minimum RAM) unless a `.graph-indexer/` directory exists in the workspace. Toggle it on-demand with `graph-indexer init`.
+
+6. **Console-Style RTK Session Dashboard**:
+   A visual dashboard in the HTML interface that mimics the popular `RTK` (Rust Token Killer) console, tracking requests, used tokens, alternative raw tokens, execution times, and efficiency ratios.
+
+---
+
+## Installation
+
+Install the package globally using npm:
+
+```bash
+# Install globally from source
+npm install -g .
+```
+
+---
+
+## CLI Commands
+
+### 1. Initialize a Project (`init`)
+Enables the MCP indexing engine for the current directory by creating the `.graph-indexer` folder:
+```bash
+graph-indexer init
+```
+
+> [!TIP]
+> **Gitignore Configuration**:
+> It is highly recommended to add the configuration folder to your project's `.gitignore` to avoid committing local stats and generated HTML views:
+> ```gitignore
+> # Exclude local Graph Indexer assets
+> .graph-indexer/
+> ```
+
+### 2. Visualize Graph & Stats (`view`)
+Generates the interactive HTML network graph and opens it in your default browser:
+```bash
+graph-indexer view
+```
+To monitor code modifications and regenerate the graph automatically, add the watch flag:
+```bash
+graph-indexer view --watch
+```
+
+### 3. Quick Index Export (`index`)
+Indexes the project once and exports the structural skeletons report directly to stdout as JSON:
+```bash
+graph-indexer index
+```
+
+---
+
+## IDE MCP Server Integration
+
+Add the server to your editor's global Model Context Protocol configuration (e.g., `mcp_config.json` in Antigravity, Claude Desktop, Cursor, or VS Code):
+
+```json
+{
+  "mcpServers": {
+    "smart-graph-indexer": {
+      "command": "graph-indexer",
+      "args": [
+        "start",
+        "--path",
+        "."
+      ]
+    }
+  }
+}
+```
+
+*Note: Since the server queries the editor for active workspace roots dynamically, `--path "."` works as a safe fallback.*
+
+---
+
+## Available MCP Tools
+
+Once connected, your AI assistant will automatically use the following tools:
+
+*   `search_symbols(query, limit)`: Performs a hybrid search over indexed structural signatures.
+*   `get_file_skeleton(file_path)`: Retrieves the clean AST skeleton (methods, properties, docstrings) of a file without internal logic blocks.
+*   `get_dependencies(file_path, direction)`: Retrieves direct imports or dependants of a file.
+*   `read_symbol_body(file_path, symbol_name)`: JIT-fetches the actual body of a class/method from disk when requested.
+*   `get_token_savings()`: Returns the detailed JSON log of token metrics.
+
+---
+
+## License
+
+ISC License. Open Source.

package/dist/graph.d.ts

@@ -0,0 +1,32 @@
+export declare class DependencyGraph {
+    private adjacencyList;
+    private reverseAdjacencyList;
+    constructor();
+    /**
+     * Adds or updates a file and its dependencies in the graph.
+     */
+    updateFileDependencies(filePath: string, dependencies: string[]): void;
+    /**
+     * Removes a file and its edges from the graph.
+     */
+    removeFile(filePath: string): void;
+    /**
+     * Clears the entire graph.
+     */
+    clear(): void;
+    /**
+     * Gets direct dependencies (files/namespaces this file imports).
+     */
+    getOutgoing(filePath: string): string[];
+    /**
+     * Gets dependants (files that import this file/namespace).
+     */
+    getIncoming(filePathOrNamespace: string): string[];
+    /**
+     * Exports the entire graph for debugging/serialization.
+     */
+    serialize(): Record<string, {
+        imports: string[];
+        importedBy: string[];
+    }>;
+}

package/dist/graph.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyGraph = void 0;
+class DependencyGraph {
+    // Map of file relative path -> set of other files/namespaces this file imports (outgoing)
+    adjacencyList = new Map();
+    // Map of file/namespace -> set of files that import it (incoming)
+    reverseAdjacencyList = new Map();
+    constructor() { }
+    /**
+     * Adds or updates a file and its dependencies in the graph.
+     */
+    updateFileDependencies(filePath, dependencies) {
+        // Clean old dependencies if file already existed
+        this.removeFile(filePath);
+        // Set outgoing dependencies
+        const outgoing = new Set(dependencies);
+        this.adjacencyList.set(filePath, outgoing);
+        // Set incoming dependencies
+        for (const dep of dependencies) {
+            if (!this.reverseAdjacencyList.has(dep)) {
+                this.reverseAdjacencyList.set(dep, new Set());
+            }
+            this.reverseAdjacencyList.get(dep).add(filePath);
+        }
+    }
+    /**
+     * Removes a file and its edges from the graph.
+     */
+    removeFile(filePath) {
+        const oldDeps = this.adjacencyList.get(filePath);
+        if (oldDeps) {
+            for (const dep of oldDeps) {
+                const incoming = this.reverseAdjacencyList.get(dep);
+                if (incoming) {
+                    incoming.delete(filePath);
+                    if (incoming.size === 0) {
+                        this.reverseAdjacencyList.delete(dep);
+                    }
+                }
+            }
+            this.adjacencyList.delete(filePath);
+        }
+        // Also remove from reverse list (in case this file was imported by others)
+        this.reverseAdjacencyList.delete(filePath);
+        for (const [node, deps] of this.adjacencyList.entries()) {
+            if (deps.has(filePath)) {
+                deps.delete(filePath);
+            }
+        }
+    }
+    /**
+     * Clears the entire graph.
+     */
+    clear() {
+        this.adjacencyList.clear();
+        this.reverseAdjacencyList.clear();
+    }
+    /**
+     * Gets direct dependencies (files/namespaces this file imports).
+     */
+    getOutgoing(filePath) {
+        return Array.from(this.adjacencyList.get(filePath) || []);
+    }
+    /**
+     * Gets dependants (files that import this file/namespace).
+     */
+    getIncoming(filePathOrNamespace) {
+        return Array.from(this.reverseAdjacencyList.get(filePathOrNamespace) || []);
+    }
+    /**
+     * Exports the entire graph for debugging/serialization.
+     */
+    serialize() {
+        const serialized = {};
+        const allNodes = new Set([...this.adjacencyList.keys(), ...this.reverseAdjacencyList.keys()]);
+        for (const node of allNodes) {
+            serialized[node] = {
+                imports: this.getOutgoing(node),
+                importedBy: this.getIncoming(node),
+            };
+        }
+        return serialized;
+    }
+}
+exports.DependencyGraph = DependencyGraph;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const mcp_server_js_1 = require("./mcp_server.js");
+const ui_js_1 = require("./ui.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const child_process_1 = require("child_process");
+const program = new commander_1.Command();
+program
+    .name('graph-indexer')
+    .description('Smart Graph Code Indexer MCP CLI')
+    .version('1.0.0');
+program
+    .command('start')
+    .description('Starts the MCP server via stdio')
+    .option('-p, --path <directory>', 'Target project directory to index', '.')
+    .action(async (options) => {
+    try {
+        const projectPath = path.resolve(options.path);
+        console.error(`[Start] Initializing SmartGraphIndexerMCP for: ${projectPath}`);
+        const engine = new mcp_server_js_1.IndexerEngine(projectPath);
+        const server = (0, mcp_server_js_1.createMCPServer)(engine);
+        const transport = new stdio_js_1.StdioServerTransport();
+        await server.connect(transport);
+        console.error('[Start] MCP Server successfully connected via Stdio.');
+        // Dynamic workspace path discovery via client roots list
+        let resolvedPath = projectPath;
+        let rootsResult = "none";
+        let rootsError = "none";
+        try {
+            const response = await server.request({ method: 'roots/list' }, types_js_1.ListRootsResultSchema);
+            rootsResult = JSON.stringify(response);
+            if (response && response.roots && response.roots.length > 0) {
+                const rootUri = response.roots[0].uri;
+                if (rootUri.startsWith('file:///')) {
+                    // Remove file:/// prefix
+                    let pathFromUri = rootUri.substring(8);
+                    pathFromUri = decodeURIComponent(pathFromUri);
+                    // Normalize Windows/Unix path
+                    resolvedPath = path.resolve(pathFromUri);
+                    engine.updateProjectPath(resolvedPath);
+                }
+            }
+        }
+        catch (err) {
+            rootsError = err?.message || String(err);
+        }
+        await engine.startIndexing();
+        // Handle termination gracefully
+        process.on('SIGINT', async () => {
+            console.error('[Shutdown] Closing watcher...');
+            await engine.shutdown();
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            console.error('[Shutdown] Closing watcher...');
+            await engine.shutdown();
+            process.exit(0);
+        });
+    }
+    catch (err) {
+        console.error('Critical error starting the MCP server:', err);
+        process.exit(1);
+    }
+});
+program
+    .command('index')
+    .description('Performs only the initial indexing of the project and exports a JSON structural report')
+    .option('-p, --path <directory>', 'Target project directory to index', '.')
+    .action(async (options) => {
+    try {
+        const projectPath = path.resolve(options.path);
+        console.log(`[Index] Indexing project at: ${projectPath}`);
+        const engine = new mcp_server_js_1.IndexerEngine(projectPath);
+        await engine.initialize();
+        await engine.scanDir(projectPath);
+        const report = engine.getReport();
+        console.log(JSON.stringify(report, null, 2));
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('Critical error during indexing:', err);
+        process.exit(1);
+    }
+});
+program
+    .command('view')
+    .description('Maps the project and opens an interactive web graph of dependencies')
+    .option('-p, --path <directory>', 'Target project directory to map', '.')
+    .option('-w, --watch', 'Monitors filesystem changes in real time and regenerates the graph automatically')
+    .action(async (options) => {
+    try {
+        const projectPath = path.resolve(options.path);
+        console.log(`[View] Mapping project dependencies at: ${projectPath}`);
+        let engine;
+        const writeHtml = () => {
+            const htmlContent = (0, ui_js_1.generateGraphHtml)(engine);
+            const mcpDir = path.join(projectPath, '.graph-indexer');
+            if (!fs.existsSync(mcpDir)) {
+                fs.mkdirSync(mcpDir, { recursive: true });
+            }
+            const htmlPath = path.join(mcpDir, 'graph.html');
+            fs.writeFileSync(htmlPath, htmlContent, 'utf-8');
+            console.log(`[View] Interactive graph updated at: ${htmlPath}`);
+        };
+        if (options.watch) {
+            engine = new mcp_server_js_1.IndexerEngine(projectPath, () => {
+                writeHtml();
+            });
+        }
+        else {
+            engine = new mcp_server_js_1.IndexerEngine(projectPath);
+        }
+        await engine.initialize();
+        await engine.scanDir(projectPath);
+        // Write initial HTML
+        writeHtml();
+        const mcpDir = path.join(projectPath, '.graph-indexer');
+        const htmlPath = path.join(mcpDir, 'graph.html');
+        // Open in the default browser based on platform
+        console.log('[View] Opening interactive graph in default browser...');
+        const platform = process.platform;
+        const fileUrl = `file:///${htmlPath.replace(/\\/g, '/')}`;
+        if (platform === 'win32') {
+            (0, child_process_1.exec)(`start "" "${fileUrl}"`);
+        }
+        else if (platform === 'darwin') {
+            (0, child_process_1.exec)(`open "${fileUrl}"`);
+        }
+        else {
+            (0, child_process_1.exec)(`xdg-open "${fileUrl}"`);
+        }
+        if (options.watch) {
+            console.log('[View] Real-time monitoring (--watch) active. Press Ctrl+C to terminate.');
+            engine.startWatcher();
+            process.on('SIGINT', async () => {
+                console.log('[Shutdown] Closing watcher...');
+                await engine.shutdown();
+                process.exit(0);
+            });
+        }
+        else {
+            process.exit(0);
+        }
+    }
+    catch (err) {
+        console.error('Critical error generating graph view:', err);
+        process.exit(1);
+    }
+});
+program
+    .command('init')
+    .description('Initializes the current project directory for SmartGraphIndexer by creating the .graph-indexer config folder')
+    .option('-p, --path <directory>', 'Target directory to initialize', '.')
+    .action(async (options) => {
+    try {
+        const projectPath = path.resolve(options.path);
+        const mcpDir = path.join(projectPath, '.graph-indexer');
+        if (fs.existsSync(mcpDir)) {
+            console.log(`[Init] Project is already initialized at: ${projectPath} (.graph-indexer directory exists).`);
+            process.exit(0);
+        }
+        fs.mkdirSync(mcpDir, { recursive: true });
+        // Create initial empty stats file
+        const statsPath = path.join(mcpDir, 'stats.json');
+        const initialStats = {
+            totalCalls: 0,
+            totalTokensSaved: 0,
+            totalTokensActual: 0,
+            totalTokensAlternative: 0,
+            efficiencyPercentage: 0,
+            callsByType: {
+                search_symbols: { calls: 0, saved: 0, actual: 0, alternative: 0, totalTimeMs: 0 },
+                get_file_skeleton: { calls: 0, saved: 0, actual: 0, alternative: 0, totalTimeMs: 0 },
+                get_dependencies: { calls: 0, saved: 0, actual: 0, alternative: 0, totalTimeMs: 0 },
+                read_symbol_body: { calls: 0, saved: 0, actual: 0, alternative: 0, totalTimeMs: 0 }
+            },
+            history: []
+        };
+        fs.writeFileSync(statsPath, JSON.stringify(initialStats, null, 2), 'utf-8');
+        console.log(`[Init] Successfully initialized SmartGraphIndexer workspace at: ${projectPath}`);
+        console.log('[Init] The MCP server will now index and analyze this project.');
+        process.exit(0);
+    }
+    catch (err) {
+        console.error('Critical error during initialization:', err);
+        process.exit(1);
+    }
+});
+program.parse(process.argv);

package/dist/mcp_server.d.ts

@@ -0,0 +1,48 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { FileSkeleton } from './parser.js';
+import { DependencyGraph } from './graph.js';
+import { VectorStore } from './vector.js';
+import { StatsManager } from './stats.js';
+export declare class IndexerEngine {
+    projectPath: string;
+    private parser;
+    private graph;
+    private vectorStore;
+    private watcher;
+    private fileSkeletons;
+    private isLoaded;
+    private stats;
+    constructor(projectPath: string, onUpdate?: () => void);
+    updateProjectPath(newPath: string, onUpdate?: () => void): void;
+    startWatcher(): void;
+    initialize(): Promise<void>;
+    /**
+     * Scans and indexes the entire directory recursively.
+     */
+    startIndexing(): Promise<void>;
+    private scanDir;
+    /**
+     * Indexes a single file.
+     */
+    indexFile(relativeFilePath: string): Promise<void>;
+    /**
+     * Gracefully updates a file on demand (for JIT read operations).
+     */
+    ensureFileUpToDate(relativeFilePath: string): Promise<FileSkeleton | undefined>;
+    getFileSkeleton(relativeFilePath: string): FileSkeleton | undefined;
+    getGraph(): DependencyGraph;
+    getVectorStore(): VectorStore;
+    getStatsManager(): StatsManager;
+    shutdown(): Promise<void>;
+    getReport(): {
+        totalFiles: number;
+        files: string[];
+        symbolsCount: number;
+        dependencyGraph: Record<string, {
+            imports: string[];
+            importedBy: string[];
+        }>;
+        tokenStats: import("./stats.js").TokenStats;
+    };
+}
+export declare function createMCPServer(engine: IndexerEngine): Server;