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

package/test/resources/schema.test.ts

@@ -0,0 +1,28 @@
+/**
+ * Tests for dynamic schema MCP resources.
+ * @module test/resources/schema
+ */
+
+import { describe, expect, it } from "vitest";
+import { registerSchemaResources } from "../../src/mcp/resources/schema.js";
+import { testSchemaStore } from "../helpers/schema-fixture.js";
+
+describe("registerSchemaResources", () => {
+  it("registers schema, limits, examples, and fields resources", () => {
+    const context = { store: testSchemaStore() };
+    const resources: Array<{ name: string; uri: string | { uriTemplate?: string } }> = [];
+    const server = {
+      resource: (name: string, uri: string | { uriTemplate?: string }, ..._rest: unknown[]) => {
+        resources.push({ name, uri });
+      },
+    };
+    registerSchemaResources(server as never, context);
+    expect(resources.some((r) => r.name === "schema-summary")).toBe(true);
+    expect(resources.some((r) => r.name === "schema-full")).toBe(true);
+    expect(resources.some((r) => r.name === "schema-limits")).toBe(true);
+    expect(resources.some((r) => r.name === "schema-policy")).toBe(true);
+    expect(resources.some((r) => r.name === "dsl-examples")).toBe(true);
+    expect(resources.some((r) => r.name === "dsl-examples-by-source")).toBe(true);
+    expect(resources.some((r) => r.name === "fields")).toBe(true);
+  });
+});

package/test/schema/describe-contract.test.ts

@@ -0,0 +1,24 @@
+/**
+ * Contract tests ensuring describe fixture matches expected shape.
+ * @module test/schema/describe-contract
+ */
+
+import { describe, expect, it } from "vitest";
+import { extractDescribeSchema } from "../../src/dsl/index.js";
+import fixture from "../fixtures/describe-schema.json";
+
+describe("describe schema contract", () => {
+  it("fixture has sources and entities", () => {
+    const schema = extractDescribeSchema(fixture);
+    expect(Object.keys(schema.sources).length).toBeGreaterThan(0);
+    expect(Object.keys(schema.entities).length).toBeGreaterThan(0);
+  });
+
+  it("publications source has fields with types", () => {
+    const schema = extractDescribeSchema(fixture);
+    const pub = schema.sources.publications;
+    expect(pub).toBeDefined();
+    expect(pub?.fields.title).toBeDefined();
+    expect(typeof pub?.fields.title?.type).toBe("string");
+  });
+});

package/test/schema/store.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Tests for {@link SchemaStore} parsing and derived views.
+ * @module test/schema/store
+ */
+
+import { describe, expect, it } from "vitest";
+import { createSchemaStoreFromResponse, type DescribeSchemaResponse } from "../../src/dsl/index.js";
+import fixture from "../fixtures/describe-schema.json";
+
+describe("SchemaStore", () => {
+  const store = createSchemaStoreFromResponse(fixture as DescribeSchemaResponse, "2.15.0");
+
+  it("loads sources and entities from fixture", () => {
+    expect(store.sourceNames().length).toBeGreaterThan(8);
+    expect(store.entityNames().length).toBeGreaterThan(0);
+    expect(store.version).toBe("2.15.0");
+  });
+
+  it("derives filterable fields for publications", () => {
+    const fields = store.filterableFields("publications");
+    expect(fields).toContain("year");
+    expect(fields.length).toBeGreaterThan(20);
+  });
+
+  it("derives facet fields for grants", () => {
+    const facets = store.facetFields("grants");
+    expect(facets.length).toBeGreaterThan(0);
+  });
+
+  it("exposes search indexes for publications", () => {
+    const indexes = store.searchIndexes("publications");
+    expect(indexes.length).toBeGreaterThan(0);
+  });
+
+  it("exposes metrics for grants", () => {
+    const metrics = store.metrics("grants");
+    expect(metrics.length).toBeGreaterThan(0);
+  });
+
+  it("structuredEntityTypes intersects structured entity list with loaded sources", () => {
+    const types = store.structuredEntityTypes();
+    expect(types).toContain("publications");
+    expect(types).toContain("organizations");
+  });
+});

