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

package/test/tools/search.test.ts

@@ -0,0 +1,415 @@
+/**
+ * Tests for search MCP tools.
+ * Verifies schema-driven registration, rawQuery DSL execution, and result formatting.
+ * @module test/tools/search
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { registerSearchTools } from "../../src/mcp/tools/search.js";
+import { testSchemaStore } from "../helpers/schema-fixture.js";
+import {
+  callTool,
+  createMockClient,
+  createMockServer,
+  parseToolResult,
+} from "../helpers/tool-test-harness.js";
+
+/** API-shaped mock response for parseEntityResponse. */
+function apiRows(
+  entity: string,
+  rows: Record<string, unknown>[],
+  totalCount?: number,
+): Record<string, unknown> {
+  return {
+    [entity]: rows,
+    _stats: { total_count: totalCount ?? rows.length },
+  };
+}
+
+describe("search tools", () => {
+  let handlers: ReturnType<typeof createMockServer>["handlers"];
+  let server: ReturnType<typeof createMockServer>["server"];
+  let client: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    ({ server, handlers } = createMockServer());
+    client = createMockClient();
+    registerSearchTools(server as never, client as never, testSchemaStore());
+  });
+
+  it("registers all 8 search tools", () => {
+    const expectedTools = [
+      "search_publications",
+      "search_grants",
+      "search_researchers",
+      "search_patents",
+      "search_clinical_trials",
+      "search_datasets",
+      "search_policy_documents",
+      "search_organizations",
+    ];
+    for (const name of expectedTools) {
+      expect(handlers.has(name)).toBe(true);
+    }
+    expect(handlers.size).toBe(8);
+  });
+
+  describe("search_publications", () => {
+    it("executes DSL via rawQuery with convenience filters", async () => {
+      client.rawQuery.mockResolvedValue(
+        apiRows(
+          "publications",
+          [
+            { id: "pub1", title: "Paper A" },
+            { id: "pub2", title: "Paper B" },
+          ],
+          5,
+        ),
+      );
+
+      await callTool(handlers, "search_publications", {
+        query: "CRISPR gene editing",
+        yearFrom: 2020,
+        yearTo: 2024,
+        type: "article",
+        limit: 50,
+        sortBy: "times_cited",
+        fields: ["id", "title", "doi"],
+      });
+
+      expect(client.rawQuery).toHaveBeenCalledTimes(1);
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("search publications");
+      expect(dsl).toContain('for "CRISPR gene editing"');
+      expect(dsl).toContain("year >= 2020");
+      expect(dsl).toContain("year <= 2024");
+      expect(dsl).toContain('type = "article"');
+      expect(dsl).toContain("limit 50");
+      expect(dsl).toContain("sort by times_cited desc");
+    });
+
+    it("formats result correctly", async () => {
+      const mockPublications = [
+        { id: "pub1", title: "Paper A" },
+        { id: "pub2", title: "Paper B" },
+      ];
+      client.rawQuery.mockResolvedValue(apiRows("publications", mockPublications, 2));
+
+      const result = await callTool(handlers, "search_publications", {
+        query: "machine learning",
+        limit: 100,
+      });
+      const parsed = parseToolResult(result);
+
+      expect(parsed.totalCount).toBe(2);
+      expect(parsed.returnedCount).toBe(2);
+      expect(parsed.publications).toEqual(mockPublications);
+    });
+
+    it("uses default limit when not specified", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [], 0));
+
+      const result = await callTool(handlers, "search_publications", {
+        query: "quantum computing",
+      });
+      const parsed = parseToolResult(result);
+
+      expect(parsed.totalCount).toBe(0);
+      expect(parsed.returnedCount).toBe(0);
+      expect(parsed.publications).toEqual([]);
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("limit 100");
+    });
+
+    it("handles errors gracefully", async () => {
+      client.rawQuery.mockRejectedValue(new Error("API rate limit exceeded"));
+
+      const result = await callTool(handlers, "search_publications", {
+        query: "failing query",
+        limit: 100,
+      });
+
+      expect(result.isError).toBe(true);
+      const parsed = parseToolResult(result);
+      expect(parsed.error).toBe("API rate limit exceeded");
+      expect(parsed.type).toBe("Error");
+    });
+  });
+
+  describe("search_grants", () => {
+    it("builds grant DSL and formats result", async () => {
+      const mockGrants = [{ id: "g1", title: "Cancer Research Grant" }];
+      client.rawQuery.mockResolvedValue(apiRows("grants", mockGrants, 1));
+
+      const result = await callTool(handlers, "search_grants", {
+        query: "cancer research",
+        startYearFrom: 2022,
+        funderOrgName: "NIH",
+        limit: 50,
+        sortBy: "funding_usd",
+        fields: ["id", "title", "funding_usd"],
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("search grants");
+      expect(dsl).toContain("start_year >= 2022");
+      expect(dsl).toContain('funder_org_name = "National Institutes of Health"');
+
+      const parsed = parseToolResult(result);
+      expect(parsed.totalCount).toBe(1);
+      expect(parsed.grants).toEqual(mockGrants);
+    });
+
+    it("resolves funder acronyms in funderOrgName", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("grants", [{ id: "g1" }], 1));
+
+      await callTool(handlers, "search_grants", {
+        query: "cancer immunotherapy",
+        funderOrgName: "NCI",
+        limit: 10,
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain('funder_org_name = "National Cancer Institute"');
+    });
+
+    it("handles errors gracefully", async () => {
+      client.rawQuery.mockRejectedValue(new Error("Connection timeout"));
+
+      const result = await callTool(handlers, "search_grants", {
+        query: "failing query",
+        limit: 100,
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).error).toBe("Connection timeout");
+    });
+  });
+
+  describe("search_researchers", () => {
+    it("describes name-oriented search in tool metadata", () => {
+      const tool = server.registerTool.mock.calls.find((c) => c[0] === "search_researchers");
+      expect(tool).toBeDefined();
+      const description = tool?.[1]?.description as string;
+      expect(description).toContain("name");
+      expect(description).toContain("facet_query");
+    });
+
+    it("formats researcher results", async () => {
+      const mockResearchers = [{ id: "r1", first_name: "Jennifer", last_name: "Doudna" }];
+      client.rawQuery.mockResolvedValue(apiRows("researchers", mockResearchers, 1));
+
+      const result = await callTool(handlers, "search_researchers", {
+        query: "Jennifer Doudna",
+        limit: 10,
+        sortBy: "total_publications",
+      });
+
+      const parsed = parseToolResult(result);
+      expect(parsed.researchers).toEqual(mockResearchers);
+    });
+  });
+
+  describe("search_patents", () => {
+    it("applies filing year filters", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("patents", [{ id: "p1" }], 1));
+
+      await callTool(handlers, "search_patents", {
+        query: "CRISPR",
+        filingYearFrom: 2015,
+        filingYearTo: 2020,
+        limit: 10,
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("year >= 2015");
+      expect(dsl).toContain("year <= 2020");
+    });
+  });
+
+  describe("search_clinical_trials", () => {
+    it("returns clinicalTrials result key", async () => {
+      client.rawQuery.mockResolvedValue(
+        apiRows("clinical_trials", [{ id: "ct1", title: "Trial" }], 1),
+      );
+
+      const result = await callTool(handlers, "search_clinical_trials", {
+        query: "diabetes",
+        phase: "Phase 3",
+        limit: 10,
+      });
+      const parsed = parseToolResult(result);
+      expect(parsed.clinicalTrials).toHaveLength(1);
+    });
+  });
+
+  describe("truncation warnings", () => {
+    it("includes truncation warning when totalCount exceeds returnedCount", async () => {
+      client.rawQuery.mockResolvedValue(
+        apiRows(
+          "publications",
+          [
+            { id: "pub1", title: "Paper A" },
+            { id: "pub2", title: "Paper B" },
+          ],
+          5000,
+        ),
+      );
+
+      const result = await callTool(handlers, "search_publications", {
+        query: "machine learning",
+        limit: 2,
+      });
+      const parsed = parseToolResult(result);
+
+      expect(parsed.truncated).toBe(true);
+      expect(parsed.truncationWarning as string).toContain("2 of 5000");
+      expect(parsed.truncationWarning as string).toContain("fetch_search_pages");
+      expect(parsed.pagination).toBeDefined();
+      expect((parsed.pagination as { nextSkip: number }).nextSkip).toBe(2);
+    });
+
+    it("omits truncation fields when all results are returned", async () => {
+      client.rawQuery.mockResolvedValue(
+        apiRows(
+          "publications",
+          [
+            { id: "pub1", title: "Paper A" },
+            { id: "pub2", title: "Paper B" },
+          ],
+          2,
+        ),
+      );
+
+      const result = await callTool(handlers, "search_publications", {
+        query: "machine learning",
+        limit: 100,
+      });
+      const parsed = parseToolResult(result);
+
+      expect(parsed.truncated).toBeUndefined();
+      expect(parsed.truncationWarning).toBeUndefined();
+    });
+  });
+
+  describe("advanced filters", () => {
+    it("includes extended filters in DSL", async () => {
+      client.rawQuery.mockResolvedValue(
+        apiRows("publications", [{ id: "pub1", title: "Filtered Paper" }], 1),
+      );
+
+      await callTool(handlers, "search_publications", {
+        query: "CRISPR",
+        limit: 100,
+        filters: [{ field: "open_access", operator: "=", value: true }],
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("open_access");
+    });
+
+    it("includes is_empty filter in DSL", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [], 0));
+
+      await callTool(handlers, "search_publications", {
+        query: "genomics",
+        filters: [{ field: "doi", operator: "is_empty" }],
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("is empty");
+    });
+  });
+
+  describe("pagination", () => {
+    it("applies skip to DSL", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [{ id: "pub.3" }], 100));
+
+      await callTool(handlers, "search_publications", {
+        query: "genomics",
+        limit: 10,
+        skip: 20,
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("skip 20");
+      expect(dsl).toContain("limit 10");
+    });
+
+    it("computes skip from page", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [], 0));
+
+      await callTool(handlers, "search_publications", {
+        query: "test",
+        limit: 100,
+        page: 3,
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("skip 300");
+    });
+
+    it("requires confirmLargeFetch for deep pagination", async () => {
+      const result = await callTool(handlers, "search_publications", {
+        query: "genomics",
+        limit: 100,
+        skip: 5000,
+      });
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).error).toContain("confirmLargeFetch");
+    });
+
+    it("includes policyNotice when results are truncated", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [{ id: "pub.1" }], 5000));
+
+      const result = await callTool(handlers, "search_publications", {
+        query: "machine learning",
+        limit: 1,
+      });
+      const parsed = parseToolResult(result);
+
+      expect(parsed.policyNotice).toBeDefined();
+    });
+
+    it("includes largeResultWarning for very large totals", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [{ id: "pub.1" }], 25_000));
+
+      const result = await callTool(handlers, "search_publications", {
+        query: "broad",
+        limit: 1,
+      });
+      const parsed = parseToolResult(result);
+
+      expect(parsed.largeResultWarning).toBeDefined();
+      expect(parsed.largeResultWarning as string).toContain("25,000");
+    });
+  });
+
+  describe("field alias resolution", () => {
+    it("resolves sortBy alias in DSL", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [{ id: "pub.1" }], 1));
+
+      await callTool(handlers, "search_publications", {
+        query: "test",
+        sortBy: "total_citations",
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("sort by times_cited");
+      expect(dsl).not.toContain("total_citations");
+    });
+
+    it("resolves fields aliases in DSL", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("publications", [{ id: "pub.1" }], 1));
+
+      await callTool(handlers, "search_publications", {
+        query: "test",
+        fields: ["total_citations", "title", "citation_ratio"],
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("times_cited");
+      expect(dsl).toContain("field_citation_ratio");
+    });
+  });
+});

