Ditto: Execute DQL query

Instructions

Implementation Reference

• src/ditto/client.ts:21-98 (handler)

  Core handler function that executes the DQL query by making an authenticated POST request to Ditto's /api/v4/store/execute endpoint. Handles timeouts, errors, and returns structured DittoResponse.

  export async function executeDql(
    req: ExecuteRequest,
    opts: ExecuteOptions,
  ): Promise<DittoResponse> {
    const url = buildUrl(opts.baseUrl);
    const controller = new AbortController();
    const timeoutMs = opts.timeoutMs ?? 20000;
    const id = setTimeout(() => controller.abort(), timeoutMs);
  
    try {
      const headers: Record<string, string> = {
        Authorization: `Bearer ${opts.apiKey}`,
        'Content-Type': 'application/json',
        'User-Agent': `ditto-mcp-server/${SERVER_VERSION}`,
      };
      if (opts.transactionId !== undefined) {
        headers['X-DITTO-TXN-ID'] = String(opts.transactionId);
      }
  
      const res = await fetch(url, {
        method: 'POST',
        headers,
        body: JSON.stringify(req),
        signal: controller.signal,
      });
  
      const text = await res.text();
      let json: DittoResponse | undefined;
  
      try {
        json = text ? (JSON.parse(text) as DittoResponse) : undefined;
      } catch {
        // Fallback plain-text error
        if (!res.ok) {
          throw Object.assign(new Error(text || `HTTP ${res.status}`), {
            status: res.status,
          });
        }
        throw new Error('Ditto response was not valid JSON');
      }
  
      if (!res.ok) {
        const errMsg = json?.error?.description || `HTTP ${res.status}`;
        class HttpStatusError extends Error {
          status?: number;
          constructor(message: string, status?: number) {
            super(message);
            this.status = status;
          }
        }
        throw new HttpStatusError(errMsg, res.status);
      }
  
      return json!;
    } catch (err: unknown) {
      let message = 'Request failed';
      if (typeof err === 'object' && err !== null) {
        const maybe = err as { message?: string };
        if (typeof maybe.message === 'string') message = maybe.message;
      } else if (typeof err === 'string') {
        message = err;
      }
      logger.error(`[ditto] request failed: ${message}`);
      // Return a Ditto-like error envelope to the tool handler
      const errorResponse: DittoResponse = {
        queryType: 'unknown',
        items: [],
        mutatedDocumentIds: [],
        totalWarningsCount: 0,
        warnings: [],
        error: { description: message },
        transactionId: undefined,
      };
      return errorResponse;
    } finally {
      clearTimeout(id);
    }
  }

• src/mcpServer.ts:76-178 (registration)

  Registers the 'execute_dql' MCP tool, including input schema, description, and the wrapper handler function that applies guards, resolves config, calls executeDql, and formats the MCP response.

  server.registerTool(
    'execute_dql',
    {
      title: 'Ditto: Execute DQL query',
      description: 'Runs a query in Ditto using a parameterized DQL statement',
      inputSchema: executeInput,
    },
    async ({
      statement,
      args,
      transactionId,
      apiKey,
      baseUrl,
      timeoutMs,
    }: ExecuteToolInput) => {
      // Guard the statement & allowed operations
      const cleaned = ensureSingleStatement(statement);
      const op = detectOperation(cleaned);
      if (op === 'UNKNOWN') {
        return {
          isError: true,
          content: [
            {
              type: 'text',
              text: 'Statement must start with SELECT/INSERT/UPDATE/DELETE/EVICT.',
            },
          ],
        };
      }
      try {
        assertAllowedOperation(op, cfg.allowedOps);
        assertAllowPatternsIfAny(cleaned, cfg.queryAllowPatterns);
      } catch (e) {
        const message = e instanceof GuardError ? e.message : String(e);
        return { isError: true, content: [{ type: 'text', text: message }] };
      }
  
      // Resolve base URL & key
      const url = baseUrl ?? cfg.dittoBaseUrl;
      if (!url) {
        return {
          isError: true,
          content: [
            {
              type: 'text',
              text: 'DITTO_BASE_URL not set. Pass baseUrl or set env DITTO_BASE_URL.',
            },
          ],
        };
      }
      const envKey = process.env[cfg.apiKeyEnvVar];
      const key = apiKey || envKey;
      if (!key) {
        return {
          isError: true,
          content: [
            {
              type: 'text',
              text: `No API key. Set env ${cfg.apiKeyEnvVar} or pass apiKey.`,
            },
          ],
        };
      }
  
      // Call Ditto
      const res = await executeDql(
        { statement: cleaned, args: args ?? undefined },
        {
          baseUrl: url,
          apiKey: key,
          transactionId,
          timeoutMs: timeoutMs ?? cfg.timeoutMs,
        },
      );
  
      if (res.error?.description) {
        return {
          isError: true,
          content: [{ type: 'text', text: `Ditto error: ${res.error.description}` }],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                transactionId: res.transactionId,
                queryType: res.queryType,
                items: res.items,
                mutatedDocumentIds: res.mutatedDocumentIds,
                warnings: res.warnings,
                totalWarningsCount: res.totalWarningsCount,
              },
              null,
              2,
            ),
          },
        ],
      };
    },
  );

