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

package/src/mcp/tools/fetch-search-pages.ts

@@ -0,0 +1,329 @@
+/**
+ * Multi-page search fetch tool for Dimensions DSL queries.
+ * Supports single-page, aggregate, and JSONL file export modes.
+ * @module mcp/tools/fetch-search-pages
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ValidationError } from "../../client/index.js";
+import {
+  DEFAULT_BATCH_MAX_PAGES,
+  type DimensionsClient,
+  HARD_MAX_BATCH_PAGES,
+  parseEntityResponse,
+  resolveSkipAndLimit,
+  SCHEMA_LIMITS,
+  type SchemaStore,
+  STRUCTURED_ENTITY_TYPES,
+  type StructuredEntityType,
+  searchResultKey,
+  validateBatchPagination,
+  validateSearchPaginationPolicy,
+} from "../../dsl/index.js";
+import { queryHashFromDsl, runAggregateFetch, runFileFetch } from "../batch-fetch.js";
+import { resolveExportFormat } from "../export-format.js";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import {
+  formatErrorResult,
+  formatToolResult,
+  READ_ONLY_API_ANNOTATIONS,
+  withSearchPagination,
+} from "../utils.js";
+import { buildStructuredSearchDsl } from "./search.js";
+import { SEARCH_ENTITY_METADATA } from "./search-entity-metadata.js";
+import { PAGINATION_OUTPUT_SCHEMA, SHARED_SEARCH_INPUT } from "./search-input.js";
+
+/** Merged optional convenience filters from all entity search tools. */
+const MERGED_ENTITY_INPUT = Object.assign(
+  {},
+  ...SEARCH_ENTITY_METADATA.map((m) => m.extraInputSchema),
+);
+
+/** Shared search fields without `limit` — fetch uses `pageSize` to avoid Zod default conflicts. */
+const { limit: _searchLimit, ...FETCH_SEARCH_INPUT } = SHARED_SEARCH_INPUT;
+
+const FETCH_MODE_SCHEMA = z
+  .enum(["page", "aggregate", "file"])
+  .default("page")
+  .describe(
+    "page: return one page in the tool response; aggregate: fetch multiple pages and return summary only; file: stream JSONL or CSV to outputPath (not returned in chat)",
+  );
+
+/** Parsed input for fetch_search_pages (after MCP SDK validation). */
+type FetchSearchPagesArgs = {
+  entityType: StructuredEntityType;
+  mode?: "page" | "aggregate" | "file";
+  query?: string;
+  skip?: number;
+  page?: number;
+  pageSize?: number;
+  startPage?: number;
+  maxPages?: number;
+  maxRecords?: number;
+  outputPath?: string;
+  outputFormat?: "jsonl" | "csv";
+  resumeFromMeta?: boolean;
+  confirmLargeFetch?: boolean;
+  fields?: string[];
+  filters?: unknown[];
+  sortBy?: string;
+  [key: string]: unknown;
+};
+
+/**
+ * Registers the fetch_search_pages tool.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ * @param schemaStore - Loaded describe schema
+ */
+export function registerFetchSearchPagesTools(
+  server: McpServer,
+  client: DimensionsClient,
+  schemaStore: SchemaStore,
+): void {
+  const entityList = schemaStore.structuredEntityTypes().join(", ");
+
+  server.registerTool(
+    "fetch_search_pages",
+    {
+      description:
+        `Fetch paginated search results with rate-limit-aware batching (max ${SCHEMA_LIMITS.maxLimit}/page, ` +
+        `${SCHEMA_LIMITS.maxPages} pages, ${SCHEMA_LIMITS.maxOffset} records total). ` +
+        "Default mode returns one page. Use aggregate for ID counts/sums without full rows. " +
+        "Use file mode to stream JSONL or CSV locally — never for bulk mirroring of Dimensions data. " +
+        `Entities: ${entityList}.`,
+      inputSchema: {
+        entityType: z
+          .enum(STRUCTURED_ENTITY_TYPES)
+          .describe("Dimensions source to search (same as search_* tools)"),
+        mode: FETCH_MODE_SCHEMA,
+        ...FETCH_SEARCH_INPUT,
+        ...MERGED_ENTITY_INPUT,
+        pageSize: z
+          .number()
+          .int()
+          .min(1)
+          .max(SCHEMA_LIMITS.maxLimit)
+          .optional()
+          .describe(
+            `Records per page (page mode default 100, aggregate/file default 1000; max ${SCHEMA_LIMITS.maxLimit})`,
+          ),
+        startPage: z
+          .number()
+          .int()
+          .min(0)
+          .max(SCHEMA_LIMITS.maxPages - 1)
+          .optional()
+          .describe("Starting page for aggregate/file modes (0-based, default 0)"),
+        maxPages: z
+          .number()
+          .int()
+          .min(1)
+          .max(HARD_MAX_BATCH_PAGES)
+          .default(DEFAULT_BATCH_MAX_PAGES)
+          .describe(
+            `Pages to fetch in aggregate/file modes (default ${DEFAULT_BATCH_MAX_PAGES}, max ${HARD_MAX_BATCH_PAGES}). Ignored in page mode.`,
+          ),
+        maxRecords: z
+          .number()
+          .int()
+          .min(1)
+          .max(SCHEMA_LIMITS.maxOffset)
+          .optional()
+          .describe("Stop after this many records across pages"),
+        outputPath: z
+          .string()
+          .optional()
+          .describe("Required for file mode — local output path (.jsonl or .csv)"),
+        outputFormat: z
+          .enum(["jsonl", "csv"])
+          .optional()
+          .describe(
+            "File format for file mode (default: infer from outputPath extension, else JSONL)",
+          ),
+        resumeFromMeta: z
+          .boolean()
+          .optional()
+          .default(false)
+          .describe("Resume file export from existing outputPath.meta.json sidecar"),
+        confirmLargeFetch: z
+          .boolean()
+          .optional()
+          .default(false)
+          .describe(
+            "Required when maxPages > 5 or planned records > 5000. Acknowledges reasonable-use policy.",
+          ),
+      },
+      outputSchema: {
+        mode: z.string(),
+        entityType: z.string(),
+        totalCount: z.number().optional(),
+        returnedCount: z.number().optional(),
+        pagesFetched: z.number().optional(),
+        ...PAGINATION_OUTPUT_SCHEMA,
+        outputPath: z.string().optional(),
+        outputFormat: z.string().optional(),
+        metaPath: z.string().optional(),
+        recordsWritten: z.number().optional(),
+        resumed: z.boolean().optional(),
+        aggregate: z
+          .object({
+            ids: z.array(z.string()),
+            idsTruncated: z.boolean(),
+            totalFundingUsd: z.number().optional(),
+          })
+          .optional(),
+      },
+      annotations: READ_ONLY_API_ANNOTATIONS,
+    },
+    withFieldAliases(
+      {
+        entitySource: { kind: "dynamic", argName: "entityType" },
+        fieldArrayArgs: ["fields"],
+        fieldStringArgs: ["sortBy"],
+        filterArrayArgs: ["filters"],
+      },
+      async (args: FetchSearchPagesArgs) => {
+        try {
+          const entityType = args.entityType;
+          const mode = args.mode ?? "page";
+          const pageSize = args.pageSize ?? (mode === "page" ? 100 : 1000);
+          const startPage = args.page ?? args.startPage ?? 0;
+          const maxPages = mode === "page" ? 1 : (args.maxPages ?? DEFAULT_BATCH_MAX_PAGES);
+
+          validateBatchPagination({
+            startPage,
+            maxPages,
+            pageSize,
+            maxRecords: args.maxRecords,
+            confirmLargeFetch: args.confirmLargeFetch,
+          });
+
+          if (mode === "page") {
+            const pageSkip =
+              args.skip !== undefined || args.page !== undefined
+                ? resolveSkipAndLimit({
+                    skip: args.skip,
+                    page: args.page,
+                    limit: pageSize,
+                  }).skip
+                : startPage * pageSize;
+            validateSearchPaginationPolicy({
+              skip: pageSkip,
+              limit: pageSize,
+              confirmLargeFetch: args.confirmLargeFetch,
+            });
+          }
+
+          const buildDsl = (skip: number, limit: number) =>
+            buildStructuredSearchDsl(client, entityType, {
+              ...args,
+              skip,
+              limit,
+              pageSize: limit,
+            });
+
+          if (mode === "file") {
+            if (!args.outputPath) {
+              return formatErrorResult(
+                new ValidationError("outputPath is required for file mode", { mode: "file" }),
+              );
+            }
+            const outputFormat = resolveExportFormat(args.outputPath, args.outputFormat);
+            const sampleDsl = buildDsl(startPage * pageSize, pageSize);
+            const hash = queryHashFromDsl(sampleDsl);
+            const fileResult = await runFileFetch(client, entityType, buildDsl, args.outputPath, {
+              startPage,
+              maxPages,
+              pageSize,
+              maxRecords: args.maxRecords,
+              queryHash: hash,
+              format: outputFormat,
+              preferredFields: args.fields,
+              resumeFromMeta: args.resumeFromMeta,
+            });
+            return formatToolResult({
+              mode: "file",
+              entityType,
+              totalCount: fileResult.totalCount,
+              pagesFetched: fileResult.pagesFetched,
+              recordsWritten: fileResult.recordsWritten,
+              outputPath: fileResult.outputPath,
+              outputFormat: fileResult.format,
+              metaPath: fileResult.metaPath,
+              resumed: fileResult.resumed,
+              largeResultWarning:
+                fileResult.totalCount > 10_000
+                  ? `${fileResult.totalCount} total matches — export may require many requests at ${SCHEMA_LIMITS.requestsPerMinute}/min.`
+                  : undefined,
+            });
+          }
+
+          if (mode === "aggregate") {
+            const summary = await runAggregateFetch(client, entityType, buildDsl, {
+              startPage,
+              maxPages,
+              pageSize,
+              maxRecords: args.maxRecords,
+            });
+            return formatToolResult({
+              mode: "aggregate",
+              entityType,
+              totalCount: summary.totalCount,
+              returnedCount: summary.recordsFetched,
+              pagesFetched: summary.pagesFetched,
+              aggregate: {
+                ids: summary.ids,
+                idsTruncated: summary.idsTruncated,
+                ...(summary.totalFundingUsd !== undefined
+                  ? { totalFundingUsd: summary.totalFundingUsd }
+                  : {}),
+              },
+              truncated: summary.totalCount > summary.recordsFetched,
+              truncationWarning:
+                summary.totalCount > summary.recordsFetched
+                  ? `Fetched ${summary.recordsFetched} of ${summary.totalCount} records across ${summary.pagesFetched} page(s). Increase maxPages or use file mode for full export.`
+                  : undefined,
+            });
+          }
+
+          // mode === "page"
+          const { skip, limit } = resolveSkipAndLimit(
+            args.skip !== undefined || args.page !== undefined
+              ? {
+                  skip: args.skip,
+                  page: args.page,
+                  limit: pageSize,
+                }
+              : { skip: startPage * pageSize, limit: pageSize },
+          );
+          const dsl = buildDsl(skip, limit);
+          const response = (await client.rawQuery(dsl)) as Record<string, unknown>;
+          const parsed = parseEntityResponse(response, entityType);
+          const rows = parsed.data as Record<string, unknown>[];
+          const resultKey = searchResultKey(entityType);
+
+          return formatToolResult(
+            withSearchPagination(
+              {
+                mode: "page",
+                entityType,
+                totalCount: parsed.totalCount,
+                returnedCount: rows.length,
+                pagesFetched: 1,
+                [resultKey]: rows,
+              },
+              parsed.totalCount,
+              rows.length,
+              skip,
+              limit,
+            ),
+          );
+        } catch (error) {
+          return formatErrorResult(error);
+        }
+      },
+    ),
+  );
+}

