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

package/dist/tools/kwq.d.ts

@@ -0,0 +1,19 @@
+/**
+ * KWQ (Keyword Query) tools for the MCP server.
+ * Provides structured query building and RRF ensemble fusion via the Dimensions API.
+ * @module mcp/tools/kwq
+ */
+import type { DimensionsClient } from "@digital-science/dimensions-dsl";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SchemaStore } from "../schema/index.js";
+/**
+ * Registers KWQ tools with the MCP server.
+ * - build_query: always registered (pure computation)
+ * - ensemble_queries: always registered (uses Dimensions API via client)
+ *
+ * @param server - MCP server instance
+ * @param client - Dimensions API client (for ensemble query execution)
+ * @param schemaStore - Loaded describe schema for search index hints
+ */
+export declare function registerKwqTools(server: McpServer, client: DimensionsClient, schemaStore: SchemaStore): void;
+//# sourceMappingURL=kwq.d.ts.map

package/dist/tools/kwq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kwq.d.ts","sourceRoot":"","sources":["../../src/tools/kwq.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAMxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA+BtD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,WAAW,GACvB,IAAI,CA2IN"}

package/dist/tools/kwq.js

@@ -0,0 +1,156 @@
+/**
+ * KWQ (Keyword Query) tools for the MCP server.
+ * Provides structured query building and RRF ensemble fusion via the Dimensions API.
+ * @module mcp/tools/kwq
+ */
+import { buildQuery, conceptGroupsToQuerySpec, ensembleQueries, } from "@digital-science/dimensions-kwq";
+import { z } from "zod";
+import { formatErrorResult, formatToolResult } from "../utils.js";
+// #region Shared schemas
+const ENTITY_ENUM = z.enum([
+    "publications",
+    "grants",
+    "researchers",
+    "patents",
+    "clinical_trials",
+    "datasets",
+    "policy_documents",
+    "organizations",
+]);
+const ConceptGroupSchema = z.object({
+    terms: z.array(z.string()).min(1).describe("Terms OR'd together (synonyms)"),
+    role: z.enum(["include", "exclude"]).describe("include = AND into query, exclude = NOT"),
+});
+const FilterSchema = z.object({
+    field: z.string(),
+    op: z.string(),
+    value: z.union([z.string(), z.number(), z.array(z.string()), z.array(z.number())]),
+});
+// #endregion
+// #region Tool registration
+/**
+ * Registers KWQ tools with the MCP server.
+ * - build_query: always registered (pure computation)
+ * - ensemble_queries: always registered (uses Dimensions API via client)
+ *
+ * @param server - MCP server instance
+ * @param client - Dimensions API client (for ensemble query execution)
+ * @param schemaStore - Loaded describe schema for search index hints
+ */
+export function registerKwqTools(server, client, schemaStore) {
+    const indexHints = ENTITY_ENUM.options
+        .map((entity) => `${entity}: ${schemaStore.searchIndexes(entity).join(", ") || "default"}`)
+        .join("; ");
+    // --- build_query ---
+    server.registerTool("build_query", {
+        description: `Build a validated Dimensions DSL query from structured concept groups.
+
+Use concept_groups for the common pattern: groups of synonym terms, AND'd together, with optional exclusions.
+Each group's terms are OR'd (synonyms), include groups are AND'd, exclude groups are NOT'd.
+
+Search indexes by entity: ${indexHints}
+
+For advanced nested boolean logic, use search_json with a SearchExpr tree instead.
+Returns the validated DSL string, validation status, human-readable description, and complexity metrics.`,
+        inputSchema: {
+            entity: ENTITY_ENUM.describe("Target entity type"),
+            concept_groups: z
+                .array(ConceptGroupSchema)
+                .optional()
+                .describe("Concept groups: include groups AND'd, each group's terms OR'd, exclude groups NOT'd"),
+            search_json: z
+                .string()
+                .optional()
+                .describe("Advanced: raw SearchExpr JSON tree (overrides concept_groups). Use for nested boolean logic."),
+            index: z
+                .string()
+                .optional()
+                .describe("Search index (e.g. title_abstract_only, full_data, title_only)"),
+            filters: z.array(FilterSchema).optional().describe("WHERE clause filters"),
+            fields: z.array(z.string()).optional().describe("Fields to return"),
+            sort_by: z.string().optional().describe("Sort field"),
+            sort_order: z.enum(["asc", "desc"]).optional().describe("Sort order"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(1000)
+                .optional()
+                .default(20)
+                .describe("Result limit (default 20, max 1000)"),
+            skip: z.number().int().min(0).optional().describe("Result offset"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        try {
+            if (args.concept_groups && args.search_json) {
+                return formatErrorResult(new Error("Provide either concept_groups or search_json, not both."));
+            }
+            const spec = conceptGroupsToQuerySpec(args);
+            const result = buildQuery(spec);
+            return formatToolResult({
+                dsl: result.dsl,
+                valid: result.validation._tag === "valid",
+                errors: result.validation._tag === "invalid" ? result.validation.errors : undefined,
+                warnings: result.validation._tag === "valid" && result.validation.warnings.length > 0
+                    ? result.validation.warnings
+                    : undefined,
+                description: result.description,
+                complexity: result.complexity,
+            });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+    // --- ensemble_queries ---
+    server.registerTool("ensemble_queries", {
+        description: `Execute 2-10 query specs in parallel and fuse results using Reciprocal Rank Fusion (RRF).
+
+Each spec uses the same concept_groups model as build_query. RRF produces a
+variance-reduced ranking by combining multiple retrieval strategies — different
+keyword formulations, different indexes, or different filter configurations.
+
+RRF score: score(d) = Σ 1/(k + rank_i(d)) across all lists containing document d.
+Higher k (default 60) weights more evenly; lower k favors top-ranked documents.`,
+        inputSchema: {
+            specs: z
+                .array(z.object({
+                entity: ENTITY_ENUM.default("publications"),
+                concept_groups: z.array(ConceptGroupSchema).optional(),
+                search_json: z.string().optional(),
+                index: z.string().optional(),
+                filters: z.array(FilterSchema).optional(),
+                fields: z.array(z.string()).optional(),
+                limit: z.number().int().optional().default(100).describe("Per-query result limit"),
+            }))
+                .min(2)
+                .max(10)
+                .describe("2-10 query specs to execute and fuse"),
+            k: z.number().int().optional().default(60).describe("RRF k parameter (default 60)"),
+            limit: z.number().int().optional().default(100).describe("Max fused results to return"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            const querySpecs = args.specs.map((spec) => conceptGroupsToQuerySpec(spec));
+            const result = await ensembleQueries((dsl) => client.rawQuery(dsl), querySpecs, { k: args.k, limit: args.limit });
+            return formatToolResult(result);
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+}
+// #endregion
+//# sourceMappingURL=kwq.js.map

package/dist/tools/kwq.js.map

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

package/dist/tools/lookup.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lookup tools for the MCP server.
+ * Provides direct lookup by identifiers (DOI, PMID, Dimensions ID).
+ * @module mcp/tools/lookup
+ */
+import { type DimensionsClient } from "@digital-science/dimensions-dsl";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers all lookup tools with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export declare function registerLookupTools(server: McpServer, client: DimensionsClient): void;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/tools/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../src/tools/lookup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWzE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAkPrF"}

package/dist/tools/lookup.js

@@ -0,0 +1,213 @@
+/**
+ * Lookup tools for the MCP server.
+ * Provides direct lookup by identifiers (DOI, PMID, Dimensions ID).
+ * @module mcp/tools/lookup
+ */
+import { EntitySchema, } from "@digital-science/dimensions-dsl";
+import { z } from "zod";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import { asArray, formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS, withTruncationWarning, } 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, client) {
+    // 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)
+                .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);
+        }
+    }));
+    // Get recent high impact publications
+    server.registerTool("recent_high_impact", {
+        description: "Find the most cited publications in a topic area from recent years. Useful for identifying influential recent research.",
+        inputSchema: {
+            query: z
+                .string()
+                .describe("Search query for the topic area (e.g., 'deep learning', 'immunotherapy')"),
+            years: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .default(5)
+                .describe("Number of recent years to consider (default: 5)"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Number of publications to return (max 100)"),
+            fields: z.array(z.string()).optional().describe("Fields to return"),
+        },
+        outputSchema: {
+            query: z.string().describe("The search query used"),
+            yearRange: z.string().describe("Year range searched (e.g., '2020-2025')"),
+            totalCount: z.number().describe("Total matching records"),
+            returnedCount: z.number().describe("Records returned in this response"),
+            truncated: z.boolean().optional().describe("True when results are truncated"),
+            truncationWarning: z.string().optional().describe("Warning message when truncated"),
+            publications: z.array(z.record(z.string(), z.unknown())).describe("Result records"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, withFieldAliases({ entitySource: { kind: "static", entity: "publications" }, fieldArrayArgs: ["fields"] }, async (args) => {
+        try {
+            const currentYear = new Date().getFullYear();
+            const startYear = currentYear - args.years;
+            const qb = client
+                .createQueryBuilder()
+                .search("publications")
+                .for(args.query)
+                .where("year", ">=", startYear)
+                .sort("times_cited", "desc")
+                .limit(args.limit);
+            if (args.fields?.length) {
+                qb.fields(args.fields);
+            }
+            else {
+                qb.fields(["id", "title", "doi", "year", "times_cited", "authors", "journal"]);
+            }
+            const dsl = qb.build();
+            const response = await client.rawQuery(dsl);
+            const publications = asArray(response.publications);
+            const totalCount = response._stats?.total_count ?? publications.length;
+            const returnedCount = publications.length;
+            return formatToolResult(withTruncationWarning({
+                query: args.query,
+                yearRange: `${startYear}-${currentYear}`,
+                totalCount,
+                returnedCount,
+                publications,
+            }, totalCount, returnedCount));
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    }));
+}
+//# sourceMappingURL=lookup.js.map

package/dist/tools/lookup.js.map

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

package/dist/tools/policy-profile.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Policy document profile tool for the MCP server.
+ * Provides deep profiling of policy documents including structural links
+ * to cited publications and their supporting grants.
+ * @module mcp/tools/policy-profile
+ */
+import type { DimensionsClient } from "@digital-science/dimensions-dsl";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers the policy_document_profile tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export declare function registerPolicyProfileTools(server: McpServer, client: DimensionsClient): void;
+//# sourceMappingURL=policy-profile.d.ts.map

package/dist/tools/policy-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-profile.d.ts","sourceRoot":"","sources":["../../src/tools/policy-profile.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAUzE;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAiL5F"}

package/dist/tools/policy-profile.js

@@ -0,0 +1,174 @@
+/**
+ * Policy document profile tool for the MCP server.
+ * Provides deep profiling of policy documents including structural links
+ * to cited publications and their supporting grants.
+ * @module mcp/tools/policy-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 policy_document_profile tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerPolicyProfileTools(server, client) {
+    server.registerTool("policy_document_profile", {
+        description: "Get a comprehensive profile for a policy document including its cited publications and their supporting grants. Uses structural links (publication_ids) rather than free-text search to trace the evidence chain from policy back to funded research.",
+        inputSchema: {
+            policyDocId: z.string().optional().describe("Dimensions policy document ID"),
+            query: z
+                .string()
+                .optional()
+                .describe("Search term to find policy documents (used when policyDocId is not known)"),
+            includeLinkedPublications: z
+                .boolean()
+                .default(true)
+                .describe("Include cited publications and their supporting grants"),
+            publicationLimit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .default(20)
+                .describe("Max linked publications to return"),
+        },
+        outputSchema: {
+            found: z.boolean().describe("Whether the policy document was found"),
+            profile: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Policy document profile with linked entities"),
+            message: z.string().optional().describe("Message when not found"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, async (args) => {
+        if (!args.policyDocId && !args.query) {
+            throw new McpError(ErrorCode.InvalidParams, "Must provide at least one of: policyDocId or query");
+        }
+        try {
+            // Step 1: Find the policy document
+            let policyDsl;
+            if (args.policyDocId) {
+                policyDsl = client
+                    .createQueryBuilder()
+                    .search("policy_documents")
+                    .where("id", "=", args.policyDocId)
+                    .fields([
+                    "id",
+                    "title",
+                    "year",
+                    "publisher_org",
+                    "linkout",
+                    "publisher_org",
+                    "publication_ids",
+                ])
+                    .limit(1)
+                    .build();
+            }
+            else {
+                policyDsl = client
+                    .createQueryBuilder()
+                    .search("policy_documents")
+                    .for(args.query)
+                    .fields([
+                    "id",
+                    "title",
+                    "year",
+                    "publisher_org",
+                    "linkout",
+                    "publisher_org",
+                    "publication_ids",
+                ])
+                    .limit(5)
+                    .build();
+            }
+            const policyResponse = await client.rawQuery(policyDsl);
+            const policyDocs = asArray(policyResponse.policy_documents);
+            if (policyDocs.length === 0) {
+                return formatToolResult({
+                    found: false,
+                    message: args.policyDocId
+                        ? `No policy document found with ID: ${args.policyDocId}`
+                        : `No policy document found matching: ${args.query}`,
+                });
+            }
+            const policyDoc = policyDocs[0];
+            const profile = {
+                policyDocument: policyDoc,
+                matchCount: policyDocs.length,
+            };
+            // Extract structural link IDs
+            const publicationIds = Array.isArray(policyDoc.publication_ids)
+                ? policyDoc.publication_ids
+                : undefined;
+            // Step 2: Fetch linked publications
+            if (args.includeLinkedPublications !== false &&
+                publicationIds &&
+                publicationIds.length > 0) {
+                const pubSlice = publicationIds.slice(0, args.publicationLimit);
+                const pubDsl = client
+                    .createQueryBuilder()
+                    .search("publications")
+                    .whereIn("id", pubSlice)
+                    .fields([
+                    "id",
+                    "title",
+                    "doi",
+                    "year",
+                    "times_cited",
+                    "journal",
+                    "authors",
+                    "research_orgs",
+                    "funders",
+                    "supporting_grant_ids",
+                ])
+                    .limit(args.publicationLimit)
+                    .build();
+                const pubResponse = await client.rawQuery(pubDsl);
+                const publications = asArray(pubResponse.publications);
+                profile.linkedPublications = {
+                    totalLinked: publicationIds.length,
+                    returnedCount: publications.length,
+                    items: publications,
+                };
+                // Second-wave: fetch grants behind the publications
+                const allGrantIds = new Set();
+                for (const pub of publications) {
+                    if (Array.isArray(pub.supporting_grant_ids)) {
+                        for (const gid of pub.supporting_grant_ids) {
+                            if (typeof gid === "string") {
+                                allGrantIds.add(gid);
+                            }
+                        }
+                    }
+                }
+                if (allGrantIds.size > 0) {
+                    const grantIds = [...allGrantIds].slice(0, 50);
+                    const grantDsl = client
+                        .createQueryBuilder()
+                        .search("grants")
+                        .whereIn("id", grantIds)
+                        .fields(["id", "title", "funding_usd", "funder_org_name", "start_year"])
+                        .limit(50)
+                        .build();
+                    const grantResponse = await client.rawQuery(grantDsl);
+                    const grants = asArray(grantResponse.grants);
+                    profile.supportingGrants = {
+                        totalLinked: allGrantIds.size,
+                        returnedCount: grants.length,
+                        items: grants,
+                    };
+                }
+            }
+            return formatToolResult({
+                found: true,
+                profile,
+            });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=policy-profile.js.map

package/dist/tools/policy-profile.js.map

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

package/dist/tools/profile.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Profile tools for the MCP server.
+ * Provides researcher and organization profile aggregation.
+ * @module mcp/tools/profile
+ */
+import type { DimensionsClient } from "@digital-science/dimensions-dsl";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Registers all profile tools with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export declare function registerProfileTools(server: McpServer, client: DimensionsClient): void;
+//# sourceMappingURL=profile.d.ts.map