db-mcp 2.0.0 → 3.0.0

package/dist/types/database.d.ts

@@ -0,0 +1,100 @@
+/**
+ * db-mcp — Database Types
+ *
+ * Core database type definitions: connections, queries, schema,
+ * tables, columns, indexes, and constraints.
+ */
+/**
+ * Supported database types.
+ * This MCP server only supports SQLite. Other database types
+ * would require separate MCP server projects.
+ */
+export type DatabaseType = "sqlite";
+/**
+ * Database connection configuration
+ */
+export interface DatabaseConfig {
+    /** Database type identifier */
+    type: DatabaseType;
+    /** Connection string (file path or ":memory:") */
+    connectionString?: string;
+    /** Additional database-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Database connection health status
+ */
+export interface HealthStatus {
+    connected: boolean;
+    latencyMs?: number;
+    version?: string;
+    details?: Record<string, unknown>;
+    error?: string;
+}
+/**
+ * Query execution result
+ */
+export interface QueryResult {
+    /** Rows returned (for SELECT queries) */
+    rows?: Record<string, unknown>[];
+    /** Number of rows affected (for INSERT/UPDATE/DELETE) */
+    rowsAffected?: number;
+    /** Last inserted ID (for INSERT with auto-increment) */
+    lastInsertId?: number | string;
+    /** Query execution time in milliseconds */
+    executionTimeMs?: number;
+    /** Column metadata */
+    columns?: ColumnInfo[];
+}
+/**
+ * Column metadata information
+ */
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    primaryKey?: boolean;
+    defaultValue?: unknown;
+}
+/**
+ * Table information
+ */
+export interface TableInfo {
+    name: string;
+    schema?: string;
+    type: "table" | "view" | "materialized_view";
+    strict?: boolean;
+    rowCount?: number;
+    columns?: ColumnInfo[];
+}
+/**
+ * Schema information for a database
+ */
+export interface SchemaInfo {
+    tables: TableInfo[];
+    views?: TableInfo[];
+    indexes?: IndexInfo[];
+    constraints?: ConstraintInfo[];
+}
+/**
+ * Index information
+ */
+export interface IndexInfo {
+    name: string;
+    tableName: string;
+    columns: string[];
+    unique: boolean;
+    type?: string;
+}
+/**
+ * Constraint information
+ */
+export interface ConstraintInfo {
+    name: string;
+    tableName: string;
+    type: "primary_key" | "foreign_key" | "unique" | "check";
+    columns: string[];
+    referencedTable?: string;
+    referencedColumns?: string[];
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/types/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/types/database.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;AAEpC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,IAAI,EAAE,YAAY,CAAC;IAEnB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAEjC,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/B,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,sBAAsB;IACtB,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,mBAAmB,CAAC;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,aAAa,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;IACzD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B"}

package/dist/types/filtering.d.ts

@@ -0,0 +1,41 @@
+/**
+ * db-mcp — Tool Filtering Types
+ *
+ * Tool groups, meta-groups, and filter configuration types.
+ */
+/**
+ * Tool group identifiers
+ */
+export type ToolGroup = "core" | "json" | "text" | "stats" | "vector" | "admin" | "transactions" | "geo" | "introspection" | "migration" | "codemode";
+/**
+ * Meta-group identifiers for common multi-group selections.
+ * These are shortcuts that expand to multiple ToolGroups.
+ */
+export type MetaGroup = "starter" | "analytics" | "search" | "spatial" | "dev-schema" | "minimal" | "full";
+/**
+ * Tool filter rule
+ */
+export interface ToolFilterRule {
+    /** Rule type: include or exclude */
+    type: "include" | "exclude";
+    /** Target: group name or tool name */
+    target: string;
+    /** Whether target is a group (true) or individual tool (false) */
+    isGroup: boolean;
+}
+/**
+ * Parsed tool filter configuration
+ */
+export interface ToolFilterConfig {
+    /** Original filter string */
+    raw: string;
+    /** Parsed rules in order */
+    rules: ToolFilterRule[];
+    /** Set of enabled tool groups after applying rules */
+    enabledGroups: Set<ToolGroup>;
+    /** Set of explicitly excluded tool names (base names without prefix) */
+    excludedTools: Set<string>;
+    /** Set of explicitly included tool names (base names without prefix) */
+    includedTools: Set<string>;
+}
+//# sourceMappingURL=filtering.d.ts.map

package/dist/types/filtering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtering.d.ts","sourceRoot":"","sources":["../../src/types/filtering.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,GACP,cAAc,GACd,KAAK,GACL,eAAe,GACf,WAAW,GACX,UAAU,CAAC;AAEf;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,WAAW,GACX,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,SAAS,GACT,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAE5B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IAEf,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IAEZ,4BAA4B;IAC5B,KAAK,EAAE,cAAc,EAAE,CAAC;IAExB,sDAAsD;IACtD,aAAa,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;IAE9B,wEAAwE;IACxE,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAE3B,wEAAwE;IACxE,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B"}

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * db-mcp — Core Type Definitions
+ *
+ * Barrel re-export from sub-modules. All consumers continue to import
+ * from 'types/index.js' — no import path changes needed.
+ */
+export type { DatabaseType, DatabaseConfig, HealthStatus, QueryResult, ColumnInfo, TableInfo, SchemaInfo, IndexInfo, ConstraintInfo, } from "./database.js";
+export type { TransportType, McpServerConfig } from "./server.js";
+export type { OAuthConfig, OAuthScope, TokenClaims, RequestContext, } from "./auth.js";
+export type { ToolGroup, MetaGroup, ToolFilterRule, ToolFilterConfig, } from "./filtering.js";
+export type { McpIcon, ToolAnnotations, AdapterCapabilities, ToolDefinition, ResourceAnnotations, ResourceDefinition, PromptDefinition, } from "./adapter.js";
+export { DbMcpError, ConnectionError, QueryError, ValidationError, AuthenticationError, AuthorizationError, ExtensionNotAvailableError, } from "../utils/errors/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,cAAc,GACf,MAAM,eAAe,CAAC;AAGvB,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGlE,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,SAAS,EACT,SAAS,EACT,cAAc,EACd,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,OAAO,EACP,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,UAAU,EACV,eAAe,EACf,UAAU,EACV,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC"}

