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

package/test/client/http-client.test.ts

@@ -10,6 +10,7 @@ import {
 } from "../../src/client/errors.js";
 import { HttpClient } from "../../src/client/http-client.js";
 import { RateLimiter } from "../../src/client/rate-limiter.js";
+import * as requestRetry from "../../src/client/request-retry.js";
 
 /**
  * Creates a mock auth provider for testing.
@@ -42,6 +43,7 @@ describe("HttpClient", () => {
 
   afterEach(() => {
     globalThis.fetch = originalFetch;
+    requestRetry.resetRequestRetryDelayFn();
     vi.restoreAllMocks();
   });
 
@@ -156,7 +158,7 @@ describe("HttpClient", () => {
 
   describe("retry behavior", () => {
     it("retries on 429 rate limit error", async () => {
-      vi.spyOn(client as never, "delay" as never).mockResolvedValue(undefined as never);
+      requestRetry.setRequestRetryDelayFn(async () => {});
 
       const mockFetch = vi
         .fn()
@@ -239,7 +241,7 @@ describe("HttpClient", () => {
     });
 
     it("exhausts retries and throws RateLimitError", async () => {
-      vi.spyOn(client as never, "delay" as never).mockResolvedValue(undefined as never);
+      requestRetry.setRequestRetryDelayFn(async () => {});
 
       const mockFetch = vi.fn().mockResolvedValue({
         ok: false,
@@ -279,9 +281,8 @@ describe("HttpClient", () => {
         rateLimiter,
       });
 
-      const delaySpy = vi
-        .spyOn(limitedClient as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delaySpy = vi.fn(async () => {});
+      requestRetry.setRequestRetryDelayFn(delaySpy);
 
       const mockFetch = vi
         .fn()
@@ -304,9 +305,8 @@ describe("HttpClient", () => {
     });
 
     it("uses exponential backoff for 5xx errors", async () => {
-      const delaySpy = vi
-        .spyOn(client as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delaySpy = vi.fn(async () => {});
+      requestRetry.setRequestRetryDelayFn(delaySpy);
 
       const mockFetch = vi
         .fn()
@@ -349,9 +349,8 @@ describe("HttpClient", () => {
         retryDelay: 100000, // Very large base delay
       });
 
-      const delaySpy = vi
-        .spyOn(largeDelayClient as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delaySpy = vi.fn(async () => {});
+      requestRetry.setRequestRetryDelayFn(delaySpy);
 
       const mockFetch = vi
         .fn()
@@ -385,9 +384,10 @@ describe("HttpClient", () => {
         rateLimiter,
       });
 
-      const delaySpy = vi
-        .spyOn(limitedClient as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delays: number[] = [];
+      requestRetry.setRequestRetryDelayFn(async (ms) => {
+        delays.push(ms);
+      });
 
       const mockFetch = vi
         .fn()
@@ -405,8 +405,8 @@ describe("HttpClient", () => {
 
       await limitedClient.query("search publications");
 
-      expect(delaySpy).toHaveBeenCalledTimes(1);
-      expect(delaySpy).toHaveBeenCalledWith(60_000);
+      expect(delays).toHaveLength(1);
+      expect(delays[0]).toBe(60_000);
     });
   });
 
@@ -865,7 +865,7 @@ describe("HttpClient", () => {
     });
 
     it("retries postJson on rate limit error", async () => {
-      vi.spyOn(client as never, "delay" as never).mockResolvedValue(undefined as never);
+      requestRetry.setRequestRetryDelayFn(async () => {});
 
       const mockFetch = vi
         .fn()

package/test/client/internal-dsl-client.test.ts

@@ -6,6 +6,16 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { QuerySyntaxError } from "../../src/client/errors.js";
 import { InternalDslClient } from "../../src/client/internal-dsl-client.js";
+import * as requestRetry from "../../src/client/request-retry.js";
+import { runWithMcpTool, setMcpUsageSession } from "../../src/client/usage-context.js";
+import {
+  USAGE_HEADER_CHANNEL,
+  USAGE_HEADER_MCP_CLIENT,
+  USAGE_HEADER_MCP_DEPLOYMENT,
+  USAGE_HEADER_MCP_SESSION_ID,
+  USAGE_HEADER_MCP_TOOL,
+  USAGE_HEADER_MCP_VERSION,
+} from "../../src/client/usage-headers.js";
 import { mockFetchJson } from "./helpers/mock-fetch.js";
 
 const CONFIG = {
@@ -22,10 +32,18 @@ describe("InternalDslClient", () => {
 
   afterEach(() => {
     globalThis.fetch = originalFetch;
+    requestRetry.resetRequestRetryDelayFn();
     vi.restoreAllMocks();
   });
 
-  it("posts JSON query with service auth and user header", async () => {
+  it("posts JSON query with service auth, user header, and MCP usage headers", async () => {
+    setMcpUsageSession({
+      sessionId: "550e8400-e29b-41d4-a716-446655440000",
+      deployment: "hosted",
+      client: "cursor",
+      version: "1.0.4",
+    });
+
     const responseBody = { publications: [] };
     const mock = mockFetchJson(responseBody);
 
@@ -35,7 +53,9 @@ describe("InternalDslClient", () => {
       clientIp: "198.51.100.4",
     });
 
-    const result = await client.query("search publications return publications limit 1");
+    const result = await runWithMcpTool("search_publications", () =>
+      client.query("search publications return publications limit 1"),
+    );
 
     expect(result).toEqual(responseBody);
     expect(mock).toHaveBeenCalledWith(
@@ -47,20 +67,19 @@ describe("InternalDslClient", () => {
           "X-DIMENSIONS-USER": "user@example.com",
           "X-Forwarded-For": "198.51.100.4",
           Authorization: `Basic ${Buffer.from("svc:secret").toString("base64")}`,
+          [USAGE_HEADER_CHANNEL]: "mcp",
+          [USAGE_HEADER_MCP_TOOL]: "search_publications",
+          [USAGE_HEADER_MCP_SESSION_ID]: "550e8400-e29b-41d4-a716-446655440000",
+          [USAGE_HEADER_MCP_CLIENT]: "cursor",
+          [USAGE_HEADER_MCP_VERSION]: "1.0.4",
+          [USAGE_HEADER_MCP_DEPLOYMENT]: "hosted",
+          "User-Agent": "dimensions-analytics-mcp/1.0.4 (cursor)",
         }),
         body: JSON.stringify({
           query: "search publications return publications limit 1",
           dsl_schema: "external",
           host: "app.example.com",
           variant: "standard",
-          additional_logging_info: {
-            user: "user@example.com",
-            dimensions_user: "user@example.com",
-            channel: "mcp",
-            mcp_user: "mcp+user@example.com",
-            product_variant: "standard",
-            source: "dimensions-analytics-mcp-hosted",
-          },
         }),
       }),
     );
@@ -76,4 +95,48 @@ describe("InternalDslClient", () => {
 
     await expect(client.query("bad query")).rejects.toBeInstanceOf(QuerySyntaxError);
   });
+
+  it("retries on 429 and 5xx like the public HttpClient", async () => {
+    requestRetry.setRequestRetryDelayFn(async () => {});
+
+    const mockFetch = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        statusText: "Too Many Requests",
+        json: () => Promise.resolve({ error: "rate limited" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ publications: [] }),
+      });
+    globalThis.fetch = mockFetch;
+
+    const client = new InternalDslClient({
+      config: CONFIG,
+      userEmail: "user@example.com",
+      clientIp: "198.51.100.4",
+      maxRetries: 2,
+      retryDelay: 10,
+    });
+
+    const result = await client.query("search publications return publications limit 1");
+    expect(result).toEqual({ publications: [] });
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not set X-Forwarded-For when clientIp is omitted", async () => {
+    mockFetchJson({ publications: [] });
+
+    const client = new InternalDslClient({
+      config: CONFIG,
+      userEmail: "user@example.com",
+    });
+
+    await client.query("search publications return publications limit 1");
+
+    const [, fetchOptions] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(fetchOptions.headers["X-Forwarded-For"]).toBeUndefined();
+  });
 });

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/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"}