@digital-science-dsl/dimensions-analytics-mcp 1.0.3 → 1.1.0

package/test/client/request-retry.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Tests for shared request retry helpers.
+ * @module test/client/request-retry
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+import { NetworkError, RateLimitError, ServerError } from "../../src/client/errors.js";
+import {
+  calculateRequestRetryDelay,
+  executeRequestWithRetry,
+  isRetryableRequestError,
+  resetRequestRetryDelayFn,
+  setRequestRetryDelayFn,
+} from "../../src/client/request-retry.js";
+
+describe("request-retry", () => {
+  afterEach(() => {
+    resetRequestRetryDelayFn();
+  });
+
+  it("identifies retryable errors", () => {
+    expect(isRetryableRequestError(new RateLimitError())).toBe(true);
+    expect(isRetryableRequestError(new ServerError("boom", 500))).toBe(true);
+    expect(isRetryableRequestError(new NetworkError("net"))).toBe(true);
+    expect(isRetryableRequestError(new Error("nope"))).toBe(false);
+  });
+
+  it("retries transient failures then succeeds", async () => {
+    setRequestRetryDelayFn(async () => {});
+
+    let calls = 0;
+    const result = await executeRequestWithRetry(
+      async () => {
+        calls += 1;
+        if (calls < 2) {
+          throw new ServerError("temporary", 503);
+        }
+        return "ok";
+      },
+      { maxRetries: 2, retryDelay: 10 },
+    );
+
+    expect(result).toBe("ok");
+    expect(calls).toBe(2);
+  });
+
+  it("uses rate-limit retry delay when provided on the error", () => {
+    const delay = calculateRequestRetryDelay(
+      new RateLimitError("limited", 2, { remaining: 0, retryAfterMs: 3500 }),
+      0,
+      { retryDelay: 10 },
+    );
+    expect(delay).toBe(3500);
+  });
+});

package/test/client/usage-headers.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Tests for MCP usage header builder.
+ * @module test/client/usage-headers
+ */
+
+import { describe, expect, it } from "vitest";
+import { runWithMcpTool, setMcpUsageSession } from "../../src/client/usage-context.js";
+import {
+  buildMcpUsageHeaders,
+  buildMcpUserAgent,
+  USAGE_HEADER_CHANNEL,
+  USAGE_HEADER_MCP_TOOL,
+} from "../../src/client/usage-headers.js";
+
+describe("buildMcpUsageHeaders", () => {
+  it("returns empty object when no session is configured", () => {
+    expect(buildMcpUsageHeaders()).toEqual({});
+  });
+
+  it("includes session fields and active tool name", () => {
+    setMcpUsageSession({
+      sessionId: "session-1",
+      deployment: "local",
+      client: "stdio",
+      version: "1.0.4",
+    });
+
+    const headers = runWithMcpTool("execute_dsl", () => buildMcpUsageHeaders());
+
+    expect(headers).toEqual({
+      [USAGE_HEADER_CHANNEL]: "mcp",
+      "X-Dimensions-MCP-Session-Id": "session-1",
+      "X-Dimensions-MCP-Client": "stdio",
+      "X-Dimensions-MCP-Version": "1.0.4",
+      "X-Dimensions-MCP-Deployment": "local",
+      [USAGE_HEADER_MCP_TOOL]: "execute_dsl",
+    });
+  });
+});
+
+describe("buildMcpUserAgent", () => {
+  it("formats version and client", () => {
+    expect(buildMcpUserAgent("1.0.4", "cursor")).toBe("dimensions-analytics-mcp/1.0.4 (cursor)");
+  });
+});

package/test/fixtures/describe-schema.json

@@ -3801,6 +3801,80 @@
       "fieldsets": ["basics", "categories"],
       "metrics": { "count": { "name": "count", "description": "Total count" } },
       "search_fields": ["full_data", "title_abstract_only", "concepts"]
