dbgraph 0.1.0

package/dist/mcp/engine.d.ts

@@ -0,0 +1,92 @@
+/**
+ * MCP Engine
+ *
+ * Manages the DBGraph instance lifecycle and dispatches to the tool handler.
+ *
+ * One engine serves many sessions (direct stdio mode or daemon socket mode).
+ * Initialization is lazy — started in the background on MCP initialize and
+ * retried synchronously before the first tool call. This lets the MCP server
+ * respond to initialize immediately without blocking on schema introspection.
+ */
+import { DBGraphToolHandler } from './tools';
+import type { ToolDefinition, ToolResult } from './tools';
+/**
+ * MCP Engine — shared state for one or more MCP sessions.
+ */
+export declare class MCPEngine {
+    private dbgraph;
+    private toolHandler;
+    private initPromise;
+    private projectPath;
+    private closed;
+    constructor();
+    /** Whether the default project's DBGraph is open and ready. */
+    isReady(): boolean;
+    /** Get tool definitions. */
+    getTools(): ToolDefinition[];
+    /** Get server instructions for the MCP initialize response. */
+    getServerInstructions(): string;
+    /** Get the underlying tool handler (for direct dispatch in server mode). */
+    getToolHandler(): DBGraphToolHandler;
+    /** The project root that was resolved on init (null if none). */
+    getProjectPath(): string | null;
+    /**
+     * Start initialization in the background (called from MCP initialize).
+     *
+     * Non-blocking — the engine will be ready by the time the first tool call
+     * arrives thanks to ensureInitialized / retry logic in the session layer.
+     * Multiple calls are idempotent; only the first starts the init flow.
+     */
+    startBackgroundInit(projectPath?: string): void;
+    /**
+     * Ensure the DBGraph instance is initialized — called before every tool call.
+     *
+     * If background init already succeeded (or is in-flight), this returns
+     * immediately (awaiting the in-flight promise if needed). If no background
+     * init was started, it runs synchronously.
+     *
+     * Throws if initialization fails, which the session layer catches and
+     * surfaces as an MCP error response.
+     */
+    ensureInitialized(projectPath?: string): Promise<void>;
+    /**
+     * Execute a tool by name.
+     */
+    executeTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Full re-index of all configured databases.
+     * Optionally store a schema fingerprint after success (for watch mode).
+     */
+    executeReindex(fingerprint?: string): Promise<{
+        sourcesIndexed: number;
+        nodesCreated: number;
+        edgesCreated: number;
+        errors: string[];
+    }>;
+    /**
+     * Check if the database schema changed by comparing a lightweight
+     * fingerprint (column list hash) against the last known value.
+     * Only supports MySQL/MariaDB for now.
+     */
+    checkSchemaChanged(): Promise<{
+        changed: boolean;
+        detail: string;
+        currentFingerprint?: string;
+    }>;
+    /**
+     * Close the DBGraph instance and release resources.
+     * Idempotent — safe to call multiple times.
+     */
+    stop(): void;
+    /**
+     * Background initialization — walks up from searchFrom to find .dbgraph/,
+     * opens the database, and sets up the DBGraph instance.
+     */
+    private doInitialize;
+    /**
+     * Synchronous open used as a fallback retry when background init missed
+     * a newly-created .dbgraph/ directory.
+     */
+    private tryOpenSync;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/mcp/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAG7C,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1D;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAAS;;IAavB,+DAA+D;IAC/D,OAAO,IAAI,OAAO;IAIlB,4BAA4B;IAC5B,QAAQ,IAAI,cAAc,EAAE;IAI5B,+DAA+D;IAC/D,qBAAqB,IAAI,MAAM;IAI/B,4EAA4E;IAC5E,cAAc,IAAI,kBAAkB;IAIpC,iEAAiE;IACjE,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;;;;;OAMG;IACH,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAa/C;;;;;;;;;OASG;IACG,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoC5D;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAInF;;;OAGG;IACG,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAClD,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IAuBF;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA+CtG;;;OAGG;IACH,IAAI,IAAI,IAAI;IAkBZ;;;OAGG;YACW,YAAY;IAwB1B;;;OAGG;IACH,OAAO,CAAC,WAAW;CAgBpB"}

package/dist/mcp/engine.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * MCP Engine
+ *
+ * Manages the DBGraph instance lifecycle and dispatches to the tool handler.
+ *
+ * One engine serves many sessions (direct stdio mode or daemon socket mode).
+ * Initialization is lazy — started in the background on MCP initialize and
+ * retried synchronously before the first tool call. This lets the MCP server
+ * respond to initialize immediately without blocking on schema introspection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPEngine = void 0;
+const index_1 = require("../index");
+const directory_1 = require("../directory");
+const tools_1 = require("./tools");
+const server_instructions_1 = require("./server-instructions");
+const connection_1 = require("../introspect/connection");
+/**
+ * MCP Engine — shared state for one or more MCP sessions.
+ */
+class MCPEngine {
+    dbgraph = null;
+    toolHandler;
+    initPromise = null;
+    projectPath = null;
+    closed = false;
+    constructor() {
+        // Pass a getter so the handler always reads the live instance.
+        // The `!` assert is safe because the handler is only called after
+        // ensureInitialized succeeds.
+        this.toolHandler = new tools_1.DBGraphToolHandler(() => this.dbgraph);
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /** Whether the default project's DBGraph is open and ready. */
+    isReady() {
+        return this.dbgraph !== null;
+    }
+    /** Get tool definitions. */
+    getTools() {
+        return this.toolHandler.getTools();
+    }
+    /** Get server instructions for the MCP initialize response. */
+    getServerInstructions() {
+        return server_instructions_1.SERVER_INSTRUCTIONS;
+    }
+    /** Get the underlying tool handler (for direct dispatch in server mode). */
+    getToolHandler() {
+        return this.toolHandler;
+    }
+    /** The project root that was resolved on init (null if none). */
+    getProjectPath() {
+        return this.projectPath;
+    }
+    /**
+     * Start initialization in the background (called from MCP initialize).
+     *
+     * Non-blocking — the engine will be ready by the time the first tool call
+     * arrives thanks to ensureInitialized / retry logic in the session layer.
+     * Multiple calls are idempotent; only the first starts the init flow.
+     */
+    startBackgroundInit(projectPath) {
+        if (this.closed)
+            return;
+        if (this.dbgraph)
+            return; // already initialized
+        if (this.initPromise)
+            return; // already in-flight
+        const searchFrom = projectPath ?? process.cwd();
+        this.projectPath = searchFrom;
+        this.initPromise = this.doInitialize(searchFrom).catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[DBGraph MCP] Background init failed: ${msg}\n`);
+        });
+    }
+    /**
+     * Ensure the DBGraph instance is initialized — called before every tool call.
+     *
+     * If background init already succeeded (or is in-flight), this returns
+     * immediately (awaiting the in-flight promise if needed). If no background
+     * init was started, it runs synchronously.
+     *
+     * Throws if initialization fails, which the session layer catches and
+     * surfaces as an MCP error response.
+     */
+    async ensureInitialized(projectPath) {
+        if (this.closed)
+            return;
+        if (this.dbgraph)
+            return;
+        // If background init is running, await it
+        if (this.initPromise) {
+            await this.initPromise;
+            // Retry once more if background init failed — the .dbgraph/ directory
+            // may have appeared after the background attempt (user ran `dbgraph init`
+            // in another terminal between listTools and tools/call).
+            if (!this.dbgraph) {
+                const searchFrom = projectPath ?? this.projectPath ?? process.cwd();
+                this.projectPath = searchFrom;
+                this.tryOpenSync(searchFrom);
+            }
+            if (this.dbgraph)
+                return;
+            throw new Error(`DBGraph not initialized. Searched from: ${projectPath ?? this.projectPath ?? process.cwd()}\n` +
+                'Run `dbgraph init` in your project directory first, then point your ' +
+                'MCP client to the project path.');
+        }
+        // No background init was started — run synchronously now
+        const searchFrom = projectPath ?? process.cwd();
+        this.projectPath = searchFrom;
+        this.tryOpenSync(searchFrom);
+        if (!this.dbgraph) {
+            throw new Error(`DBGraph not initialized. Searched from: ${searchFrom}\n` +
+                'Run `dbgraph init` in your project directory to create the .dbgraph/ index.');
+        }
+    }
+    /**
+     * Execute a tool by name.
+     */
+    async executeTool(name, args) {
+        return this.toolHandler.execute(name, args);
+    }
+    /**
+     * Full re-index of all configured databases.
+     * Optionally store a schema fingerprint after success (for watch mode).
+     */
+    async executeReindex(fingerprint) {
+        if (!this.dbgraph) {
+            throw new Error('DBGraph not initialized. Cannot re-index.');
+        }
+        const config = this.dbgraph.getConfig();
+        if (!config || config.databases.length === 0) {
+            throw new Error('No databases configured. Create a dbgraph-db.json file.');
+        }
+        const result = await this.dbgraph.indexAll();
+        // Store fingerprint after successful re-index so next poll can compare
+        if (fingerprint) {
+            this.dbgraph.getQueryBuilder().setMetadata('schema_fingerprint', fingerprint);
+        }
+        return {
+            sourcesIndexed: result.sourcesIndexed,
+            nodesCreated: result.nodesCreated,
+            edgesCreated: result.edgesCreated,
+            errors: result.errors,
+        };
+    }
+    /**
+     * Check if the database schema changed by comparing a lightweight
+     * fingerprint (column list hash) against the last known value.
+     * Only supports MySQL/MariaDB for now.
+     */
+    async checkSchemaChanged() {
+        if (!this.dbgraph)
+            return { changed: false, detail: 'No graph loaded' };
+        const config = this.dbgraph.getConfig();
+        if (!config || config.databases.length === 0)
+            return { changed: false, detail: 'No databases configured' };
+        const dbConfigs = config.databases.filter(d => d.engine === 'mysql' || d.engine === 'mariadb');
+        if (dbConfigs.length === 0)
+            return { changed: false, detail: 'No MySQL/MariaDB databases' };
+        // Compute current fingerprint: for each DB, MD5 of all (table.column, type, nullable)
+        const currentParts = [];
+        for (const db of dbConfigs) {
+            let conn;
+            try {
+                conn = await (0, connection_1.createConnection)(db);
+                const rows = await conn.query(`SELECT MD5(GROUP_CONCAT(
+            CONCAT_WS('.', TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE)
+            ORDER BY TABLE_NAME, ORDINAL_POSITION
+          )) AS fingerprint
+          FROM information_schema.COLUMNS
+          WHERE TABLE_SCHEMA = ?`, [db.database]);
+                const fp = rows[0]?.fingerprint ?? '';
+                currentParts.push(`${db.alias}=${fp}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                currentParts.push(`${db.alias}=ERROR:${msg}`);
+            }
+            finally {
+                if (conn)
+                    await conn.close().catch(() => { });
+            }
+        }
+        const currentFingerprint = currentParts.join('|');
+        // Load last fingerprint from project metadata
+        const lastFingerprint = this.dbgraph.getQueryBuilder().getMetadata('schema_fingerprint') ?? '';
+        if (currentFingerprint === lastFingerprint) {
+            return { changed: false, detail: 'Schema unchanged', currentFingerprint };
+        }
+        return { changed: true, detail: 'Schema changed: re-index required', currentFingerprint };
+    }
+    /**
+     * Close the DBGraph instance and release resources.
+     * Idempotent — safe to call multiple times.
+     */
+    stop() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.dbgraph) {
+            try {
+                this.dbgraph.close();
+            }
+            catch {
+                // Ignore close errors — resources may already be freed
+            }
+            this.dbgraph = null;
+        }
+        this.initPromise = null;
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    /**
+     * Background initialization — walks up from searchFrom to find .dbgraph/,
+     * opens the database, and sets up the DBGraph instance.
+     */
+    async doInitialize(searchFrom) {
+        const resolvedRoot = (0, directory_1.findNearestDBGraphRoot)(searchFrom);
+        if (!resolvedRoot) {
+            // No .dbgraph/ found — that's normal. The session layer will retry
+            // on the first tool call, at which point the user may have run init.
+            this.projectPath = searchFrom;
+            return;
+        }
+        this.projectPath = resolvedRoot;
+        try {
+            this.dbgraph = await index_1.DBGraph.open(resolvedRoot);
+            process.stderr.write(`[DBGraph MCP] Opened schema graph at ${resolvedRoot}\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[DBGraph MCP] Failed to open schema graph at ${resolvedRoot}: ${msg}\n`);
+            throw err;
+        }
+    }
+    /**
+     * Synchronous open used as a fallback retry when background init missed
+     * a newly-created .dbgraph/ directory.
+     */
+    tryOpenSync(searchFrom) {
+        try {
+            const resolvedRoot = (0, directory_1.findNearestDBGraphRoot)(searchFrom);
+            if (!resolvedRoot)
+                return;
+            this.dbgraph = index_1.DBGraph.openSync(resolvedRoot);
+            this.projectPath = resolvedRoot;
+            process.stderr.write(`[DBGraph MCP] Opened schema graph at ${resolvedRoot}\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[DBGraph MCP] Sync open failed: ${msg}\n`);
+            this.dbgraph = null;
+        }
+    }
+}
+exports.MCPEngine = MCPEngine;
+//# sourceMappingURL=engine.js.map

