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

package/test/funder-org-names.test.ts

@@ -0,0 +1,20 @@
+/**
+ * @module test/funder-org-names
+ */
+
+import { describe, expect, it } from "vitest";
+import { resolveFunderOrgName } from "../src/mcp/funder-org-names.js";
+
+describe("resolveFunderOrgName", () => {
+  it("resolves common acronyms case-insensitively", () => {
+    expect(resolveFunderOrgName("NCI")).toBe("National Cancer Institute");
+    expect(resolveFunderOrgName("nci")).toBe("National Cancer Institute");
+    expect(resolveFunderOrgName("NSF")).toBe("National Science Foundation");
+    expect(resolveFunderOrgName("NIH")).toBe("National Institutes of Health");
+  });
+
+  it("passes through unknown names unchanged", () => {
+    expect(resolveFunderOrgName("European Commission")).toBe("European Commission");
+    expect(resolveFunderOrgName("  Custom Funder  ")).toBe("Custom Funder");
+  });
+});

package/test/helpers/schema-fixture.ts

@@ -0,0 +1,18 @@
+/**
+ * Test helper providing a pre-loaded {@link SchemaStore} from fixture data.
+ * @module test/helpers/schema-fixture
+ */
+
+import {
+  createSchemaStoreFromResponse,
+  type DescribeSchemaResponse,
+} from "../../src/mcp/schema/index.js";
+import fixture from "../fixtures/describe-schema.json";
+
+/**
+ * Returns a schema store built from the committed describe fixture.
+ * @returns Schema store for unit tests
+ */
+export function testSchemaStore() {
+  return createSchemaStoreFromResponse(fixture as DescribeSchemaResponse, "2.15.0");
+}

package/test/helpers/tool-test-harness.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared test harness for MCP tool handlers.
+ * Captures tool registrations from register*Tools() functions and provides
+ * helpers to invoke handlers directly without MCP SDK transport overhead.
+ * @module test/helpers/tool-test-harness
+ */
+
+import { vi } from "vitest";
+import { QueryBuilder } from "../../src/dsl/index.js";
+import type { ToolResult } from "../../src/mcp/utils.js";
+import { testSchemaStore } from "./schema-fixture.js";
+
+/** Captured tool handler function signature. */
+type ToolHandler = (
+  args: Record<string, unknown>,
+  extra?: Record<string, unknown>,
+) => Promise<ToolResult>;
+
+/**
+ * Creates a mock McpServer that captures `.tool()` and `.registerTool()` registrations into a Map.
+ * @returns Object with the mock server and a Map of tool name to handler
+ */
+export function createMockServer() {
+  const handlers = new Map<string, ToolHandler>();
+
+  const registerTool = vi.fn((name: string, _config: unknown, handler: ToolHandler) => {
+    handlers.set(name, (args, extra) => handler(args, extra));
+  });
+
+  const server = {
+    // Legacy — kept for backward compatibility during migration
+    tool: vi.fn(
+      (
+        name: string,
+        _descriptionOrSchema: unknown,
+        schemaOrHandler: unknown,
+        maybeHandler?: unknown,
+      ) => {
+        // server.tool() has two overloads:
+        //   tool(name, description, schema, handler)
+        //   tool(name, schema, handler)
+        const handler = (maybeHandler ?? schemaOrHandler) as ToolHandler;
+        handlers.set(name, handler);
+      },
+    ),
+    registerTool,
+  };
+
+  return { server, handlers };
+}
+
+/**
+ * Creates a mock DimensionsClient with vi.fn() stubs for all methods
+ * used by the tool handlers.
+ * @returns Mock client with spyable methods
+ */
+export function createMockClient() {
+  const schemaStore = testSchemaStore();
+  const mockBuilder = {
+    where: vi.fn().mockReturnThis(),
+    fields: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    forSimilar: vi.fn().mockReturnThis(),
+    execute: vi.fn().mockResolvedValue({ totalCount: 0, data: [] }),
+  };
+
+  return {
+    createQueryBuilder: vi.fn(() => new QueryBuilder(schemaStore)),
+    attachSchemaStore: vi.fn(),
+    rawQuery: vi.fn().mockResolvedValue({}),
+    send: vi.fn().mockResolvedValue({}),
+    classify: vi.fn().mockResolvedValue({}),
+    extractConcepts: vi.fn().mockResolvedValue({ extracted_concepts: [] }),
+    extractAffiliations: vi.fn().mockResolvedValue({ extracted_affiliations: [] }),
+    extractGrants: vi.fn().mockResolvedValue({ extracted_grants: [] }),
+    publications: vi.fn().mockReturnValue(mockBuilder),
+    grants: vi.fn().mockReturnValue(mockBuilder),
+    /** Access the fluent builder mock for assertions. */
+    _builder: mockBuilder,
+  };
+}
+
+/**
+ * Invokes a captured tool handler by name.
+ * @param handlers - Map of tool handlers from createMockServer()
+ * @param name - Tool name to invoke
+ * @param args - Arguments to pass to the handler
+ * @returns The raw tool result
+ */
+export async function callTool(
+  handlers: Map<string, ToolHandler>,
+  name: string,
+  args: Record<string, unknown> = {},
+  extra?: Record<string, unknown>,
+): Promise<ToolResult> {
+  const handler = handlers.get(name);
+  if (!handler) {
+    throw new Error(`Tool "${name}" not registered. Available: ${[...handlers.keys()].join(", ")}`);
+  }
+  return handler(args, extra);
+}
+
+/**
+ * Parses the JSON payload from a tool result envelope.
+ * @param result - The raw tool result from callTool()
+ * @returns Parsed JSON data from the text content
+ */
+export function parseToolResult(result: ToolResult): Record<string, unknown> {
+  const text = result.content[0]?.text;
+  if (!text) {
+    throw new Error("Tool result has no text content");
+  }
+  return JSON.parse(text) as Record<string, unknown>;
+}