package/dist/types/server.d.ts

@@ -0,0 +1,48 @@
+/**
+ * db-mcp — MCP Server Types
+ *
+ * Configuration types for the MCP server: transport, port, host,
+ * database config references, and server-level options.
+ */
+import type { DatabaseConfig } from "./database.js";
+import type { OAuthConfig } from "./auth.js";
+import type { AuditConfig } from "../audit/types.js";
+/**
+ * Transport type for MCP communication
+ */
+export type TransportType = "stdio" | "http" | "sse";
+/**
+ * MCP Server configuration
+ */
+export interface McpServerConfig {
+    /** Server name */
+    name: string;
+    /** Server version */
+    version: string;
+    /** Transport configuration */
+    transport: TransportType;
+    /** HTTP port (for http/sse transports) */
+    port?: number;
+    /** Host/IP to bind to (for http/sse transports, default: 0.0.0.0) */
+    host?: string;
+    /** Database configurations */
+    databases: DatabaseConfig[];
+    /** OAuth 2.1 configuration */
+    oauth?: OAuthConfig;
+    /** Simple bearer token for HTTP authentication (non-OAuth) */
+    authToken?: string;
+    /** Tool filtering configuration */
+    toolFilter?: string;
+    /**
+     * Enable stateless HTTP mode (no session management, no SSE streaming).
+     * Ideal for serverless deployments (Lambda, Workers, Vercel).
+     * Default: false (stateful mode with session management and SSE support)
+     */
+    statelessHttp?: boolean;
+    enableHSTS?: boolean;
+    /** Audit logging configuration */
+    audit?: AuditConfig;
+    /** Explicitly bypass auth requirement for HTTP transport */
+    noAuthEnforcement?: boolean;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/types/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/types/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IAEb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,SAAS,EAAE,aAAa,CAAC;IAEzB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,8BAA8B;IAC9B,SAAS,EAAE,cAAc,EAAE,CAAC;IAE5B,8BAA8B;IAC9B,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,kCAAkC;IAClC,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B"}

package/dist/utils/annotations.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool Annotations Presets
+ *
+ * Reusable annotation configurations for common tool behavior patterns.
+ * Used by all tool definition files for consistency.
+ *
+ * Follows MCP 2025-11-25 specification.
+ */
+import type { ToolAnnotations } from "../types/index.js";
+/** Read-only query tools (SELECT, schema retrieval, metadata) */
+export declare const READ_ONLY: ToolAnnotations;
+/** Standard write tools (INSERT, UPDATE, CREATE) */
+export declare const WRITE: ToolAnnotations;
+/** Destructive tools (DELETE, DROP, TRUNCATE) */
+export declare const DESTRUCTIVE: ToolAnnotations;
+/** Idempotent tools (CREATE IF NOT EXISTS, upserts) */
+export declare const IDEMPOTENT: ToolAnnotations;
+/** Admin/maintenance tools (VACUUM, ANALYZE, PRAGMA) */
+export declare const ADMIN: ToolAnnotations;
+/**
+ * Create annotations with a custom title
+ */
+export declare function withTitle(title: string, base?: ToolAnnotations): ToolAnnotations;
+/**
+ * Create read-only annotations with title
+ */
+export declare function readOnly(title: string): ToolAnnotations;
+/**
+ * Create write annotations with title
+ */
+export declare function write(title: string): ToolAnnotations;
+/**
+ * Create destructive annotations with title
+ */
+export declare function destructive(title: string): ToolAnnotations;
+/**
+ * Create idempotent annotations with title
+ */
+export declare function idempotent(title: string): ToolAnnotations;
+/**
+ * Create admin annotations with title
+ */
+export declare function admin(title: string): ToolAnnotations;
+/** Admin tools that interact with the filesystem (ATTACH, VACUUM INTO, DUMP) */
+export declare const ADMIN_FS: ToolAnnotations;
+/** Write tools that interact with the filesystem (SpatiaLite Import) */
+export declare const WRITE_FS: ToolAnnotations;
+/**
+ * Create admin-filesystem annotations with title
+ */
+export declare function adminFs(title: string): ToolAnnotations;
+/**
+ * Create write-filesystem annotations with title
+ */
+export declare function writeFs(title: string): ToolAnnotations;
+/** Code Mode tools (can invoke any tool group internally) */
+export declare const CODEMODE: ToolAnnotations;
+/**
+ * Create codemode annotations with title
+ */
+export declare function codemode(title: string): ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/utils/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD,iEAAiE;AACjE,eAAO,MAAM,SAAS,EAAE,eAKvB,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,KAAK,EAAE,eAKnB,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,WAAW,EAAE,eAKzB,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,UAAU,EAAE,eAMxB,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,KAAK,EAAE,eAKnB,CAAC;AAMF;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,eAA2B,GAChC,eAAe,CAEjB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEvD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAE1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEzD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEpD;AAED,gFAAgF;AAChF,eAAO,MAAM,QAAQ,EAAE,eAKtB,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,QAAQ,EAAE,eAKtB,CAAC;AAEF;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEtD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEtD;AAED,6DAA6D;AAC7D,eAAO,MAAM,QAAQ,EAAE,eAMtB,CAAC;AAEF;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEvD"}

package/dist/utils/errors/base.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Base Error Class
+ *
+ * DbMcpError provides enhanced diagnostics: category, code, suggestion,
+ * recoverable flag, and structured response conversion.
+ */
+import type { ErrorCategory, ErrorResponse } from "./categories.js";
+/**
+ * Base error class for db-mcp with enhanced diagnostics
+ */
+export declare class DbMcpError extends Error {
+    /** Error category for classification */
+    readonly category: ErrorCategory;
+    /** Module-prefixed error code (e.g., DB_QUERY_FAILED) */
+    readonly code: string;
+    /** Actionable suggestion for resolving the error */
+    readonly suggestion: string | undefined;
+    /** Additional error details */
+    readonly details: Record<string, unknown> | undefined;
+    /** Whether the error is recoverable (can retry) */
+    readonly recoverable: boolean;
+    constructor(message: string, code: string, category: ErrorCategory, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        recoverable?: boolean | undefined;
+        cause?: Error | undefined;
+    });
+    /**
+     * Convert to structured response object
+     */
+    toResponse(): ErrorResponse;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/utils/errors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/base.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAepE;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtD,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC9C,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAClC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;KAC3B;IAmBH;;OAEG;IACH,UAAU,IAAI,aAAa;CAW5B"}

package/dist/utils/errors/categories.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Error Categories
+ *
+ * Classification enum for all db-mcp errors.
+ */
+/**
+ * Error categories for classification and handling
+ */
+export declare enum ErrorCategory {
+    /** Input validation failures (invalid names, paths, types) */
+    VALIDATION = "validation",
+    /** Database connection issues */
+    CONNECTION = "connection",
+    /** SQL execution errors */
+    QUERY = "query",
+    /** Authorization/permission failures */
+    PERMISSION = "permission",
+    /** Configuration/setup issues */
+    CONFIGURATION = "config",
+    /** Missing resources (tables, columns, views) */
+    RESOURCE = "resource",
+    /** Authentication failures (invalid credentials, expired tokens) */
+    AUTHENTICATION = "authentication",
+    /** Authorization failures (insufficient scope/permissions) */
+    AUTHORIZATION = "authorization",
+    /** Unexpected internal errors */
+    INTERNAL = "internal"
+}
+/**
+ * Structured error response format
+ */
+export interface ErrorResponse {
+    success: false;
+    error: string;
+    code: string;
+    category: ErrorCategory;
+    suggestion: string | undefined;
+    recoverable: boolean;
+    details: Record<string, unknown> | undefined;
+}
+//# sourceMappingURL=categories.d.ts.map

package/dist/utils/errors/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/categories.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,oBAAY,aAAa;IACvB,8DAA8D;IAC9D,UAAU,eAAe;IACzB,iCAAiC;IACjC,UAAU,eAAe;IACzB,2BAA2B;IAC3B,KAAK,UAAU;IACf,wCAAwC;IACxC,UAAU,eAAe;IACzB,iCAAiC;IACjC,aAAa,WAAW;IACxB,iDAAiD;IACjD,QAAQ,aAAa;IACrB,oEAAoE;IACpE,cAAc,mBAAmB;IACjC,8DAA8D;IAC9D,aAAa,kBAAkB;IAC/B,iCAAiC;IACjC,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC9C"}

package/dist/utils/errors/classes.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Specific Error Classes
+ *
+ * Typed error subclasses for each ErrorCategory.
+ */
+import { DbMcpError } from "./base.js";
+/**
+ * Validation error for invalid inputs
+ */
+export declare class ValidationError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Connection error for database connectivity issues
+ */
+export declare class ConnectionError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Query error for SQL execution failures
+ */
+export declare class QueryError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        sql?: string | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Permission error for authorization failures
+ */
+export declare class PermissionError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Resource not found error
+ */
+export declare class ResourceNotFoundError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        resourceType?: string | undefined;
+        resourceName?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Configuration error
+ */
+export declare class ConfigurationError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Internal error for unexpected failures
+ */
+export declare class InternalError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Authentication error (401-type: invalid credentials, expired tokens)
+ */
+export declare class AuthenticationError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Authorization error (403-type: insufficient permissions)
+ */
+export declare class AuthorizationError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Transaction error for commit/rollback/savepoint failures
+ */
+export declare class TransactionError extends DbMcpError {
+    constructor(message: string, code?: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+    });
+}
+/**
+ * Extension not available error
+ *
+ * Used when a required SQLite extension (SpatiaLite, CSV, R-Tree, etc.)
+ * is not installed or cannot be loaded in the current runtime.
+ */
+export declare class ExtensionNotAvailableError extends DbMcpError {
+    constructor(extensionName: string, options?: {
+        suggestion?: string | undefined;
+        details?: Record<string, unknown> | undefined;
+        cause?: Error | undefined;
+        wasmLimitation?: boolean | undefined;
+    });
+}
+//# sourceMappingURL=classes.d.ts.map

