drizzle-cube 0.6.1 → 0.6.3

package/dist/cjs/adapters/mcp-tools.d.ts

@@ -0,0 +1,134 @@
+import { SemanticLayerCompiler, SecurityContext } from '../server/index.js';
+import { DiscoverRequest, ValidateRequest, LoadRequest } from './utils.js';
+import { MCPPrompt } from '../server/ai/mcp-prompts.js';
+import { MCPResource, McpAppConfig } from './mcp-transport.js';
+export type { MCPPrompt, MCPResource, DiscoverRequest, ValidateRequest, LoadRequest };
+export type { SecurityContext } from '../server/index.js';
+/**
+ * MCP tool content block (matches MCP spec)
+ */
+export interface MCPToolContent {
+    type: 'text';
+    text: string;
+}
+/**
+ * MCP tool result (matches MCP spec CallToolResult)
+ */
+export interface MCPToolResult {
+    content: MCPToolContent[];
+    isError: boolean;
+}
+/**
+ * MCP tool definition (matches MCP spec Tool)
+ */
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        required?: string[];
+        properties: Record<string, unknown>;
+    };
+}
+/**
+ * Options for creating composable cube tools
+ */
+export interface GetCubeToolsOptions {
+    /** The semantic layer compiler instance with registered cubes */
+    semanticLayer: SemanticLayerCompiler;
+    /**
+     * Extract security context for query execution.
+     * Called when the `load` tool is invoked.
+     * Receives whatever metadata your MCP server provides (auth info, request context, etc.)
+     */
+    getSecurityContext: (meta?: unknown) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * Optional tool name prefix. Defaults to 'drizzle_cube_'.
+     * Set to '' for no prefix, or provide your own like 'analytics_'.
+     */
+    toolPrefix?: string;
+    /**
+     * Which tools to expose. Defaults to all: ['discover', 'validate', 'load']
+     */
+    tools?: ('discover' | 'validate' | 'load')[];
+    /** Custom MCP prompts (defaults to built-in drizzle-cube prompts) */
+    prompts?: MCPPrompt[];
+    /** Custom MCP resources (defaults to built-in drizzle-cube resources) */
+    resources?: MCPResource[];
+    /**
+     * Enable MCP App visualization for the load tool.
+     * Pass `true` to enable with defaults, or a config object to set locale options.
+     * @example app: { defaultLocale: 'nl-NL', detectBrowserLocale: false }
+     */
+    app?: boolean | McpAppConfig;
+}
+/**
+ * The composable tools object returned by getCubeTools()
+ */
+export interface CubeTools {
+    /** Tool definitions for MCP tools/list responses */
+    definitions: MCPToolDefinition[];
+    /**
+     * Execute a tool by name. Returns MCP-spec-compliant result.
+     * @param name - Tool name (with or without prefix)
+     * @param args - Tool arguments from the MCP client
+     * @param meta - Optional metadata passed to getSecurityContext
+     */
+    handle: (name: string, args: unknown, meta?: unknown) => Promise<MCPToolResult>;
+    /**
+     * Check if a tool name is handled by these cube tools
+     * @param name - Tool name to check (with or without prefix)
+     */
+    handles: (name: string) => boolean;
+    /** MCP prompts for prompts/list responses */
+    prompts: MCPPrompt[];
+    /** MCP resources for resources/list responses */
+    resources: MCPResource[];
+    /** The tool names this instance handles (with prefix applied) */
+    toolNames: string[];
+}
+/**
+ * Create composable MCP tools for your semantic layer.
+ *
+ * Returns tool definitions, a handler function, and prompts/resources
+ * that you can register on any MCP server.
+ *
+ * @example With @modelcontextprotocol/sdk
+ * ```typescript
+ * import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+ * import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+ * import { getCubeTools } from 'drizzle-cube/mcp'
+ *
+ * const cubeTools = getCubeTools({
+ *   semanticLayer,
+ *   getSecurityContext: async (meta) => ({ orgId: meta.authInfo?.orgId })
+ * })
+ *
+ * const server = new Server({ name: 'my-server', version: '1.0.0' })
+ *
+ * server.setRequestHandler(ListToolsRequestSchema, async () => ({
+ *   tools: [...myOtherTools, ...cubeTools.definitions]
+ * }))
+ *
+ * server.setRequestHandler(CallToolRequestSchema, async (req) => {
+ *   if (cubeTools.handles(req.params.name)) {
+ *     return cubeTools.handle(req.params.name, req.params.arguments, req)
+ *   }
+ *   return handleOtherTools(req)
+ * })
+ * ```
+ *
+ * @example With Hono + postgrest-mcp style
+ * ```typescript
+ * import { getCubeTools } from 'drizzle-cube/mcp'
+ *
+ * const cubeTools = getCubeTools({
+ *   semanticLayer,
+ *   getSecurityContext: async () => ({ orgId: 'default' })
+ * })
+ *
+ * // Merge with your existing PostgREST tools
+ * const allTools = [...postgrestTools, ...cubeTools.definitions]
+ * ```
+ */
+export declare function getCubeTools(options: GetCubeToolsOptions): CubeTools;

