dbgraph 0.1.0

package/dist/mcp/session.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * MCP Session
+ *
+ * Manages a single MCP session — handles initialization, tool listing,
+ * and tool call dispatching.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPSession = void 0;
+const transport_1 = require("./transport");
+class MCPSession {
+    transport;
+    engine;
+    clientSupportsRoots = false;
+    rootsAttempted = false;
+    explicitProjectPath;
+    watchConfig;
+    constructor(transport, engine, opts = {}) {
+        this.transport = transport;
+        this.engine = engine;
+        this.explicitProjectPath = opts.explicitProjectPath ?? null;
+        this.watchConfig = opts.autoRefresh ?? false;
+    }
+    start() {
+        this.transport.start(this.handleMessage.bind(this));
+    }
+    stop() {
+        this.transport.stop();
+    }
+    getTransport() {
+        return this.transport;
+    }
+    async handleMessage(message) {
+        const isRequest = 'id' in message;
+        switch (message.method) {
+            case 'initialize':
+                if (isRequest)
+                    await this.handleInitialize(message);
+                break;
+            case 'initialized':
+                break;
+            case 'tools/list':
+                if (isRequest)
+                    await this.handleToolsList(message);
+                break;
+            case 'tools/call':
+                if (isRequest)
+                    await this.handleToolsCall(message);
+                break;
+            case 'ping':
+                if (isRequest)
+                    this.transport.sendResult(message.id, {});
+                break;
+            default:
+                if (isRequest) {
+                    this.transport.sendError(message.id, transport_1.ErrorCodes.MethodNotFound, `Method not found: ${message.method}`);
+                }
+        }
+    }
+    async retryInitIfNeeded() {
+        if (!this.engine.isReady()) {
+            await this.engine.ensureInitialized();
+        }
+    }
+    /**
+     * Before each tool call, lazily check if the database schema changed
+     * and re-index if needed. Zero overhead when idle.
+     */
+    async refreshIfSchemaChanged() {
+        if (!this.watchConfig || !this.engine.isReady())
+            return;
+        try {
+            const { changed, currentFingerprint } = await this.engine.checkSchemaChanged();
+            if (changed) {
+                process.stderr.write(`[DBGraph MCP] Schema changed, re-indexing...\n`);
+                const result = await this.engine.executeReindex(currentFingerprint);
+                process.stderr.write(`[DBGraph MCP] Re-indexed: ${result.sourcesIndexed} source(s), ` +
+                    `${result.nodesCreated} node(s), ${result.edgesCreated} edge(s)\n`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[DBGraph MCP] Schema refresh failed: ${msg}\n`);
+        }
+    }
+    async handleInitialize(request) {
+        const params = request.params;
+        const clientInfo = params?.clientInfo;
+        const clientName = clientInfo?.name ?? 'unknown';
+        // Forward roots capability
+        if (params?.capabilities) {
+            const caps = params.capabilities;
+            this.clientSupportsRoots = !!caps.roots?.listChanged;
+        }
+        // Do NOT block init on engine readiness — start it in background and
+        // retry on first tool call. Unresponsive daemon is worse than stale.
+        this.engine.startBackgroundInit(this.explicitProjectPath ?? undefined);
+        const instructions = this.engine.getServerInstructions();
+        this.transport.sendResult(request.id, {
+            protocolVersion: '2024-11-05',
+            serverInfo: { name: 'dbgraph', version: '0.1.0' },
+            capabilities: {
+                tools: {},
+                ...(this.clientSupportsRoots ? {} : { roots: { listChanged: false } }),
+            },
+            instructions,
+        });
+    }
+    async handleToolsList(request) {
+        this.transport.sendResult(request.id, {
+            tools: this.engine.getTools(),
+        });
+    }
+    async handleToolsCall(request) {
+        const params = request.params;
+        if (!params || !params.name) {
+            this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, 'Missing tool name');
+            return;
+        }
+        const toolName = params.name;
+        const toolArgs = params.arguments || {};
+        const tool = this.engine.getTools().find((t) => t.name === toolName);
+        if (!tool) {
+            this.transport.sendError(request.id, transport_1.ErrorCodes.MethodNotFound, `Unknown tool: ${toolName}`);
+            return;
+        }
+        try {
+            await this.retryInitIfNeeded();
+            await this.refreshIfSchemaChanged();
+            const result = await this.engine.executeTool(toolName, toolArgs);
+            this.transport.sendResult(request.id, result);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.transport.sendError(request.id, transport_1.ErrorCodes.InternalError, msg);
+        }
+    }
+}
+exports.MCPSession = MCPSession;
+//# sourceMappingURL=session.js.map

package/dist/mcp/session.js.map

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

package/dist/mcp/tools.d.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP Tool Definitions & Handlers
+ *
+ * Defines the tools exposed by the DBGraph MCP server and implements their
+ * execution against a DBGraph knowledge graph instance.
+ */
+import { DBGraph } from '../index';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, PropertySchema>;
+        required?: string[];
+    };
+}
+interface PropertySchema {
+    type: string;
+    description: string;
+    enum?: string[];
+    default?: unknown;
+}
+export interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Executes dbgraph MCP tools against a DBGraph instance.
+ *
+ * The handler does NOT own the DBGraph lifecycle — the caller (MCPEngine)
+ * provides a getter so the handler always uses the current (possibly
+ * lazily-initialized) instance.
+ */
+export declare class DBGraphToolHandler {
+    private readonly getDBGraph;
+    private readonly formatter;
+    constructor(getDBGraph: () => DBGraph);
+    /**
+     * Return the tool definitions, optionally enriched with dynamic context
+     * (e.g. stats) from the live graph.
+     */
+    getTools(): ToolDefinition[];
+    /**
+     * Execute a tool by name.
+     */
+    execute(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * dbgraph_search — Search schema objects by name. Delegates to
+     * QueryBuilder.searchNodes with optional kind filter and limit, then
+     * formats via SchemaFormatter.
+     */
+    private handleSearch;
+    /**
+     * dbgraph_context — Get full schema context for a table or view.
+     *
+     * Resolves the name (simple, qualified, or fully qualified) via
+     * ContextBuilder.buildContext, which searches the graph and returns a
+     * complete markdown description.
+     */
+    private handleContext;
+    /**
+     * dbgraph_trace — Trace FK join path between two tables.
+     *
+     * Resolves both names to nodes, then runs GraphTraverser.findPath over
+     * 'references', 'foreign_key', and 'contains' edges. Formats the
+     * resulting path as a readable join chain.
+     */
+    private handleTrace;
+    /**
+     * dbgraph_explore — Fetch schema context for multiple objects in one call.
+     *
+     * Splits the space-separated names, finds each table/view node, and calls
+     * ContextBuilder.getTableSchema for each. Assembles a single markdown
+     * document.
+     */
+    private handleExplore;
+    /**
+     * dbgraph_sources — List all database sources.
+     */
+    private handleSources;
+    /**
+     * dbgraph_status — Show graph statistics.
+     */
+    private handleStatus;
+    /**
+     * Resolve a table or view name to graph nodes.
+     *
+     * Attempts, in order:
+     *  1. Exact node ID lookup
+     *  2. Qualified name lookup
+     *  3. FTS5 search for table/view kind
+     */
+    private resolveTableNodes;
+}
+export {};
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAenC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QAC3C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAwHD;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAGjB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAEtB,UAAU,EAAE,MAAM,OAAO;IAEtD;;;OAGG;IACH,QAAQ,IAAI,cAAc,EAAE;IAI5B;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IA6B/E;;;;OAIG;YACW,YAAY;IA4B1B;;;;;;OAMG;YACW,aAAa;IAS3B;;;;;;OAMG;YACW,WAAW;IAkFzB;;;;;;OAMG;YACW,aAAa;IAkD3B;;OAEG;YACW,aAAa;IAa3B;;OAEG;YACW,YAAY;IAkF1B;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;CAqB1B"}