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

package/test/integration/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Core types for the MCP evaluation harness.
+ *
+ * Each eval suite defines a set of cases that exercise MCP tools against the
+ * live Dimensions API and verify response correctness with assertions.
+ * @module test/integration/types
+ */
+
+/** A single assertion to run against a tool result. */
+export interface Assertion {
+  /** Human-readable label shown in reports. */
+  readonly label: string;
+  /**
+   * Evaluates the assertion against parsed tool output.
+   * @param data - Parsed JSON from the tool result
+   * @returns `true` if the assertion passes, or an error message string
+   */
+  readonly check: (data: unknown) => true | string;
+}
+
+/** A single evaluation case — one tool call plus its expected assertions. */
+export interface EvalCase {
+  /** Short descriptive name for the case (e.g., "CRISPR DOI lookup"). */
+  readonly name: string;
+  /** MCP tool name to invoke. */
+  readonly tool: string;
+  /** Arguments passed to the tool. */
+  readonly args: Record<string, unknown>;
+  /** Assertions that must all pass for the case to succeed. */
+  readonly assertions: readonly Assertion[];
+  /** Optional tags for filtering (e.g., "slow", "optional-api-key"). */
+  readonly tags?: readonly string[];
+  /** Timeout in ms for the tool call (default: 30_000). */
+  readonly timeout?: number;
+}
+
+/** An evaluation suite — a named group of related cases. */
+export interface EvalSuite {
+  /** Suite name (e.g., "search", "lookup"). */
+  readonly name: string;
+  /** Suite description. */
+  readonly description: string;
+  /** Eval cases in this suite. */
+  readonly cases: readonly EvalCase[];
+  /**
+   * Optional API keys this suite requires beyond the base Dimensions key.
+   * If any are missing from the environment, the suite is skipped.
+   */
+  readonly requiredEnvVars?: readonly string[];
+}
+
+/** Result of a single assertion check. */
+export interface AssertionResult {
+  readonly label: string;
+  readonly passed: boolean;
+  readonly error?: string;
+}
+
+/** Result of a single eval case. */
+export interface CaseResult {
+  readonly suiteName: string;
+  readonly caseName: string;
+  readonly tool: string;
+  readonly passed: boolean;
+  readonly assertions: readonly AssertionResult[];
+  /** Wall-clock duration in ms. */
+  readonly durationMs: number;
+  /** Set if the tool call itself failed (threw or returned isError). */
+  readonly toolError?: string;
+  /** Whether the case was skipped (e.g., missing env var). */
+  readonly skipped?: boolean;
+  readonly skipReason?: string;
+}
+
+/** Aggregate result for an entire suite. */
+export interface SuiteResult {
+  readonly name: string;
+  readonly cases: readonly CaseResult[];
+  readonly passed: number;
+  readonly failed: number;
+  readonly skipped: number;
+  readonly durationMs: number;
+}
+
+/** Aggregate result for the full eval run. */
+export interface EvalRunResult {
+  readonly suites: readonly SuiteResult[];
+  readonly totalPassed: number;
+  readonly totalFailed: number;
+  readonly totalSkipped: number;
+  readonly durationMs: number;
+}