package/dist/cjs/adapters/mcp-transport.d.ts

@@ -0,0 +1,158 @@
+import { SemanticLayerCompiler, SecurityContext } from '../server/index.js';
+import { MCPPrompt } from '../server/ai/mcp-prompts.js';
+import { McpAppConfig } from './utils.js';
+export type { McpAppConfig };
+export { type MCPPrompt };
+export declare const MCP_APP_RESOURCE_URI = "ui://drizzle-cube/visualization.html";
+export declare const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+/** Get the bundled MCP App HTML, optionally with locale config injected. Returns empty string if not yet built. */
+export declare function getMcpAppHtml(config?: McpAppConfig): string;
+export type JsonRpcId = string | number | null | undefined;
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface McpDispatchContext {
+    semanticLayer: SemanticLayerCompiler;
+    extractSecurityContext: (req: any, res: any) => SecurityContext | Promise<SecurityContext>;
+    rawRequest: unknown;
+    rawResponse: unknown;
+    negotiatedProtocol?: string | null;
+    resources?: MCPResource[];
+    prompts?: MCPPrompt[];
+    /**
+     * Pre-resolved instructions string returned in the `initialize` result
+     * (`InitializeResult.instructions` per MCP spec). When omitted, falls
+     * back to `getDefaultMcpInstructions()`. Adapters resolve this from the
+     * `MCPOptions.instructions` resolver before calling `dispatchMcpMethod`.
+     */
+    instructions?: string;
+    /** Enable MCP App visualization for load tool */
+    appEnabled?: boolean;
+    /** Locale configuration for the MCP App (only used when appEnabled is true) */
+    appConfig?: McpAppConfig;
+    /** Optional name for the MCP serverInfo.name field. Defaults to 'drizzle-cube'. */
+    serverName?: string;
+}
+export interface MCPResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    text: string;
+}
+export type MCPPromptResolver = MCPPrompt[] | ((defaults: MCPPrompt[]) => MCPPrompt[]);
+export type MCPResourceResolver = MCPResource[] | ((defaults: MCPResource[]) => MCPResource[]);
+export type MCPInstructionsResolver = string | ((defaults: string) => string);
+export interface ProtocolNegotiation {
+    ok: boolean;
+    negotiated: string | null;
+    supported: string[];
+}
+export declare const SUPPORTED_MCP_PROTOCOLS: string[];
+export declare const DEFAULT_MCP_PROTOCOL = "2025-11-25";
+export declare function negotiateProtocol(headers: Record<string, string | string[] | undefined>): ProtocolNegotiation;
+export declare function wantsEventStream(accept: string | null | undefined): boolean;
+/**
+ * MCP Session ID header name (per 2025-11-25 spec)
+ */
+export declare const MCP_SESSION_ID_HEADER = "mcp-session-id";
+/**
+ * MCP Protocol Version header name (per 2025-11-25 spec)
+ */
+export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+/**
+ * Validate the Accept header per MCP 2025-11-25 spec.
+ * Client MUST include both `application/json` and `text/event-stream` as supported content types.
+ *
+ * @returns true if valid, false if invalid
+ */
+export declare function validateAcceptHeader(accept: string | null | undefined): boolean;
+export interface OriginValidationOptions {
+    /**
+     * List of allowed origins (e.g., ['http://localhost:3000', 'https://myapp.com'])
+     * If not provided, defaults to localhost origins only
+     */
+    allowedOrigins?: string[];
+    /**
+     * If true, allows requests without an Origin header (non-browser clients)
+     * @default true
+     */
+    allowMissingOrigin?: boolean;
+}
+/**
+ * Validate the Origin header per MCP 2025-11-25 spec.
+ * Servers MUST validate Origin to prevent DNS rebinding attacks.
+ * If Origin is present and invalid, MUST respond with 403 Forbidden.
+ *
+ * @returns { valid: true } if allowed, or { valid: false, reason: string } if blocked
+ */
+export declare function validateOriginHeader(origin: string | null | undefined, options?: OriginValidationOptions): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Extract a Bearer token from an Authorization header.
+ * Returns the token string if present and well-formed, or null otherwise.
+ */
+export declare function extractBearerToken(authHeader: string | null | undefined): string | null;
+/**
+ * Build a WWW-Authenticate challenge header value per MCP / RFC 9728.
+ * Points the client to the Protected Resource Metadata document so it can
+ * discover the authorization server and begin the OAuth 2.1 flow.
+ */
+export declare function buildWwwAuthenticateChallenge(resourceMetadataUrl: string): string;
+export declare function serializeSseEvent(payload: unknown, eventId?: string, retryMs?: number): string;
+export declare function buildJsonRpcError(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcResponse;
+export declare function buildJsonRpcResult(id: JsonRpcId, result: unknown): JsonRpcResponse;
+export declare function parseJsonRpc(body: unknown): JsonRpcRequest | null;
+export declare function dispatchMcpMethod(method: string, params: unknown, ctx: McpDispatchContext): Promise<unknown>;
+export declare function jsonRpcError(code: number, message: string, data?: unknown): Error & {
+    code: number;
+    data?: unknown;
+};
+export declare function normalizeHeader(value: string | string[] | undefined): string | null;
+export declare function isNotification(request: JsonRpcRequest): boolean;
+export declare function primeEventId(): string;
+export declare function buildToolList(options?: {
+    appEnabled?: boolean;
+}): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    _meta?: unknown;
+}[];
+export declare function getDefaultResources(): MCPResource[];
+export declare function getDefaultPrompts(): MCPPrompt[];
+/**
+ * Default instructions string returned in `InitializeResult.instructions`.
+ * Re-exported here so adapter consumers don't need to reach into `server/ai`.
+ */
+export declare function getDefaultInstructions(): string;
+export declare function resolveMcpPrompts(prompts?: MCPPromptResolver): MCPPrompt[];
+export declare function resolveMcpResources(resources?: MCPResourceResolver): MCPResource[];
+/**
+ * Resolve the MCP instructions string for the `initialize` response.
+ *
+ * - `undefined` → returns the built-in defaults.
+ * - `string`    → replaces the defaults entirely.
+ * - `(defaults) => string` → derive from / extend the defaults (e.g. append
+ *   project-specific guidance like custom cube semantics).
+ */
+export declare function resolveMcpInstructions(instructions?: MCPInstructionsResolver): string;
+export declare function buildMcpSchemaResource(semanticLayer: SemanticLayerCompiler): MCPResource;
+export declare function buildMcpResources(semanticLayer: SemanticLayerCompiler, resources?: MCPResourceResolver): MCPResource[];