+    },
+    "funder_groups": {
+      "fields": {
+        "id": {
+          "type": "string",
+          "description": "The Dimensions ID of the group.",
+          "long_description": null,
+          "is_entity": false,
+          "is_filter": true,
+          "is_facet": false,
+          "is_multivalue": false,
+          "solr_fields": { "return": "id", "filter": "id" }
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the group.",
+          "long_description": null,
+          "is_entity": false,
+          "is_filter": true,
+          "is_facet": false,
+          "is_multivalue": false,
+          "solr_fields": { "return": "name", "filter": "name" }
+        },
+        "organization_ids": {
+          "type": "string",
+          "description": "The GRID IDs of the organizations which are members of this group.",
+          "long_description": null,
+          "is_entity": false,
+          "is_filter": true,
+          "is_facet": false,
+          "is_multivalue": true,
+          "solr_fields": { "return": "values", "filter": "values" }
+        }
+      },
+      "fieldsets": ["basics"],
+      "metrics": { "count": { "name": "count", "description": "Total count" } },
+      "search_fields": ["name"]
+    },
+    "research_org_groups": {
+      "fields": {
+        "id": {
+          "type": "string",
+          "description": "The Dimensions ID of the group.",
+          "long_description": null,
+          "is_entity": false,
+          "is_filter": true,
+          "is_facet": false,
+          "is_multivalue": false,
+          "solr_fields": { "return": "id", "filter": "id" }
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the group.",
+          "long_description": null,
+          "is_entity": false,
+          "is_filter": true,
+          "is_facet": false,
+          "is_multivalue": false,
+          "solr_fields": { "return": "name", "filter": "name" }
+        },
+        "organization_ids": {
+          "type": "string",
+          "description": "The GRID IDs of the organizations which are members of this group.",
+          "long_description": null,
+          "is_entity": false,
+          "is_filter": true,
+          "is_facet": false,
+          "is_multivalue": true,
+          "solr_fields": { "return": "values", "filter": "values" }
+        }
+      },
+      "fieldsets": ["basics"],
+      "metrics": { "count": { "name": "count", "description": "Total count" } },
+      "search_fields": ["name"]
     }
   },
   "entities": {

package/test/integration/suites/search.integration.ts

@@ -76,5 +76,29 @@ export const searchSuite: EvalSuite = {
       args: { query: "Massachusetts Institute of Technology", limit: 5 },
       assertions: [isSuccess(), hasField("totalCount"), arrayMinLength("organizations", 1)],
     },
+    {
+      name: "search reports for climate",
+      tool: "search_reports",
+      args: { query: "climate change", limit: 5 },
+      assertions: [isSuccess(), hasField("totalCount"), arrayMinLength("reports", 1)],
+    },
+    {
+      name: "search source titles for Nature",
+      tool: "search_source_titles",
+      args: { query: "Nature", limit: 5 },
+      assertions: [isSuccess(), hasField("totalCount"), arrayMinLength("source_titles", 1)],
+    },
+    {
+      name: "search funder groups for NIH",
+      tool: "search_funder_groups",
+      args: { query: "NIH", limit: 5 },
+      assertions: [isSuccess(), hasField("totalCount"), arrayMinLength("funder_groups", 1)],
+    },
+    {
+      name: "search research org groups",
+      tool: "search_research_org_groups",
+      args: { query: "University", limit: 5 },
+      assertions: [isSuccess(), hasField("totalCount"), arrayMinLength("research_org_groups", 1)],
+    },
   ],
 };

package/test/schema/store.test.ts

@@ -41,5 +41,10 @@ describe("SchemaStore", () => {
     const types = store.structuredEntityTypes();
     expect(types).toContain("publications");
     expect(types).toContain("organizations");
+    expect(types).toContain("reports");
+    expect(types).toContain("source_titles");
+    expect(types).toContain("funder_groups");
+    expect(types).toContain("research_org_groups");
+    expect(types).toHaveLength(12);
   });
 });

package/test/server.test.ts

@@ -60,6 +60,9 @@ describe("createMcpServerAsync", () => {
     expect(instructions).toContain("search_researchers matches names only");
     expect(instructions).toContain("research_orgs.id");
     expect(instructions).toContain("funder_orgs");
+    expect(instructions).toContain("search_organizations for institution lookup");
+    expect(instructions).toContain("search_source_titles");
+    expect(instructions).toContain("search_reports");
     expect(instructions).toContain("fetch_search_pages");
     expect(instructions).toContain("dimensions://schema/policy");
   });

package/test/tools/search.test.ts

@@ -37,7 +37,7 @@ describe("search tools", () => {
     registerSearchTools(server as never, client as never, testSchemaStore());
   });
 
-  it("registers all 8 search tools", () => {
+  it("registers all 12 search tools", () => {
     const expectedTools = [
       "search_publications",
       "search_grants",
@@ -47,11 +47,15 @@ describe("search tools", () => {
       "search_datasets",
       "search_policy_documents",
       "search_organizations",
+      "search_reports",
+      "search_source_titles",
+      "search_funder_groups",
+      "search_research_org_groups",
     ];
     for (const name of expectedTools) {
       expect(handlers.has(name)).toBe(true);
     }
-    expect(handlers.size).toBe(8);
+    expect(handlers.size).toBe(12);
   });
 
   describe("search_publications", () => {
@@ -243,6 +247,42 @@ describe("search tools", () => {
     });
   });
 
+  describe("search_reports", () => {
+    it("applies year filters and returns reports", async () => {
+      client.rawQuery.mockResolvedValue(apiRows("reports", [{ id: "rep.1", title: "Report" }], 1));
+
+      const result = await callTool(handlers, "search_reports", {
+        query: "climate",
+        yearFrom: 2020,
+        yearTo: 2024,
+        limit: 10,
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("search reports");
+      expect(dsl).toContain("year >= 2020");
+      expect(dsl).toContain("year <= 2024");
+      expect(parseToolResult(result).reports).toHaveLength(1);
+    });
+  });
+
+  describe("search_funder_groups", () => {
+    it("searches funder groups by name", async () => {
+      client.rawQuery.mockResolvedValue(
+        apiRows("funder_groups", [{ id: "fg.1", name: "NIH Institutes" }], 1),
+      );
+
+      const result = await callTool(handlers, "search_funder_groups", {
+        query: "NIH",
+        limit: 10,
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("search funder_groups");
+      expect(parseToolResult(result).funder_groups).toHaveLength(1);
+    });
+  });
+
   describe("truncation warnings", () => {
     it("includes truncation warning when totalCount exceeds returnedCount", async () => {
       client.rawQuery.mockResolvedValue(

package/tsconfig.tsbuildinfo

@@ -1 +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"}
+{"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/request-retry.ts","./src/client/resolve-api-key-user.ts","./src/client/types.ts","./src/client/usage-context.ts","./src/client/usage-headers.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/usage-tracking.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"}