db-mcp 2.0.0 → 3.0.0

package/dist/utils/icons.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tool Group Icons
+ *
+ * Maps tool groups to Material Design Icons (MDI) hosted on jsDelivr CDN.
+ * Follows the MCP 2025-11-25 icon specification.
+ *
+ * @see https://modelcontextprotocol.io/specification/draft
+ */
+import type { McpIcon } from "../types/index.js";
+/** Server icon for built-in tools (server_info, server_health, list_adapters) */
+export declare const SERVER_ICONS: McpIcon[];
+/**
+ * Get the icon array for a tool group.
+ *
+ * @param group - Tool group identifier
+ * @returns McpIcon array for the group, or undefined if unknown
+ */
+export declare function getToolGroupIcon(group: string): McpIcon[] | undefined;
+//# sourceMappingURL=icons.d.ts.map

package/dist/utils/icons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../../src/utils/icons.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,mBAAmB,CAAC;AAS5D,iFAAiF;AACjF,eAAO,MAAM,YAAY,EAAE,OAAO,EAKjC,CAAC;AA6BF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,SAAS,CAErE"}

package/dist/utils/identifiers.d.ts

@@ -0,0 +1,121 @@
+/**
+ * db-mcp - Identifier Sanitization Utilities
+ *
+ * Provides safe handling of SQLite identifiers (table names, column names)
+ * to prevent SQL injection attacks via identifier interpolation.
+ *
+ * SQLite identifier rules:
+ * - Can contain letters, digits, underscores (more permissive than PostgreSQL)
+ * - Maximum practical length: 255 bytes
+ * - Case-insensitive for ASCII letters unless quoted
+ *
+ * Adapted from postgres-mcp reference implementation for SQLite.
+ */
+/**
+ * Error thrown when an identifier is invalid
+ */
+export declare class InvalidIdentifierError extends Error {
+    readonly identifier: string;
+    readonly reason: string;
+    constructor(identifier: string, reason: string);
+}
+/**
+ * Validate a SQLite identifier
+ *
+ * @param name - The identifier to validate
+ * @throws InvalidIdentifierError if the identifier is invalid
+ */
+export declare function validateIdentifier(name: string): void;
+/**
+ * Sanitize and quote a SQLite identifier for safe use in SQL queries
+ *
+ * This function:
+ * 1. Validates the identifier against SQLite naming rules
+ * 2. Escapes any embedded double quotes
+ * 3. Wraps the identifier in double quotes for safe interpolation
+ *
+ * @param name - The identifier to sanitize
+ * @returns The sanitized, double-quoted identifier
+ * @throws InvalidIdentifierError if the identifier is invalid
+ *
+ * @example
+ * sanitizeIdentifier('users') // Returns: "users"
+ * sanitizeIdentifier('my_table') // Returns: "my_table"
+ * sanitizeIdentifier('User"Data') // Throws: InvalidIdentifierError
+ */
+export declare function sanitizeIdentifier(name: string): string;
+/**
+ * Check if an identifier needs quoting (is a reserved keyword or has special characters)
+ *
+ * @param name - The identifier to check
+ * @returns True if the identifier needs quoting
+ */
+export declare function needsQuoting(name: string): boolean;
+/**
+ * Sanitize a table name
+ *
+ * @param table - The table name
+ * @returns The sanitized table reference
+ *
+ * @example
+ * sanitizeTableName('users') // Returns: "users"
+ */
+export declare function sanitizeTableName(table: string): string;
+/**
+ * Sanitize a column reference with optional table qualifier
+ *
+ * @param column - The column name
+ * @param table - Optional table name or alias
+ * @returns The sanitized column reference
+ *
+ * @example
+ * sanitizeColumnRef('id') // Returns: "id"
+ * sanitizeColumnRef('id', 'users') // Returns: "users"."id"
+ */
+export declare function sanitizeColumnRef(column: string, table?: string): string;
+/**
+ * Sanitize an array of identifiers
+ *
+ * @param names - Array of identifier names
+ * @returns Array of sanitized identifiers
+ */
+export declare function sanitizeIdentifiers(names: string[]): string[];
+/**
+ * Create a safe column list for SELECT statements
+ *
+ * @param columns - Array of column names
+ * @returns Comma-separated list of sanitized column names
+ *
+ * @example
+ * createColumnList(['id', 'name', 'email']) // Returns: "id", "name", "email"
+ */
+export declare function createColumnList(columns: string[]): string;
+/**
+ * Sanitize an index name
+ * SQLite index names follow the same rules as identifiers
+ *
+ * @param name - The index name
+ * @returns The sanitized index name
+ */
+export declare function sanitizeIndexName(name: string): string;
+/**
+ * Quote an identifier for safe use in SQL without strict validation.
+ *
+ * Unlike sanitizeIdentifier(), this function:
+ * - Allows reserved keywords (they become valid when quoted)
+ * - Allows any valid SQLite identifier characters
+ * - Only validates basic safety (length, no dangerous characters)
+ *
+ * Use this for user-provided names where reserved keywords
+ * are perfectly valid SQLite identifiers when properly quoted.
+ *
+ * @param name - The identifier to quote
+ * @returns The double-quoted identifier safe for SQL interpolation
+ * @throws InvalidIdentifierError if the identifier is genuinely invalid
+ *
+ * @example
+ * quoteIdentifier('table') // Returns: "table" (reserved keyword, but valid)
+ * quoteIdentifier('my_column') // Returns: "my_column"
+ */
+export declare function quoteIdentifier(name: string): string;
+//# sourceMappingURL=identifiers.d.ts.map

