db-mcp 2.0.0 → 3.0.1

package/dist/transports/http/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTTP Transport Module — Public Exports
+ *
+ * Barrel file re-exporting the HTTP transport class, factory, and config type.
+ */
+export { HttpTransport, createHttpTransport } from "./transport.js";
+export type { HttpTransportConfig } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/transports/http/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transports/http/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/transports/http/middleware.d.ts

@@ -0,0 +1,25 @@
+/**
+ * HTTP Transport Middleware
+ *
+ * Security headers, CORS configuration, and rate limiting.
+ * These are standalone functions that operate on HttpTransportState.
+ */
+import { type HttpTransportState } from "./types.js";
+/**
+ * Set security headers on all responses
+ */
+export declare function setupSecurityHeaders(state: HttpTransportState): void;
+/**
+ * Check if an origin matches a CORS pattern.
+ * Supports exact matches and wildcard subdomain patterns (e.g., "*.example.com").
+ */
+export declare function matchesCorsOrigin(origin: string, pattern: string): boolean;
+/**
+ * Configure CORS with configurable origins
+ */
+export declare function setupCors(state: HttpTransportState): void;
+/**
+ * Set up per-IP sliding-window rate limiting using express-rate-limit
+ */
+export declare function setupRateLimiting(state: HttpTransportState): void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/transports/http/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/transports/http/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAUpB;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAkCpE;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAkB1E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CA6CzD;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CA+CjE"}

package/dist/transports/http/oauth.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HTTP Transport OAuth Setup
+ *
+ * OAuth 2.1 component initialization and auth middleware application.
+ */
+import type { HttpTransportState } from "./types.js";
+/**
+ * Apply authentication middleware if configured.
+ *
+ * Priority: OAuth 2.1 > simple bearer token > none.
+ * Warns if no auth is configured.
+ */
+export declare function applyAuthMiddleware(state: HttpTransportState): void;
+/**
+ * Apply per-tool scope enforcement middleware for tools/call requests.
+ * Parses the tool name from the JSON-RPC body and checks against the
+ * OAuth scopes provided in req.auth.
+ */
+export declare function applyScopeEnforcementMiddleware(state: HttpTransportState): void;
+/**
+ * Set up OAuth 2.1 components (resource server, discovery, token validator)
+ */
+export declare function setupOAuth(state: HttpTransportState, resourceUri: string): Promise<void>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/transports/http/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../../src/transports/http/oauth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AASrD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAiCnE;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,kBAAkB,GACxB,IAAI,CA0KN;AAMD;;GAEG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,kBAAkB,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAiEf"}

package/dist/transports/http/session.d.ts

@@ -0,0 +1,2 @@
+export * from "./sessions/index.js";
+//# sourceMappingURL=session.d.ts.map

package/dist/transports/http/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/transports/http/session.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}

package/dist/transports/http/sessions/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./stateless.js";
+export * from "./stateful.js";
+export * from "./legacy-sse.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/transports/http/sessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/transports/http/sessions/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}

package/dist/transports/http/sessions/legacy-sse.d.ts

@@ -0,0 +1,6 @@
+import type { HttpTransportState } from "../types.js";
+/**
+ * Set up Legacy SSE endpoints for backward compatibility (MCP 2024-11-05)
+ */
+export declare function setupLegacySSEEndpoints(state: HttpTransportState): void;
+//# sourceMappingURL=legacy-sse.d.ts.map

package/dist/transports/http/sessions/legacy-sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-sse.d.ts","sourceRoot":"","sources":["../../../../src/transports/http/sessions/legacy-sse.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAStD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAsKvE"}

package/dist/transports/http/sessions/mutex.d.ts

@@ -0,0 +1,6 @@
+export declare class Mutex {
+    private queue;
+    private locked;
+    acquire(): Promise<() => void>;
+}
+//# sourceMappingURL=mutex.d.ts.map

package/dist/transports/http/sessions/mutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../../../src/transports/http/sessions/mutex.ts"],"names":[],"mappings":"AAAA,qBAAa,KAAK;IAChB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAAS;IAEjB,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;CAmBrC"}

package/dist/transports/http/sessions/stateful.d.ts

