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

package/src/mcp/tools/search.ts

@@ -0,0 +1,168 @@
+/**
+ * Search tools for the MCP server.
+ * Registers `search_{source}` tools from describe schema and shared QueryBuilder handlers.
+ * @module mcp/tools/search
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { DimensionsClient } from "../../dsl/index.js";
+import {
+  applyFilters,
+  type ExtendedWhereFilterInput,
+  parseEntityResponse,
+  resolveSkipAndLimit,
+  type SchemaStore,
+  type StructuredEntityType,
+  searchResultKey,
+  searchToolName,
+  validateSearchPaginationPolicy,
+} from "../../dsl/index.js";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import {
+  formatErrorResult,
+  formatToolResult,
+  READ_ONLY_API_ANNOTATIONS,
+  withSearchPagination,
+} from "../utils.js";
+import { SEARCH_ENTITY_METADATA } from "./search-entity-metadata.js";
+import { PAGINATION_OUTPUT_SCHEMA, SHARED_SEARCH_INPUT } from "./search-input.js";
+
+const metadataBySource = new Map(
+  SEARCH_ENTITY_METADATA.map((meta) => [meta.source, meta] as const),
+);
+
+/**
+ * Builds DSL for a structured search from tool arguments.
+ * @param client - Dimensions client
+ * @param source - Dimensions source name
+ * @param args - Tool arguments (after field-alias resolution)
+ * @returns DSL query string
+ */
+export function buildStructuredSearchDsl(
+  client: DimensionsClient,
+  source: StructuredEntityType,
+  args: Record<string, unknown>,
+): string {
+  const meta = metadataBySource.get(source);
+  const builder = client.createQueryBuilder().search(source);
+
+  if (typeof args.query === "string" && args.query.length > 0) {
+    builder.for(args.query);
+  }
+
+  meta?.applyConvenienceFilters(builder, args);
+
+  const filters = args.filters as ExtendedWhereFilterInput[] | undefined;
+  if (filters?.length) {
+    applyFilters(builder, filters);
+  }
+
+  const fields = args.fields as string[] | undefined;
+  if (fields?.length) {
+    builder.fields(fields);
+  }
+
+  if (typeof args.sortBy === "string") {
+    builder.sort(args.sortBy, "desc");
+  }
+
+  const { skip, limit } = resolveSkipAndLimit({
+    skip: args.skip as number | undefined,
+    page: args.page as number | undefined,
+    limit: args.limit as number | undefined,
+    pageSize: args.pageSize as number | undefined,
+  });
+  builder.limit(limit);
+  if (skip > 0) {
+    builder.skip(skip);
+  }
+
+  return builder.build();
+}
+
+/**
+ * Registers structured search tools for sources present in the schema store.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ * @param schemaStore - Loaded describe schema
+ */
+export function registerSearchTools(
+  server: McpServer,
+  client: DimensionsClient,
+  schemaStore: SchemaStore,
+): void {
+  for (const source of schemaStore.structuredEntityTypes()) {
+    const meta = metadataBySource.get(source);
+    if (!meta) continue;
+
+    const resultKey = searchResultKey(source);
+    const toolName = searchToolName(source);
+
+    server.registerTool(
+      toolName,
+      {
+        description: meta.description,
+        inputSchema: {
+          ...SHARED_SEARCH_INPUT,
+          ...meta.extraInputSchema,
+        },
+        outputSchema: {
+          totalCount: z.number().describe("Total matching records"),
+          returnedCount: z.number().describe("Records returned in this response"),
+          truncated: z
+            .boolean()
+            .optional()
+            .describe("True when more results exist beyond this page"),
+          truncationWarning: z.string().optional().describe("Warning message when truncated"),
+          ...PAGINATION_OUTPUT_SCHEMA,
+          [resultKey]: z.array(z.record(z.string(), z.unknown())).describe("Result records"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+      },
+      withFieldAliases(
+        {
+          entitySource: { kind: "static", entity: source },
+          fieldArrayArgs: ["fields"],
+          fieldStringArgs: ["sortBy"],
+          filterArrayArgs: ["filters"],
+        },
+        async (args) => {
+          try {
+            const record = args as Record<string, unknown>;
+            const { skip, limit } = resolveSkipAndLimit({
+              skip: record.skip as number | undefined,
+              page: record.page as number | undefined,
+              limit: record.limit as number | undefined,
+            });
+            validateSearchPaginationPolicy({
+              skip,
+              limit,
+              confirmLargeFetch: record.confirmLargeFetch as boolean | undefined,
+            });
+            const dsl = buildStructuredSearchDsl(client, source, record);
+            const response = (await client.rawQuery(dsl)) as Record<string, unknown>;
+            const parsed = parseEntityResponse(response, source);
+            const rows = parsed.data as Record<string, unknown>[];
+
+            return formatToolResult(
+              withSearchPagination(
+                {
+                  totalCount: parsed.totalCount,
+                  returnedCount: rows.length,
+                  [resultKey]: rows,
+                },
+                parsed.totalCount,
+                rows.length,
+                skip,
+                limit,
+              ),
+            );
+          } catch (error) {
+            return formatErrorResult(error);
+          }
+        },
+      ),
+    );
+  }
+}

package/src/mcp/utils.ts

@@ -0,0 +1,199 @@
+/**
+ * Utility functions for MCP tools.
+ * @module mcp/utils
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import {
+  buildPaginationMetadata,
+  DimensionsError,
+  largeResultWarning,
+  type PaginationMetadata,
+  POLICY_NOTICE,
+} from "../dsl/index.js";
+
+/** Annotations for read-only tools that call external APIs. */
+export const READ_ONLY_API_ANNOTATIONS: ToolAnnotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+} as const;
+
+/**
+ * Coerces an unknown value to an array of records, returning `[]` if not an array.
+ * Replaces unsafe `as Array<Record<string, unknown>>` casts from API responses.
+ * @param value - Unknown value from a DSL response property
+ * @returns The value as an array of records, or empty array if not an array
+ */
+export function asArray(value: unknown): Array<Record<string, unknown>> {
+  return Array.isArray(value) ? (value as Array<Record<string, unknown>>) : [];
+}
+
+/**
+ * MCP tool result format.
+ * Includes index signature for MCP SDK compatibility.
+ */
+export interface ToolResult {
+  [key: string]: unknown;
+  content: Array<{
+    type: "text";
+    text: string;
+  }>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+}
+
+/**
+ * Formats a successful tool result.
+ * Populates both `content` (text/JSON) and `structuredContent` for SDK output schema validation.
+ * @param data - The data to return
+ * @returns Formatted tool result
+ */
+export function formatToolResult(data: unknown): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+    structuredContent: data as Record<string, unknown>,
+  };
+}
+
+/**
+ * Builds a JSON-serializable error payload for MCP tool responses.
+ * Surfaces Dimensions API metadata (status codes, client rate-limit hints) when available.
+ * @param error - The error that occurred
+ * @returns Error payload object
+ */
+export function formatErrorPayload(error: unknown): Record<string, unknown> {
+  if (error instanceof DimensionsError) {
+    const json = error.toJSON();
+    return {
+      ...json,
+      error: json.message,
+      type: json.name,
+    };
+  }
+
+  return {
+    error: error instanceof Error ? error.message : String(error),
+    type: error instanceof Error ? error.name : "Error",
+  };
+}
+
+/**
+ * Formats an error tool result.
+ * @param error - The error that occurred
+ * @returns Formatted error result
+ */
+export function formatErrorResult(error: unknown): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(formatErrorPayload(error), null, 2),
+      },
+    ],
+    isError: true,
+  };
+}
+
+/** Fields added to paginated search tool responses. */
+export type SearchPaginationFields = {
+  truncated?: boolean;
+  truncationWarning?: string;
+  pagination?: PaginationMetadata;
+  largeResultWarning?: string;
+  policyNotice?: string;
+};
+
+/**
+ * Augments a search result with truncation warnings and pagination metadata.
+ * @param data - The result data object
+ * @param totalCount - Total matching records from the API
+ * @param returnedCount - Records actually returned
+ * @param skip - Current skip offset
+ * @param pageSize - Page size used for this request
+ * @returns The data object with pagination fields when applicable
+ */
+export function withSearchPagination<T extends Record<string, unknown>>(
+  data: T,
+  totalCount: number,
+  returnedCount: number,
+  skip: number,
+  pageSize: number,
+): T & SearchPaginationFields {
+  const warning = largeResultWarning(totalCount);
+  const truncated = totalCount > skip + returnedCount;
+  const needsPagination = skip > 0 || truncated || warning !== undefined;
+
+  if (!needsPagination) {
+    return data;
+  }
+
+  const pagination = buildPaginationMetadata(skip, pageSize, totalCount);
+
+  const showPolicyNotice = truncated || warning !== undefined;
+
+  return {
+    ...data,
+    ...(warning ? { largeResultWarning: warning } : {}),
+    ...(showPolicyNotice ? { policyNotice: POLICY_NOTICE } : {}),
+    ...(truncated
+      ? {
+          truncated: true,
+          truncationWarning:
+            `Only ${returnedCount} of ${totalCount} results in this page (skip ${skip}). ` +
+            "Use skip/page on search_* or fetch_search_pages for the next page; narrow filters when possible.",
+        }
+      : {}),
+    pagination,
+  };
+}
+
+/**
+ * @deprecated Use {@link withSearchPagination} — kept as alias for gradual migration.
+ */
+export function withTruncationWarning<T extends Record<string, unknown>>(
+  data: T,
+  totalCount: number,
+  returnedCount: number,
+): T & SearchPaginationFields {
+  const pageSize = returnedCount > 0 ? returnedCount : 100;
+  return withSearchPagination(data, totalCount, returnedCount, 0, pageSize);
+}
+
+/** Logging levels supported by the MCP protocol (syslog severity). */
+export type McpLogLevel =
+  | "debug"
+  | "info"
+  | "notice"
+  | "warning"
+  | "error"
+  | "critical"
+  | "alert"
+  | "emergency";
+
+/**
+ * Sends a structured log message via the MCP protocol with stderr fallback.
+ * @param server - MCP server instance
+ * @param level - Log severity level
+ * @param data - Structured log data (any JSON-serializable value)
+ * @param logger - Optional logger namespace (e.g., "search", "schema")
+ */
+export function mcpLog(
+  server: McpServer,
+  level: McpLogLevel,
+  data: unknown,
+  logger?: string,
+): void {
+  server.sendLoggingMessage({ level, data, logger }).catch(() => {
+    console.error(
+      `[${level}]${logger ? ` [${logger}]` : ""} ${typeof data === "string" ? data : JSON.stringify(data)}`,
+    );
+  });
+}

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