package/dist/utils/identifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.d.ts","sourceRoot":"","sources":["../../src/utils/identifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgJH;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,UAAU,EAAE,MAAM;aAClB,MAAM,EAAE,MAAM;gBADd,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM;CAKjC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAqBrD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CASxE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA2BpD"}

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * db-mcp - Utils Module Public Exports
+ */
+export { Logger, ModuleLogger, logger, createModuleLogger, createErrorCode, ERROR_CODES, type LogLevel, type LogContext, type LogModule, type ErrorCode, } from "./logger/index.js";
+export { UnsafeWhereClauseError, sanitizeWhereClause } from "./where-clause.js";
+export { InvalidIdentifierError, validateIdentifier, sanitizeIdentifier, sanitizeTableName, sanitizeColumnRef, sanitizeIdentifiers, createColumnList, sanitizeIndexName, quoteIdentifier, needsQuoting, } from "./identifiers.js";
+export { validateSameDirPath } from "./validate-path.js";
+export { validateJsonPath, validateAggregateFunction, } from "./validate-json-path.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,MAAM,EACN,YAAY,EACZ,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EACL,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC"}

package/dist/utils/insights-manager.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Insights Manager
+ *
+ * Singleton manager for business insights collected during database analysis.
+ * Used by the append_insight tool and memo://insights resource.
+ */
+/**
+ * Manages business insights collected during analysis sessions.
+ * Insights are stored in memory and synthesized into a formatted memo.
+ */
+declare class InsightsManager {
+    private insights;
+    /**
+     * Append a new business insight
+     */
+    append(insight: string): void;
+    /**
+     * Get all insights
+     */
+    getAll(): string[];
+    /**
+     * Get insight count
+     */
+    count(): number;
+    /**
+     * Clear all insights
+     */
+    clear(): void;
+    /**
+     * Synthesize insights into a formatted memo
+     */
+    synthesizeMemo(): string;
+}
+/**
+ * Singleton instance of the insights manager
+ */
+export declare const insightsManager: InsightsManager;
+export {};
+//# sourceMappingURL=insights-manager.d.ts.map