package/dist/utils/errors/classes.d.ts.map

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

package/dist/utils/errors/error-response-fields.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared Error Response Fields for Output Schemas
+ *
+ * Defines the ErrorResponseFields Zod schema fragment that gets extended into
+ * every output schema. This ensures formatHandlerError() responses pass
+ * output schema validation (MCP SDK enforces additionalProperties: false).
+ *
+ * This is the 6-field standard required by the mcp-builder skill (§2.2.2).
+ */
+import { z } from "zod";
+/**
+ * Standard error response fields returned by formatHandlerError().
+ * Extend this into every output schema:
+ *   export const MyOutputSchema = z.object({ ... }).extend(ErrorResponseFields.shape);
+ */
+export declare const ErrorResponseFields: z.ZodObject<{
+    error: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    recoverable: z.ZodOptional<z.ZodBoolean>;
+    suggestion: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+//# sourceMappingURL=error-response-fields.d.ts.map

package/dist/utils/errors/error-response-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-response-fields.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/error-response-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;iBAmB9B,CAAC"}

package/dist/utils/errors/format.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Error Response Type and Formatting Utilities
+ *
+ * Converts errors (typed or untyped) into structured ErrorResponse objects.
+ * Harmonized standard: combines rich ErrorResponse (db-mcp), Zod path
+ * extraction (memory-journal-mcp), and ErrorContext (postgres-mcp).
+ */
+import { ErrorCategory, type ErrorResponse } from "./categories.js";
+export type { ErrorResponse };
+import { DbMcpError } from "./base.js";
+/**
+ * Sanitize error messages to prevent leaking physical paths or credentials
+ */
+export declare function sanitizeErrorMessage(msg: string): string;
+/**
+ * Context about the operation that triggered the error.
+ * Adapted from postgres-mcp's ErrorContext pattern for contextual
+ * error intelligence.
+ */
+export interface ErrorContext {
+    /** Tool name that triggered the error */
+    tool?: string;
+    /** SQL statement that was being executed */
+    sql?: string;
+    /** Target table name */
+    table?: string;
+    /** Target index name */
+    index?: string;
+    /** Target database/schema */
+    database?: string;
+    /** Generic target identifier */
+    target?: string;
+}
+/**
+ * Format any caught error into a structured handler error response.
+ *
+ * Handles:
+ * 1. `DbMcpError` — converts via `.toResponse()`
+ * 2. `ZodError` — extracts path + message for clear validation feedback
+ * 3. `Error` — maps message to suggestion via regex patterns
+ * 4. Non-Error values — stringified with INTERNAL category
+ *
+ * Use as the single catch block for all tool handlers:
+ *
+ * ```typescript
+ * handler: async (params: unknown, _context: RequestContext) => {
+ *   try {
+ *     const parsed = Schema.parse(params);
+ *     // ... domain logic ...
+ *     return { success: true, ... };
+ *   } catch (err) {
+ *     return formatHandlerError(err);
+ *   }
+ * }
+ * ```
+ *
+ * @param error - The caught error value
+ * @param context - Optional tool context for richer error messages
+ */
+export declare function formatHandlerError(error: unknown, _context?: ErrorContext): ErrorResponse;
+/**
+ * @deprecated Use `formatHandlerError` instead.
+ * Kept for backward compatibility during migration.
+ */
+export declare const formatHandlerErrorResponse: typeof formatHandlerError;
+/**
+ * Wrap an error with enhanced diagnostics
+ */
+export declare function wrapError(error: unknown, defaultCode?: string, defaultCategory?: ErrorCategory): DbMcpError;
+/**
+ * Check if an error is a DbMcpError
+ */
+export declare function isDbMcpError(error: unknown): error is DbMcpError;
+//# sourceMappingURL=format.d.ts.map

package/dist/utils/errors/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiBxD;AAMD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,YAAY,GACtB,aAAa,CAgDf;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,2BAAqB,CAAC;AAM7D;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,WAAW,SAAkB,EAC7B,eAAe,gBAAyB,GACvC,UAAU,CAkBZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}

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

