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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@digital-science-dsl/dimensions-analytics-mcp",
+  "version": "0.5.3",
+  "description": "Dimensions Analytics MCP server for Dimensions DSL querying",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "dimensions-analytics-mcp": "bin/dimensions-analytics-mcp.js",
+    "dimensions-analytics-mcp-http": "bin/dimensions-analytics-mcp-http.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "fast-check": "^4.6.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/digital-science/dimensions-analytics-mcp.git",
+    "directory": "apps/mcp"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs');for (const f of ['dist/main.js','dist/http-main.js','bin/dimensions-analytics-mcp.js','bin/dimensions-analytics-mcp-http.js']) { if (!fs.existsSync(f)) continue; const c=fs.readFileSync(f,'utf8'); if (!c.startsWith('#!')) fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c); }\" && chmod +x dist/main.js dist/http-main.js bin/dimensions-analytics-mcp.js bin/dimensions-analytics-mcp-http.js",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/client/auth/config-loaders.ts

@@ -0,0 +1,81 @@
+/**
+ * Configuration loaders for JWT AuthConfig.
+ * @module client/auth/config-loaders
+ */
+
+import { readFileSync } from "node:fs";
+import { ValidationError } from "../errors.js";
+import { JwtAuthConfigSchema } from "./schemas.js";
+import type { AuthConfig, JwtAuthConfig } from "./types.js";
+
+/** Options for loading config from environment variables. */
+export interface FromEnvOptions {
+  /** Env prefix (default `DIMENSIONS` → `DIMENSIONS_API_KEY`) */
+  prefix?: string;
+}
+
+/**
+ * Load JWT auth config from environment variables.
+ * @param type - Must be `"jwt"`
+ * @param options - Optional env prefix
+ * @returns Validated JwtAuthConfig
+ */
+export function fromEnv(type: "jwt", options?: FromEnvOptions): JwtAuthConfig {
+  if (type !== "jwt") {
+    throw new ValidationError("Only JWT auth is supported");
+  }
+
+  const envPrefix = options?.prefix ?? "DIMENSIONS";
+  const apiKey = process.env[`${envPrefix}_API_KEY`];
+  if (!apiKey) {
+    throw new ValidationError(`Missing required environment variable: ${envPrefix}_API_KEY`);
+  }
+
+  const authUrl = process.env[`${envPrefix}_AUTH_URL`];
+  const tokenCacheDuration = process.env[`${envPrefix}_TOKEN_CACHE_DURATION`];
+  const timeout = process.env[`${envPrefix}_TIMEOUT`];
+
+  return {
+    type: "jwt",
+    apiKey,
+    ...(authUrl && { authUrl }),
+    ...(tokenCacheDuration && {
+      tokenCacheDuration: Number.parseInt(tokenCacheDuration, 10),
+    }),
+    ...(timeout && { timeout: Number.parseInt(timeout, 10) }),
+  };
+}
+
+/** Load JWT auth config from a JSON file. */
+export function fromPath(filePath: string): AuthConfig {
+  let fileContent: string;
+  try {
+    fileContent = readFileSync(filePath, "utf-8");
+  } catch (error) {
+    throw new ValidationError(`Failed to read config file: ${filePath}`, {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fileContent);
+  } catch (error) {
+    throw new ValidationError(`Invalid JSON in config file: ${filePath}`, {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  return fromObject(parsed);
+}
+
+/** Validate and return JWT auth config from an object. */
+export function fromObject(obj: unknown): AuthConfig {
+  const parseResult = JwtAuthConfigSchema.safeParse(obj);
+  if (!parseResult.success) {
+    throw new ValidationError(`Invalid auth configuration: ${parseResult.error.message}`, {
+      issues: parseResult.error.issues,
+    });
+  }
+  return parseResult.data;
+}

package/src/client/auth/decorators/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Auth provider decorators.
+ * @module core/auth/decorators
+ */
+
+export type { CachingOptions } from "./with-caching.js";
+export { withCaching } from "./with-caching.js";

package/src/client/auth/decorators/with-caching.ts

@@ -0,0 +1,237 @@
+/**
+ * Caching decorator for AuthProvider.
+ * @module core/auth/decorators/with-caching
+ */
+
+import type { AuthConfig, AuthProvider } from "../types.js";
+
+/**
+ * Configuration options for the caching decorator.
+ */
+export interface CachingOptions {
+  /**
+   * Cache duration in milliseconds.
+   * Headers will be refreshed after this time.
+   * @default 3600000 (1 hour)
+   */
+  cacheDurationMs?: number;
+
+  /**
+   * Buffer before expiry to trigger refresh, as a decimal (0-1).
+   * E.g., 0.1 means refresh when 90% of TTL has passed.
+   * @default 0.1
+   */
+  expiryBuffer?: number;
+
+  /**
+   * Initial backoff delay in milliseconds after a failed fetch.
+   * Grows exponentially on consecutive failures up to {@link failureBackoffMaxMs}.
+   * @default 1000
+   */
+  failureBackoffMs?: number;
+
+  /**
+   * Maximum backoff delay in milliseconds. Caps exponential growth.
+   * @default 60000
+   */
+  failureBackoffMaxMs?: number;
+
+  /**
+   * Multiplication factor applied to the base delay on each consecutive failure.
+   * Set to 1 for flat (non-exponential) backoff.
+   * @default 2
+   */
+  failureBackoffFactor?: number;
+
+  /**
+   * Jitter as a fraction of the computed delay (0–1), e.g. 0.1 = ±10%.
+   * Prevents thundering herd by spreading retry times across clients.
+   * Set to 0 for deterministic delays (useful in tests).
+   * @default 0.1
+   */
+  failureBackoffJitter?: number;
+}
+
+/** Default cache duration: 1 hour */
+const DEFAULT_CACHE_DURATION_MS = 3600000;
+
+/** Default expiry buffer: 10% */
+const DEFAULT_EXPIRY_BUFFER = 0.1;
+
+/** Default failure backoff: 1 second */
+const DEFAULT_FAILURE_BACKOFF_MS = 1000;
+
+/** Default max backoff delay: 60 seconds */
+const DEFAULT_FAILURE_BACKOFF_MAX_MS = 60_000;
+
+/** Default backoff multiplication factor */
+const DEFAULT_FAILURE_BACKOFF_FACTOR = 2;
+
+/** Default jitter fraction: ±10% */
+const DEFAULT_FAILURE_BACKOFF_JITTER = 0.1;
+
+/**
+ * Wraps an AuthProvider with caching behavior.
+ *
+ * Features:
+ * - Caches getHeaders() results with configurable TTL
+ * - Deduplicates concurrent calls (reuses in-flight promise)
+ * - Calls underlying provider's getHeaders() when cache expires
+ * - Propagates errors (no stale fallback)
+ * - Implements exponential backoff with jitter after failures to prevent thundering herd
+ *
+ * @param provider - The AuthProvider to wrap
+ * @param options - Caching configuration
+ * @returns A new AuthProvider with caching behavior
+ *
+ * @example
+ * ```typescript
+ * const baseProvider = new JwtAuthProvider(config);
+ * const cachedProvider = withCaching(baseProvider, {
+ *   cacheDurationMs: 3600000,    // 1 hour
+ *   expiryBuffer: 0.1,           // Refresh at 90% of TTL
+ *   failureBackoffMs: 1000,      // Initial backoff: 1s
+ *   failureBackoffMaxMs: 60000,  // Cap at 60s
+ *   failureBackoffFactor: 2,     // Double each failure: 1s, 2s, 4s, 8s...
+ *   failureBackoffJitter: 0.1,   // ±10% jitter
+ * });
+ *
+ * // First call fetches headers
+ * const headers1 = await cachedProvider.getHeaders();
+ *
+ * // Subsequent calls return cached value
+ * const headers2 = await cachedProvider.getHeaders();
+ * ```
+ */
+export function withCaching(provider: AuthProvider, options?: CachingOptions): AuthProvider {
+  const cacheDurationMs = options?.cacheDurationMs ?? DEFAULT_CACHE_DURATION_MS;
+  const expiryBuffer = options?.expiryBuffer ?? DEFAULT_EXPIRY_BUFFER;
+  const failureBackoffMs = options?.failureBackoffMs ?? DEFAULT_FAILURE_BACKOFF_MS;
+  const failureBackoffMaxMs = options?.failureBackoffMaxMs ?? DEFAULT_FAILURE_BACKOFF_MAX_MS;
+  const failureBackoffFactor = options?.failureBackoffFactor ?? DEFAULT_FAILURE_BACKOFF_FACTOR;
+  const failureBackoffJitter = options?.failureBackoffJitter ?? DEFAULT_FAILURE_BACKOFF_JITTER;
+
+  let cachedHeaders: Record<string, string> | null = null;
+  let cacheExpiry = 0;
+  let refreshPromise: Promise<Record<string, string>> | null = null;
+  let failureCount = 0;
+  let backoffDeadline = 0;
+
+  /**
+   * Calculate the effective expiry time with buffer.
+   * @param durationMs - Full cache duration
+   * @returns Expiry timestamp with buffer applied
+   */
+  const calculateExpiry = (durationMs: number): number => {
+    // Buffer is at least 1 minute, but never more than 90% of duration
+    const bufferMs = Math.min(Math.max(durationMs * expiryBuffer, 60000), durationMs * 0.9);
+    return Date.now() + durationMs - bufferMs;
+  };
+
+  /**
+   * Calculates the backoff delay for a given consecutive failure count.
+   * Uses exponential backoff with multiplicative jitter.
+   * @param count - Number of consecutive failures (must be >= 1)
+   * @returns Delay in milliseconds
+   */
+  const calculateBackoffDelay = (count: number): number => {
+    const base = Math.min(
+      failureBackoffMs * failureBackoffFactor ** (count - 1),
+      failureBackoffMaxMs,
+    );
+    const jittered = base * (1 + (Math.random() - 0.5) * 2 * failureBackoffJitter);
+    return Math.max(0, jittered);
+  };
+
+  /**
+   * Check if we're in a backoff period after a failure.
+   * @returns True if still in backoff period
+   */
+  const isInBackoffPeriod = (): boolean => {
+    if (backoffDeadline === 0) return false;
+    return Date.now() < backoffDeadline;
+  };
+
+  /**
+   * Fetch fresh headers from the underlying provider.
+   *
+   * Calls getHeaders() directly rather than refresh() + getHeaders().
+   * The provider's getHeaders() is self-sufficient (fetches a token when
+   * needed), so an explicit refresh() is unnecessary and creates a race
+   * window where invalidate() between the two calls triggers a redundant
+   * token fetch.
+   *
+   * @returns Fresh headers
+   */
+  const fetchHeaders = async (): Promise<Record<string, string>> => {
+    try {
+      const headers = await provider.getHeaders();
+      cachedHeaders = headers;
+      cacheExpiry = calculateExpiry(cacheDurationMs);
+      failureCount = 0;
+      backoffDeadline = 0;
+      return headers;
+    } catch (error) {
+      failureCount += 1;
+      backoffDeadline = Date.now() + calculateBackoffDelay(failureCount);
+      throw error;
+    }
+  };
+
+  const wrapper = {
+    get type(): AuthConfig["type"] {
+      return provider.type;
+    },
+
+    async initialize(): Promise<void> {
+      await provider.initialize();
+    },
+
+    async getHeaders(): Promise<Record<string, string>> {
+      // Return cached headers if valid
+      if (cachedHeaders && Date.now() < cacheExpiry) {
+        return cachedHeaders;
+      }
+
+      // If already refreshing, wait for that promise
+      if (refreshPromise) {
+        return refreshPromise;
+      }
+
+      // Check backoff period - if in backoff, rethrow if no cache
+      if (isInBackoffPeriod()) {
+        if (cachedHeaders) {
+          // Return stale cache during backoff rather than failing
+          return cachedHeaders;
+        }
+        // No cache available and in backoff - we must try anyway
+      }
+
+      // Fetch new headers
+      refreshPromise = fetchHeaders();
+      try {
+        return await refreshPromise;
+      } finally {
+        refreshPromise = null;
+      }
+    },
+
+    async refresh(): Promise<void> {
+      cachedHeaders = null;
+      cacheExpiry = 0;
+      failureCount = 0;
+      backoffDeadline = 0;
+      await provider.refresh();
+    },
+
+    invalidate(): void {
+      cachedHeaders = null;
+      cacheExpiry = 0;
+      failureCount = 0;
+      backoffDeadline = 0;
+      provider.invalidate();
+    },
+  };
+
+  return wrapper;
+}

package/src/client/auth/factory.ts

@@ -0,0 +1,34 @@
+/**
+ * Factory function for creating JWT AuthProvider instances.
+ * @module client/auth/factory
+ */
+
+import { ValidationError } from "../errors.js";
+import { withCaching } from "./decorators/index.js";
+import { JwtAuthProvider } from "./providers/jwt-auth-provider.js";
+import { JwtAuthConfigSchema } from "./schemas.js";
+import type { AuthProvider, JwtAuthConfig } from "./types.js";
+
+/** Default token cache duration for JWT: 1 hour */
+const DEFAULT_TOKEN_CACHE_DURATION_MS = 3600000;
+
+/**
+ * Creates a JWT AuthProvider with token caching.
+ * @param config - JWT authentication configuration
+ * @returns Configured AuthProvider instance
+ * @throws {ValidationError} If the configuration is invalid
+ */
+export function createAuthProvider(config: JwtAuthConfig): AuthProvider {
+  const parseResult = JwtAuthConfigSchema.safeParse(config);
+  if (!parseResult.success) {
+    throw new ValidationError(`Invalid auth configuration: ${parseResult.error.message}`, {
+      issues: parseResult.error.issues,
+    });
+  }
+
+  const validConfig = parseResult.data;
+  const jwtProvider = new JwtAuthProvider(validConfig);
+  const cacheDurationMs =
+    (validConfig.tokenCacheDuration ?? 3600) * 1000 || DEFAULT_TOKEN_CACHE_DURATION_MS;
+  return withCaching(jwtProvider, { cacheDurationMs });
+}

package/src/client/auth/index.ts

@@ -0,0 +1,6 @@
+export { fromEnv, fromObject, fromPath } from "./config-loaders.js";
+export { createAuthProvider } from "./factory.js";
+export { JwtAuthProvider } from "./providers/jwt-auth-provider.js";
+export { AuthResponseSchema, JwtAuthConfigSchema } from "./schemas.js";
+export type { AuthConfig, AuthProvider, JwtAuthConfig } from "./types.js";
+export { isJwtAuthConfig } from "./types.js";

package/src/client/auth/jwt-utils.ts

@@ -0,0 +1,36 @@
+/**
+ * JWT structure validation for Dimensions auth responses.
+ * @module client/auth/jwt-utils
+ */
+
+import { AuthenticationError } from "../errors.js";
+
+const JWT_SEGMENT = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Validates a JWT has three base64url segments.
+ * @param token - Raw token from auth response
+ * @returns The token string
+ * @throws {AuthenticationError} When structure is invalid
+ */
+export function validateJwtStructure(token: unknown): string {
+  if (typeof token !== "string") {
+    throw new AuthenticationError("Invalid token: expected string");
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts.some((part) => !part || !JWT_SEGMENT.test(part))) {
+    throw new AuthenticationError("Invalid JWT structure");
+  }
+  return token;
+}
+
+/**
+ * Decodes the JWT payload (middle segment) without signature verification.
+ * Use only for tokens returned by a trusted auth.json endpoint.
+ */
+export function decodeJwtPayload(token: string): Record<string, unknown> {
+  const validated = validateJwtStructure(token);
+  const payloadSegment = validated.split(".")[1];
+  const json = Buffer.from(payloadSegment, "base64url").toString("utf8");
+  return JSON.parse(json) as Record<string, unknown>;
+}

package/src/client/auth/node.ts

@@ -0,0 +1,16 @@
+/**
+ * Node.js-only auth config loaders.
+ *
+ * These utilities read credentials from the filesystem and environment variables.
+ * They depend on `node:fs` and must not be imported in browser/edge contexts.
+ *
+ * @example
+ * ```typescript
+ * import { fromEnv, fromPath } from "./node.js";
+ * ```
+ *
+ * @module core/auth/node
+ */
+
+export type { FromEnvOptions } from "./config-loaders.js";
+export { fromEnv, fromObject, fromPath } from "./config-loaders.js";

package/src/client/auth/providers/index.ts

@@ -0,0 +1 @@
+export { JwtAuthProvider } from "./jwt-auth-provider.js";

package/src/client/auth/providers/jwt-auth-provider.ts

@@ -0,0 +1,153 @@
+/**
+ * JWT authentication provider for Dimensions API.
+ * @module core/auth/providers/jwt-auth-provider
+ */
+
+import { AuthenticationError, NetworkError, sanitizeErrorMessage } from "../../errors.js";
+import { validateJwtStructure } from "../jwt-utils.js";
+import { AuthResponseSchema } from "../schemas.js";
+import type { AuthProvider, JwtAuthConfig } from "../types.js";
+
+/** Default auth endpoint URL */
+const DEFAULT_AUTH_URL = "https://app.dimensions.ai/api/auth.json";
+
+/** Default request timeout in milliseconds */
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Authentication provider using JWT tokens from Dimensions API.
+ * Exchanges an API key for a short-lived JWT token.
+ *
+ * Note: This provider does NOT cache tokens internally. Use the withCaching()
+ * decorator if caching is needed.
+ *
+ * @example
+ * ```typescript
+ * import { JwtAuthProvider } from "../../index.js";
+ * import { withCaching } from "../../index.js";
+ *
+ * const provider = new JwtAuthProvider({
+ *   type: 'jwt',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Wrap with caching for production use
+ * const cachedProvider = withCaching(provider, {
+ *   cacheDurationMs: 3600000 // 1 hour
+ * });
+ *
+ * const headers = await cachedProvider.getHeaders();
+ * // { Authorization: 'JWT eyJ...' }
+ * ```
+ */
+export class JwtAuthProvider implements AuthProvider {
+  readonly type = "jwt" as const;
+
+  private readonly apiKey: string;
+  private readonly authUrl: string;
+  private readonly timeout: number;
+
+  private currentToken: string | null = null;
+  private initialized = false;
+
+  /**
+   * Creates a new JwtAuthProvider.
+   * @param config - JWT auth configuration
+   */
+  constructor(config: JwtAuthConfig) {
+    this.apiKey = config.apiKey;
+    this.authUrl = config.authUrl ?? DEFAULT_AUTH_URL;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  }
+
+  /**
+   * Initialize the provider by fetching an initial token.
+   * Called automatically on first getHeaders() if not called explicitly.
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+    await this.fetchToken();
+    this.initialized = true;
+  }
+
+  /**
+   * Get the Authorization header with JWT token.
+   * Fetches a new token if not initialized.
+   * @returns Headers object with Authorization header
+   */
+  async getHeaders(): Promise<Record<string, string>> {
+    if (!this.currentToken) {
+      await this.fetchToken();
+    }
+    return {
+      Authorization: `JWT ${this.currentToken}`,
+    };
+  }
+
+  /**
+   * Force refresh of the JWT token by fetching a new one.
+   */
+  async refresh(): Promise<void> {
+    await this.fetchToken();
+  }
+
+  /**
+   * Invalidate the current token, forcing a refresh on next getHeaders().
+   */
+  invalidate(): void {
+    this.currentToken = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Fetches a new JWT token from the auth endpoint.
+   * @throws {AuthenticationError} If authentication fails
+   * @throws {NetworkError} If a network error occurs
+   */
+  private async fetchToken(): Promise<void> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(this.authUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key: this.apiKey }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new AuthenticationError(
+          `Authentication failed: ${response.status} ${response.statusText}`,
+        );
+      }
+
+      const rawData: unknown = await response.json();
+      const parseResult = AuthResponseSchema.safeParse(rawData);
+
+      if (!parseResult.success) {
+        throw new AuthenticationError(
+          `Invalid authentication response: ${parseResult.error.message}`,
+        );
+      }
+
+      // Schema guarantees at least one non-empty token field
+      const rawToken = parseResult.data.token || parseResult.data.access_token;
+      this.currentToken = validateJwtStructure(rawToken);
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError("Authentication request timeout");
+      }
+      throw new NetworkError(`Authentication failed: ${sanitizeErrorMessage(error)}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}

package/src/client/auth/schemas.ts

@@ -0,0 +1,25 @@
+/**
+ * Zod schemas for JWT authentication configuration.
+ * @module client/auth/schemas
+ */
+
+import { z } from "zod";
+
+/** Zod schema for JWT auth configuration. */
+export const JwtAuthConfigSchema = z.object({
+  type: z.literal("jwt"),
+  apiKey: z.string().min(1, "API key is required"),
+  authUrl: z.string().url().optional(),
+  tokenCacheDuration: z.number().positive().optional(),
+  timeout: z.number().positive().optional(),
+});
+
+/** Zod schema for authentication API response. */
+export const AuthResponseSchema = z
+  .object({
+    token: z.string().min(1, "token must be a non-empty string").optional(),
+    access_token: z.string().min(1, "access_token must be a non-empty string").optional(),
+  })
+  .refine((data) => data.token || data.access_token, {
+    message: "Either 'token' or 'access_token' field is required with a non-empty value",
+  });

package/src/client/auth/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Authentication provider types for Dimensions API key → JWT exchange.
+ * @module client/auth/types
+ */
+
+/** Base interface for authentication providers. */
+export interface AuthProvider {
+  readonly type: AuthConfig["type"];
+  initialize(): Promise<void>;
+  getHeaders(): Promise<Record<string, string>>;
+  refresh(): Promise<void>;
+  invalidate(): void;
+}
+
+/** JWT auth configuration (Dimensions API key). */
+export type AuthConfig = JwtAuthConfig;
+
+/** Configuration for JWT-based authentication with Dimensions API. */
+export interface JwtAuthConfig {
+  readonly type: "jwt";
+  readonly apiKey: string;
+  readonly authUrl?: string;
+  readonly tokenCacheDuration?: number;
+  readonly timeout?: number;
+}
+
+/** Type guard for JWT auth configuration. */
+export function isJwtAuthConfig(config: AuthConfig): config is JwtAuthConfig {
+  return config.type === "jwt";
+}