package/test/integration/verify-usage-scenarios.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * Live verification of docs/USAGE.md natural-language scenarios.
+ * Run: node --import tsx apps/mcp/test/integration/verify-usage-scenarios.ts
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { USAGE_SCENARIOS } from "../../src/mcp/examples/usage-scenarios.js";
+import { buildServerInstructions, createMcpServerAsync } from "../../src/mcp/server.js";
+
+interface Row {
+  id: string;
+  tool: string;
+  ok: boolean;
+  summary: string;
+  note?: string;
+}
+
+function summarize(tool: string, data: Record<string, unknown>): string {
+  if (data.error) return `error: ${String(data.error)}`;
+  switch (tool) {
+    case "search_publications":
+    case "search_grants":
+    case "search_researchers":
+      return `totalCount=${data.totalCount}, returned=${data.returnedCount}`;
+    case "facet_query":
+    case "aggregate_query":
+      return `buckets=${data.totalBuckets}`;
+    case "get_by_doi":
+      return data.found
+        ? `found: ${(data.publication as { title?: string })?.title ?? "ok"}`
+        : `not found`;
+    case "citation_trend": {
+      const series = data.citationsPerYear as unknown[] | undefined;
+      return `years=${series?.length ?? 0}`;
+    }
+    case "execute_dsl":
+      return "ok";
+    default:
+      return "ok";
+  }
+}
+
+async function callTool(client: Client, tool: string, args: Record<string, unknown>) {
+  const result = await client.callTool({ name: tool, arguments: args });
+  if ("isError" in result && result.isError) {
+    const text = result.content.find((c) => c.type === "text" && "text" in c)?.text;
+    const parsed = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+    return { ok: false, data: parsed };
+  }
+  const text = result.content.find((c) => c.type === "text" && "text" in c)?.text;
+  if (!text) return { ok: false, data: { error: "no text content" } };
+  const data = JSON.parse(text) as Record<string, unknown>;
+  return { ok: true, data };
+}
+
+async function main() {
+  const apiKey = process.env.DIMENSIONS_API_KEY;
+  if (!apiKey) {
+    console.error("DIMENSIONS_API_KEY required");
+    process.exit(1);
+  }
+
+  const { server, schemaStore } = await createMcpServerAsync({ apiKey });
+  const instructions = buildServerInstructions(schemaStore);
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: "usage-verify", version: "1.0.0" });
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+
+  const rows: Row[] = [];
+
+  for (const scenario of USAGE_SCENARIOS) {
+    const { ok, data } = await callTool(client, scenario.tool, scenario.args);
+    rows.push({
+      id: scenario.id,
+      tool: scenario.tool,
+      ok,
+      summary: summarize(scenario.tool, data),
+    });
+  }
+
+  // Extra checks for documented edge cases
+  const extras: Array<{ id: string; tool: string; args: Record<string, unknown> }> = [
+    {
+      id: "nih-acronym-grants",
+      tool: "search_grants",
+      args: {
+        query: "cancer immunotherapy",
+        startYearFrom: 2020,
+        funderOrgName: "NIH",
+        limit: 5,
+      },
+    },
+    {
+      id: "stanford-org-search",
+      tool: "search_organizations",
+      args: { query: "Stanford University", limit: 10 },
+    },
+    {
+      id: "topic-on-search-researchers",
+      tool: "search_researchers",
+      args: { query: "quantum computing", limit: 5 },
+    },
+    {
+      id: "funder-facet-funder_orgs",
+      tool: "aggregate_query",
+      args: {
+        entityType: "grants",
+        facetField: "funder_orgs",
+        indicators: ["funding"],
+        query: "climate adaptation",
+        limit: 5,
+      },
+    },
+    {
+      id: "funder-facet-funder_org_name",
+      tool: "aggregate_query",
+      args: {
+        entityType: "grants",
+        facetField: "funder_org_name",
+        indicators: ["funding"],
+        query: "climate adaptation",
+        limit: 5,
+      },
+    },
+  ];
+
+  for (const extra of extras) {
+    const { ok, data } = await callTool(client, extra.tool, extra.args);
+    rows.push({
+      id: extra.id,
+      tool: extra.tool,
+      ok,
+      summary: summarize(extra.tool, data),
+      note: "edge-case",
+    });
+  }
+
+  await client.close();
+  await server.close();
+
+  console.log("\n=== Server instructions (routing excerpt) ===");
+  const routingLine = instructions.split("\n\n").find((p) => p.startsWith("Routing:"));
+  console.log(routingLine ?? "(no routing section)");
+
+  console.log("\n=== USAGE.md scenario verification ===");
+  for (const row of rows) {
+    const status = row.ok ? "PASS" : "FAIL";
+    const tag = row.note ? ` [${row.note}]` : "";
+    console.log(`${status}  ${row.id} → ${row.tool}: ${row.summary}${tag}`);
+  }
+
+  const failed = rows.filter((r) => !r.ok).length;
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/test/mcp/export-format.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Tests for batch export formatting helpers.
+ * @module test/mcp/export-format
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  deriveCsvColumns,
+  escapeCsvCell,
+  formatRowsForExport,
+  resolveExportFormat,
+} from "../../src/mcp/export-format.js";
+
+describe("export-format", () => {
+  describe("resolveExportFormat", () => {
+    it("infers CSV from .csv extension", () => {
+      expect(resolveExportFormat("/tmp/results.csv")).toBe("csv");
+    });
+
+    it("defaults to JSONL for other extensions", () => {
+      expect(resolveExportFormat("/tmp/results.jsonl")).toBe("jsonl");
+    });
+
+    it("prefers explicit format", () => {
+      expect(resolveExportFormat("/tmp/results.jsonl", "csv")).toBe("csv");
+    });
+  });
+
+  describe("escapeCsvCell", () => {
+    it("quotes values with commas", () => {
+      expect(escapeCsvCell("a,b")).toBe('"a,b"');
+    });
+
+    it("JSON-stringifies nested values", () => {
+      expect(escapeCsvCell({ id: "pub.1" })).toBe('"{""id"":""pub.1""}"');
+    });
+  });
+
+  describe("formatRowsForExport", () => {
+    it("writes CSV with header and preferred field order", () => {
+      const { text } = formatRowsForExport(
+        [
+          { id: "pub.1", title: "Alpha", year: 2024 },
+          { id: "pub.2", title: "Beta", journal: "Nature" },
+        ],
+        "csv",
+        { preferredFields: ["title", "id"], includeHeader: true },
+      );
+
+      expect(text).toBe("title,id,journal,year\n" + "Alpha,pub.1,,2024\n" + "Beta,pub.2,Nature,\n");
+    });
+
+    it("writes JSONL lines", () => {
+      const { text } = formatRowsForExport([{ id: "pub.1" }], "jsonl");
+      expect(text).toBe('{"id":"pub.1"}\n');
+    });
+  });
+
+  describe("deriveCsvColumns", () => {
+    it("reuses existing columns on resume", () => {
+      expect(deriveCsvColumns([{ id: "pub.2", extra: true }], ["title"], ["id", "title"])).toEqual([
+        "id",
+        "title",
+      ]);
+    });
+  });
+});

