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

package/test/tools/functions.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for the function MCP tools (extract_affiliations, extract_grants).
+ * @module test/tools/functions
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { registerFunctionTools } from "../../src/mcp/tools/functions.js";
+import {
+  callTool,
+  createMockClient,
+  createMockServer,
+  parseToolResult,
+} from "../helpers/tool-test-harness.js";
+
+describe("function tools", () => {
+  let handlers: ReturnType<typeof createMockServer>["handlers"];
+  let client: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    const { server, handlers: h } = createMockServer();
+    client = createMockClient();
+    handlers = h;
+    registerFunctionTools(server as never, client as never);
+  });
+
+  describe("extract_affiliations", () => {
+    it("passes affiliations array to client", async () => {
+      const affiliations = [
+        { affiliation: "University of Oxford, Department of Physics, UK" },
+        { name: "MIT", city: "Cambridge", country: "US" },
+      ];
+      const extractedAffiliations = [
+        { id: "grid.4991.5", name: "University of Oxford", confidence: 0.95 },
+        { id: "grid.116068.8", name: "Massachusetts Institute of Technology", confidence: 0.99 },
+      ];
+
+      client.extractAffiliations.mockResolvedValueOnce({
+        extracted_affiliations: extractedAffiliations,
+      });
+
+      await callTool(handlers, "extract_affiliations", { affiliations });
+
+      expect(client.extractAffiliations).toHaveBeenCalledTimes(1);
+      expect(client.extractAffiliations).toHaveBeenCalledWith(affiliations);
+    });
+
+    it("returns match count and affiliations", async () => {
+      const extractedAffiliations = [
+        { id: "grid.4991.5", name: "University of Oxford", confidence: 0.95 },
+      ];
+      client.extractAffiliations.mockResolvedValueOnce({
+        extracted_affiliations: extractedAffiliations,
+      });
+
+      const result = await callTool(handlers, "extract_affiliations", {
+        affiliations: [{ affiliation: "University of Oxford, UK" }],
+      });
+      const data = parseToolResult(result);
+
+      expect(data.matchCount).toBe(1);
+      expect(data.affiliations).toEqual(extractedAffiliations);
+    });
+
+    it("handles errors gracefully", async () => {
+      client.extractAffiliations.mockRejectedValueOnce(new Error("Resolution failed"));
+
+      const result = await callTool(handlers, "extract_affiliations", {
+        affiliations: [{ affiliation: "Unknown Org" }],
+      });
+      const data = parseToolResult(result);
+
+      expect(result.isError).toBe(true);
+      expect(data.error).toBe("Resolution failed");
+    });
+  });
+
+  describe("extract_grants", () => {
+    it("maps parameter names correctly", async () => {
+      client.extractGrants.mockResolvedValueOnce({
+        extracted_grants: [{ id: "grant.1", title: "NIH R01 Grant" }],
+      });
+
+      await callTool(handlers, "extract_grants", {
+        grant_number: "R01HL117329",
+        fundref: "100000050",
+        funder_name: "NIH",
+      });
+
+      expect(client.extractGrants).toHaveBeenCalledTimes(1);
+      expect(client.extractGrants).toHaveBeenCalledWith({
+        grantNumber: "R01HL117329",
+        fundref: "100000050",
+        funderName: "NIH",
+      });
+    });
+
+    it("returns match count and grants", async () => {
+      client.extractGrants.mockResolvedValueOnce({
+        grant_id: "grant.2544064",
+      });
+
+      const result = await callTool(handlers, "extract_grants", {
+        grant_number: "R01HL117329",
+      });
+      const data = parseToolResult(result);
+
+      expect(data.matchCount).toBe(1);
+      expect(data.grants).toEqual([{ grant_id: "grant.2544064" }]);
+    });
+
+    it("returns zero matches when grant_id is null", async () => {
+      client.extractGrants.mockResolvedValueOnce({
+        grant_id: null,
+      });
+
+      const result = await callTool(handlers, "extract_grants", {
+        grant_number: "NONEXISTENT-123",
+      });
+      const data = parseToolResult(result);
+
+      expect(data.matchCount).toBe(0);
+      expect(data.grants).toEqual([]);
+    });
+
+    it("passes only grant_number when optional params are omitted", async () => {
+      client.extractGrants.mockResolvedValueOnce({
+        grant_id: null,
+      });
+
+      await callTool(handlers, "extract_grants", {
+        grant_number: "ABC-123",
+      });
+
+      expect(client.extractGrants).toHaveBeenCalledWith({
+        grantNumber: "ABC-123",
+        fundref: undefined,
+        funderName: undefined,
+      });
+    });
+
+    it("handles errors gracefully", async () => {
+      client.extractGrants.mockRejectedValueOnce(new Error("Grant lookup failed"));
+
+      const result = await callTool(handlers, "extract_grants", {
+        grant_number: "R01HL117329",
+      });
+      const data = parseToolResult(result);
+
+      expect(result.isError).toBe(true);
+      expect(data.error).toBe("Grant lookup failed");
+    });
+  });
+});