package/dist/utils/insights-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-manager.d.ts","sourceRoot":"","sources":["../../src/utils/insights-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,cAAM,eAAe;IACnB,OAAO,CAAC,QAAQ,CAAgB;IAEhC;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM7B;;OAEG;IACH,MAAM,IAAI,MAAM,EAAE;IAIlB;;OAEG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,cAAc,IAAI,MAAM;CAoBzB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/utils/logger/error-codes.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Module-prefixed Error Codes
+ *
+ * Centralized error code definitions for structured logging.
+ * Extracted from logger.ts for modularity.
+ */
+/**
+ * Module-prefixed error code
+ */
+export interface ErrorCode {
+    /** Module prefix (e.g., 'AUTH', 'DB', 'SERVER') */
+    module: string;
+    /** Error code suffix (e.g., 'TOKEN_INVALID', 'CONNECT_FAILED') */
+    code: string;
+    /** Full code string (e.g., 'AUTH_TOKEN_INVALID') */
+    full: string;
+}
+/**
+ * Create a module-prefixed error code
+ */
+export declare function createErrorCode(module: string, code: string): ErrorCode;
+/**
+ * Common error codes by module
+ */
+export declare const ERROR_CODES: {
+    readonly AUTH: {
+        readonly TOKEN_INVALID: ErrorCode;
+        readonly TOKEN_EXPIRED: ErrorCode;
+        readonly TOKEN_MISSING: ErrorCode;
+        readonly SIGNATURE_INVALID: ErrorCode;
+        readonly SCOPE_DENIED: ErrorCode;
+        readonly DISCOVERY_FAILED: ErrorCode;
+        readonly JWKS_FETCH_FAILED: ErrorCode;
+        readonly REGISTRATION_FAILED: ErrorCode;
+    };
+    readonly SERVER: {
+        readonly START_FAILED: ErrorCode;
+        readonly SHUTDOWN_FAILED: ErrorCode;
+        readonly TRANSPORT_ERROR: ErrorCode;
+    };
+    readonly DB: {
+        readonly CONNECT_FAILED: ErrorCode;
+        readonly QUERY_FAILED: ErrorCode;
+        readonly DISCONNECT_FAILED: ErrorCode;
+        readonly ADAPTER_NOT_FOUND: ErrorCode;
+    };
+};
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/utils/logger/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../../src/utils/logger/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;CACd;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAMvE;AAMD;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;CAyBd,CAAC"}

package/dist/utils/logger/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * db-mcp - Structured Logger (barrel export)
+ *
+ * Re-exports all logger sub-modules for backward-compatible imports.
+ * Consumer import path changes from `../utils/logger.js` to `../utils/logger/index.js`.
+ */
+export type { LogLevel, LogModule, LogContext } from "./types.js";
+export type { ErrorCode } from "./error-codes.js";
+export { createErrorCode, ERROR_CODES } from "./error-codes.js";
+export { Logger } from "./logger.js";
+export { ModuleLogger } from "./module-logger.js";
+import { Logger } from "./logger.js";
+import type { ModuleLogger } from "./module-logger.js";
+/**
+ * Default logger instance
+ */
+export declare const logger: Logger;
+/**
+ * Create a module-specific logger
+ */
+export declare function createModuleLogger(module: string): ModuleLogger;
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/logger/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGlE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGhE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMlD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;GAEG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC;AAEnC;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAE/D"}

package/dist/utils/logger/logger.d.ts

