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

package/dist/mcp/tools/dataset-profile.js

@@ -0,0 +1,194 @@
+/**
+ * Dataset profile tool for the MCP server.
+ * Provides deep profiling of Dimensions datasets including structural links
+ * to associated publications and grants.
+ * @module mcp/tools/dataset-profile
+ */
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { asArray, formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS, } from "../utils.js";
+/**
+ * Registers the dataset_profile tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerDatasetProfileTools(server, client) {
+    server.registerTool("dataset_profile", {
+        description: "Get a comprehensive profile for a research dataset including its associated publication, linked grants, and related publications. Uses structural links (associated_publication_id, associated_grant_ids) rather than free-text search.",
+        inputSchema: {
+            datasetId: z.string().optional().describe("Dimensions dataset ID"),
+            query: z
+                .string()
+                .optional()
+                .describe("Search term to find datasets (used when datasetId is not known)"),
+            includeLinkedPublications: z
+                .boolean()
+                .default(true)
+                .describe("Include the associated publication and related publications"),
+            includeLinkedGrants: z.boolean().default(true).describe("Include associated grants"),
+            publicationLimit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .default(10)
+                .describe("Max related publications to return"),
+        },
+        outputSchema: {
+            found: z.boolean().describe("Whether the dataset was found"),
+            profile: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Dataset profile with linked entities"),
+            message: z.string().optional().describe("Message when not found"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, async (args) => {
+        if (!args.datasetId && !args.query) {
+            throw new McpError(ErrorCode.InvalidParams, "Must provide at least one of: datasetId or query");
+        }
+        try {
+            // Step 1: Find the dataset
+            let datasetDsl;
+            if (args.datasetId) {
+                datasetDsl = client
+                    .createQueryBuilder()
+                    .search("datasets")
+                    .where("id", "=", args.datasetId)
+                    .fields([
+                    "id",
+                    "title",
+                    "doi",
+                    "year",
+                    "repository",
+                    "description",
+                    "associated_publication_id",
+                    "associated_grant_ids",
+                ])
+                    .limit(1)
+                    .build();
+            }
+            else {
+                datasetDsl = client
+                    .createQueryBuilder()
+                    .search("datasets")
+                    .for(args.query)
+                    .fields([
+                    "id",
+                    "title",
+                    "doi",
+                    "year",
+                    "repository",
+                    "description",
+                    "associated_publication_id",
+                    "associated_grant_ids",
+                ])
+                    .limit(5)
+                    .build();
+            }
+            const datasetResponse = await client.rawQuery(datasetDsl);
+            const datasets = asArray(datasetResponse.datasets);
+            if (datasets.length === 0) {
+                return formatToolResult({
+                    found: false,
+                    message: args.datasetId
+                        ? `No dataset found with ID: ${args.datasetId}`
+                        : `No dataset found matching: ${args.query}`,
+                });
+            }
+            const dataset = datasets[0];
+            const profile = {
+                dataset,
+                matchCount: datasets.length,
+            };
+            // Extract structural link IDs
+            const associatedPubId = typeof dataset.associated_publication_id === "string"
+                ? dataset.associated_publication_id
+                : undefined;
+            const associatedGrantIds = Array.isArray(dataset.associated_grant_ids)
+                ? dataset.associated_grant_ids
+                : undefined;
+            const datasetTitle = typeof dataset.title === "string" ? dataset.title : undefined;
+            // Step 2: Concurrent linked entity fetches
+            const queries = [];
+            if (args.includeLinkedPublications !== false) {
+                // Linked publication via structural ID
+                if (associatedPubId) {
+                    queries.push((async () => {
+                        const pubDsl = client
+                            .createQueryBuilder()
+                            .search("publications")
+                            .where("id", "=", associatedPubId)
+                            .fields([
+                            "id",
+                            "title",
+                            "doi",
+                            "year",
+                            "times_cited",
+                            "journal",
+                            "authors",
+                            "research_orgs",
+                        ])
+                            .limit(1)
+                            .build();
+                        const pubResponse = await client.rawQuery(pubDsl);
+                        const pubs = asArray(pubResponse.publications);
+                        if (pubs.length > 0) {
+                            profile.linkedPublication = pubs[0];
+                        }
+                    })());
+                }
+                // Related publications on same topic
+                if (datasetTitle) {
+                    queries.push((async () => {
+                        const relDsl = client
+                            .createQueryBuilder()
+                            .search("publications")
+                            .for(datasetTitle)
+                            .fields(["id", "title", "doi", "year", "times_cited", "journal"])
+                            .sort("times_cited", "desc")
+                            .limit(args.publicationLimit)
+                            .build();
+                        const relResponse = await client.rawQuery(relDsl);
+                        const relPubs = asArray(relResponse.publications);
+                        profile.relatedPublications = {
+                            totalCount: typeof relResponse._stats?.total_count === "number"
+                                ? relResponse._stats.total_count
+                                : relPubs.length,
+                            returnedCount: relPubs.length,
+                            items: relPubs,
+                        };
+                    })());
+                }
+            }
+            if (args.includeLinkedGrants !== false &&
+                associatedGrantIds &&
+                associatedGrantIds.length > 0) {
+                queries.push((async () => {
+                    const grantDsl = client
+                        .createQueryBuilder()
+                        .search("grants")
+                        .whereIn("id", associatedGrantIds)
+                        .fields(["id", "title", "funding_usd", "funder_org_name", "start_year"])
+                        .limit(10)
+                        .build();
+                    const grantResponse = await client.rawQuery(grantDsl);
+                    const grants = asArray(grantResponse.grants);
+                    profile.linkedGrants = {
+                        totalCount: grants.length,
+                        items: grants,
+                    };
+                })());
+            }
+            await Promise.all(queries);
+            return formatToolResult({
+                found: true,
+                profile,
+            });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=dataset-profile.js.map

package/dist/mcp/tools/dataset-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-profile.js","sourceRoot":"","sources":["../../../src/mcp/tools/dataset-profile.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/fetch-search-pages.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { type DimensionsClient, type SchemaStore } from "../../dsl/index.js";
+/**
+ * Registers the fetch_search_pages tool.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ * @param schemaStore - Loaded describe schema
+ */
+export declare function registerFetchSearchPagesTools(server: McpServer, client: DimensionsClient, schemaStore: SchemaStore): void;
+//# sourceMappingURL=fetch-search-pages.d.ts.map

