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

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

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

package/dist/tools/profile.js

@@ -0,0 +1,349 @@
+/**
+ * Profile tools for the MCP server.
+ * Provides researcher and organization profile aggregation.
+ * @module mcp/tools/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 all profile tools with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerProfileTools(server, client) {
+    // Author/Researcher Profile
+    server.registerTool("author_profile", {
+        description: "Get a comprehensive profile for a researcher including their publications, grants, and institutional affiliations. Search by name or ORCID.",
+        inputSchema: {
+            researcherId: z.string().optional().describe("Dimensions researcher ID (if known)"),
+            orcid: z.string().optional().describe("ORCID identifier (e.g., '0000-0001-2345-6789')"),
+            name: z
+                .string()
+                .optional()
+                .describe("Researcher name to search for (e.g., 'Jennifer Doudna')"),
+            includePublications: z
+                .boolean()
+                .default(true)
+                .describe("Include recent publications in profile"),
+            includeGrants: z.boolean().default(true).describe("Include grants in profile"),
+            publicationLimit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Max publications to return"),
+            grantLimit: z.number().int().min(1).max(100).default(10).describe("Max grants to return"),
+        },
+        outputSchema: {
+            found: z.boolean().describe("Whether the researcher was found"),
+            profile: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Aggregated researcher profile"),
+            message: z.string().optional().describe("Message when not found"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, async (args) => {
+        // Validate that at least one identifier is provided
+        if (!args.researcherId && !args.orcid && !args.name) {
+            throw new McpError(ErrorCode.InvalidParams, "Must provide at least one of: researcherId, orcid, or name");
+        }
+        try {
+            // Step 1: Find the researcher
+            let researcherDsl;
+            if (args.researcherId) {
+                researcherDsl = client
+                    .createQueryBuilder()
+                    .search("researchers")
+                    .where("id", "=", args.researcherId)
+                    .limit(1)
+                    .build();
+            }
+            else if (args.orcid) {
+                researcherDsl = client
+                    .createQueryBuilder()
+                    .search("researchers")
+                    .where("orcid_id", "=", args.orcid)
+                    .limit(1)
+                    .build();
+            }
+            else {
+                const name = args.name;
+                if (!name) {
+                    throw new McpError(ErrorCode.InvalidParams, "Must provide at least one of: researcherId, orcid, or name");
+                }
+                researcherDsl = client
+                    .createQueryBuilder()
+                    .search("researchers")
+                    .for(name)
+                    .limit(5)
+                    .build();
+            }
+            const researcherResponse = await client.rawQuery(researcherDsl);
+            const researchers = asArray(researcherResponse.researchers);
+            if (researchers.length === 0) {
+                return formatToolResult({
+                    found: false,
+                    message: args.name
+                        ? `No researcher found matching: ${args.name}`
+                        : `No researcher found with provided identifier`,
+                });
+            }
+            // Use the first/best match
+            const researcher = researchers[0];
+            if (typeof researcher.id !== "string") {
+                return formatErrorResult(new Error("API returned researcher record without a valid id field"));
+            }
+            const researcherId = researcher.id;
+            const profile = {
+                researcher,
+                matchCount: researchers.length,
+            };
+            // Steps 2 & 3: Get publications and grants concurrently
+            const queries = [];
+            if (args.includePublications) {
+                queries.push((async () => {
+                    const pubDsl = client
+                        .createQueryBuilder()
+                        .search("publications")
+                        .where("researchers.id", "=", researcherId)
+                        .fields(["id", "title", "doi", "year", "times_cited", "journal", "type"])
+                        .sort("year", "desc")
+                        .limit(args.publicationLimit)
+                        .build();
+                    const pubResponse = await client.rawQuery(pubDsl);
+                    const publications = asArray(pubResponse.publications);
+                    profile.publications = {
+                        totalCount: pubResponse._stats?.total_count ?? publications.length,
+                        returnedCount: publications.length,
+                        items: publications,
+                    };
+                })());
+            }
+            if (args.includeGrants) {
+                queries.push((async () => {
+                    const grantDsl = client
+                        .createQueryBuilder()
+                        .search("grants")
+                        .where("researchers.id", "=", researcherId)
+                        .fields(["id", "title", "funding_usd", "funder_org_name", "start_year"])
+                        .sort("start_year", "desc")
+                        .limit(args.grantLimit)
+                        .build();
+                    const grantResponse = await client.rawQuery(grantDsl);
+                    const grants = asArray(grantResponse.grants);
+                    profile.grants = {
+                        totalCount: grantResponse._stats?.total_count ?? grants.length,
+                        returnedCount: grants.length,
+                        items: grants,
+                    };
+                })());
+            }
+            await Promise.all(queries);
+            return formatToolResult({
+                found: true,
+                profile,
+            });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+    // Organization Profile
+    server.registerTool("org_profile", {
+        description: "Get a comprehensive profile for a research organization including publication output, funding received, and top researchers. " +
+            "Prefer organizationId (GRID id) when known — common names can match multiple organizations.",
+        inputSchema: {
+            organizationId: z
+                .string()
+                .optional()
+                .describe("Dimensions organization GRID id (preferred, e.g. grid.168010.e for Stanford University)"),
+            name: z
+                .string()
+                .optional()
+                .describe("Organization name to search for (e.g., 'Stanford University', 'MIT')"),
+            includePublications: z.boolean().default(true).describe("Include recent publications"),
+            includeGrants: z.boolean().default(true).describe("Include grants received"),
+            includeTopResearchers: z
+                .boolean()
+                .default(true)
+                .describe("Include top researchers by publication count"),
+            publicationLimit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Max publications to return"),
+            grantLimit: z.number().int().min(1).max(100).default(10).describe("Max grants to return"),
+            researcherLimit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .default(10)
+                .describe("Max researchers to return"),
+        },
+        outputSchema: {
+            found: z.boolean().describe("Whether the organization was found"),
+            ambiguous: z
+                .boolean()
+                .optional()
+                .describe("True when name search matched multiple organizations"),
+            matchCount: z.number().optional().describe("Number of name matches returned"),
+            candidates: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("Matching organizations when ambiguous (id and name)"),
+            profile: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Aggregated organization profile"),
+            message: z.string().optional().describe("Message when not found or ambiguous"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, async (args) => {
+        // Validate that at least one identifier is provided
+        if (!args.organizationId && !args.name) {
+            throw new McpError(ErrorCode.InvalidParams, "Must provide either organizationId or name");
+        }
+        try {
+            // Step 1: Find the organization
+            let orgDsl;
+            if (args.organizationId) {
+                orgDsl = client
+                    .createQueryBuilder()
+                    .search("organizations")
+                    .where("id", "=", args.organizationId)
+                    .limit(1)
+                    .build();
+            }
+            else {
+                const name = args.name;
+                if (!name) {
+                    throw new McpError(ErrorCode.InvalidParams, "Must provide either organizationId or name");
+                }
+                orgDsl = client.createQueryBuilder().search("organizations").for(name).limit(5).build();
+            }
+            const orgResponse = await client.rawQuery(orgDsl);
+            const organizations = asArray(orgResponse.organizations);
+            if (organizations.length === 0) {
+                return formatToolResult({
+                    found: false,
+                    message: args.name
+                        ? `No organization found matching: ${args.name}`
+                        : `No organization found with provided ID`,
+                });
+            }
+            if (!args.organizationId && organizations.length > 1) {
+                const candidates = organizations.map((org) => ({
+                    id: org.id,
+                    name: org.name,
+                }));
+                return formatToolResult({
+                    found: false,
+                    ambiguous: true,
+                    matchCount: organizations.length,
+                    candidates,
+                    message: `Name "${args.name}" matched ${organizations.length} organizations. ` +
+                        "Pass organizationId (GRID id) to disambiguate.",
+                });
+            }
+            const organization = organizations[0];
+            if (typeof organization.id !== "string") {
+                return formatErrorResult(new Error("API returned organization record without a valid id field"));
+            }
+            const orgId = organization.id;
+            const profile = {
+                organization,
+                matchCount: organizations.length,
+            };
+            // Steps 2, 3 & 4: Get publications, grants, and top researchers concurrently
+            const orgQueries = [];
+            if (args.includePublications) {
+                orgQueries.push((async () => {
+                    const pubDsl = client
+                        .createQueryBuilder()
+                        .search("publications")
+                        .where("research_orgs.id", "=", orgId)
+                        .fields(["id", "title", "doi", "year", "times_cited", "authors"])
+                        .sort("year", "desc")
+                        .limit(args.publicationLimit)
+                        .build();
+                    const pubResponse = await client.rawQuery(pubDsl);
+                    const publications = asArray(pubResponse.publications);
+                    profile.publications = {
+                        totalCount: pubResponse._stats?.total_count ?? publications.length,
+                        returnedCount: publications.length,
+                        items: publications,
+                    };
+                })());
+            }
+            if (args.includeGrants) {
+                orgQueries.push((async () => {
+                    const grantDsl = client
+                        .createQueryBuilder()
+                        .search("grants")
+                        .where("research_orgs.id", "=", orgId)
+                        .fields(["id", "title", "funding_usd", "funder_org_name", "start_year"])
+                        .sort("start_year", "desc")
+                        .limit(args.grantLimit)
+                        .build();
+                    const grantResponse = await client.rawQuery(grantDsl);
+                    const grants = asArray(grantResponse.grants);
+                    // Calculate total funding if available
+                    let totalFunding = 0;
+                    for (const grant of grants) {
+                        const funding = typeof grant.funding_usd === "number" ? grant.funding_usd : 0;
+                        if (funding > 0) {
+                            totalFunding += funding;
+                        }
+                    }
+                    profile.grants = {
+                        totalCount: grantResponse._stats?.total_count ?? grants.length,
+                        returnedCount: grants.length,
+                        totalFundingUsd: totalFunding,
+                        items: grants,
+                    };
+                })());
+            }
+            if (args.includeTopResearchers) {
+                orgQueries.push((async () => {
+                    const resDsl = client
+                        .createQueryBuilder()
+                        .search("researchers")
+                        .where("research_orgs.id", "=", orgId)
+                        .fields([
+                        "id",
+                        "first_name",
+                        "last_name",
+                        "orcid_id",
+                        "total_publications",
+                        "total_grants",
+                    ])
+                        .sort("total_publications", "desc")
+                        .limit(args.researcherLimit)
+                        .build();
+                    const resResponse = await client.rawQuery(resDsl);
+                    const researchers = asArray(resResponse.researchers);
+                    profile.topResearchers = {
+                        totalCount: resResponse._stats?.total_count ?? researchers.length,
+                        returnedCount: researchers.length,
+                        items: researchers,
+                    };
+                })());
+            }
+            await Promise.all(orgQueries);
+            return formatToolResult({
+                found: true,
+                profile,
+            });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=profile.js.map

package/dist/tools/profile.js.map

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

package/dist/tools/query.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Query tools for the MCP server.
+ * Provides raw DSL query execution for power users.
+ * @module mcp/tools/query
+ */
+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 the raw DSL query tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ * @param schemaStore - Loaded describe schema for enriched descriptions
+ */
+export declare function registerQueryTools(server: McpServer, client: DimensionsClient, schemaStore: SchemaStore): void;
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,WAAW,GACvB,IAAI,CAyCN"}

