@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/src/dsl/usage-policy.ts

@@ -0,0 +1,219 @@
+/**
+ * Dimensions reasonable-use policy guardrails for MCP tools.
+ * @see https://docs.dimensions.ai/dsl/usagepolicy.html
+ * @module dsl/usage-policy
+ */
+
+import { ValidationError } from "../client/index.js";
+import {
+  CONFIRM_LARGE_FETCH_PAGES,
+  CONFIRM_LARGE_FETCH_RECORDS,
+  LARGE_RESULT_THRESHOLD,
+  largeResultWarning,
+  validatePaginationBounds,
+} from "./pagination.js";
+import { SCHEMA_LIMITS } from "./schema/store.js";
+
+/** Official Dimensions usage policy URL. */
+export const USAGE_POLICY_URL = "https://docs.dimensions.ai/dsl/usagepolicy.html";
+
+/** MCP resource URI for policy guidance. */
+export const USAGE_POLICY_RESOURCE_URI = "dimensions://schema/policy";
+
+/** Short notice included in guarded tool responses. */
+export const POLICY_NOTICE =
+  "Dimensions API is for task-sized analytical queries, not bulk local copies or training data. " +
+  `See ${USAGE_POLICY_RESOURCE_URI} and ${USAGE_POLICY_URL}.`;
+
+/** Parsed skip/limit modifiers from a DSL query string. */
+export type DslPaginationModifiers = {
+  readonly limit?: number;
+  readonly skip?: number;
+};
+
+/** Payload for dimensions://schema/policy. */
+export type UsagePolicyPayload = {
+  readonly source: string;
+  readonly purpose: string;
+  readonly limits: typeof SCHEMA_LIMITS;
+  readonly guardrails: {
+    readonly largeResultWarningThreshold: number;
+    readonly confirmLargeFetchRequiredWhen: {
+      readonly batchMaxPagesExceeds: number;
+      readonly batchRecordsExceeds: number;
+      readonly searchSkipAtLeast: number;
+      readonly searchPageAtLeast: number;
+    };
+    readonly clientRateLimitPerMinute: number;
+  };
+  readonly recommendations: readonly string[];
+  readonly notice: string;
+};
+
+/**
+ * Builds the usage policy payload for MCP resources and agent discovery.
+ * @returns Policy guidance object
+ */
+export function buildUsagePolicy(): UsagePolicyPayload {
+  return {
+    source: USAGE_POLICY_URL,
+    purpose:
+      "Support complex analytical tasks — not local copies of Dimensions data, training corpora, or open-ended crawling.",
+    limits: SCHEMA_LIMITS,
+    guardrails: {
+      largeResultWarningThreshold: LARGE_RESULT_THRESHOLD,
+      confirmLargeFetchRequiredWhen: {
+        batchMaxPagesExceeds: CONFIRM_LARGE_FETCH_PAGES,
+        batchRecordsExceeds: CONFIRM_LARGE_FETCH_RECORDS,
+        searchSkipAtLeast: CONFIRM_LARGE_FETCH_RECORDS,
+        searchPageAtLeast: CONFIRM_LARGE_FETCH_PAGES,
+      },
+      clientRateLimitPerMinute: SCHEMA_LIMITS.requestsPerMinute,
+    },
+    recommendations: [
+      "Start with narrow filters and facet_query before paginating large sets",
+      "Use search_* with default limit 100 for discovery; raise only when needed",
+      "Use fetch_search_pages aggregate mode for ID lists and counts without full rows",
+      "Use fetch_search_pages file mode (JSONL or CSV) only with outputPath and confirmLargeFetch for large exports",
+      "Facets return at most 1000 buckets with no pagination — do not loop facet queries",
+    ],
+    notice: POLICY_NOTICE,
+  };
+}
+
+/**
+ * Extracts `limit` and `skip` modifiers from a DSL query string.
+ * @param dsl - Raw DSL query
+ * @returns Parsed modifiers (undefined when absent)
+ */
+export function parseDslPagination(dsl: string): DslPaginationModifiers {
+  const limitMatch = dsl.match(/\blimit\s+(\d+)\b/i);
+  const skipMatch = dsl.match(/\bskip\s+(\d+)\b/i);
+  return {
+    ...(limitMatch ? { limit: Number.parseInt(limitMatch[1], 10) } : {}),
+    ...(skipMatch ? { skip: Number.parseInt(skipMatch[1], 10) } : {}),
+  };
+}
+
+/**
+ * Returns true when the DSL appears to be a facet-only query (no entity row pagination).
+ * @param dsl - Raw DSL query
+ * @returns Whether the query targets facets without entity records
+ */
+export function isFacetOnlyQuery(dsl: string): boolean {
+  const hasFacetReturn =
+    /\breturn\s+(?:year|journal|funder|researcher|category|phase|source|repository|funder_orgs?)\b/i.test(
+      dsl,
+    ) ||
+    /\breturn\s+\w+\s+facet\b/i.test(dsl) ||
+    /\bfacet\s+\w+/i.test(dsl);
+  const hasEntityReturn =
+    /\breturn\s+(?:publications|grants|patents|clinical_trials|datasets|policy_documents|researchers|organizations)\b/i.test(
+      dsl,
+    );
+  const limitZero = /\blimit\s+0\b/i.test(dsl);
+  return hasFacetReturn && (!hasEntityReturn || limitZero);
+}
+
+/** Options for single-page search policy validation. */
+export type SearchPolicyOptions = {
+  readonly skip: number;
+  readonly limit: number;
+  readonly confirmLargeFetch?: boolean;
+};
+
+/**
+ * Validates single-page search pagination against reasonable-use guardrails.
+ * @param options - Resolved skip/limit and optional confirmation flag
+ * @throws {ValidationError} When deep pagination lacks confirmation
+ */
+export function validateSearchPaginationPolicy(options: SearchPolicyOptions): void {
+  const { skip, limit, confirmLargeFetch } = options;
+  const page = limit > 0 ? Math.floor(skip / limit) : 0;
+
+  const needsConfirm =
+    skip >= CONFIRM_LARGE_FETCH_RECORDS ||
+    page >= CONFIRM_LARGE_FETCH_PAGES ||
+    (limit === SCHEMA_LIMITS.maxLimit && skip > 0);
+
+  if (needsConfirm && !confirmLargeFetch) {
+    throw new ValidationError(
+      `Deep pagination requires confirmLargeFetch: true (skip=${skip}, limit=${limit}, page≈${page}). ` +
+        "Narrow filters first or use facet_query. See dimensions://schema/policy.",
+      { skip, limit, page, confirmLargeFetch, policyUri: USAGE_POLICY_RESOURCE_URI },
+    );
+  }
+}
+
+/** Options for raw DSL policy validation. */
+export type ExecuteDslPolicyOptions = {
+  readonly dsl: string;
+  readonly confirmLargeFetch?: boolean;
+};
+
+/**
+ * Validates a raw DSL query against pagination and reasonable-use guardrails.
+ * @param options - DSL string and optional confirmation flag
+ * @throws {ValidationError} When the query violates policy bounds
+ */
+export function validateExecuteDslPolicy(options: ExecuteDslPolicyOptions): void {
+  const { dsl, confirmLargeFetch } = options;
+  const { limit, skip } = parseDslPagination(dsl);
+
+  if (isFacetOnlyQuery(dsl) && skip !== undefined && skip > 0) {
+    throw new ValidationError(
+      "Facet queries cannot be paginated with skip — facets return at most 1000 buckets with no pagination.",
+      { skip, policyUri: USAGE_POLICY_RESOURCE_URI },
+    );
+  }
+
+  if (skip !== undefined || limit !== undefined) {
+    validatePaginationBounds(skip ?? 0, limit ?? SCHEMA_LIMITS.maxLimit);
+    validateSearchPaginationPolicy({
+      skip: skip ?? 0,
+      limit: limit ?? 100,
+      confirmLargeFetch,
+    });
+  }
+}
+
+/**
+ * Builds response-level policy hints for execute_dsl results.
+ * @param dsl - Executed DSL query
+ * @param response - Raw API response
+ * @returns Optional policy fields to merge into the tool result
+ */
+export function buildExecuteDslPolicyHints(
+  dsl: string,
+  response: Record<string, unknown>,
+): {
+  policyNotice?: string;
+  largeResultWarning?: string;
+  paginationHint?: string;
+} {
+  const stats = response._stats as { total_count?: number } | undefined;
+  const totalCount = stats?.total_count;
+  const hints: {
+    policyNotice?: string;
+    largeResultWarning?: string;
+    paginationHint?: string;
+  } = {};
+
+  const warning = totalCount !== undefined ? largeResultWarning(totalCount) : undefined;
+  if (warning) {
+    hints.largeResultWarning = warning;
+    hints.policyNotice = POLICY_NOTICE;
+  }
+
+  const { limit, skip } = parseDslPagination(dsl);
+  if (totalCount !== undefined && limit !== undefined && totalCount > (skip ?? 0) + limit) {
+    const pages = Math.ceil(totalCount / limit);
+    const minutes = Math.ceil(pages / SCHEMA_LIMITS.requestsPerMinute);
+    hints.paginationHint =
+      `${totalCount} total matches; this page returned up to ${limit}. ` +
+      `Full pagination ≈${pages} requests (~${minutes} min). Prefer search_* or fetch_search_pages.`;
+    hints.policyNotice ??= POLICY_NOTICE;
+  }
+
+  return hints;
+}