@@ -0,0 +1,12 @@
+import type { HttpTransportState } from "../types.js";
+/**
+ * H-2: Verify that the requesting client owns the target session.
+ * When auth is disabled (owner is undefined), verification is skipped.
+ * Returns true if access is allowed, false if denied.
+ */
+export declare function verifySessionOwner(state: HttpTransportState, sessionId: string, reqAuthSub: string | undefined): boolean;
+/**
+ * Set up stateful mode endpoints with session management and SSE
+ */
+export declare function setupStatefulEndpoints(state: HttpTransportState): void;
+//# sourceMappingURL=stateful.d.ts.map

package/dist/transports/http/sessions/stateful.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful.d.ts","sourceRoot":"","sources":["../../../../src/transports/http/sessions/stateful.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAUtD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAOT;AAYD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CA4QtE"}

package/dist/transports/http/sessions/stateless.d.ts

@@ -0,0 +1,6 @@
+import type { HttpTransportState } from "../types.js";
+/**
+ * Set up stateless mode endpoints (serverless-compatible)
+ */
+export declare function setupStatelessEndpoints(state: HttpTransportState): Promise<void>;
+//# sourceMappingURL=stateless.d.ts.map

package/dist/transports/http/sessions/stateless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateless.d.ts","sourceRoot":"","sources":["../../../../src/transports/http/sessions/stateless.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAQtD;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CAmDf"}

package/dist/transports/http/transport.d.ts

@@ -0,0 +1,65 @@
+/**
+ * HTTP Transport
+ *
+ * Dual-protocol HTTP transport with OAuth 2.1 integration.
+ * Supports both Streamable HTTP (MCP 2025-03-26) and Legacy SSE
+ * (MCP 2024-11-05) simultaneously, with security headers, CORS,
+ * rate limiting, and body size enforcement.
+ *
+ * Modes:
+ * - Stateful (default): Multi-session management with SSE streaming
+ * - Stateless (opt-in): Lightweight serverless-compatible mode
+ */
+import express from "express";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type HttpTransportConfig } from "./types.js";
+import type { OAuthResourceServer } from "../../auth/oauth-resource-server.js";
+/**
+ * HTTP Transport for MCP with OAuth 2.1 integration.
+ *
+ * Supports both Streamable HTTP (MCP 2025-03-26) and Legacy SSE
+ * (MCP 2024-11-05) protocols simultaneously.
+ *
+ * Modes:
+ * - Stateful (default): Multi-session management with SSE streaming for notifications
+ * - Stateless: Single transport, no session management - ideal for serverless
+ */
+export declare class HttpTransport {
+    /** Internal state shared with session/middleware/oauth modules */
+    private readonly state;
+    constructor(config: HttpTransportConfig);
+    /**
+     * Initialize the transport with the MCP server.
+     *
+     * For stateful mode, the server reference is stored to connect new sessions.
+     * For stateless mode, a single transport is created and connected.
+     *
+     * @param server - The MCP server instance
+     */
+    initialize(server: McpServer): Promise<void>;
+    /**
+     * Start listening on the configured port
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server and close all active sessions
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the underlying Express app
+     */
+    getApp(): express.Express | null;
+    /**
+     * Get the number of active sessions (stateful mode only)
+     */
+    getActiveSessionCount(): number;
+    /**
+     * Get the OAuth Resource Server
+     */
+    getResourceServer(): OAuthResourceServer | null;
+}
+/**
+ * Create an HTTP transport instance
+ */
+export declare function createHttpTransport(config: HttpTransportConfig): HttpTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transports/http/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/transports/http/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,OAAgC,MAAM,SAAS,CAAC;AAEvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE,OAAO,EAKL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AAgBpB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAU/E;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,MAAM,EAAE,mBAAmB;IAsBvC;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAoLlD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgD5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuE3B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI;IAIhC;;OAEG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;OAEG;IACH,iBAAiB,IAAI,mBAAmB,GAAG,IAAI;CAGhD;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,mBAAmB,GAC1B,aAAa,CAEf"}

package/dist/transports/http/type-adapters.d.ts

@@ -0,0 +1,20 @@
+/**
+ * HTTP Transport Type Adapters
+ *
+ * Centralizes the Express ↔ Node.js HTTP type casts needed because
+ * Express v5 Request/Response types don't extend http.IncomingMessage /
+ * http.ServerResponse at the type level (they do at runtime).
+ */
+import type { Request, Response } from "express";
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Cast Express Request to Node.js IncomingMessage.
+ * Safe at runtime — Express Request extends IncomingMessage.
+ */
+export declare function asIncoming(req: Request): IncomingMessage;
+/**
+ * Cast Express Response to Node.js ServerResponse.
+ * Safe at runtime — Express Response extends ServerResponse.
+ */
+export declare function asServerResponse(res: Response): ServerResponse;
+//# sourceMappingURL=type-adapters.d.ts.map