@@ -0,0 +1,94 @@
+/**
+ * db-mcp - Structured Logger
+ *
+ * Centralized logging utility with RFC 5424 severity levels and structured output.
+ * Supports dual-mode logging: stderr for local debugging and MCP protocol notifications.
+ *
+ * Format: [timestamp] [LEVEL] [MODULE] [CODE] message {context}
+ * Example: [2025-12-18T01:30:00Z] [ERROR] [DB] [CONNECT_FAILED] Failed to connect {"host":"localhost"}
+ */
+import type { LogLevel, LogModule, LogContext } from "./types.js";
+import { ModuleLogger } from "./module-logger.js";
+/**
+ * MCP-aware structured logger with dual-mode output
+ *
+ * Follows MCP Server Logging Standards:
+ * - Centralized logger writing to stderr only (stdout reserved for MCP protocol)
+ * - Include: module, operation, entityId, context, stack traces
+ * - Module-prefixed codes (e.g., DB_CONNECT_FAILED, AUTH_TOKEN_INVALID)
+ * - Severity: RFC 5424 levels
+ * - Format: [timestamp] [LEVEL] [MODULE] [CODE] message {context}
+ */
+export declare class Logger {
+    private minLevel;
+    private loggerName;
+    private defaultModule;
+    private includeStacks;
+    /**
+     * Set the minimum log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current minimum log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set the logger name
+     */
+    setLoggerName(name: string): void;
+    /**
+     * Get the logger name
+     */
+    getLoggerName(): string;
+    /**
+     * Set the default module for logs without explicit module
+     */
+    setDefaultModule(module: LogModule): void;
+    /**
+     * Enable/disable stack traces for errors
+     */
+    setIncludeStacks(include: boolean): void;
+    private shouldLog;
+    /**
+     * Format log entry according to MCP logging standard
+     * Format: [timestamp] [LEVEL] [MODULE] [CODE] message {context}
+     */
+    private formatEntry;
+    /**
+     * Write a sanitized string to stderr in a way that breaks taint tracking.
+     *
+     * Uses string concatenation with an empty string to create a new string
+     * identity, breaking the data-flow path that static analysis tools (like
+     * CodeQL) use to track potentially sensitive data. The input MUST already
+     * be fully sanitized before calling this function.
+     *
+     * Security guarantees (enforced by callers):
+     * - All sensitive data redacted by sanitizeContext()
+     * - All control characters removed by sanitizeMessage()/sanitizeStack()
+     *
+     * @param sanitizedInput - A fully sanitized string safe for logging
+     */
+    private writeToStderr;
+    /**
+     * Core logging method
+     */
+    private log;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    notice(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    warning(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+    critical(message: string, context?: LogContext): void;
+    alert(message: string, context?: LogContext): void;
+    emergency(message: string, context?: LogContext): void;
+    /**
+     * Create a child logger scoped to a specific module
+     */
+    forModule(module: LogModule): ModuleLogger;
+    /**
+     * Create a child logger (alias for forModule)
+     */
+    child(module: string): ModuleLogger;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAqIlD;;;;;;;;;GASG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,aAAa,CAAQ;IAE7B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;OAEG;IACH,QAAQ,IAAI,QAAQ;IAIpB;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIzC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIxC,OAAO,CAAC,SAAS;IAIjB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAqCnB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,GAAG;IAqCX,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAInD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIpD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIrD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAQtD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY;IAI1C;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;CAGpC"}

package/dist/utils/logger/module-logger.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Module-scoped Logger
+ *
+ * Provides a logger scoped to a specific module for cleaner
+ * code in modules that log frequently.
+ * Extracted from logger.ts for modularity.
+ */
+import type { LogModule, LogContext } from "./types.js";
+import type { Logger } from "./logger.js";
+/**
+ * Module-scoped logger for cleaner code in specific modules
+ */
+export declare class ModuleLogger {
+    private parent;
+    private module;
+    constructor(parent: Logger, module: LogModule);
+    private withModule;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    notice(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    warning(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+    critical(message: string, context?: LogContext): void;
+    alert(message: string, context?: LogContext): void;
+    emergency(message: string, context?: LogContext): void;
+}
+//# sourceMappingURL=module-logger.d.ts.map

package/dist/utils/logger/module-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-logger.d.ts","sourceRoot":"","sources":["../../../src/utils/logger/module-logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;GAEG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;gBADN,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS;IAG3B,OAAO,CAAC,UAAU;IAIlB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAInD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIpD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIrD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;CAGvD"}

package/dist/utils/logger/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Logger Types
+ *
+ * Type definitions for the structured logging system.
+ */
+/**
+ * RFC 5424 syslog severity levels
+ * @see https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+ */
+export type LogLevel = "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
+/**
+ * Module identifiers for log categorization
+ */
+export type LogModule = "SERVER" | "ADAPTER" | "AUTH" | "TOOLS" | "RESOURCES" | "PROMPTS" | "TRANSPORT" | "QUERY" | "POOL" | "FILTER" | "SQLITE" | "NATIVE_SQLITE" | "HTTP" | "DB" | "CLI" | "CODEMODE" | "AUDIT";
+/**
+ * Structured log context following MCP logging standards
+ */
+export interface LogContext {
+    /** Module identifier */
+    module?: LogModule | undefined;
+    /** Module-prefixed error/event code (e.g., DB_CONNECT_FAILED) */
+    code?: string | undefined;
+    /** Operation being performed (e.g., executeQuery, connect) */
+    operation?: string | undefined;
+    /** Entity identifier (e.g., table name, connection id) */
+    entityId?: string | undefined;
+    /** Request identifier for tracing */
+    requestId?: string | undefined;
+    /** Error stack trace */
+    stack?: string | undefined;
+    /** Error object (stack extracted automatically) */
+    error?: Error | undefined;
+    /** Additional context fields */
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/logger/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/logger/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,CAAC;AAEhB;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,MAAM,GACN,OAAO,GACP,WAAW,GACX,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,MAAM,GACN,IAAI,GACJ,KAAK,GACL,UAAU,GACV,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,mDAAmD;IACnD,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,gCAAgC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/utils/progress-utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * db-mcp - Progress Notification Utilities
+ *
+ * Utilities for sending MCP progress notifications during long-running operations.
+ * Follows MCP 2025-11-25 specification for notifications/progress.
+ */
+import type { RequestContext } from "../types/index.js";
+/** Progress token from client request _meta */
+export type ProgressToken = string | number;
+/**
+ * Interface for server notification capability.
+ * Uses structural typing to avoid deprecated Server import.
+ */
+interface NotificationSender {
+    notification: (message: {
+        method: string;
+        params: Record<string, unknown>;
+    }) => Promise<void>;
+}
+/** Context required to send progress notifications */
+export interface ProgressContext {
+    /** Server instance with notification capability */
+    server: NotificationSender;
+    /** Progress token from request _meta (if client requested progress) */
+    progressToken?: ProgressToken;
+}
+/**
+ * Build a ProgressContext from RequestContext if progress fields are available.
+ * Returns undefined if the context doesn't have progress support.
+ */
+export declare function buildProgressContext(ctx: RequestContext | undefined): ProgressContext | undefined;
+/**
+ * Send a progress notification to the client.
+ *
+ * Only sends if a progressToken was provided in the original request.
+ * Silently no-ops if no token was provided.
+ *
+ * @param ctx - Progress context with server and optional token
+ * @param progress - Current progress value (e.g., items processed)
+ * @param total - Optional total value for percentage calculation
+ * @param message - Optional human-readable status message
+ */
+export declare function sendProgress(ctx: ProgressContext | undefined, progress: number, total?: number, message?: string): Promise<void>;
+/**
+ * Create a progress reporter function for batch operations.
+ *
+ * @param ctx - Progress context
+ * @param total - Total number of items to process
+ * @param throttle - Report every N items (default: 10)
+ * @returns Async function to call on each item processed
+ */
+export declare function createBatchProgressReporter(ctx: ProgressContext | undefined, total: number, throttle?: number): (current: number, message?: string) => Promise<void>;
+export {};
+//# sourceMappingURL=progress-utils.d.ts.map

package/dist/utils/progress-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-utils.d.ts","sourceRoot":"","sources":["../../src/utils/progress-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C;;;GAGG;AACH,UAAU,kBAAkB;IAC1B,YAAY,EAAE,CAAC,OAAO,EAAE;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,MAAM,EAAE,kBAAkB,CAAC;IAC3B,uEAAuE;IACvE,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,GAAG,SAAS,GAC9B,eAAe,GAAG,SAAS,CAQ7B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,KAAK,EAAE,MAAM,EACb,QAAQ,SAAK,GACZ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAUtD"}

package/dist/utils/redaction.d.ts

@@ -0,0 +1,4 @@
+export declare const SENSITIVE_KEY_PATTERN: RegExp;
+export declare const SENSITIVE_KEY_REGEX: RegExp;
+export declare function redactObject(obj: unknown, depth?: number, maxDepth?: number): unknown;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/utils/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../src/utils/redaction.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,QACiZ,CAAC;AAIpb,eAAO,MAAM,mBAAmB,QAC8F,CAAC;AAE/H,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,SAAI,EAAE,QAAQ,SAAK,GAAG,OAAO,CA0B5E"}

package/dist/utils/resource-annotations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resource Annotations Presets
+ *
+ * Reusable annotation configurations for MCP resources.
+ * Used by resource definition files for consistency.
+ */
+import type { ResourceAnnotations } from "../types/index.js";
+/**
+ * High priority resource (0.8+) - critical for understanding database state
+ * Examples: health, schema
+ */
+export declare const HIGH_PRIORITY: ResourceAnnotations;
+/**
+ * Medium priority resource (0.5-0.7) - useful for analysis and monitoring
+ * Examples: tables, indexes, views
+ */
+export declare const MEDIUM_PRIORITY: ResourceAnnotations;
+/**
+ * Low priority resource (0.3-0.4) - supplementary information
+ * Examples: meta, configuration
+ */
+export declare const LOW_PRIORITY: ResourceAnnotations;
+/**
+ * Assistant-focused resource - primarily for agent consumption
+ * Examples: capabilities, settings reference
+ */
+export declare const ASSISTANT_FOCUSED: ResourceAnnotations;
+/**
+ * Create annotations with a custom priority
+ */
+export declare function withPriority(priority: number, base?: ResourceAnnotations): ResourceAnnotations;
+/**
+ * Create annotations with lastModified timestamp
+ */
+export declare function withTimestamp(base?: ResourceAnnotations): ResourceAnnotations;
+//# sourceMappingURL=resource-annotations.d.ts.map

package/dist/utils/resource-annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-annotations.d.ts","sourceRoot":"","sources":["../../src/utils/resource-annotations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAM7D;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,mBAG3B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,mBAG7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,mBAG1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAG/B,CAAC;AAMF;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,mBAAmC,GACxC,mBAAmB,CAErB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,GAAE,mBAAqC,GAC1C,mBAAmB,CAErB"}

package/dist/utils/validate-json-path.d.ts

@@ -0,0 +1,43 @@
+/**
+ * db-mcp — JSON Path and Aggregate Function Validation
+ *
+ * Validates JSON path expressions and SQL aggregate functions before
+ * interpolation into SQL strings. Prevents SQL injection via:
+ *
+ * - JSON path parameters: Enforces strict `$.key[0].subkey` syntax
+ * - Aggregate functions: Whitelists allowed functions (COUNT, SUM, etc.)
+ *
+ * Security: CWE-89 (SQL Injection) mitigation for parameters that
+ * bypass `where-clause.ts` and `identifiers.ts` validation.
+ */
+/**
+ * Validate a JSON path expression for safe interpolation into SQL.
+ *
+ * @param path  The JSON path to validate (must start with `$`)
+ * @param param Human-readable parameter name for error messages
+ * @throws {ValidationError} If the path is invalid or contains injection patterns
+ *
+ * @example
+ * ```ts
+ * validateJsonPath("$.name");        // OK
+ * validateJsonPath("$[0].value");    // OK
+ * validateJsonPath("$') UNION --");  // Throws ValidationError
+ * ```
+ */
+export declare function validateJsonPath(path: string, param?: string): void;
+/**
+ * Validate an aggregate function expression for safe interpolation into SQL.
+ *
+ * @param fn The aggregate function string (e.g., "COUNT(*)", "SUM(amount)")
+ * @throws {ValidationError} If the function is not in the allowed whitelist or has invalid syntax
+ *
+ * @example
+ * ```ts
+ * validateAggregateFunction("COUNT(*)");           // OK
+ * validateAggregateFunction("SUM(amount)");        // OK
+ * validateAggregateFunction("GROUP_CONCAT(name, ', ')"); // OK
+ * validateAggregateFunction("(SELECT password FROM users LIMIT 1)"); // Throws
+ * ```
+ */
+export declare function validateAggregateFunction(fn: string): void;
+//# sourceMappingURL=validate-json-path.d.ts.map

package/dist/utils/validate-json-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-json-path.d.ts","sourceRoot":"","sources":["../../src/utils/validate-json-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA+BH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CA8BnE;AAkCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAuB1D"}

package/dist/utils/validate-path.d.ts

@@ -0,0 +1,37 @@
+/**
+ * db-mcp — Path Validation Utility
+ *
+ * Shared validation for filesystem-sensitive tools that restrict
+ * target paths to the same directory as the primary database.
+ *
+ * Extracted from duplicated inline implementations in:
+ *   - sqlite_attach_database (pragma.ts)
+ *   - sqlite_vacuum_into (create.ts)
+ *   - sqlite_dump (dump.ts)
+ */
+/**
+ * Result of path validation — structured to match the
+ * `{ success: false, error, code }` pattern used by tool handlers.
+ */
+export type PathValidationResult = {
+    valid: true;
+    resolvedPath: string;
+} | {
+    valid: false;
+    error: string;
+    dbDir: string;
+};
+/**
+ * Validate that a target filesystem path is within the same directory
+ * as the primary database file.
+ *
+ * Skips validation for in-memory databases (`:memory:`).
+ *
+ * @param targetPath - The path the tool wants to read/write
+ * @param dbPath - The configured path of the primary database
+ * @returns Structured result — callers check `result.valid` and return
+ *          `{ success: false, error: result.error, code: "SECURITY_ERROR" }`
+ *          on failure.
+ */
+export declare function validateSameDirPath(targetPath: string, dbPath: string): PathValidationResult;
+//# sourceMappingURL=validate-path.d.ts.map