package/test/mcp/http-server.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Smoke tests for hosted HTTP MCP server.
+ * @module test/mcp/http-server
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { HostedEnvConfig } from "../../src/client/deployment-config.js";
+import { AuthenticationError } from "../../src/client/errors.js";
+import { startHostedHttpServer } from "../../src/mcp/http-server.js";
+
+const HOSTED: HostedEnvConfig = {
+  deploymentMode: "hosted",
+  radarAuthUrl: "https://app.example.com",
+  internal: {
+    serviceUrl: "https://dsl.example.com",
+    username: "svc",
+    password: "secret",
+    dslSchema: "external",
+    host: "app.example.com",
+    variant: "standard",
+  },
+  httpPort: 8080,
+};
+
+vi.mock("../../src/mcp/server.js", () => ({
+  warmHostedSchemaCache: vi.fn().mockResolvedValue({}),
+  createMcpServerAsync: vi.fn().mockResolvedValue({
+    server: {
+      connect: vi.fn().mockResolvedValue(undefined),
+      close: vi.fn().mockResolvedValue(undefined),
+    },
+  }),
+}));
+
+vi.mock("../../src/client/resolve-api-key-user.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../src/client/resolve-api-key-user.js")>();
+  return {
+    ...actual,
+    resolveUserFromApiKey: vi.fn().mockResolvedValue("user@example.com"),
+    parseBearerToken: vi.fn((header?: string) => {
+      if (!header?.startsWith("Bearer ")) {
+        throw new AuthenticationError("Missing Authorization header");
+      }
+      return header.slice("Bearer ".length);
+    }),
+  };
+});
+
+describe("startHostedHttpServer", () => {
+  let handle: ReturnType<typeof startHostedHttpServer> | undefined;
+
+  afterEach(async () => {
+    if (handle) {
+      await handle.close();
+      handle = undefined;
+    }
+  });
+
+  it("serves GET /health", async () => {
+    handle = startHostedHttpServer({ hosted: HOSTED, port: 0 });
+    const port = await handle.ready;
+
+    const response = await fetch(`http://127.0.0.1:${port}/health`);
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ status: "ok" });
+  });
+
+  it("returns 401 when Authorization header is missing", async () => {
+    handle = startHostedHttpServer({ hosted: HOSTED, port: 0 });
+    const port = await handle.ready;
+
+    const response = await fetch(`http://127.0.0.1:${port}/mcp`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", method: "initialize", id: 1, params: {} }),
+    });
+
+    expect(response.status).toBe(401);
+  });
+});