package/src/dsl/utils/escape.ts

@@ -0,0 +1,123 @@
+/**
+ * Escapes a string for safe inclusion in a DSL query.
+ *
+ * Handles backslashes, double quotes (including Unicode smart quotes),
+ * and control characters to prevent DSL injection attacks when
+ * user-supplied strings are interpolated into queries.
+ *
+ * Characters escaped via `\uXXXX` (ANTLR grammar-compatible):
+ * - Null byte and C0 controls (U+0000–U+001F) not covered by named escapes
+ * - DEL and C1 controls (U+007F–U+009F)
+ * - Smart single quotes (U+2018, U+2019)
+ * - Line and paragraph separators (U+2028, U+2029)
+ *
+ * @param text - The string to escape
+ * @returns The escaped string safe for DSL interpolation
+ */
+export function escapeDslString(text: string): string {
+  let result = "";
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    switch (ch) {
+      case "\\":
+        result += "\\\\";
+        break;
+      case '"':
+        result += '\\"';
+        break;
+      case "\u201c":
+        result += "\\\u201c";
+        break;
+      case "\u201d":
+        result += "\\\u201d";
+        break;
+      case "\n":
+        result += "\\n";
+        break;
+      case "\t":
+        result += "\\t";
+        break;
+      case "\r":
+        result += "\\r";
+        break;
+      case "\b":
+        result += "\\b";
+        break;
+      case "\f":
+        result += "\\f";
+        break;
+      default: {
+        const code = ch.charCodeAt(0);
+        if (
+          code <= 0x001f ||
+          (code >= 0x007f && code <= 0x009f) ||
+          code === 0x2018 ||
+          code === 0x2019 ||
+          code === 0x2028 ||
+          code === 0x2029
+        ) {
+          result += `\\u${code.toString(16).padStart(4, "0")}`;
+        } else {
+          result += ch;
+        }
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Unescapes DSL string literal content (inverse of {@link escapeDslString} for common sequences).
+ * @param text - Escaped string content without surrounding quotes
+ * @returns Unescaped string
+ */
+export function unescapeDslString(text: string): string {
+  if (!text.includes("\\")) return text;
+
+  let result = "";
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\\" && i + 1 < text.length) {
+      const next = text[i + 1];
+      switch (next) {
+        case '"':
+        case "\\":
+        case "n":
+          result += next === "n" ? "\n" : next;
+          i++;
+          break;
+        case "t":
+          result += "\t";
+          i++;
+          break;
+        case "r":
+          result += "\r";
+          i++;
+          break;
+        case "b":
+          result += "\b";
+          i++;
+          break;
+        case "f":
+          result += "\f";
+          i++;
+          break;
+        case "u": {
+          const hex = text.slice(i + 2, i + 6);
+          if (hex.length === 4 && /^[0-9a-fA-F]{4}$/.test(hex)) {
+            result += String.fromCharCode(Number.parseInt(hex, 16));
+            i += 5;
+          } else {
+            result += "\\";
+          }
+          break;
+        }
+        default:
+          result += "\\";
+          break;
+      }
+    } else {
+      result += text[i];
+    }
+  }
+  return result;
+}

package/src/dsl/utils/sanitize.ts

@@ -0,0 +1,21 @@
+/**
+ * Input sanitization for DSL query construction.
+ * @module utils/sanitize
+ */
+
+/** Maximum allowed length for search text within a `for "..."` clause. */
+export const MAX_SEARCH_TEXT_LENGTH = 10_000;
+
+const ZERO_WIDTH_RE = /[\u00AD\u180E\u200B-\u200F\u2028\u2029\uFEFF\u2060-\u2064]/g;
+
+/**
+ * Normalizes user search text before embedding in DSL.
+ * @param text - Raw input text
+ * @returns Sanitized text
+ */
+export function sanitizeInput(text: string): string {
+  return text
+    .normalize("NFC")
+    .replace(ZERO_WIDTH_RE, "")
+    .replace(/[\u201c\u201d]/g, '"');
+}

package/src/dsl/utils/string-utils.ts

@@ -0,0 +1,147 @@
+/**
+ * String manipulation utilities for DSL quoting and escape sequences.
+ * @module utils/string-utils
+ */
+
+/**
+ * Strips the first and last character from a quoted string token.
+ * @param text - The raw STRING token text including quotes
+ * @returns The unquoted string content
+ */
+export function stripQuotes(text: string): string {
+  return unescapeString(text.slice(1, -1));
+}
+
+/**
+ * Strips triple quotes from a LONG_STRING token.
+ * @param text - The raw LONG_STRING token text including triple quotes
+ * @returns The unquoted string content
+ */
+export function stripTripleQuotes(text: string): string {
+  return unescapeString(text.slice(3, -3));
+}
+
+/**
+ * Processes escape sequences in a DSL string.
+ * @param text - The string content (without outer quotes)
+ * @returns The unescaped string
+ */
+export function unescapeString(text: string): string {
+  if (!text.includes("\\")) return text;
+
+  let result = "";
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\\" && i + 1 < text.length) {
+      const next = text[i + 1];
+      switch (next) {
+        case '"':
+        case "\u201c":
+        case "\u201d":
+        case "\\":
+        case "/":
+        case "^":
+        case "*":
+        case "?":
+        case ":":
+        case "~":
+        case "[":
+        case "]":
+        case "{":
+        case "}":
+        case "(":
+        case ")":
+        case "!":
+        case "|":
+        case "&":
+        case "+":
+        case "-":
+          result += next;
+          i++;
+          break;
+        case "n":
+          result += "\n";
+          i++;
+          break;
+        case "t":
+          result += "\t";
+          i++;
+          break;
+        case "r":
+          result += "\r";
+          i++;
+          break;
+        case "b":
+          result += "\b";
+          i++;
+          break;
+        case "f":
+          result += "\f";
+          i++;
+          break;
+        case "u": {
+          const hex = text.slice(i + 2, i + 6);
+          if (hex.length === 4 && /^[0-9a-fA-F]{4}$/.test(hex)) {
+            result += String.fromCharCode(Number.parseInt(hex, 16));
+            i += 5;
+          } else {
+            result += "\\";
+          }
+          break;
+        }
+        default:
+          result += "\\";
+          break;
+      }
+    } else {
+      result += text[i];
+    }
+  }
+  return result;
+}
+
+/**
+ * Escapes special characters in a string for DSL output.
+ * @param text - The raw string content
+ * @returns The escaped string (without surrounding quotes)
+ */
+export function escapeString(text: string): string {
+  let result = "";
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    switch (ch) {
+      case "\\":
+        result += "\\\\";
+        break;
+      case '"':
+        result += '\\"';
+        break;
+      case "\n":
+        result += "\\n";
+        break;
+      case "\t":
+        result += "\\t";
+        break;
+      case "\r":
+        result += "\\r";
+        break;
+      case "\b":
+        result += "\\b";
+        break;
+      case "\f":
+        result += "\\f";
+        break;
+      default:
+        result += ch;
+    }
+  }
+  return result;
+}
+
+/**
+ * Wraps a string in double quotes after escaping special characters.
+ * @param text - The raw string content
+ * @returns The quoted and escaped string
+ */
+export function quoteString(text: string): string {
+  return `"${escapeString(text)}"`;
+}