• src/mcpServer.ts:37-66 (schema)

  Zod schema defining the input parameters for the 'execute_dql' tool.

  const executeInput = {
    statement: z
      .string()
      .min(1)
      .describe("DQL statement to execute (single statement; no trailing ';')"),
    args: z.record(z.unknown()).optional().describe('Named parameters for the DQL'),
    transactionId: z
      .number()
      .int()
      .nonnegative()
      .optional()
      .describe('Optional X-DITTO-TXN-ID for consistency'),
    apiKey: z
      .string()
      .min(1)
      .optional()
      .describe('Ditto API key (prefer env over passing here)'),
    baseUrl: z
      .string()
      .url()
      .optional()
      .describe('Overrides DITTO_BASE_URL for this call'),
    timeoutMs: z
      .number()
      .int()
      .positive()
      .max(60000)
      .optional()
      .describe('Per-call timeout override (ms)'),
  };

• src/ditto/types.ts:1-24 (schema)

  TypeScript type definitions for ExecuteRequest, ExecuteOptions, and DittoResponse used by the executeDql handler.

  export type DittoQueryArgs = Record<string, unknown>;
  
  export type ExecuteRequest = {
    statement: string;
    args?: DittoQueryArgs;
  };
  
  export type DittoResponse = {
    transactionId?: number;
    queryType: string; // "select" | "insert" | "update" | ...
    items: unknown[];
    mutatedDocumentIds: unknown[];
    warnings: { _id?: unknown; description: string }[];
    totalWarningsCount: number;
    error?: { description?: string };
  };
  
  export type ExecuteOptions = {
    baseUrl: string; // canonical root, e.g. https://APP.cloud.ditto.live
    apiKey: string; // Ditto API key (Authorization: Bearer ...)
    timeoutMs?: number;
    transactionId?: number; // optional X-DITTO-TXN-ID
  };

• src/guards/dql.ts:1-46 (helper)

  Helper functions for DQL statement validation and guarding: single-statement enforcement, operation detection, allowed ops/patterns checks. Used in the tool handler.

  import type { DqlOp } from '../config.js';
  
  export class GuardError extends Error {
    status = 400;
    constructor(message: string, status = 400) {
      super(message);
      this.status = status;
    }
  }
  
  /** Remove trailing semicolons and ensure a single statement. */
  export function ensureSingleStatement(statement: string): string {
    const cleaned = statement.replace(/;+\s*$/, '').trim();
    if (!cleaned) throw new GuardError('DQL statement cannot be empty');
    if (cleaned.includes(';'))
      throw new GuardError('Multiple DQL statements are not allowed');
    return cleaned;
  }
  
  /** Very small lexer: strip block/line comments, then return first token uppercased. */
  export function detectOperation(statement: string): DqlOp | 'UNKNOWN' {
    const noBlock = statement.replace(/\/\*[\s\S]*?\*\//g, ' ');
    const noLine = noBlock.replace(/--.*$/gm, ' ').replace(/#[^\n]*$/gm, ' ');
    const firstToken = noLine.trim().split(/\s+/)[0]?.toUpperCase();
    const ops = new Set(['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'EVICT']);
    return firstToken && ops.has(firstToken) ? (firstToken as DqlOp) : 'UNKNOWN';
  }
  
  export function assertAllowedOperation(op: DqlOp, allowed: Set<DqlOp>) {
    if (!allowed.has(op)) {
      const allowedList = [...allowed].join(', ');
      throw new GuardError(
        `Operation "${op}" is disabled. Allowed operations: ${allowedList}`,
        403,
      );
    }
  }
  
  export function assertAllowPatternsIfAny(statement: string, allowPatterns: RegExp[]) {
    if (allowPatterns.length === 0) return;
    const ok = allowPatterns.some((rx) => rx.test(statement));
    if (!ok) {
      throw new GuardError('Statement does not match any allowed pattern (policy).', 403);
    }
  }