package/test/utils.test.ts

@@ -0,0 +1,45 @@
+/**
+ * @module test/utils
+ */
+
+import { describe, expect, it } from "vitest";
+import { RateLimitError } from "../src/dsl/index.js";
+import { formatErrorPayload, formatErrorResult } from "../src/mcp/utils.js";
+
+describe("formatErrorPayload", () => {
+  it("serializes RateLimitError with client rate-limit info", () => {
+    const error = new RateLimitError("Rate limit exceeded", 3, {
+      remaining: 0,
+      retryAfterMs: 2050,
+    });
+
+    const payload = formatErrorPayload(error);
+
+    expect(payload.type).toBe("RateLimitError");
+    expect(payload.name).toBe("RateLimitError");
+    expect(payload.error).toBe("Rate limit exceeded");
+    expect(payload.statusCode).toBe(429);
+    expect(payload.retryAfter).toBe(3);
+    expect(payload.clientRateLimit).toEqual({
+      remaining: 0,
+      retryAfterMs: 2050,
+    });
+  });
+
+  it("falls back for generic errors", () => {
+    expect(formatErrorPayload(new Error("boom"))).toEqual({
+      error: "boom",
+      type: "Error",
+    });
+  });
+});
+
+describe("formatErrorResult", () => {
+  it("marks tool results as errors", () => {
+    const result = formatErrorResult(new RateLimitError("Rate limit exceeded", 5));
+    expect(result.isError).toBe(true);
+    const parsed = JSON.parse(result.content[0].text) as Record<string, unknown>;
+    expect(parsed.name).toBe("RateLimitError");
+    expect(parsed.retryAfter).toBe(5);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/http-main.ts","./src/index.ts","./src/main.ts","./src/client/command.ts","./src/client/config.ts","./src/client/deployment-config.ts","./src/client/errors.ts","./src/client/http-client.ts","./src/client/index.ts","./src/client/internal-dsl-client.ts","./src/client/rate-limiter.ts","./src/client/resolve-api-key-user.ts","./src/client/types.ts","./src/client/auth/config-loaders.ts","./src/client/auth/factory.ts","./src/client/auth/index.ts","./src/client/auth/jwt-utils.ts","./src/client/auth/node.ts","./src/client/auth/schemas.ts","./src/client/auth/types.ts","./src/client/auth/decorators/index.ts","./src/client/auth/decorators/with-caching.ts","./src/client/auth/providers/index.ts","./src/client/auth/providers/jwt-auth-provider.ts","./src/client/config/index.ts","./src/client/config/loader.ts","./src/client/config/node.ts","./src/client/config/schemas.ts","./src/client/config/types.ts","./src/client/config/unified-loader.ts","./src/dsl/client.ts","./src/dsl/create-client.ts","./src/dsl/fluent-query-builder.ts","./src/dsl/index.ts","./src/dsl/pagination.ts","./src/dsl/query-builder.ts","./src/dsl/response-parser.ts","./src/dsl/usage-policy.ts","./src/dsl/commands/apply-filters.ts","./src/dsl/commands/index.ts","./src/dsl/commands/validate-input.ts","./src/dsl/commands/facet/index.ts","./src/dsl/commands/facet/schemas.ts","./src/dsl/commands/functions/classifycommand.ts","./src/dsl/commands/functions/extractaffiliationscommand.ts","./src/dsl/commands/functions/extractconceptscommand.ts","./src/dsl/commands/functions/extractgrantscommand.ts","./src/dsl/commands/functions/index.ts","./src/dsl/schema/cache.ts","./src/dsl/schema/extract.ts","./src/dsl/schema/index.ts","./src/dsl/schema/load.ts","./src/dsl/schema/store.ts","./src/dsl/schema/structured-entities.ts","./src/dsl/schema/summary.ts","./src/dsl/schema/types.ts","./src/dsl/schema/validation.ts","./src/dsl/types/buckets.ts","./src/dsl/types/common.ts","./src/dsl/types/entities.ts","./src/dsl/types/index.ts","./src/dsl/types/return-clauses.ts","./src/dsl/types/special-functions.ts","./src/dsl/types/vocabulary.ts","./src/dsl/utils/escape.ts","./src/dsl/utils/sanitize.ts","./src/dsl/utils/string-utils.ts","./src/dsl/utils/validate-field-name.ts","./src/mcp/batch-fetch.ts","./src/mcp/export-format.ts","./src/mcp/funder-org-names.ts","./src/mcp/http-server.ts","./src/mcp/server.ts","./src/mcp/shared-schema.ts","./src/mcp/utils.ts","./src/mcp/examples/dsl-examples.ts","./src/mcp/examples/usage-scenarios.ts","./src/mcp/middleware/field-aliases.ts","./src/mcp/resources/schema.ts","./src/mcp/schema/context.ts","./src/mcp/schema/index.ts","./src/mcp/tools/analytics-filters.ts","./src/mcp/tools/analytics.ts","./src/mcp/tools/fetch-search-pages.ts","./src/mcp/tools/functions.ts","./src/mcp/tools/lookup.ts","./src/mcp/tools/query.ts","./src/mcp/tools/schema.ts","./src/mcp/tools/search-entity-metadata.ts","./src/mcp/tools/search-input.ts","./src/mcp/tools/search.ts"],"version":"5.9.3"}