package/dist/tools/query.js

@@ -0,0 +1,53 @@
+/**
+ * Query tools for the MCP server.
+ * Provides raw DSL query execution for power users.
+ * @module mcp/tools/query
+ */
+import { z } from "zod";
+import { formatErrorResult, formatToolResult } from "../utils.js";
+/**
+ * Registers the raw DSL query tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ * @param schemaStore - Loaded describe schema for enriched descriptions
+ */
+export function registerQueryTools(server, client, schemaStore) {
+    const sources = schemaStore.structuredEntityTypes().join(", ");
+    server.registerTool("execute_dsl", {
+        description: `Execute a raw Dimensions DSL query. Read dimensions://schema and dimensions://examples first. Official docs: https://docs.dimensions.ai/dsl/
+
+Prefer search_* tools for keyword search with yearFrom/yearTo and sortBy — they build valid DSL automatically.
+
+DSL modifier order (required): return <entity>[fields] sort by <field> desc limit <n> skip <n>
+- Use "sort by", not "sort"
+- Put sort before limit (limit before sort causes a syntax error)
+
+Examples:
+- search publications for "CRISPR" where year >= 2020 return publications[id+title+times_cited] sort by times_cited desc limit 20
+- search publications return publications facet journal limit 20
+- return funders aggregate funding_usd
+
+Structured entity types: ${sources}`,
+        inputSchema: {
+            dsl: z.string().describe("Complete DSL query string to execute"),
+        },
+        outputSchema: {
+            result: z.record(z.string(), z.unknown()).describe("Raw DSL query response"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            const response = await client.rawQuery(args.dsl);
+            return formatToolResult({ result: response });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=query.js.map

package/dist/tools/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAElE;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAAwB,EACxB,WAAwB;IAExB,MAAM,OAAO,GAAG,WAAW,CAAC,qBAAqB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;QACE,WAAW,EAAE;;;;;;;;;;;;;2BAaQ,OAAO,EAAE;QAC9B,WAAW,EAAE;YACX,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;SACjE;QACD,YAAY,EAAE;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,wBAAwB,CAAC;SAC7E;QACD,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,KAAK;YACrB,aAAa,EAAE,IAAI;SACpB;KACF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjD,OAAO,gBAAgB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Schema introspection and validation tools for the MCP server.
+ * @module mcp/tools/schema
+ */
+import type { DimensionsClient } from "@digital-science/dimensions-dsl";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SchemaContext } from "../schema/context.js";
+import { type SchemaStore } from "../schema/index.js";
+/** @deprecated Use {@link SchemaContext} from schema/context.js */
+export type { SchemaContext } from "../schema/context.js";
+/**
+ * Registers schema introspection and validation tools.
+ * @param server - MCP server instance
+ * @param client - Dimensions client
+ * @param context - Mutable schema context shared with refresh
+ */
+export declare function registerSchemaTools(server: McpServer, client: DimensionsClient, context: SchemaContext): void;
+/**
+ * Validates field aliases against loaded schema; logs warnings for unknown targets.
+ * @param schemaStore - Loaded schema store
+ */
+export declare function validateFieldAliases(schemaStore: SchemaStore): void;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGlE,mEAAmE;AACnE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,aAAa,GACrB,IAAI,CAsGN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAYnE"}

package/dist/tools/schema.js

@@ -0,0 +1,124 @@
+/**
+ * Schema introspection and validation tools for the MCP server.
+ * @module mcp/tools/schema
+ */
+import { z } from "zod";
+import { buildReverseAliasMap } from "../middleware/field-aliases.js";
+import { loadSchema } from "../schema/index.js";
+import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "../utils.js";
+/**
+ * Registers schema introspection and validation tools.
+ * @param server - MCP server instance
+ * @param client - Dimensions client
+ * @param context - Mutable schema context shared with refresh
+ */
+export function registerSchemaTools(server, client, context) {
+    server.registerTool("describe_schema", {
+        description: "Return Dimensions DSL schema metadata loaded at server startup. " +
+            "Default: compact summary with source/entity counts and resource URIs. " +
+            "Use full=true or dimensions://schema for the complete describe payload. " +
+            "Optionally fetch live describe for a single source or entity.",
+        inputSchema: {
+            source: z.string().optional().describe("Source name (e.g. publications)"),
+            entity: z.string().optional().describe("Auxiliary entity name (e.g. journals)"),
+            full: z
+                .boolean()
+                .optional()
+                .describe("When true, return the full raw describe schema instead of the summary"),
+            live: z
+                .boolean()
+                .optional()
+                .describe("When true, fetch fresh describe for source/entity from the API"),
+        },
+        outputSchema: {
+            summary: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Compact schema overview (default response)"),
+            schema: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Full or sliced schema when full=true or source/entity is set"),
+            version: z.string().optional().describe("DSL version"),
+            stats: z.record(z.string(), z.unknown()).optional().describe("Load stats and provenance"),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, async (args) => {
+        try {
+            if (args.live && args.source) {
+                const raw = await client.rawQuery(`describe source ${args.source}`);
+                return formatToolResult({ schema: raw });
+            }
+            if (args.live && args.entity) {
+                const raw = await client.rawQuery(`describe entity ${args.entity}`);
+                return formatToolResult({ schema: raw });
+            }
+            if (args.source) {
+                const source = context.store.getSource(args.source);
+                if (!source) {
+                    return formatErrorResult(new Error(`Unknown source: ${args.source}`));
+                }
+                return formatToolResult({ schema: source });
+            }
+            if (args.entity) {
+                const entity = context.store.getEntity(args.entity);
+                if (!entity) {
+                    return formatErrorResult(new Error(`Unknown entity: ${args.entity}`));
+                }
+                return formatToolResult({ schema: entity });
+            }
+            if (args.full) {
+                return formatToolResult({
+                    schema: context.store.raw,
+                    version: context.store.version,
+                    stats: context.store.stats(),
+                });
+            }
+            return formatToolResult({
+                summary: context.store.summary(),
+                version: context.store.version,
+                stats: context.store.stats(),
+            });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+    server.registerTool("refresh_schema", {
+        description: "Re-fetch describe schema from the Dimensions API, rebuild in-memory schema, and re-register MCP resources.",
+        inputSchema: {},
+        outputSchema: {
+            refreshed: z.boolean(),
+            stats: z.record(z.string(), z.unknown()),
+        },
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, async () => {
+        try {
+            const store = await loadSchema(client, {
+                cachePath: process.env.SCHEMA_CACHE_PATH,
+                forceRefresh: true,
+            });
+            context.store = store;
+            return formatToolResult({ refreshed: true, stats: store.stats() });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+}
+/**
+ * Validates field aliases against loaded schema; logs warnings for unknown targets.
+ * @param schemaStore - Loaded schema store
+ */
+export function validateFieldAliases(schemaStore) {
+    for (const entity of schemaStore.structuredEntityTypes()) {
+        const filterable = new Set(schemaStore.filterableFields(entity));
+        const reverse = buildReverseAliasMap(entity);
+        for (const [canonical, aliases] of reverse) {
+            if (!filterable.has(canonical)) {
+                console.error(`Field alias warning: ${entity}.${canonical} not in describe filterable fields (aliases: ${aliases.join(", ")})`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/tools/schema.js.map

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

package/dist/tools/search-entity-metadata.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Per-entity search tool metadata (descriptions, convenience filters, sort hints).
+ * @module mcp/tools/search-entity-metadata
+ */
+import type { QueryBuilder, StructuredEntityType } from "@digital-science/dimensions-dsl";
+import { z } from "zod";
+/** Convenience filters applied before extended `filters`. */
+export type ConvenienceFilterApplier = (builder: QueryBuilder, args: Record<string, unknown>) => void;
+/** Static configuration for one structured search entity. */
+export interface SearchEntityMetadata {
+    readonly source: StructuredEntityType;
+    readonly description: string;
+    readonly applyConvenienceFilters: ConvenienceFilterApplier;
+    readonly extraInputSchema: Record<string, z.ZodTypeAny>;
+}
+/** Metadata for all structured search tools. */
+export declare const SEARCH_ENTITY_METADATA: readonly SearchEntityMetadata[];
+//# sourceMappingURL=search-entity-metadata.d.ts.map

package/dist/tools/search-entity-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-entity-metadata.d.ts","sourceRoot":"","sources":["../../src/tools/search-entity-metadata.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC1F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,6DAA6D;AAC7D,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,IAAI,CAAC;AAEV,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,uBAAuB,EAAE,wBAAwB,CAAC;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;CACzD;AAiBD,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EAqNjE,CAAC"}