package/dist/mcp/engine.js.map

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

package/dist/mcp/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP Server
+ *
+ * Entry point for the MCP server. Wires transport, session, and engine.
+ */
+export { MCPEngine } from './engine';
+export interface MCPServerOptions {
+    projectPath?: string;
+    autoRefresh?: boolean;
+}
+/**
+ * MCPServer — manages MCP lifecycle (stdio or daemon mode)
+ */
+export declare class MCPServer {
+    private engine;
+    private session;
+    private projectPath?;
+    private autoRefresh;
+    constructor(options?: MCPServerOptions);
+    /**
+     * Start MCP server in stdio mode (used by AI agents directly)
+     */
+    start(): void;
+    /**
+     * Start MCP server as a daemon listening on a Unix socket / named pipe
+     */
+    startDaemon(projectRoot: string): Promise<void>;
+    /**
+     * Stop the MCP server
+     */
+    stop(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,WAAW,CAAU;gBAEjB,OAAO,GAAE,gBAAqB;IAM1C;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCrD;;OAEG;IACH,IAAI,IAAI,IAAI;CAIb"}

package/dist/mcp/index.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * MCP Server
+ *
+ * Entry point for the MCP server. Wires transport, session, and engine.
+ */
+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 });
+exports.MCPServer = exports.MCPEngine = void 0;
+const transport_1 = require("./transport");
+const session_1 = require("./session");
+const engine_1 = require("./engine");
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const transport_2 = require("./transport");
+var engine_2 = require("./engine");
+Object.defineProperty(exports, "MCPEngine", { enumerable: true, get: function () { return engine_2.MCPEngine; } });
+/**
+ * MCPServer — manages MCP lifecycle (stdio or daemon mode)
+ */
+class MCPServer {
+    engine;
+    session = null;
+    projectPath;
+    autoRefresh;
+    constructor(options = {}) {
+        this.engine = new engine_1.MCPEngine();
+        this.projectPath = options.projectPath;
+        this.autoRefresh = options.autoRefresh ?? false;
+    }
+    /**
+     * Start MCP server in stdio mode (used by AI agents directly)
+     */
+    start() {
+        const transport = new transport_1.StdioTransport();
+        this.session = new session_1.MCPSession(transport, this.engine, {
+            explicitProjectPath: this.projectPath,
+            autoRefresh: this.autoRefresh,
+        });
+        this.session.start();
+    }
+    /**
+     * Start MCP server as a daemon listening on a Unix socket / named pipe
+     */
+    async startDaemon(projectRoot) {
+        const socketPath = (0, transport_2.getDaemonSocketPath)(projectRoot);
+        const pidPath = (0, transport_2.getDaemonPidPath)(projectRoot);
+        // Ensure .dbgraph dir exists
+        const dbgraphDir = path.join(projectRoot, '.dbgraph');
+        if (!fs.existsSync(dbgraphDir)) {
+            fs.mkdirSync(dbgraphDir, { recursive: true });
+        }
+        // Clean up stale socket
+        try {
+            if (fs.existsSync(socketPath)) {
+                fs.unlinkSync(socketPath);
+            }
+        }
+        catch { /* ignore */ }
+        // Write PID file
+        fs.writeFileSync(pidPath, String(process.pid), 'utf-8');
+        return new Promise((resolve) => {
+            const server = net.createServer((socket) => {
+                const transport = new transport_1.SocketTransport(socket);
+                const session = new session_1.MCPSession(transport, this.engine, {
+                    explicitProjectPath: this.projectPath ?? projectRoot,
+                    autoRefresh: this.autoRefresh,
+                });
+                session.start();
+            });
+            server.listen(socketPath, () => {
+                console.error(`DBGraph daemon listening on ${socketPath}`);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop the MCP server
+     */
+    stop() {
+        this.session?.stop();
+        this.engine.stop();
+    }
+}
+exports.MCPServer = MCPServer;
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

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

package/dist/mcp/server-instructions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Server-level instructions emitted in the MCP `initialize` response.
+ *
+ * MCP clients surface this text in the agent's system prompt automatically,
+ * giving the agent a high-level playbook for the dbgraph toolset before it
+ * sees individual tool descriptions.
+ */
+export declare const SERVER_INSTRUCTIONS = "# DBGraph \u2014 database knowledge graph for schema-aware SQL generation\n\nDBGraph is a SQLite knowledge graph of every database schema object (tables,\ncolumns, views, indexes, foreign keys) in your project. The schema is\nintrospected ahead of time \u2014 reads are sub-millisecond and require no live\ndatabase connection.\n\n**Always consult dbgraph BEFORE writing SQL.** Understanding the schema first\nis the single largest quality lever for generated queries. A minute of\nschema exploration saves many rounds of \"fix the column name\" corrections.\n\n## Recommended workflow\n\n1. **`dbgraph_search`** \u2014 Find tables, columns, or views by name. Start here\n   when you know roughly what you're looking for.\n\n2. **`dbgraph_context`** (PRIMARY) \u2014 Get the full schema of a table or view:\n   columns, types, primary keys, foreign keys, indexes, and what references it.\n   This is the main tool for understanding a schema object.\n\n3. **`dbgraph_trace`** \u2014 Trace foreign key join paths between two tables.\n   Use this to discover how tables relate before writing JOIN clauses.\n\n4. **`dbgraph_explore`** \u2014 Fetch schemas for several related tables at once\n   (fewer round-trips than calling `dbgraph_context` repeatedly).\n\n5. **`dbgraph_sources`** \u2014 List all configured databases and their engines.\n   Useful when you don't know which database alias contains the table you need.\n\n6. **`dbgraph_status`** \u2014 See overall graph statistics: node/edge counts,\n   breakdown by kind, and last index time. Quick health check.\n\n## When to use each tool\n\n| You want to... | Use this tool |\n|---|---|\n| Find a table or column by name | `dbgraph_search` |\n| See a table's full schema (columns, PKs, FKs, indexes) | `dbgraph_context` |\n| Discover how two tables join (FK path) | `dbgraph_trace` |\n| Explore several related tables at once | `dbgraph_explore` |\n| List available databases | `dbgraph_sources` |\n| Check if the schema index is healthy | `dbgraph_status` |\n\n## Common chains\n\n- **Write a correct JOIN**: `dbgraph_context` on each table \u2192 `dbgraph_trace`\n  to confirm the FK path \u2192 then write SQL.\n- **Understand an unfamiliar schema**: `dbgraph_search` for key terms \u2192\n  `dbgraph_context` on the main tables \u2192 `dbgraph_explore` on related ones.\n- **Debug a broken query**: `dbgraph_context` on each referenced table \u2192\n  check column names and types \u2192 `dbgraph_trace` to verify join columns.\n\n## Anti-patterns\n\n- **Don't guess column names** \u2014 use `dbgraph_context` to see them.\n- **Don't chain many `dbgraph_context` calls** \u2014 use `dbgraph_explore` with\n  space-separated table names for a batch view.\n- **Don't write JOINs without tracing** \u2014 `dbgraph_trace` reveals the FK path\n  and often shows intermediate tables you didn't know existed.\n";
+//# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/server-instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,mBAAmB,ozFA2D/B,CAAC"}

package/dist/mcp/server-instructions.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Server-level instructions emitted in the MCP `initialize` response.
+ *
+ * MCP clients surface this text in the agent's system prompt automatically,
+ * giving the agent a high-level playbook for the dbgraph toolset before it
+ * sees individual tool descriptions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_INSTRUCTIONS = void 0;
+exports.SERVER_INSTRUCTIONS = `# DBGraph — database knowledge graph for schema-aware SQL generation
+
+DBGraph is a SQLite knowledge graph of every database schema object (tables,
+columns, views, indexes, foreign keys) in your project. The schema is
+introspected ahead of time — reads are sub-millisecond and require no live
+database connection.
+
+**Always consult dbgraph BEFORE writing SQL.** Understanding the schema first
+is the single largest quality lever for generated queries. A minute of
+schema exploration saves many rounds of "fix the column name" corrections.
+
+## Recommended workflow
+
+1. **\`dbgraph_search\`** — Find tables, columns, or views by name. Start here
+   when you know roughly what you're looking for.
+
+2. **\`dbgraph_context\`** (PRIMARY) — Get the full schema of a table or view:
+   columns, types, primary keys, foreign keys, indexes, and what references it.
+   This is the main tool for understanding a schema object.
+
+3. **\`dbgraph_trace\`** — Trace foreign key join paths between two tables.
+   Use this to discover how tables relate before writing JOIN clauses.
+
+4. **\`dbgraph_explore\`** — Fetch schemas for several related tables at once
+   (fewer round-trips than calling \`dbgraph_context\` repeatedly).
+
+5. **\`dbgraph_sources\`** — List all configured databases and their engines.
+   Useful when you don't know which database alias contains the table you need.
+
+6. **\`dbgraph_status\`** — See overall graph statistics: node/edge counts,
+   breakdown by kind, and last index time. Quick health check.
+
+## When to use each tool
+
+| You want to... | Use this tool |
+|---|---|
+| Find a table or column by name | \`dbgraph_search\` |
+| See a table's full schema (columns, PKs, FKs, indexes) | \`dbgraph_context\` |
+| Discover how two tables join (FK path) | \`dbgraph_trace\` |
+| Explore several related tables at once | \`dbgraph_explore\` |
+| List available databases | \`dbgraph_sources\` |
+| Check if the schema index is healthy | \`dbgraph_status\` |
+
+## Common chains
+
+- **Write a correct JOIN**: \`dbgraph_context\` on each table → \`dbgraph_trace\`
+  to confirm the FK path → then write SQL.
+- **Understand an unfamiliar schema**: \`dbgraph_search\` for key terms →
+  \`dbgraph_context\` on the main tables → \`dbgraph_explore\` on related ones.
+- **Debug a broken query**: \`dbgraph_context\` on each referenced table →
+  check column names and types → \`dbgraph_trace\` to verify join columns.
+
+## Anti-patterns
+
+- **Don't guess column names** — use \`dbgraph_context\` to see them.
+- **Don't chain many \`dbgraph_context\` calls** — use \`dbgraph_explore\` with
+  space-separated table names for a batch view.
+- **Don't write JOINs without tracing** — \`dbgraph_trace\` reveals the FK path
+  and often shows intermediate tables you didn't know existed.
+`;
+//# sourceMappingURL=server-instructions.js.map

package/dist/mcp/server-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2DlC,CAAC"}

package/dist/mcp/session.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MCP Session
+ *
+ * Manages a single MCP session — handles initialization, tool listing,
+ * and tool call dispatching.
+ */
+import { JsonRpcTransport } from './transport';
+import { MCPEngine } from './engine';
+export interface MCPSessionOptions {
+    explicitProjectPath?: string;
+    autoRefresh?: boolean;
+}
+export declare class MCPSession {
+    private transport;
+    private engine;
+    private clientSupportsRoots;
+    private rootsAttempted;
+    private explicitProjectPath;
+    private watchConfig;
+    constructor(transport: JsonRpcTransport, engine: MCPEngine, opts?: MCPSessionOptions);
+    start(): void;
+    stop(): void;
+    getTransport(): JsonRpcTransport;
+    private handleMessage;
+    private retryInitIfNeeded;
+    /**
+     * Before each tool call, lazily check if the database schema changed
+     * and re-index if needed. Zero overhead when idle.
+     */
+    private refreshIfSchemaChanged;
+    private handleInitialize;
+    private handleToolsList;
+    private handleToolsCall;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/mcp/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/mcp/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,UAAU;IAOnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;IAPhB,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,mBAAmB,CAAgB;IAC3C,OAAO,CAAC,WAAW,CAAU;gBAGnB,SAAS,EAAE,gBAAgB,EAC3B,MAAM,EAAE,SAAS,EACzB,IAAI,GAAE,iBAAsB;IAM9B,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI;IAIZ,YAAY,IAAI,gBAAgB;YAIlB,aAAa;YA4Bb,iBAAiB;IAM/B;;;OAGG;YACW,sBAAsB;YAkBtB,gBAAgB;YA4BhB,eAAe;YAMf,eAAe;CA+B9B"}