@@ -0,0 +1,11 @@
+/**
+ * db-mcp Enhanced Error System
+ *
+ * Barrel re-export — preserves the original public API.
+ */
+export { ErrorCategory } from "./categories.js";
+export { findSuggestion } from "./suggestions.js";
+export { DbMcpError } from "./base.js";
+export { ValidationError, ConnectionError, QueryError, PermissionError, ResourceNotFoundError, ConfigurationError, InternalError, AuthenticationError, AuthorizationError, TransactionError, ExtensionNotAvailableError, } from "./classes.js";
+export { type ErrorResponse, type ErrorContext, formatHandlerError, wrapError, isDbMcpError, } from "./format.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EACL,eAAe,EACf,eAAe,EACf,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,kBAAkB,EAClB,SAAS,EACT,YAAY,GACb,MAAM,aAAa,CAAC"}

package/dist/utils/errors/suggestions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Error Suggestions
+ *
+ * Pattern-based suggestions for common errors. Maps error message patterns
+ * to actionable user-facing suggestions.
+ */
+import { ErrorCategory } from "./categories.js";
+/**
+ * Find a suggestion for an error message
+ */
+export declare function findSuggestion(message: string): {
+    suggestion: string;
+    category?: ErrorCategory | undefined;
+    code?: string | undefined;
+} | null;
+//# sourceMappingURL=suggestions.d.ts.map

package/dist/utils/errors/suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.d.ts","sourceRoot":"","sources":["../../../src/utils/errors/suggestions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAwQhD;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B,GAAG,IAAI,CAWP"}