package/dist/cjs/adapters/nextjs/index.d.ts

@@ -0,0 +1,195 @@
+import { NextRequest } from 'next/server';
+import { SemanticQuery, SecurityContext, DatabaseExecutor, DrizzleDatabase, Cube, CacheConfig, RLSSetupFn } from '../../server/index.js';
+import { AgentConfig } from '../../server/agent/types.js';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { MySql2Database } from 'drizzle-orm/mysql2';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import { MCPOptions } from '../utils.js';
+export interface NextCorsOptions {
+    /**
+     * Allowed origins for CORS
+     */
+    origin?: string | string[] | ((origin: string) => boolean);
+    /**
+     * Allowed HTTP methods
+     */
+    methods?: string[];
+    /**
+     * Allowed headers
+     */
+    allowedHeaders?: string[];
+    /**
+     * Allow credentials
+     */
+    credentials?: boolean;
+}
+export interface NextAdapterOptions {
+    /**
+     * Array of cube definitions to register
+     */
+    cubes: Cube[];
+    /**
+     * Drizzle database instance (REQUIRED)
+     * This is the core of drizzle-cube - Drizzle ORM integration
+     * Accepts PostgreSQL, MySQL, or SQLite database instances
+     */
+    drizzle: PostgresJsDatabase<any> | MySql2Database<any> | BetterSQLite3Database<any> | DrizzleDatabase;
+    /**
+     * Database schema for type inference (RECOMMENDED)
+     * Provides full type safety for cube definitions
+     */
+    schema?: any;
+    /**
+     * Extract security context from incoming HTTP request.
+     * Called for EVERY API request to determine user permissions and multi-tenant isolation.
+     *
+     * This is your security boundary - ensure proper authentication and authorization here.
+     *
+     * @param request - Next.js Request object containing the incoming HTTP request
+     * @param context - Route context with params (optional)
+     * @returns Security context with organisationId, userId, roles, etc.
+     *
+     * @example
+     * extractSecurityContext: async (request, context) => {
+     *   // Extract JWT from Authorization header
+     *   const token = request.headers.get('Authorization')?.replace('Bearer ', '')
+     *   const decoded = await verifyJWT(token)
+     *
+     *   // Return context that will be available in all cube SQL functions
+     *   return {
+     *     organisationId: decoded.orgId,
+     *     userId: decoded.userId,
+     *     roles: decoded.roles
+     *   }
+     * }
+     */
+    extractSecurityContext: (request: NextRequest, context?: RouteContext) => SecurityContext | Promise<SecurityContext>;
+    /**
+     * Database engine type (optional - auto-detected if not provided)
+     */
+    engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+    /**
+     * CORS configuration (optional)
+     */
+    cors?: NextCorsOptions;
+    /**
+     * Runtime environment (default: 'nodejs')
+     * 'edge' for Edge Runtime, 'nodejs' for Node.js Runtime
+     */
+    runtime?: 'edge' | 'nodejs';
+    /**
+     * Cache configuration for query result caching
+     * When provided, query results will be cached using the specified provider
+     */
+    cache?: CacheConfig;
+    /**
+     * MCP (AI-Ready) endpoint configuration
+     * Enables AI agents to discover and query your data
+     * @default { enabled: true }
+     */
+    mcp?: MCPOptions;
+    /**
+     * Agent configuration for the agentic AI notebook feature.
+     * When provided, enables the POST /agent/chat SSE endpoint.
+     * Requires `@anthropic-ai/sdk` as a peer dependency.
+     */
+    agent?: AgentConfig;
+    /**
+     * Row-Level Security setup function.
+     * When provided, every query execution opens a transaction, calls this function
+     * to configure RLS (e.g., set JWT claims and switch Postgres roles), then runs the query.
+     */
+    rlsSetup?: RLSSetupFn;
+}
+export interface RouteContext {
+    params?: Record<string, string | string[]>;
+}
+export type RouteHandler = (request: NextRequest, context?: RouteContext) => Promise<Response>;
+export interface CubeHandlers {
+    load: RouteHandler;
+    meta: RouteHandler;
+    sql: RouteHandler;
+    dryRun: RouteHandler;
+    batch: RouteHandler;
+    explain: RouteHandler;
+    mcpRpc?: RouteHandler;
+    agentChat?: RouteHandler;
+}
+/**
+ * Create OPTIONS handler for CORS preflight requests
+ */
+export declare function createOptionsHandler(corsOptions: NextCorsOptions): RouteHandler;
+/**
+ * Create load handler - Execute queries (GET + POST via the core)
+ */
+export declare function createLoadHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create meta handler - Get cube metadata
+ */
+export declare function createMetaHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create SQL handler - Generate SQL without execution (GET + POST via the core)
+ */
+export declare function createSqlHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create dry-run handler - Validate queries without execution (GET + POST via the core)
+ */
+export declare function createDryRunHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create batch handler - Execute multiple queries in a single request (POST via the core)
+ */
+export declare function createBatchHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create explain handler - Get execution plan for a query (POST via the core)
+ */
+export declare function createExplainHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create discover handler - Find relevant cubes based on topic/intent
+ */
+export declare function createDiscoverHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create suggest handler - Generate query from natural language
+ */
+export declare function createSuggestHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create validate handler - Validate query with helpful corrections
+ */
+export declare function createValidateHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create MCP load handler - Execute a query and return results
+ * Completes the AI workflow: discover → suggest → validate → load
+ */
+export declare function createMcpLoadHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create MCP Streamable HTTP handler (JSON-RPC 2.0 + optional SSE)
+ * Implements MCP 2025-11-25 spec. POST is dispatched via the core; the GET
+ * streaming connection and DELETE lifecycle stay inline (transport-bound).
+ */
+export declare function createMcpRpcHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Create agent chat handler - Agentic AI notebook chat
+ * Streams SSE events as the agent discovers data, executes queries,
+ * and creates visualizations. Inherently transport-bound, so it stays inline.
+ */
+export declare function createAgentChatHandler(options: NextAdapterOptions): RouteHandler;
+/**
+ * Convenience function to create all route handlers
+ *
+ * @example
+ * const handlers = createCubeHandlers({
+ *   cubes: [salesCube, employeesCube],
+ *   drizzle: db,
+ *   schema,
+ *   extractSecurityContext: async (request, context) => {
+ *     const token = request.headers.get('Authorization')?.replace('Bearer ', '')
+ *     const decoded = await verifyJWT(token)
+ *     return { organisationId: decoded.orgId, userId: decoded.userId }
+ *   }
+ * })
+ *
+ * // Use in your API routes:
+ * export const GET = handlers.load
+ * export const POST = handlers.load
+ */
+export declare function createCubeHandlers(options: NextAdapterOptions): CubeHandlers;
+export type { SecurityContext, DatabaseExecutor, SemanticQuery, DrizzleDatabase, NextCorsOptions as CorsOptions };