package/test/tools/lookup.test.ts

@@ -0,0 +1,296 @@
+/**
+ * Tests for the lookup MCP tools (get_by_doi, get_by_pmid, get_by_id).
+ * @module test/tools/lookup
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { registerLookupTools } from "../../src/mcp/tools/lookup.js";
+import {
+  callTool,
+  createMockClient,
+  createMockServer,
+  parseToolResult,
+} from "../helpers/tool-test-harness.js";
+
+describe("lookup tools", () => {
+  let handlers: ReturnType<typeof createMockServer>["handlers"];
+  let client: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    const { server, handlers: h } = createMockServer();
+    client = createMockClient();
+    handlers = h;
+    registerLookupTools(server as never, client as never);
+  });
+
+  describe("get_by_doi", () => {
+    it("generates correct DSL query", async () => {
+      client.rawQuery.mockResolvedValueOnce({
+        publications: [{ id: "pub.123", title: "Test Paper", doi: "10.1038/test" }],
+      });
+
+      await callTool(handlers, "get_by_doi", { doi: "10.1038/test" });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain('where doi = "10.1038/test"');
+      expect(dsl).toContain("search publications");
+      expect(dsl).toContain("limit 1");
+    });
+
+    it("escapes DOI in DSL query", async () => {
+      client.rawQuery.mockResolvedValueOnce({ publications: [] });
+
+      await callTool(handlers, "get_by_doi", { doi: '10.1038/"special' });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain('where doi = "10.1038/\\"special"');
+    });
+
+    it("includes custom fields when specified", async () => {
+      client.rawQuery.mockResolvedValueOnce({
+        publications: [{ id: "pub.123", title: "Test Paper" }],
+      });
+
+      await callTool(handlers, "get_by_doi", {
+        doi: "10.1038/test",
+        fields: ["id", "title"],
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("publications[id+title]");
+    });
+
+    it("returns found publication when match exists", async () => {
+      const pub = { id: "pub.123", title: "Test Paper", doi: "10.1038/test" };
+      client.rawQuery.mockResolvedValueOnce({ publications: [pub] });
+
+      const result = await callTool(handlers, "get_by_doi", { doi: "10.1038/test" });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(true);
+      expect(data.publication).toEqual(pub);
+    });
+
+    it("returns not-found when no publication matches", async () => {
+      client.rawQuery.mockResolvedValueOnce({ publications: [] });
+
+      const result = await callTool(handlers, "get_by_doi", { doi: "10.9999/nonexistent" });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(false);
+      expect(data.message).toContain("No publication found with DOI: 10.9999/nonexistent");
+    });
+
+    it("returns not-found when publications key is missing", async () => {
+      client.rawQuery.mockResolvedValueOnce({});
+
+      const result = await callTool(handlers, "get_by_doi", { doi: "10.9999/missing" });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(false);
+    });
+
+    it("rejects invalid field names", async () => {
+      const result = await callTool(handlers, "get_by_doi", {
+        doi: "10.1038/test",
+        fields: ["id]+title//"],
+      });
+      expect(result.isError).toBe(true);
+      const parsed = parseToolResult(result);
+      expect(parsed.error).toContain("Invalid field name");
+      expect(client.rawQuery).not.toHaveBeenCalled();
+    });
+
+    it("handles errors gracefully", async () => {
+      client.rawQuery.mockRejectedValueOnce(new Error("API rate limit exceeded"));
+
+      const result = await callTool(handlers, "get_by_doi", { doi: "10.1038/test" });
+      const data = parseToolResult(result);
+
+      expect(result.isError).toBe(true);
+      expect(data.error).toBe("API rate limit exceeded");
+    });
+  });
+
+  describe("get_by_pmid", () => {
+    it("generates correct DSL query", async () => {
+      client.rawQuery.mockResolvedValueOnce({
+        publications: [{ id: "pub.456", title: "PMID Paper", pmid: "23846567" }],
+      });
+
+      await callTool(handlers, "get_by_pmid", { pmid: "23846567" });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain('where pmid = "23846567"');
+      expect(dsl).toContain("search publications");
+      expect(dsl).toContain("limit 1");
+    });
+
+    it("returns found publication when match exists", async () => {
+      const pub = { id: "pub.456", title: "PMID Paper", pmid: "23846567" };
+      client.rawQuery.mockResolvedValueOnce({ publications: [pub] });
+
+      const result = await callTool(handlers, "get_by_pmid", { pmid: "23846567" });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(true);
+      expect(data.publication).toEqual(pub);
+    });
+
+    it("returns not-found for unknown PMID", async () => {
+      client.rawQuery.mockResolvedValueOnce({ publications: [] });
+
+      const result = await callTool(handlers, "get_by_pmid", { pmid: "00000000" });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(false);
+      expect(data.message).toContain("No publication found with PMID: 00000000");
+    });
+
+    it("includes custom fields when specified", async () => {
+      client.rawQuery.mockResolvedValueOnce({
+        publications: [{ id: "pub.456", title: "PMID Paper" }],
+      });
+
+      await callTool(handlers, "get_by_pmid", {
+        pmid: "23846567",
+        fields: ["id", "title", "times_cited"],
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("publications[id+title+times_cited]");
+    });
+
+    it("rejects invalid field names", async () => {
+      const result = await callTool(handlers, "get_by_pmid", {
+        pmid: "23846567",
+        fields: ["id]+title//"],
+      });
+      expect(result.isError).toBe(true);
+      const parsed = parseToolResult(result);
+      expect(parsed.error).toContain("Invalid field name");
+      expect(client.rawQuery).not.toHaveBeenCalled();
+    });
+
+    it("handles errors gracefully", async () => {
+      client.rawQuery.mockRejectedValueOnce(new Error("Network failure"));
+
+      const result = await callTool(handlers, "get_by_pmid", { pmid: "23846567" });
+      const data = parseToolResult(result);
+
+      expect(result.isError).toBe(true);
+      expect(data.error).toBe("Network failure");
+    });
+  });
+
+  describe("get_by_id", () => {
+    it("uses entity type in DSL query", async () => {
+      client.rawQuery.mockResolvedValueOnce({
+        grants: [{ id: "grant.123", title: "Test Grant" }],
+      });
+
+      await callTool(handlers, "get_by_id", {
+        entityType: "grants",
+        id: "grant.123",
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain('search grants where id = "grant.123"');
+      expect(dsl).toContain("return grants");
+      expect(dsl).toContain("limit 1");
+    });
+
+    it("returns found entity with entityType", async () => {
+      const entity = { id: "pat.789", title: "Test Patent" };
+      client.rawQuery.mockResolvedValueOnce({ patents: [entity] });
+
+      const result = await callTool(handlers, "get_by_id", {
+        entityType: "patents",
+        id: "pat.789",
+      });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(true);
+      expect(data.entity).toEqual(entity);
+      expect(data.entityType).toBe("patents");
+    });
+
+    it("includes singularized entity name in not-found message", async () => {
+      client.rawQuery.mockResolvedValueOnce({ publications: [] });
+
+      const result = await callTool(handlers, "get_by_id", {
+        entityType: "publications",
+        id: "pub.nonexistent",
+      });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(false);
+      expect(data.message).toContain("No publication found with ID: pub.nonexistent");
+    });
+
+    it("singularizes other entity types in not-found message", async () => {
+      client.rawQuery.mockResolvedValueOnce({ researchers: [] });
+
+      const result = await callTool(handlers, "get_by_id", {
+        entityType: "researchers",
+        id: "res.nonexistent",
+      });
+      const data = parseToolResult(result);
+
+      expect(data.found).toBe(false);
+      expect(data.message).toContain("No researcher found with ID: res.nonexistent");
+    });
+
+    it("includes custom fields when specified", async () => {
+      client.rawQuery.mockResolvedValueOnce({
+        datasets: [{ id: "ds.100", title: "Test Dataset" }],
+      });
+
+      await callTool(handlers, "get_by_id", {
+        entityType: "datasets",
+        id: "ds.100",
+        fields: ["id", "title", "year"],
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain("datasets[id+title+year]");
+    });
+
+    it("escapes ID in DSL query", async () => {
+      client.rawQuery.mockResolvedValueOnce({ publications: [] });
+
+      await callTool(handlers, "get_by_id", {
+        entityType: "publications",
+        id: 'pub."test',
+      });
+
+      const dsl = client.rawQuery.mock.calls[0][0] as string;
+      expect(dsl).toContain('where id = "pub.\\"test"');
+    });
+
+    it("rejects invalid field names", async () => {
+      const result = await callTool(handlers, "get_by_id", {
+        entityType: "grants",
+        id: "grant.123",
+        fields: ["id]+title return publications//"],
+      });
+      expect(result.isError).toBe(true);
+      const parsed = parseToolResult(result);
+      expect(parsed.error).toContain("Invalid field name");
+      expect(client.rawQuery).not.toHaveBeenCalled();
+    });
+
+    it("handles errors gracefully", async () => {
+      client.rawQuery.mockRejectedValueOnce(new Error("Unauthorized"));
+
+      const result = await callTool(handlers, "get_by_id", {
+        entityType: "grants",
+        id: "grant.123",
+      });
+      const data = parseToolResult(result);
+
+      expect(result.isError).toBe(true);
+      expect(data.error).toBe("Unauthorized");
+    });
+  });
+});

package/test/tools/query.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Tests for the query MCP tools (execute_dsl).
+ * Validates raw DSL passthrough, response forwarding, and error handling.
+ * @module test/tools/query
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { registerQueryTools } from "../../src/mcp/tools/query.js";
+import { testSchemaStore } from "../helpers/schema-fixture.js";
+import {
+  callTool,
+  createMockClient,
+  createMockServer,
+  parseToolResult,
+} from "../helpers/tool-test-harness.js";
+
+describe("query tools", () => {
+  let handlers: ReturnType<typeof createMockServer>["handlers"];
+  let server: ReturnType<typeof createMockServer>["server"];
+  let client: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    ({ server, handlers } = createMockServer());
+    client = createMockClient();
+    registerQueryTools(server as never, client as never, testSchemaStore());
+  });
+
+  describe("execute_dsl", () => {
+    it("passes raw DSL query through to client", async () => {
+      const dsl = 'search publications for "test" return publications limit 5';
+      client.rawQuery.mockResolvedValueOnce({ publications: [] });
+
+      await callTool(handlers, "execute_dsl", { dsl });
+
+      expect(client.rawQuery).toHaveBeenCalledTimes(1);
+      expect(client.rawQuery).toHaveBeenCalledWith(dsl);
+    });
+
+    it("returns raw response from client", async () => {
+      const mockResponse = {
+        publications: [{ id: "pub.1", title: "Test Paper", times_cited: 42 }],
+        _stats: { total_count: 1 },
+      };
+      client.rawQuery.mockResolvedValueOnce(mockResponse);
+
+      const result = await callTool(handlers, "execute_dsl", {
+        dsl: 'search publications for "test" return publications limit 5',
+      });
+      const data = parseToolResult(result);
+
+      expect(data.result).toEqual(mockResponse);
+      expect(result.isError).toBeUndefined();
+    });
+
+    it("requires confirmLargeFetch for deep DSL pagination", async () => {
+      const result = await callTool(handlers, "execute_dsl", {
+        dsl: 'search publications for "ml" return publications limit 100 skip 5000',
+      });
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).error).toContain("confirmLargeFetch");
+    });
+
+    it("rejects skip on facet queries", async () => {
+      const result = await callTool(handlers, "execute_dsl", {
+        dsl: 'search publications for "ml" return year limit 20 skip 50',
+      });
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).error).toContain("Facet queries cannot be paginated");
+    });
+
+    it("adds policy hints for large truncated results", async () => {
+      client.rawQuery.mockResolvedValueOnce({
+        publications: [{ id: "pub.1" }],
+        _stats: { total_count: 12_000 },
+      });
+
+      const result = await callTool(handlers, "execute_dsl", {
+        dsl: 'search publications for "ml" return publications limit 1',
+      });
+      const data = parseToolResult(result);
+
+      expect(data.largeResultWarning).toBeDefined();
+      expect(data.paginationHint).toContain("12");
+      expect(data.policyNotice).toBeDefined();
+    });
+
+    it("handles errors gracefully", async () => {
+      client.rawQuery.mockRejectedValueOnce(new Error("Query syntax error"));
+
+      const result = await callTool(handlers, "execute_dsl", {
+        dsl: "invalid query",
+      });
+      const data = parseToolResult(result);
+
+      expect(result.isError).toBe(true);
+      expect(data.error).toBe("Query syntax error");
+      expect(data.type).toBe("Error");
+    });
+  });
+});

package/test/tools/schema.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Tests for schema MCP tools.
+ * @module test/tools/schema
+ */
+
+import { describe, expect, it } from "vitest";
+import { registerSchemaTools } from "../../src/mcp/tools/schema.js";
+import { testSchemaStore } from "../helpers/schema-fixture.js";
+import { callTool, createMockClient, createMockServer } from "../helpers/tool-test-harness.js";
+
+describe("schema tools", () => {
+  const schemaStore = testSchemaStore();
+  const context = { store: schemaStore };
+  const client = createMockClient();
+  const { server, handlers } = createMockServer();
+
+  registerSchemaTools(server as never, client as never, context);
+
+  it("describe_schema returns summary by default", async () => {
+    const result = await callTool(handlers, "describe_schema", {});
+    expect(result.isError).toBeFalsy();
+    const parsed = JSON.parse(result.content[0].text) as Record<string, unknown>;
+    expect(parsed.summary).toBeDefined();
+    expect(parsed.schema).toBeUndefined();
+    const summary = parsed.summary as Record<string, unknown>;
+    expect(summary.resources).toBeDefined();
+    expect(summary.stats).toBeDefined();
+  });
+
+  it("describe_schema returns full schema when full=true", async () => {
+    const result = await callTool(handlers, "describe_schema", { full: true });
+    expect(result.isError).toBeFalsy();
+    const parsed = JSON.parse(result.content[0].text) as Record<string, unknown>;
+    expect(parsed.schema).toBeDefined();
+    expect(parsed.summary).toBeUndefined();
+  });
+});