package/dist/mcp/tools/fetch-search-pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-search-pages.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/fetch-search-pages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAEL,KAAK,gBAAgB,EAKrB,KAAK,WAAW,EAMjB,MAAM,oBAAoB,CAAC;AAmD5B;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,WAAW,GACvB,IAAI,CAqPN"}

package/dist/mcp/tools/fetch-search-pages.js

@@ -0,0 +1,237 @@
+/**
+ * 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 { z } from "zod";
+import { ValidationError } from "../../client/index.js";
+import { DEFAULT_BATCH_MAX_PAGES, HARD_MAX_BATCH_PAGES, parseEntityResponse, resolveSkipAndLimit, SCHEMA_LIMITS, STRUCTURED_ENTITY_TYPES, 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)");
+/**
+ * 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, client, schemaStore) {
+    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) => {
+        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, limit) => 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));
+            const parsed = parseEntityResponse(response, entityType);
+            const rows = parsed.data;
+            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);
+        }
+    }));
+}
+//# sourceMappingURL=fetch-search-pages.js.map

package/dist/mcp/tools/fetch-search-pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-search-pages.js","sourceRoot":"","sources":["../../../src/mcp/tools/fetch-search-pages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,uBAAuB,EAEvB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EAEb,uBAAuB,EAEvB,eAAe,EACf,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAElF,wEAAwE;AACxE,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CACvC,EAAE,EACF,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CACzD,CAAC;AAEF,mGAAmG;AACnG,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,kBAAkB,EAAE,GAAG,mBAAmB,CAAC;AAE3E,MAAM,iBAAiB,GAAG,CAAC;KACxB,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;KACnC,OAAO,CAAC,MAAM,CAAC;KACf,QAAQ,CACP,qKAAqK,CACtK,CAAC;AAuBJ;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAiB,EACjB,MAAwB,EACxB,WAAwB;IAExB,MAAM,UAAU,GAAG,WAAW,CAAC,qBAAqB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAElE,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,WAAW,EACT,sEAAsE,aAAa,CAAC,QAAQ,SAAS;YACrG,GAAG,aAAa,CAAC,QAAQ,WAAW,aAAa,CAAC,SAAS,mBAAmB;YAC9E,qFAAqF;YACrF,8FAA8F;YAC9F,aAAa,UAAU,GAAG;QAC5B,WAAW,EAAE;YACX,UAAU,EAAE,CAAC;iBACV,IAAI,CAAC,uBAAuB,CAAC;iBAC7B,QAAQ,CAAC,sDAAsD,CAAC;YACnE,IAAI,EAAE,iBAAiB;YACvB,GAAG,kBAAkB;YACrB,GAAG,mBAAmB;YACtB,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC;iBAC3B,QAAQ,EAAE;iBACV,QAAQ,CACP,6EAA6E,aAAa,CAAC,QAAQ,GAAG,CACvG;YACH,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,aAAa,CAAC,QAAQ,GAAG,CAAC,CAAC;iBAC/B,QAAQ,EAAE;iBACV,QAAQ,CAAC,6DAA6D,CAAC;YAC1E,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,oBAAoB,CAAC;iBACzB,OAAO,CAAC,uBAAuB,CAAC;iBAChC,QAAQ,CACP,mDAAmD,uBAAuB,SAAS,oBAAoB,0BAA0B,CAClI;YACH,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC;iBAC5B,QAAQ,EAAE;iBACV,QAAQ,CAAC,2CAA2C,CAAC;YACxD,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,6DAA6D,CAAC;YAC1E,YAAY,EAAE,CAAC;iBACZ,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;iBACtB,QAAQ,EAAE;iBACV,QAAQ,CACP,kFAAkF,CACnF;YACH,cAAc,EAAE,CAAC;iBACd,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;iBACd,QAAQ,CAAC,+DAA+D,CAAC;YAC5E,iBAAiB,EAAE,CAAC;iBACjB,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;iBACd,QAAQ,CACP,2FAA2F,CAC5F;SACJ;QACD,YAAY,EAAE;YACZ,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;YAChB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;YACtB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACjC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACpC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACnC,GAAG,wBAAwB;YAC3B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACjC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACnC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC/B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YACrC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;YAC/B,SAAS,EAAE,CAAC;iBACT,MAAM,CAAC;gBACN,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;gBACxB,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE;gBACzB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;aACvC,CAAC;iBACD,QAAQ,EAAE;SACd;QACD,WAAW,EAAE,yBAAyB;KACvC,EACD,gBAAgB,CACd;QACE,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,EAAE;QACxD,cAAc,EAAE,CAAC,QAAQ,CAAC;QAC1B,eAAe,EAAE,CAAC,QAAQ,CAAC;QAC3B,eAAe,EAAE,CAAC,SAAS,CAAC;KAC7B,EACD,KAAK,EAAE,IAA0B,EAAE,EAAE;QACnC,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;YACnC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACjE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;YACnD,MAAM,QAAQ,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,uBAAuB,CAAC,CAAC;YAElF,uBAAuB,CAAC;gBACtB,SAAS;gBACT,QAAQ;gBACR,QAAQ;gBACR,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;aAC1C,CAAC,CAAC;YAEH,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,MAAM,QAAQ,GACZ,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;oBAChD,CAAC,CAAC,mBAAmB,CAAC;wBAClB,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,KAAK,EAAE,QAAQ;qBAChB,CAAC,CAAC,IAAI;oBACT,CAAC,CAAC,SAAS,GAAG,QAAQ,CAAC;gBAC3B,8BAA8B,CAAC;oBAC7B,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE,QAAQ;oBACf,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;iBAC1C,CAAC,CAAC;YACL,CAAC;YAED,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,KAAa,EAAE,EAAE,CAC/C,wBAAwB,CAAC,MAAM,EAAE,UAAU,EAAE;gBAC3C,GAAG,IAAI;gBACP,IAAI;gBACJ,KAAK;gBACL,QAAQ,EAAE,KAAK;aAChB,CAAC,CAAC;YAEL,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;oBACrB,OAAO,iBAAiB,CACtB,IAAI,eAAe,CAAC,sCAAsC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAC9E,CAAC;gBACJ,CAAC;gBACD,MAAM,YAAY,GAAG,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;gBAC7E,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,GAAG,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAC3D,MAAM,IAAI,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;gBACzC,MAAM,UAAU,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE;oBACnF,SAAS;oBACT,QAAQ;oBACR,QAAQ;oBACR,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,SAAS,EAAE,IAAI;oBACf,MAAM,EAAE,YAAY;oBACpB,eAAe,EAAE,IAAI,CAAC,MAAM;oBAC5B,cAAc,EAAE,IAAI,CAAC,cAAc;iBACpC,CAAC,CAAC;gBACH,OAAO,gBAAgB,CAAC;oBACtB,IAAI,EAAE,MAAM;oBACZ,UAAU;oBACV,UAAU,EAAE,UAAU,CAAC,UAAU;oBACjC,YAAY,EAAE,UAAU,CAAC,YAAY;oBACrC,cAAc,EAAE,UAAU,CAAC,cAAc;oBACzC,UAAU,EAAE,UAAU,CAAC,UAAU;oBACjC,YAAY,EAAE,UAAU,CAAC,MAAM;oBAC/B,QAAQ,EAAE,UAAU,CAAC,QAAQ;oBAC7B,OAAO,EAAE,UAAU,CAAC,OAAO;oBAC3B,kBAAkB,EAChB,UAAU,CAAC,UAAU,GAAG,MAAM;wBAC5B,CAAC,CAAC,GAAG,UAAU,CAAC,UAAU,wDAAwD,aAAa,CAAC,iBAAiB,OAAO;wBACxH,CAAC,CAAC,SAAS;iBAChB,CAAC,CAAC;YACL,CAAC;YAED,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;gBACzB,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE;oBACpE,SAAS;oBACT,QAAQ;oBACR,QAAQ;oBACR,UAAU,EAAE,IAAI,CAAC,UAAU;iBAC5B,CAAC,CAAC;gBACH,OAAO,gBAAgB,CAAC;oBACtB,IAAI,EAAE,WAAW;oBACjB,UAAU;oBACV,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,aAAa,EAAE,OAAO,CAAC,cAAc;oBACrC,YAAY,EAAE,OAAO,CAAC,YAAY;oBAClC,SAAS,EAAE;wBACT,GAAG,EAAE,OAAO,CAAC,GAAG;wBAChB,YAAY,EAAE,OAAO,CAAC,YAAY;wBAClC,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS;4BACvC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE;4BAC9C,CAAC,CAAC,EAAE,CAAC;qBACR;oBACD,SAAS,EAAE,OAAO,CAAC,UAAU,GAAG,OAAO,CAAC,cAAc;oBACtD,iBAAiB,EACf,OAAO,CAAC,UAAU,GAAG,OAAO,CAAC,cAAc;wBACzC,CAAC,CAAC,WAAW,OAAO,CAAC,cAAc,OAAO,OAAO,CAAC,UAAU,mBAAmB,OAAO,CAAC,YAAY,+DAA+D;wBAClK,CAAC,CAAC,SAAS;iBAChB,CAAC,CAAC;YACL,CAAC;YAED,kBAAkB;YAClB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,mBAAmB,CACzC,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;gBAChD,CAAC,CAAC;oBACE,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,KAAK,EAAE,QAAQ;iBAChB;gBACH,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CACpD,CAAC;YACF,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAClC,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAA4B,CAAC;YACzE,MAAM,MAAM,GAAG,mBAAmB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACzD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAiC,CAAC;YACtD,MAAM,SAAS,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;YAE9C,OAAO,gBAAgB,CACrB,oBAAoB,CAClB;gBACE,IAAI,EAAE,MAAM;gBACZ,UAAU;gBACV,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,aAAa,EAAE,IAAI,CAAC,MAAM;gBAC1B,YAAY,EAAE,CAAC;gBACf,CAAC,SAAS,CAAC,EAAE,IAAI;aAClB,EACD,MAAM,CAAC,UAAU,EACjB,IAAI,CAAC,MAAM,EACX,IAAI,EACJ,KAAK,CACN,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CACF,CACF,CAAC;AACJ,CAAC"}

package/dist/mcp/tools/functions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 type { DimensionsClient } from "../../dsl/index.js";
+/**
+ * Registers special function tools with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export declare function registerFunctionTools(server: McpServer, client: DimensionsClient): void;
+//# sourceMappingURL=functions.d.ts.map

package/dist/mcp/tools/functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/functions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAwFvF"}

package/dist/mcp/tools/functions.js

@@ -0,0 +1,87 @@
+/**
+ * Special function tools for the MCP server.
+ * Entity resolution helpers (affiliations, grants).
+ * @module mcp/tools/functions
+ */
+import { z } from "zod";
+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, client) {
+    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);
+        }
+    });
+}
+//# sourceMappingURL=functions.js.map

package/dist/mcp/tools/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../../../src/mcp/tools/functions.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/impact-chain.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Research impact chain tool for the MCP server.
+ * Traces how a research topic flows from publications through patents,
+ * clinical trials, and policy documents.
+ * @module mcp/tools/impact-chain
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DimensionsClient } from "../../dsl/index.js";
+/**
+ * Registers the research_impact_chain tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export declare function registerImpactChainTools(server: McpServer, client: DimensionsClient): void;
+//# sourceMappingURL=impact-chain.d.ts.map

package/dist/mcp/tools/impact-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-chain.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/impact-chain.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAgC3D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAqE1F"}