package/src/dsl/utils/validate-field-name.ts

@@ -0,0 +1,19 @@
+import { ValidationError } from "../../client/index.js";
+
+/** Regex for valid DSL field names: letters, digits, underscores, dots. */
+const FIELD_NAME_RE = /^[a-z_][a-z0-9_.]*$/i;
+
+/**
+ * Validates a DSL field name to prevent injection via field interpolation.
+ * Valid names start with a letter or underscore and contain only letters,
+ * digits, underscores, and dots (for nested fields like `authors.first_name`).
+ *
+ * @param field - The field name to validate
+ * @returns void
+ * @throws {ValidationError} If the field name contains invalid characters
+ */
+export function validateFieldName(field: string): void {
+  if (!FIELD_NAME_RE.test(field)) {
+    throw new ValidationError(`Invalid field name: ${field}`);
+  }
+}

package/src/http-main.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * HTTP MCP server entry for hosted deployment (Streamable HTTP at /mcp).
+ * @module http-main
+ */
+
+import { loadDeploymentConfig } from "./client/deployment-config.js";
+import { startHostedHttpServer } from "./mcp/http-server.js";
+
+const deployment = loadDeploymentConfig();
+if (deployment.deploymentMode !== "hosted") {
+  console.error("http-main requires DEPLOYMENT_MODE=hosted");
+  process.exit(1);
+}
+
+const { close, ready } = startHostedHttpServer({
+  hosted: deployment,
+  port: deployment.httpPort,
+});
+
+ready
+  .then((port) => {
+    console.error(`Dimensions Analytics MCP HTTP server listening on port ${port}`);
+  })
+  .catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Failed to start HTTP server: ${message}`);
+    process.exit(1);
+  });
+
+async function shutdown(): Promise<void> {
+  await close();
+  process.exit(0);
+}
+
+process.on("SIGTERM", () => {
+  void shutdown();
+});
+process.on("SIGINT", () => {
+  void shutdown();
+});

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @digital-science-dsl/dimensions-analytics-mcp - Dimensions Analytics MCP server for Dimensions Analytics API.
+ * @module @digital-science-dsl/dimensions-analytics-mcp
+ */
+
+export type { SchemaStore } from "./dsl/schema/index.js";
+export type { SchemaContext } from "./mcp/schema/context.js";
+export {
+  createMcpServerAsync,
+  type McpServerConfig,
+  type McpServerHandle,
+  startMcpServer,
+} from "./mcp/server.js";
+export { type McpLogLevel, mcpLog } from "./mcp/utils.js";

package/src/main.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * MCP server entry point.
+ * Starts the Dimensions Analytics MCP server with stdio transport.
+ * @module main
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServerAsync } from "./mcp/server.js";
+
+let close: () => Promise<void>;
+
+try {
+  const { server } = await createMcpServerAsync();
+
+  const transport = new StdioServerTransport();
+
+  server.server.onerror = (error: Error) => console.error(`MCP server error: ${error.message}`);
+  server.server.onclose = () => {
+    process.exit(0);
+  };
+
+  await server.connect(transport);
+
+  close = async () => {
+    await server.close();
+  };
+} catch (error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Failed to start MCP server: ${message}`);
+  process.exit(1);
+}
+
+const shutdown = async () => {
+  await close();
+  process.exit(0);
+};
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);