package/test/integration/assertions.ts

@@ -0,0 +1,263 @@
+/**
+ * Assertion factory functions for MCP eval cases.
+ *
+ * Each function returns an {@link Assertion} object with a label and a check
+ * function. The check receives the parsed JSON output from a tool call.
+ * @module test/integration/assertions
+ */
+
+import type { Assertion } from "./types.js";
+
+/**
+ * Resolves a dot-separated path on an unknown value.
+ * @param data - Root object
+ * @param path - Dot-separated path (e.g., "publications.0.title")
+ * @returns The resolved value, or `undefined` if the path does not exist
+ */
+function resolvePath(data: unknown, path: string): unknown {
+  let current: unknown = data;
+  for (const segment of path.split(".")) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+/**
+ * Asserts the result is not an error (no `isError` flag, no `error` field at top level).
+ * @returns Assertion
+ */
+export function isSuccess(): Assertion {
+  return {
+    label: "result is not an error",
+    check(data) {
+      const obj = data as Record<string, unknown>;
+      if (obj.error) return `Got error: ${String(obj.error)}`;
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts a field at the given path exists (is not undefined).
+ * @param path - Dot-separated path
+ * @returns Assertion
+ */
+export function hasField(path: string): Assertion {
+  return {
+    label: `has field "${path}"`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (value === undefined) return `Field "${path}" is missing`;
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts a field at the given path equals the expected value.
+ * @param path - Dot-separated path
+ * @param expected - Expected value (compared with ===)
+ * @returns Assertion
+ */
+export function fieldEquals(path: string, expected: unknown): Assertion {
+  return {
+    label: `"${path}" === ${JSON.stringify(expected)}`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (value !== expected) {
+        return `Expected "${path}" to be ${JSON.stringify(expected)}, got ${JSON.stringify(value)}`;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts a string field at the given path contains a substring (case-insensitive).
+ * @param path - Dot-separated path
+ * @param substring - Expected substring
+ * @returns Assertion
+ */
+export function fieldContains(path: string, substring: string): Assertion {
+  return {
+    label: `"${path}" contains "${substring}"`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (typeof value !== "string") {
+        return `Expected "${path}" to be a string, got ${typeof value}`;
+      }
+      if (!value.toLowerCase().includes(substring.toLowerCase())) {
+        return `"${path}" does not contain "${substring}" (got "${value.slice(0, 200)}")`;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts a string field at the given path matches a regex.
+ * @param path - Dot-separated path
+ * @param pattern - Regular expression
+ * @returns Assertion
+ */
+export function fieldMatches(path: string, pattern: RegExp): Assertion {
+  return {
+    label: `"${path}" matches ${pattern}`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (typeof value !== "string") {
+        return `Expected "${path}" to be a string, got ${typeof value}`;
+      }
+      if (!pattern.test(value)) {
+        return `"${path}" does not match ${pattern} (got "${value.slice(0, 200)}")`;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts the value at the given path is an array with at least `min` items.
+ * @param path - Dot-separated path
+ * @param min - Minimum array length
+ * @returns Assertion
+ */
+export function arrayMinLength(path: string, min: number): Assertion {
+  return {
+    label: `"${path}" has at least ${min} items`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (!Array.isArray(value)) {
+        return `Expected "${path}" to be an array, got ${typeof value}`;
+      }
+      if (value.length < min) {
+        return `"${path}" has ${value.length} items, expected at least ${min}`;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts a numeric field at the given path is greater than a threshold.
+ * @param path - Dot-separated path
+ * @param threshold - Minimum exclusive value
+ * @returns Assertion
+ */
+export function fieldGreaterThan(path: string, threshold: number): Assertion {
+  return {
+    label: `"${path}" > ${threshold}`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (typeof value !== "number") {
+        return `Expected "${path}" to be a number, got ${typeof value}`;
+      }
+      if (value <= threshold) {
+        return `"${path}" is ${value}, expected > ${threshold}`;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts a numeric field at the given path is at least a threshold.
+ * @param path - Dot-separated path
+ * @param threshold - Minimum inclusive value
+ * @returns Assertion
+ */
+export function fieldAtLeast(path: string, threshold: number): Assertion {
+  return {
+    label: `"${path}" >= ${threshold}`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (typeof value !== "number") {
+        return `Expected "${path}" to be a number, got ${typeof value}`;
+      }
+      if (value < threshold) {
+        return `"${path}" is ${value}, expected >= ${threshold}`;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts the value at the given path is one of the allowed values.
+ * @param path - Dot-separated path
+ * @param allowed - Set of allowed values
+ * @returns Assertion
+ */
+export function fieldOneOf(path: string, allowed: readonly unknown[]): Assertion {
+  return {
+    label: `"${path}" is one of [${allowed.map((v) => JSON.stringify(v)).join(", ")}]`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (!allowed.includes(value)) {
+        return `"${path}" is ${JSON.stringify(value)}, expected one of [${allowed.map((v) => JSON.stringify(v)).join(", ")}]`;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts that every element of the array at `path` satisfies all given assertions.
+ * @param path - Dot-separated path to an array
+ * @param itemAssertions - Assertions to apply to each item
+ * @returns Assertion
+ */
+export function everyItem(path: string, itemAssertions: readonly Assertion[]): Assertion {
+  return {
+    label: `every item in "${path}" passes ${itemAssertions.length} assertions`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (!Array.isArray(value)) {
+        return `Expected "${path}" to be an array, got ${typeof value}`;
+      }
+      for (let i = 0; i < value.length; i++) {
+        for (const assertion of itemAssertions) {
+          const result = assertion.check(value[i]);
+          if (result !== true) {
+            return `Item [${i}] failed "${assertion.label}": ${result}`;
+          }
+        }
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * Asserts that at least one element of the array at `path` satisfies all given assertions.
+ * @param path - Dot-separated path to an array
+ * @param itemAssertions - Assertions to apply
+ * @returns Assertion
+ */
+export function someItem(path: string, itemAssertions: readonly Assertion[]): Assertion {
+  return {
+    label: `some item in "${path}" passes all assertions`,
+    check(data) {
+      const value = resolvePath(data, path);
+      if (!Array.isArray(value)) {
+        return `Expected "${path}" to be an array, got ${typeof value}`;
+      }
+      for (const item of value) {
+        const allPass = itemAssertions.every((a) => a.check(item) === true);
+        if (allPass) return true;
+      }
+      return `No item in "${path}" (${value.length} items) satisfied all assertions`;
+    },
+  };
+}
+
+/**
+ * Custom assertion with a user-provided check function.
+ * @param label - Human-readable label
+ * @param check - Check function
+ * @returns Assertion
+ */
+export function custom(label: string, check: (data: unknown) => true | string): Assertion {
+  return { label, check };
+}

package/test/integration/env.ts

@@ -0,0 +1,108 @@
+/**
+ * Environment variable helpers for live integration and hosted e2e tests.
+ * @module test/integration/env
+ */
+
+import type { HostedEnvConfig } from "../../src/client/deployment-config.js";
+import { loadDeploymentConfig } from "../../src/client/deployment-config.js";
+
+/** Env vars required for local (stdio) MCP integration smoke tests. */
+export const LOCAL_INTEGRATION_ENV_VARS = ["DIMENSIONS_API_KEY"] as const;
+
+/** Env vars required for hosted MCP integration smoke tests (live backends). */
+export const HOSTED_INTEGRATION_ENV_VARS = [
+  "DIMENSIONS_API_KEY",
+  "DSL_SERVICE_URL",
+  "DSL_SERVICE_USERNAME",
+  "DSL_SERVICE_PASSWORD",
+  "DSL_SCHEMA",
+  "DSL_HOST",
+  "DSL_VARIANT",
+  "RADAR_AUTH_URL",
+] as const;
+
+/** Optional env vars for hosted integration. */
+export const HOSTED_INTEGRATION_OPTIONAL_ENV_VARS = [
+  "HOSTED_MCP_BASE_URL",
+  "SCHEMA_CACHE_PATH",
+  "MCP_HTTP_PORT",
+] as const;
+
+export type LocalIntegrationEnvVar = (typeof LOCAL_INTEGRATION_ENV_VARS)[number];
+export type HostedIntegrationEnvVar = (typeof HOSTED_INTEGRATION_ENV_VARS)[number];
+
+export interface LocalIntegrationConfig {
+  readonly apiKey: string;
+  readonly baseUrl?: string;
+}
+
+export interface HostedIntegrationConfig {
+  readonly apiKey: string;
+  readonly hosted: HostedEnvConfig;
+  /** When set, tests hit this base URL instead of starting an in-process HTTP server. */
+  readonly remoteBaseUrl?: string;
+}
+
+/**
+ * Returns env var names from `required` that are unset or empty.
+ */
+export function missingEnvVars(required: readonly string[]): string[] {
+  return required.filter((name) => !process.env[name]?.trim());
+}
+
+/**
+ * Returns true when local integration smoke can run.
+ */
+export function isLocalIntegrationConfigured(): boolean {
+  return missingEnvVars(LOCAL_INTEGRATION_ENV_VARS).length === 0;
+}
+
+/**
+ * Returns true when hosted integration smoke can run against live backends.
+ */
+export function isHostedIntegrationConfigured(): boolean {
+  return missingEnvVars(HOSTED_INTEGRATION_ENV_VARS).length === 0;
+}
+
+/**
+ * Loads local integration config from environment, or undefined when credentials are missing.
+ */
+export function loadLocalIntegrationConfig(): LocalIntegrationConfig | undefined {
+  if (!isLocalIntegrationConfigured()) {
+    return undefined;
+  }
+  return {
+    apiKey: process.env.DIMENSIONS_API_KEY!,
+    baseUrl: process.env.DIMENSIONS_BASE_URL,
+  };
+}
+
+/**
+ * Loads hosted integration config from environment, or undefined when credentials are missing.
+ * Sets `DEPLOYMENT_MODE=hosted` when loading deployment config.
+ */
+export function loadHostedIntegrationConfig(): HostedIntegrationConfig | undefined {
+  if (!isHostedIntegrationConfigured()) {
+    return undefined;
+  }
+
+  process.env.DEPLOYMENT_MODE = "hosted";
+  const deployment = loadDeploymentConfig();
+  if (deployment.deploymentMode !== "hosted") {
+    return undefined;
+  }
+
+  return {
+    apiKey: process.env.DIMENSIONS_API_KEY!,
+    hosted: deployment,
+    remoteBaseUrl: process.env.HOSTED_MCP_BASE_URL?.replace(/\/$/, ""),
+  };
+}
+
+/**
+ * Builds the MCP `/mcp` endpoint URL for hosted integration.
+ */
+export function hostedMcpEndpoint(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/$/, "");
+  return trimmed.endsWith("/mcp") ? trimmed : `${trimmed}/mcp`;
+}