package/test/server.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Tests for the MCP server factory function and startup lifecycle.
+ * @module test/server
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  buildServerInstructions,
+  createMcpServerAsync,
+  startMcpServer,
+} from "../src/mcp/server.js";
+import { testSchemaStore } from "./helpers/schema-fixture.js";
+
+describe("createMcpServerAsync", () => {
+  const originalEnv = process.env.DIMENSIONS_API_KEY;
+
+  beforeEach(() => {
+    delete process.env.DIMENSIONS_API_KEY;
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.DIMENSIONS_API_KEY = originalEnv;
+    } else {
+      delete process.env.DIMENSIONS_API_KEY;
+    }
+  });
+
+  it("throws when no API key is provided via config or env", async () => {
+    await expect(createMcpServerAsync()).rejects.toThrow("Dimensions API key required");
+  });
+
+  it("accepts API key via config parameter", async () => {
+    const { server } = await createMcpServerAsync({
+      apiKey: "test-key-123",
+      schemaStore: testSchemaStore(),
+    });
+    expect(server).toBeDefined();
+  });
+
+  it("accepts API key via environment variable", async () => {
+    process.env.DIMENSIONS_API_KEY = "env-key-456";
+    const { server } = await createMcpServerAsync({ schemaStore: testSchemaStore() });
+    expect(server).toBeDefined();
+  });
+
+  it("returns a configured McpServer instance", async () => {
+    const { server } = await createMcpServerAsync({
+      apiKey: "test-key",
+      schemaStore: testSchemaStore(),
+    });
+    expect(server.server).toBeDefined();
+  });
+
+  it("builds server instructions with agent routing hints", () => {
+    const instructions = buildServerInstructions(testSchemaStore());
+    expect(instructions).toContain("facet_query");
+    expect(instructions).toContain("search_researchers matches names only");
+    expect(instructions).toContain("research_orgs.id");
+    expect(instructions).toContain("funder_orgs");
+    expect(instructions).toContain("fetch_search_pages");
+    expect(instructions).toContain("dimensions://schema/policy");
+  });
+});
+
+describe("startMcpServer", () => {
+  const originalApiKey = process.env.DIMENSIONS_API_KEY;
+
+  beforeEach(() => {
+    process.env.DIMENSIONS_API_KEY = "test-key-for-startup";
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (originalApiKey !== undefined) {
+      process.env.DIMENSIONS_API_KEY = originalApiKey;
+    } else {
+      delete process.env.DIMENSIONS_API_KEY;
+    }
+  });
+
+  it("accepts an injected transport and returns a handle with close", async () => {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    const handle = await startMcpServer(serverTransport, {
+      apiKey: "test-key",
+      schemaStore: testSchemaStore(),
+    });
+
+    const client = new Client({ name: "test-client", version: "1.0.0" });
+    await client.connect(clientTransport);
+
+    expect(handle).toBeDefined();
+    expect(typeof handle.close).toBe("function");
+
+    await client.close();
+    await handle.close();
+  });
+
+  it("does not call process.exit when using injected transport", async () => {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+
+    const handle = await startMcpServer(serverTransport, {
+      apiKey: "test-key",
+      schemaStore: testSchemaStore(),
+    });
+
+    const client = new Client({ name: "test-client", version: "1.0.0" });
+    await client.connect(clientTransport);
+
+    await client.close();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(exitSpy).not.toHaveBeenCalled();
+    await handle.close();
+  });
+});
+
+describe("MCP protocol", () => {
+  it("lists DSL tools and schema resources over in-memory transport", async () => {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const handle = await startMcpServer(serverTransport, {
+      apiKey: "test-key",
+      schemaStore: testSchemaStore(),
+    });
+
+    const client = new Client({ name: "test-client", version: "1.0.0" });
+    await client.connect(clientTransport);
+
+    const tools = await client.listTools();
+    const toolNames = tools.tools.map((t) => t.name);
+    expect(toolNames).toContain("search_publications");
+    expect(toolNames).toContain("fetch_search_pages");
+    expect(toolNames).toContain("execute_dsl");
+    expect(toolNames).not.toContain("validate_dsl");
+
+    const resources = await client.listResources();
+    const uris = resources.resources.map((r) => r.uri);
+    expect(uris.some((u) => u.startsWith("dimensions://schema"))).toBe(true);
+
+    const schemaResource = await client.readResource({ uri: "dimensions://schema" });
+    expect(schemaResource.contents.length).toBeGreaterThan(0);
+
+    await client.close();
+    await handle.close();
+  });
+
+  it("calls describe_schema via in-memory transport", async () => {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const handle = await startMcpServer(serverTransport, {
+      apiKey: "test-key",
+      schemaStore: testSchemaStore(),
+    });
+
+    const client = new Client({ name: "test-client", version: "1.0.0" });
+    await client.connect(clientTransport);
+
+    const result = await client.callTool({
+      name: "describe_schema",
+      arguments: {},
+    });
+    expect(result.isError).toBeFalsy();
+
+    await client.close();
+    await handle.close();
+  });
+});

package/test/tools/analytics-filters.test.ts

@@ -0,0 +1,35 @@
+/**
+ * @module test/tools/analytics-filters
+ */
+
+import { describe, expect, it } from "vitest";
+import { DimensionsClient } from "../../src/dsl/index.js";
+import { applyAnalyticsFilters } from "../../src/mcp/tools/analytics-filters.js";
+
+describe("applyAnalyticsFilters", () => {
+  const client = new DimensionsClient({ apiKey: "test" });
+
+  it("applies yearFrom and yearTo for publications", () => {
+    const builder = client.createQueryBuilder().search("publications").for("machine learning");
+    applyAnalyticsFilters(builder, "publications", { yearFrom: 2020, yearTo: 2024 });
+    const dsl = builder.returnFacet("type", { limit: 10 }).build();
+    expect(dsl).toContain("year >= 2020");
+    expect(dsl).toContain("year <= 2024");
+  });
+
+  it("applies start_year range for grants", () => {
+    const builder = client.createQueryBuilder().search("grants").for("cancer");
+    applyAnalyticsFilters(builder, "grants", { yearFrom: 2019 });
+    const dsl = builder.returnFacet("funders", { limit: 5 }).build();
+    expect(dsl).toContain("start_year >= 2019");
+  });
+
+  it("applies extended filters", () => {
+    const builder = client.createQueryBuilder().search("publications").for("CRISPR");
+    applyAnalyticsFilters(builder, "publications", {
+      filters: [{ field: "type", operator: "=", value: "article" }],
+    });
+    const dsl = builder.returnFacet("journal", { limit: 5 }).build();
+    expect(dsl).toContain('type = "article"');
+  });
+});