package/src/mcp/tools/functions.ts

@@ -0,0 +1,105 @@
+/**
+ * Special function tools for the MCP server.
+ * Entity resolution helpers (affiliations, grants).
+ * @module mcp/tools/functions
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { DimensionsClient } from "../../dsl/index.js";
+import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "../utils.js";
+
+/**
+ * Registers special function tools with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerFunctionTools(server: McpServer, client: DimensionsClient): void {
+  server.registerTool(
+    "extract_affiliations",
+    {
+      description:
+        "Resolve and disambiguate organization affiliations using Dimensions entity resolution. " +
+        "Takes freetext affiliation strings or structured organization data and returns matched " +
+        "organizations with GRID/ROR identifiers and confidence scores.",
+      inputSchema: {
+        affiliations: z
+          .array(
+            z.object({
+              affiliation: z
+                .string()
+                .optional()
+                .describe("Freetext affiliation string (e.g., 'University of Oxford, UK')"),
+              name: z.string().optional().describe("Organization name"),
+              city: z.string().optional().describe("City"),
+              state: z.string().optional().describe("State/province"),
+              country: z.string().optional().describe("Country"),
+            }),
+          )
+          .min(1)
+          .describe(
+            "Array of affiliations to resolve. Each must have either 'affiliation' or 'name'",
+          ),
+      },
+      outputSchema: {
+        matchCount: z.number().describe("Number of resolved affiliations"),
+        affiliations: z.array(z.record(z.string(), z.unknown())).describe("Resolved affiliations"),
+      },
+      annotations: READ_ONLY_API_ANNOTATIONS,
+    },
+    async (args) => {
+      try {
+        const result = await client.extractAffiliations(args.affiliations);
+
+        return formatToolResult({
+          matchCount: result.extracted_affiliations.length,
+          affiliations: result.extracted_affiliations,
+        });
+      } catch (error) {
+        return formatErrorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "extract_grants",
+    {
+      description:
+        "Resolve grant numbers to Dimensions grant records. " +
+        "Takes a grant number and optional funder information to find matching grants " +
+        "with full metadata including funding amounts, dates, and funder details.",
+      inputSchema: {
+        grant_number: z.string().min(1).describe("Grant number to look up (e.g., 'R01HL117329')"),
+        fundref: z
+          .string()
+          .optional()
+          .describe("FundRef ID of the funder (e.g., '100000050' for NIH)"),
+        funder_name: z
+          .string()
+          .optional()
+          .describe("Funder name as alternative to FundRef ID (e.g., 'NIH')"),
+      },
+      outputSchema: {
+        matchCount: z.number().describe("Number of matched grants"),
+        grants: z.array(z.record(z.string(), z.unknown())).describe("Matched grant records"),
+      },
+      annotations: READ_ONLY_API_ANNOTATIONS,
+    },
+    async (args) => {
+      try {
+        const result = await client.extractGrants({
+          grantNumber: args.grant_number,
+          fundref: args.fundref,
+          funderName: args.funder_name,
+        });
+
+        return formatToolResult({
+          matchCount: result.grant_id ? 1 : 0,
+          grants: result.grant_id ? [{ grant_id: result.grant_id }] : [],
+        });
+      } catch (error) {
+        return formatErrorResult(error);
+      }
+    },
+  );
+}

package/src/mcp/tools/lookup.ts

@@ -0,0 +1,182 @@
+/**
+ * Lookup tools for the MCP server.
+ * Provides direct lookup by identifiers (DOI, PMID, Dimensions ID).
+ * @module mcp/tools/lookup
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { type DimensionsClient, EntitySchema, type EntityType } from "../../dsl/index.js";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import {
+  asArray,
+  formatErrorResult,
+  formatToolResult,
+  READ_ONLY_API_ANNOTATIONS,
+} from "../utils.js";
+
+/**
+ * Registers all lookup tools with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerLookupTools(server: McpServer, client: DimensionsClient): void {
+  // Get publication by DOI
+  server.registerTool(
+    "get_by_doi",
+    {
+      description:
+        "Retrieve a publication by its Digital Object Identifier (DOI). Returns full publication details including abstract, citations, and authors.",
+      inputSchema: {
+        doi: z.string().describe("The DOI to look up (e.g., '10.1038/nature12373')"),
+        fields: z
+          .array(z.string())
+          .optional()
+          .describe("Fields to return (e.g., ['id', 'title', 'abstract', 'times_cited'])"),
+      },
+      outputSchema: {
+        found: z.boolean().describe("Whether the entity was found"),
+        publication: z.record(z.string(), z.unknown()).optional().describe("The found entity"),
+        message: z.string().optional().describe("Message when not found"),
+      },
+      annotations: READ_ONLY_API_ANNOTATIONS,
+    },
+    withFieldAliases(
+      { entitySource: { kind: "static", entity: "publications" }, fieldArrayArgs: ["fields"] },
+      async (args) => {
+        try {
+          const qb = client
+            .createQueryBuilder()
+            .search("publications")
+            .where("doi", "=", args.doi)
+            .limit(1);
+          if (args.fields?.length) qb.fields(args.fields);
+          const dsl = qb.build();
+
+          const response = await client.rawQuery(dsl);
+          const publications = asArray(response.publications);
+
+          if (publications.length === 0) {
+            return formatToolResult({
+              found: false,
+              message: `No publication found with DOI: ${args.doi}`,
+            });
+          }
+
+          return formatToolResult({
+            found: true,
+            publication: publications[0],
+          });
+        } catch (error) {
+          return formatErrorResult(error);
+        }
+      },
+    ),
+  );
+
+  // Get publication by PubMed ID
+  server.registerTool(
+    "get_by_pmid",
+    {
+      description:
+        "Retrieve a publication by its PubMed ID (PMID). Returns full publication details from Dimensions.",
+      inputSchema: {
+        pmid: z.string().describe("The PubMed ID to look up (e.g., '23846567')"),
+        fields: z
+          .array(z.string())
+          .optional()
+          .describe("Fields to return (e.g., ['id', 'title', 'abstract', 'times_cited'])"),
+      },
+      outputSchema: {
+        found: z.boolean().describe("Whether the entity was found"),
+        publication: z.record(z.string(), z.unknown()).optional().describe("The found entity"),
+        message: z.string().optional().describe("Message when not found"),
+      },
+      annotations: READ_ONLY_API_ANNOTATIONS,
+    },
+    withFieldAliases(
+      { entitySource: { kind: "static", entity: "publications" }, fieldArrayArgs: ["fields"] },
+      async (args) => {
+        try {
+          const qb = client
+            .createQueryBuilder()
+            .search("publications")
+            .where("pmid", "=", args.pmid)
+            .limit(1);
+          if (args.fields?.length) qb.fields(args.fields);
+          const dsl = qb.build();
+
+          const response = await client.rawQuery(dsl);
+          const publications = asArray(response.publications);
+
+          if (publications.length === 0) {
+            return formatToolResult({
+              found: false,
+              message: `No publication found with PMID: ${args.pmid}`,
+            });
+          }
+
+          return formatToolResult({
+            found: true,
+            publication: publications[0],
+          });
+        } catch (error) {
+          return formatErrorResult(error);
+        }
+      },
+    ),
+  );
+
+  // Get entity by Dimensions ID
+  server.registerTool(
+    "get_by_id",
+    {
+      description:
+        "Retrieve any entity by its Dimensions ID. Supports publications, grants, patents, clinical trials, datasets, policy documents, researchers, and organizations.",
+      inputSchema: {
+        entityType: EntitySchema.describe("The type of entity to look up"),
+        id: z.string().describe("The Dimensions ID to look up"),
+        fields: z.array(z.string()).optional().describe("Fields to return"),
+      },
+      outputSchema: {
+        found: z.boolean().describe("Whether the entity was found"),
+        entity: z.record(z.string(), z.unknown()).optional().describe("The found entity"),
+        entityType: z.string().optional().describe("The type of the found entity"),
+        message: z.string().optional().describe("Message when not found"),
+      },
+      annotations: READ_ONLY_API_ANNOTATIONS,
+    },
+    withFieldAliases(
+      { entitySource: { kind: "dynamic", argName: "entityType" }, fieldArrayArgs: ["fields"] },
+      async (args) => {
+        try {
+          const qb = client
+            .createQueryBuilder()
+            .search(args.entityType as EntityType)
+            .where("id", "=", args.id)
+            .limit(1);
+          if (args.fields?.length) qb.fields(args.fields);
+          const dsl = qb.build();
+
+          const response = await client.rawQuery(dsl);
+          const entities = asArray(response[args.entityType]);
+
+          if (entities.length === 0) {
+            return formatToolResult({
+              found: false,
+              message: `No ${args.entityType.slice(0, -1)} found with ID: ${args.id}`,
+            });
+          }
+
+          return formatToolResult({
+            found: true,
+            entity: entities[0],
+            entityType: args.entityType,
+          });
+        } catch (error) {
+          return formatErrorResult(error);
+        }
+      },
+    ),
+  );
+}