@@ -0,0 +1,92 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { fromEnv, fromObject, fromPath } from "../../../src/client/auth/config-loaders.js";
+import { ValidationError } from "../../../src/client/errors.js";
+
+describe("config-loaders", () => {
+  describe("fromEnv", () => {
+    const originalEnv = { ...process.env };
+    let savedApiKey: string | undefined;
+
+    beforeEach(() => {
+      savedApiKey = process.env.DIMENSIONS_API_KEY;
+      delete process.env.DIMENSIONS_API_KEY;
+      delete process.env.DIMENSIONS_AUTH_URL;
+      delete process.env.DIMENSIONS_TOKEN_CACHE_DURATION;
+      delete process.env.DIMENSIONS_TIMEOUT;
+      delete process.env.CUSTOM_API_KEY;
+    });
+
+    afterEach(() => {
+      if (savedApiKey !== undefined) {
+        process.env.DIMENSIONS_API_KEY = savedApiKey;
+      } else {
+        delete process.env.DIMENSIONS_API_KEY;
+      }
+      Object.assign(process.env, originalEnv);
+    });
+
+    it("loads JWT config from environment", () => {
+      process.env.DIMENSIONS_API_KEY = "test-api-key";
+      expect(fromEnv("jwt")).toEqual({ type: "jwt", apiKey: "test-api-key" });
+    });
+
+    it("loads optional JWT config fields", () => {
+      process.env.DIMENSIONS_API_KEY = "test-api-key";
+      process.env.DIMENSIONS_AUTH_URL = "https://custom.auth.com/token";
+      process.env.DIMENSIONS_TOKEN_CACHE_DURATION = "7200";
+      process.env.DIMENSIONS_TIMEOUT = "60000";
+
+      expect(fromEnv("jwt")).toEqual({
+        type: "jwt",
+        apiKey: "test-api-key",
+        authUrl: "https://custom.auth.com/token",
+        tokenCacheDuration: 7200,
+        timeout: 60000,
+      });
+    });
+
+    it("throws when API key is missing", () => {
+      expect(() => fromEnv("jwt")).toThrow(ValidationError);
+    });
+  });
+
+  describe("fromObject", () => {
+    it("validates JWT config object", () => {
+      expect(fromObject({ type: "jwt", apiKey: "key" })).toEqual({
+        type: "jwt",
+        apiKey: "key",
+      });
+    });
+
+    it("rejects invalid config", () => {
+      expect(() => fromObject({ type: "basic", username: "u", password: "p" })).toThrow(
+        ValidationError,
+      );
+    });
+  });
+
+  describe("fromPath", () => {
+    const tempDir = join(tmpdir(), `dsl-auth-config-${Date.now()}`);
+
+    beforeEach(() => {
+      mkdirSync(tempDir, { recursive: true });
+    });
+
+    afterEach(() => {
+      rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it("loads JWT config from JSON file", () => {
+      const filePath = join(tempDir, "auth.json");
+      writeFileSync(filePath, JSON.stringify({ type: "jwt", apiKey: "file-key" }));
+      expect(fromPath(filePath)).toEqual({ type: "jwt", apiKey: "file-key" });
+    });
+
+    it("throws for missing file", () => {
+      expect(() => fromPath(join(tempDir, "missing.json"))).toThrow(ValidationError);
+    });
+  });
+});