package/dist/transports/http/type-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-adapters.d.ts","sourceRoot":"","sources":["../../../src/transports/http/type-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAExD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,cAAc,CAE9D"}

package/dist/transports/http/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * HTTP Transport Types
+ *
+ * Shared interfaces and constants for the HTTP transport module.
+ */
+import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OAuthResourceServer } from "../../auth/oauth-resource-server.js";
+import type { AuthorizationServerDiscovery } from "../../auth/authorization-server-discovery.js";
+import type { TokenValidator } from "../../auth/token-validator.js";
+import type http from "node:http";
+import type { Express } from "express";
+export declare const DEFAULT_RATE_LIMIT_WINDOW_MS = 60000;
+export declare const DEFAULT_RATE_LIMIT_MAX = 100;
+export declare const DEFAULT_MAX_BODY_BYTES = 1048576;
+export declare const DEFAULT_HSTS_MAX_AGE = 31536000;
+/** JSON-RPC standard error codes */
+export declare const JSONRPC_SERVER_ERROR = -32000;
+export declare const JSONRPC_INTERNAL_ERROR = -32603;
+/** HTTP request timeout (ms) — prevents slowloris-style DoS */
+export declare const HTTP_REQUEST_TIMEOUT_MS = 120000;
+/** Keep-alive timeout (ms) — slightly above common LB idle timeout */
+export declare const HTTP_KEEP_ALIVE_TIMEOUT_MS = 65000;
+/** Headers timeout (ms) — must be > keepAliveTimeout per Node.js docs */
+export declare const HTTP_HEADERS_TIMEOUT_MS = 66000;
+/**
+ * HTTP transport configuration
+ */
+export interface HttpTransportConfig {
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to (default: '0.0.0.0') */
+    host?: 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)
+     */
+    stateless?: boolean;
+    /** Explicitly bypass auth requirement */
+    noAuthEnforcement?: boolean;
+    /** OAuth 2.1 configuration */
+    oauth: {
+        /** Enable OAuth authentication */
+        enabled: boolean;
+        /** Authorization server URL */
+        authorizationServerUrl: string;
+        /** Expected audience in tokens */
+        audience: string;
+        /** Expected issuer (defaults to authorizationServerUrl) */
+        issuer?: string;
+        /** JWKS URI (auto-discovered if not provided) */
+        jwksUri?: string;
+        /** Clock tolerance in seconds (default: 60) */
+        clockTolerance?: number;
+        /** Paths that bypass authentication */
+        publicPaths?: string[];
+    };
+    /** CORS configuration */
+    cors?: {
+        /** Allowed origins */
+        origin?: string | string[] | boolean;
+        /** Allowed methods */
+        methods?: string[];
+        /** Allowed headers */
+        allowedHeaders?: string[];
+        /** Exposed headers */
+        exposedHeaders?: string[];
+        /** Allow credentials */
+        credentials?: boolean;
+    };
+    /**
+     * Allowed CORS origins. Defaults to [] (deny-all).
+     * Supports wildcard subdomains (e.g., "*.example.com" matches "app.example.com").
+     * Must be explicitly configured for production deployments.
+     */
+    corsOrigins?: string[];
+    /** Maximum request body size in bytes (default: 1 MB) */
+    maxBodyBytes?: number;
+    /**
+     * Trust proxy headers for client IP extraction.
+     * Provide a list of trusted reverse proxy IPs or CIDR blocks.
+     * If running behind a proxy, this MUST be explicitly configured to prevent
+     * IP spoofing via X-Forwarded-For headers.
+     */
+    trustedProxyIps?: string | string[];
+    /**
+     * Enable HTTP Strict Transport Security header (default: false).
+     * Should only be enabled when running behind HTTPS.
+     */
+    enableHSTS?: boolean;
+    /**
+     * HSTS max-age in seconds (default: 31536000 = 1 year).
+     * Only used when enableHSTS is true.
+     */
+    hstsMaxAge?: number;
+    /** Resource URI (defaults to http://localhost:{port}) */
+    resourceUri?: string;
+    /** Maximum number of concurrent stateful sessions (default: 1000) */
+    maxSessions?: number;
+}
+/**
+ * Internal state shared across HTTP transport modules.
+ * Passed to setup functions so they can access and modify transport state.
+ */
+export interface HttpTransportState {
+    readonly config: HttpTransportConfig;
+    app: Express | null;
+    httpServer: http.Server | null;
+    transports: Map<string, StreamableHTTPServerTransport>;
+    sseTransports: Map<string, SSEServerTransport>;
+    statelessTransport: StreamableHTTPServerTransport | null;
+    sessionOwners: Map<string, string | undefined>;
+    resourceServer: OAuthResourceServer | null;
+    authServerDiscovery: AuthorizationServerDiscovery | null;
+    tokenValidator: TokenValidator | null;
+    mcpServer: McpServer | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transports/http/types.d.ts.map

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

package/dist/types/adapter.d.ts

@@ -0,0 +1,138 @@
+/**
+ * db-mcp — Adapter Types
+ *
+ * Types for database adapter capabilities, tool/resource/prompt definitions,
+ * MCP icons, and tool annotations.
+ */
+import type { ToolGroup } from "./filtering.js";
+import type { OAuthScope, RequestContext } from "./auth.js";
+/**
+ * MCP Icon Definition (MCP Spec 2025-11-25)
+ *
+ * Icons can be added to servers, tools, resources, and prompts for
+ * visual representation in client interfaces.
+ */
+export interface McpIcon {
+    /** Icon source — URL or data URI */
+    src: string;
+    /** MIME type (e.g., 'image/svg+xml', 'image/png') */
+    mimeType?: string;
+    /** Size descriptors (e.g., ['48x48'], ['any']) */
+    sizes?: string[];
+    /** Theme hint: 'light' or 'dark' */
+    theme?: "light" | "dark";
+}
+/**
+ * Tool annotations provide behavioral hints to clients
+ * following the MCP 2025-11-25 specification.
+ */
+export interface ToolAnnotations {
+    /** Human-readable title for the tool */
+    title?: string;
+    /** If true, the tool is guaranteed not to modify any state */
+    readOnlyHint?: boolean;
+    /** If true, multiple identical requests have the same effect as a single request */
+    idempotentHint?: boolean;
+    /** If true, the operation is irreversible or causes significant data loss */
+    destructiveHint?: boolean;
+    /** If true, the tool interacts with external/"open world" systems (network, filesystem, etc.) */
+    openWorldHint?: boolean;
+    /** If true, the tool handles or returns sensitive data */
+    sensitiveHint?: boolean;
+}
+/**
+ * Capabilities supported by a database adapter
+ */
+export interface AdapterCapabilities {
+    /** Supports JSON operations */
+    json: boolean;
+    /** Supports full-text search */
+    fullTextSearch: boolean;
+    /** Supports vector/embedding operations */
+    vector: boolean;
+    /** Supports geospatial operations */
+    geospatial: boolean;
+    /** Supports transactions */
+    transactions: boolean;
+    /** Supports prepared statements */
+    preparedStatements: boolean;
+    /** Supports connection pooling */
+    connectionPooling: boolean;
+    /** Additional capability flags */
+    [key: string]: boolean;
+}
+/**
+ * Tool definition for registration
+ */
+export interface ToolDefinition {
+    /** Unique tool name */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Tool group for filtering */
+    group: ToolGroup;
+    /** Zod schema for input validation */
+    inputSchema?: unknown;
+    /** Zod schema for output validation (MCP 2025-11-25) */
+    outputSchema?: unknown;
+    /** Required OAuth scopes */
+    requiredScopes?: OAuthScope[];
+    /** MCP tool annotations (behavioral hints) */
+    annotations?: ToolAnnotations;
+    /** MCP icons for visual representation (MCP 2025-11-25) */
+    icons?: McpIcon[];
+    /** Tool handler function */
+    handler: (params: unknown, context: RequestContext) => Promise<unknown>;
+}
+/**
+ * MCP Resource Annotations (SDK 1.25+)
+ * Provides metadata hints about resource content to help clients
+ * manage and display resources appropriately.
+ */
+export interface ResourceAnnotations {
+    /** Intended audience for the resource content */
+    audience?: ("user" | "assistant")[];
+    /** Priority hint for display ordering (0-1 range) */
+    priority?: number;
+    /** ISO 8601 timestamp of last modification for cache invalidation */
+    lastModified?: string;
+}
+/**
+ * Resource definition for MCP
+ */
+export interface ResourceDefinition {
+    /** Resource URI template */
+    uri: string;
+    /** Human-readable name */
+    name: string;
+    /** Description */
+    description: string;
+    /** MIME type */
+    mimeType?: string;
+    /** MCP Resource Annotations for behavior hints */
+    annotations?: ResourceAnnotations;
+    /** MCP icons for visual representation (MCP 2025-11-25) */
+    icons?: McpIcon[];
+    /** Resource handler */
+    handler: (uri: string, context: RequestContext) => Promise<unknown>;
+}
+/**
+ * Prompt definition for MCP
+ */
+export interface PromptDefinition {
+    /** Prompt name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Argument definitions */
+    arguments?: {
+        name: string;
+        description: string;
+        required?: boolean;
+    }[];
+    /** MCP icons for visual representation (MCP 2025-11-25) */
+    icons?: McpIcon[];
+    /** Prompt handler */
+    handler: (args: Record<string, string>, context: RequestContext) => Promise<unknown>;
+}
+//# sourceMappingURL=adapter.d.ts.map

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

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

package/dist/types/auth.d.ts

@@ -0,0 +1,79 @@
+/**
+ * db-mcp — OAuth & Auth Types
+ *
+ * OAuth 2.1 configuration, scopes, token claims, and request context.
+ */
+/**
+ * OAuth 2.1 configuration
+ */
+export interface OAuthConfig {
+    /** Enable OAuth authentication */
+    enabled: boolean;
+    /** Authorization server URL */
+    authorizationServerUrl?: string;
+    /** Token validation endpoint */
+    tokenEndpoint?: string;
+    /** JWKS URI for token verification */
+    jwksUri?: string;
+    /** Expected audience in tokens */
+    audience?: string;
+    /** Expected issuer in tokens */
+    issuer?: string;
+    /** Clock tolerance for token validation (seconds) */
+    clockTolerance?: number;
+    /** JWKS cache TTL (seconds) */
+    jwksCacheTtl?: number;
+    /** Paths that bypass authentication */
+    publicPaths?: string[];
+}
+/**
+ * OAuth scopes for access control
+ */
+export type OAuthScope = "read" | "write" | "admin" | `db:${string}` | `table:${string}:${string}`;
+/**
+ * Validated OAuth token claims
+ */
+export interface TokenClaims {
+    /** Subject (user ID) */
+    sub: string;
+    /** Granted scopes */
+    scopes: string[];
+    /** Token expiration time */
+    exp: number;
+    /** Token issued at time */
+    iat: number;
+    /** Token issuer */
+    iss?: string | undefined;
+    /** Token audience */
+    aud?: string | string[] | undefined;
+    /** Additional claims */
+    [key: string]: unknown;
+}
+/**
+ * Request context with authentication info
+ */
+export interface RequestContext {
+    /** Validated token claims (if authenticated) */
+    auth?: TokenClaims | undefined;
+    /** Raw access token */
+    accessToken?: string;
+    /** Request timestamp */
+    timestamp: Date;
+    /** Request ID for tracing */
+    requestId: string;
+    /**
+     * MCP Server instance for sending progress notifications.
+     * Only available when running in HTTP/SSE transport with stateful sessions.
+     */
+    server?: unknown;
+    /**
+     * Progress token from client request _meta (MCP 2025-11-25).
+     * If present, the client has requested progress updates.
+     */
+    progressToken?: string | number;
+    /**
+     * Client IP address for rate limiting fallback
+     */
+    clientIp?: string | undefined;
+}
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IAEjB,+BAA+B;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,OAAO,GACP,OAAO,GACP,MAAM,MAAM,EAAE,GACd,SAAS,MAAM,IAAI,MAAM,EAAE,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IAEZ,qBAAqB;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IAEZ,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IAEZ,mBAAmB;IACnB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzB,qBAAqB;IACrB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAEpC,wBAAwB;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAE/B,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,wBAAwB;IACxB,SAAS,EAAE,IAAI,CAAC;IAEhB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B"}