package/dist/cjs/adapters/nextjs/mcp-handler.d.ts

@@ -0,0 +1,8 @@
+import { NextRequest, NextResponse } from 'next/server';
+/** Applies adapter CORS headers to an outgoing header set (no-op when CORS is disabled). */
+export type ApplyCors = (request: NextRequest, headers: Headers) => void;
+/**
+ * Build the SSE `Response` for a GET (streaming connection open) request,
+ * emitting the initial `mcp/ready` event.
+ */
+export declare function buildMcpGetResponse(request: NextRequest, applyCors: ApplyCors): NextResponse;

package/dist/cjs/adapters/types.d.ts

@@ -0,0 +1,41 @@
+import { SemanticLayerCompiler, SecurityContext, DatabaseExecutor } from '../server/index.js';
+/**
+ * Base adapter configuration
+ */
+export interface BaseAdapterOptions {
+    semanticLayer: SemanticLayerCompiler;
+    databaseExecutor?: DatabaseExecutor;
+    basePath?: string;
+}
+/**
+ * Framework-specific context extractor
+ * Each framework adapter will provide their own context type
+ */
+export interface ContextExtractor<TContext = any> {
+    (context: TContext): SecurityContext | Promise<SecurityContext>;
+}
+/**
+ * Standard CORS configuration
+ */
+export interface CorsConfig {
+    origin?: string | string[] | ((origin: string) => boolean);
+    allowMethods?: string[];
+    allowHeaders?: string[];
+    credentials?: boolean;
+}
+/**
+ * Standard adapter response format
+ */
+export interface AdapterResponse {
+    data?: any;
+    error?: string;
+    status?: number;
+}
+/**
+ * Future adapter interface (for Express, Fastify, etc.)
+ */
+export interface AdapterFactory<TOptions extends BaseAdapterOptions, TApp = any> {
+    createRoutes(options: TOptions): TApp;
+    mountRoutes?(app: TApp, options: TOptions): TApp;
+    createApp?(options: TOptions): TApp;
+}