package/test/middleware/field-aliases.test.ts

@@ -0,0 +1,287 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { describe, expect, it } from "vitest";
+import {
+  buildReverseAliasMap,
+  ENTITY_ALIASES,
+  resolveFacetFieldName,
+  resolveFieldName,
+  resolveFieldNames,
+  withFieldAliases,
+} from "../../src/mcp/middleware/field-aliases.js";
+
+// ---------------------------------------------------------------------------
+// resolveFieldName
+// ---------------------------------------------------------------------------
+
+describe("resolveFieldName", () => {
+  it("resolves a known alias to its DSL name", () => {
+    expect(resolveFieldName("publications", "total_citations")).toBe("times_cited");
+  });
+
+  it("passes through raw DSL field names unchanged", () => {
+    expect(resolveFieldName("publications", "times_cited")).toBe("times_cited");
+  });
+
+  it("passes through unknown names unchanged (backward compat)", () => {
+    expect(resolveFieldName("publications", "some_unknown_field")).toBe("some_unknown_field");
+  });
+
+  it("resolves grant aliases", () => {
+    expect(resolveFieldName("grants", "funding_amount_usd")).toBe("funding_usd");
+    expect(resolveFieldName("grants", "funder_name")).toBe("funder_org_name");
+  });
+
+  it("resolves grant facet field aliases separately from filter fields", () => {
+    expect(resolveFacetFieldName("grants", "funders")).toBe("funder_orgs");
+    expect(resolveFacetFieldName("grants", "funder_org_name")).toBe("funder_org_name");
+    expect(resolveFieldName("grants", "funder_name")).toBe("funder_org_name");
+  });
+
+  it("resolves researcher aliases", () => {
+    expect(resolveFieldName("researchers", "orcid")).toBe("orcid_id");
+  });
+
+  it("resolves indicator aliases", () => {
+    expect(resolveFieldName("publications", "field_citation_ratio_avg")).toBe("fcr_gavg");
+    expect(resolveFieldName("publications", "relative_citation_ratio_avg")).toBe("rcr_avg");
+    expect(resolveFieldName("publications", "average_citations")).toBe("citations_avg");
+    expect(resolveFieldName("grants", "total_funding")).toBe("funding");
+  });
+
+  it("does not resolve an alias from a different entity", () => {
+    // total_citations is a publications alias, not a grants alias
+    expect(resolveFieldName("grants", "total_citations")).toBe("total_citations");
+  });
+
+  it("returns name unchanged for an unknown entity type", () => {
+    // Simulates dynamic entity source receiving unvalidated user input
+    expect(resolveFieldName("unknown_entity" as never, "some_field")).toBe("some_field");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveFieldNames
+// ---------------------------------------------------------------------------
+
+describe("resolveFieldNames", () => {
+  it("resolves an array mixing aliases and DSL names", () => {
+    const result = resolveFieldNames("publications", [
+      "total_citations",
+      "title",
+      "citation_ratio",
+    ]);
+    expect(result).toEqual(["times_cited", "title", "field_citation_ratio"]);
+  });
+
+  it("returns empty array for empty input", () => {
+    expect(resolveFieldNames("publications", [])).toEqual([]);
+  });
+
+  it("returns names unchanged for an unknown entity type", () => {
+    expect(resolveFieldNames("unknown_entity" as never, ["a", "b"])).toEqual(["a", "b"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ENTITY_ALIASES registry
+// ---------------------------------------------------------------------------
+
+describe("ENTITY_ALIASES", () => {
+  const ALL_ENTITIES = [
+    "publications",
+    "grants",
+    "patents",
+    "clinical_trials",
+    "datasets",
+    "policy_documents",
+    "researchers",
+    "organizations",
+  ] as const;
+
+  it("has an entry for every entity type", () => {
+    for (const entity of ALL_ENTITIES) {
+      expect(ENTITY_ALIASES[entity]).toBeDefined();
+      expect(typeof ENTITY_ALIASES[entity]).toBe("object");
+    }
+  });
+
+  it("has no alias that collides with a DSL name from another entity's aliases", () => {
+    // Collect all alias keys across all entities
+    const aliasToEntity = new Map<string, string[]>();
+    for (const entity of ALL_ENTITIES) {
+      for (const alias of Object.keys(ENTITY_ALIASES[entity])) {
+        const entities = aliasToEntity.get(alias) ?? [];
+        entities.push(entity);
+        aliasToEntity.set(alias, entities);
+      }
+    }
+    // Each alias should only appear on one entity (or on multiple where it maps to the same concept)
+    for (const [alias, entities] of aliasToEntity) {
+      if (entities.length > 1) {
+        // Verify they all map to the same DSL name
+        const targets = new Set(
+          entities.map((e) => ENTITY_ALIASES[e as keyof typeof ENTITY_ALIASES][alias]),
+        );
+        expect(targets.size).toBe(1);
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildReverseAliasMap
+// ---------------------------------------------------------------------------
+
+describe("buildReverseAliasMap", () => {
+  it("maps DSL name to its aliases", () => {
+    const reverse = buildReverseAliasMap("publications");
+    expect(reverse.get("times_cited")).toEqual(["total_citations"]);
+    expect(reverse.get("field_citation_ratio")).toEqual(["citation_ratio"]);
+  });
+
+  it("returns empty map for entities with no aliases", () => {
+    const reverse = buildReverseAliasMap("patents");
+    expect(reverse.size).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// withFieldAliases HOF
+// ---------------------------------------------------------------------------
+
+describe("withFieldAliases", () => {
+  /** Helper to create a handler that captures its received args. */
+  function createCapturingHandler() {
+    let capturedArgs: Record<string, unknown> = {};
+    const handler = (args: Record<string, unknown>) => {
+      capturedArgs = args;
+      return { content: [{ type: "text" as const, text: "{}" }] } satisfies CallToolResult;
+    };
+    return { handler, getCapturedArgs: () => capturedArgs };
+  }
+
+  it("resolves fieldArrayArgs (e.g., fields)", () => {
+    const { handler, getCapturedArgs } = createCapturingHandler();
+    const wrapped = withFieldAliases(
+      {
+        entitySource: { kind: "static", entity: "publications" },
+        fieldArrayArgs: ["fields"],
+      },
+      handler,
+    );
+
+    wrapped({ fields: ["total_citations", "title", "doi"] }, {});
+    expect(getCapturedArgs().fields).toEqual(["times_cited", "title", "doi"]);
+  });
+
+  it("resolves fieldStringArgs (e.g., sortBy)", () => {
+    const { handler, getCapturedArgs } = createCapturingHandler();
+    const wrapped = withFieldAliases(
+      {
+        entitySource: { kind: "static", entity: "publications" },
+        fieldStringArgs: ["sortBy"],
+      },
+      handler,
+    );
+
+    wrapped({ sortBy: "total_citations" }, {});
+    expect(getCapturedArgs().sortBy).toBe("times_cited");
+  });
+
+  it("resolves filterArrayArgs (e.g., filters[].field)", () => {
+    const { handler, getCapturedArgs } = createCapturingHandler();
+    const wrapped = withFieldAliases(
+      {
+        entitySource: { kind: "static", entity: "publications" },
+        filterArrayArgs: ["filters"],
+      },
+      handler,
+    );
+
+    wrapped(
+      {
+        filters: [
+          { field: "total_citations", operator: ">=", value: 10 },
+          { field: "year", operator: ">=", value: 2020 },
+        ],
+      },
+      {},
+    );
+    const filters = getCapturedArgs().filters as Array<Record<string, unknown>>;
+    expect(filters[0].field).toBe("times_cited");
+    expect(filters[1].field).toBe("year"); // pass-through
+  });
+
+  it("handles dynamic entitySource from args", () => {
+    const { handler, getCapturedArgs } = createCapturingHandler();
+    const wrapped = withFieldAliases(
+      {
+        entitySource: { kind: "dynamic", argName: "entityType" },
+        fieldArrayArgs: ["fields"],
+      },
+      handler,
+    );
+
+    wrapped({ entityType: "grants", fields: ["funding_amount_usd"] }, {});
+    expect(getCapturedArgs().fields).toEqual(["funding_usd"]);
+  });
+
+  it("leaves non-field args untouched", () => {
+    const { handler, getCapturedArgs } = createCapturingHandler();
+    const wrapped = withFieldAliases(
+      {
+        entitySource: { kind: "static", entity: "publications" },
+        fieldArrayArgs: ["fields"],
+      },
+      handler,
+    );
+
+    wrapped({ query: "CRISPR", limit: 50, fields: ["title"] }, {});
+    expect(getCapturedArgs().query).toBe("CRISPR");
+    expect(getCapturedArgs().limit).toBe(50);
+  });
+
+  it("handles undefined/missing optional args gracefully", () => {
+    const { handler, getCapturedArgs } = createCapturingHandler();
+    const wrapped = withFieldAliases(
+      {
+        entitySource: { kind: "static", entity: "publications" },
+        fieldArrayArgs: ["fields"],
+        fieldStringArgs: ["sortBy"],
+        filterArrayArgs: ["filters"],
+      },
+      handler,
+    );
+
+    wrapped({ query: "test" }, {});
+    expect(getCapturedArgs().fields).toBeUndefined();
+    expect(getCapturedArgs().sortBy).toBeUndefined();
+    expect(getCapturedArgs().filters).toBeUndefined();
+  });
+
+  it("preserves the return value from the inner handler", () => {
+    const result: CallToolResult = {
+      content: [{ type: "text", text: '{"count":42}' }],
+    };
+    const handler = () => result;
+    const wrapped = withFieldAliases(
+      { entitySource: { kind: "static", entity: "publications" } },
+      handler,
+    );
+
+    expect(wrapped({}, {})).toBe(result);
+  });
+
+  it("preserves async handler behavior", async () => {
+    const result: CallToolResult = {
+      content: [{ type: "text", text: '{"count":42}' }],
+    };
+    const handler = async () => result;
+    const wrapped = withFieldAliases(
+      { entitySource: { kind: "static", entity: "publications" } },
+      handler,
+    );
+
+    expect(await wrapped({}, {})).toBe(result);
+  });
+});