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

package/dist/mcp/tools/query.js

@@ -0,0 +1,75 @@
+/**
+ * Query tools for the MCP server.
+ * Provides raw DSL query execution for power users.
+ * @module mcp/tools/query
+ */
+import { z } from "zod";
+import { buildExecuteDslPolicyHints, validateExecuteDslPolicy, } from "../../dsl/index.js";
+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/policy 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.
+Use fetch_search_pages for multi-page entity retrieval; facets cannot be paginated (max 1000 buckets).
+
+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)
+- Deep pagination (skip≥5000 or page≥5) requires confirmLargeFetch: true
+
+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"),
+            confirmLargeFetch: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Required for deep pagination in DSL (skip≥5000). See dimensions://schema/policy."),
+        },
+        outputSchema: {
+            result: z.record(z.string(), z.unknown()).describe("Raw DSL query response"),
+            policyNotice: z.string().optional().describe("Reasonable-use reminder"),
+            largeResultWarning: z
+                .string()
+                .optional()
+                .describe("Warning when total_count exceeds 10,000"),
+            paginationHint: z
+                .string()
+                .optional()
+                .describe("Pagination guidance when results are truncated"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            validateExecuteDslPolicy({
+                dsl: args.dsl,
+                confirmLargeFetch: args.confirmLargeFetch,
+            });
+            const response = (await client.rawQuery(args.dsl));
+            const hints = buildExecuteDslPolicyHints(args.dsl, response);
+            return formatToolResult({ result: response, ...hints });
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    });
+}
+//# sourceMappingURL=query.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/mcp/tools/query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,0BAA0B,EAE1B,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,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;;;;;;;;;;;;;;;2BAeQ,OAAO,EAAE;QAC9B,WAAW,EAAE;YACX,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;YAChE,iBAAiB,EAAE,CAAC;iBACjB,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,OAAO,CAAC,KAAK,CAAC;iBACd,QAAQ,CACP,kFAAkF,CACnF;SACJ;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;YAC5E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;YACvE,kBAAkB,EAAE,CAAC;iBAClB,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,yCAAyC,CAAC;YACtD,cAAc,EAAE,CAAC;iBACd,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,gDAAgD,CAAC;SAC9D;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,wBAAwB,CAAC;gBACvB,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;aAC1C,CAAC,CAAC;YACH,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAA4B,CAAC;YAC9E,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC7D,OAAO,gBAAgB,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,23 @@
+/**
+ * Schema introspection and validation tools for the MCP server.
+ * @module mcp/tools/schema
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DimensionsClient } from "../../dsl/index.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/mcp/tools/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,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/mcp/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/mcp/tools/schema.js.map

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

package/dist/mcp/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 { z } from "zod";
+import type { QueryBuilder, StructuredEntityType } from "../../dsl/index.js";
+/** 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/mcp/tools/search-entity-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-entity-metadata.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/search-entity-metadata.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG7E,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"}

package/dist/mcp/tools/search-entity-metadata.js

@@ -0,0 +1,221 @@
+/**
+ * Per-entity search tool metadata (descriptions, convenience filters, sort hints).
+ * @module mcp/tools/search-entity-metadata
+ */
+import { z } from "zod";
+import { resolveFunderOrgName } from "../funder-org-names.js";
+const noop = () => { };
+function yearRange(fromKey, toKey, field) {
+    return (builder, args) => {
+        const from = args[fromKey];
+        const to = args[toKey];
+        if (typeof from === "number") {
+            builder.where(field, ">=", from);
+        }
+        if (typeof to === "number") {
+            builder.where(field, "<=", to);
+        }
+    };
+}
+/** Metadata for all structured search tools. */
+export const SEARCH_ENTITY_METADATA = [
+    {
+        source: "publications",
+        description: "Search research publications in the Dimensions database. Returns articles, preprints, books, and other scholarly works with citation metrics, author information, and metadata.",
+        applyConvenienceFilters: (builder, args) => {
+            yearRange("yearFrom", "yearTo", "year")(builder, args);
+            if (typeof args.type === "string") {
+                builder.where("type", "=", args.type);
+            }
+        },
+        extraInputSchema: {
+            yearFrom: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter publications from this year (inclusive)"),
+            yearTo: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter publications up to this year (inclusive)"),
+            type: z
+                .enum(["article", "chapter", "proceeding", "monograph", "preprint", "book"])
+                .optional()
+                .describe("Filter by publication type"),
+            sortBy: z
+                .enum([
+                "times_cited",
+                "total_citations",
+                "recent_citations",
+                "relative_citation_ratio",
+                "field_citation_ratio",
+                "citation_ratio",
+                "altmetric",
+                "altmetric_score",
+                "year",
+                "date",
+            ])
+                .optional()
+                .describe("Sort results by this field (total_citations = times_cited, citation_ratio = field_citation_ratio, altmetric_score = altmetric)"),
+        },
+    },
+    {
+        source: "grants",
+        description: "Search research grants and funding awards in the Dimensions database. Returns grant information including funding amounts, funders, and research organizations. " +
+            "funderOrgName must match an exact Dimensions funder name (acronyms like NCI and NSF are resolved automatically). " +
+            "Umbrella labels such as NIH often match no grants — discover institute names with facet_query or aggregate_query on facetField funder_orgs.",
+        applyConvenienceFilters: (builder, args) => {
+            yearRange("startYearFrom", "startYearTo", "start_year")(builder, args);
+            if (typeof args.funderOrgName === "string") {
+                builder.where("funder_org_name", "=", resolveFunderOrgName(args.funderOrgName));
+            }
+        },
+        extraInputSchema: {
+            startYearFrom: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter grants starting from this year (inclusive)"),
+            startYearTo: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter grants starting up to this year (inclusive)"),
+            funderOrgName: z
+                .string()
+                .optional()
+                .describe("Filter by funder organization name. Acronyms NCI, NSF, NEH resolve automatically; use facet_query/aggregate_query on funder_orgs to discover exact names."),
+            sortBy: z
+                .enum([
+                "funding_usd",
+                "funding_eur",
+                "funding_amount_usd",
+                "funding_amount_eur",
+                "start_year",
+                "start_date",
+                "end_date",
+            ])
+                .optional()
+                .describe("Sort results by this field (funding_amount_usd = funding_usd, funding_amount_eur = funding_eur)"),
+        },
+    },
+    {
+        source: "researchers",
+        description: "Search researcher profiles by name in the Dimensions database. The query matches researcher names, not research topics — " +
+            "for topic→researcher discovery use facet_query with entityType publications and facetField researchers.",
+        applyConvenienceFilters: noop,
+        extraInputSchema: {
+            sortBy: z
+                .enum(["total_publications", "total_grants"])
+                .optional()
+                .describe("Sort results by this field"),
+        },
+    },
+    {
+        source: "patents",
+        description: "Search patents in the Dimensions database. Returns patent information including titles, abstracts, assignees, and filing dates.",
+        applyConvenienceFilters: (builder, args) => {
+            yearRange("filingYearFrom", "filingYearTo", "year")(builder, args);
+        },
+        extraInputSchema: {
+            filingYearFrom: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter patents filed from this year (inclusive)"),
+            filingYearTo: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter patents filed up to this year (inclusive)"),
+            sortBy: z
+                .enum(["filing_date", "publication_date", "granted_date"])
+                .optional()
+                .describe("Sort results by this field"),
+        },
+    },
+    {
+        source: "clinical_trials",
+        description: "Search clinical trials in the Dimensions database. Returns trial information including phases, conditions studied, and status.",
+        applyConvenienceFilters: (builder, args) => {
+            if (typeof args.phase === "string") {
+                builder.where("phase", "=", args.phase);
+            }
+            if (typeof args.overallStatus === "string") {
+                builder.where("overall_status", "=", args.overallStatus);
+            }
+            yearRange("yearFrom", "yearTo", "year")(builder, args);
+        },
+        extraInputSchema: {
+            phase: z.string().optional().describe("Filter by trial phase (e.g., 'Phase 3')"),
+            overallStatus: z
+                .string()
+                .optional()
+                .describe("Filter by trial status (e.g., 'Completed', 'Recruiting')"),
+            yearFrom: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter trials starting from this year (inclusive)"),
+            yearTo: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter trials starting up to this year (inclusive)"),
+            sortBy: z.enum(["start_date"]).optional().describe("Sort results by this field"),
+        },
+    },
+    {
+        source: "datasets",
+        description: "Search research datasets in the Dimensions database. Returns dataset information including descriptions, repositories, and associated publications.",
+        applyConvenienceFilters: (builder, args) => {
+            yearRange("yearFrom", "yearTo", "year")(builder, args);
+            if (typeof args.repository === "string") {
+                builder.where("repository", "=", args.repository);
+            }
+        },
+        extraInputSchema: {
+            yearFrom: z.number().int().optional().describe("Filter datasets from this year (inclusive)"),
+            yearTo: z.number().int().optional().describe("Filter datasets up to this year (inclusive)"),
+            repository: z.string().optional().describe("Filter by repository name"),
+            sortBy: z.enum(["year"]).optional().describe("Sort results by this field"),
+        },
+    },
+    {
+        source: "policy_documents",
+        description: "Search policy documents in the Dimensions database. Returns policy briefs, reports, and government documents that cite research.",
+        applyConvenienceFilters: (builder, args) => {
+            yearRange("yearFrom", "yearTo", "year")(builder, args);
+        },
+        extraInputSchema: {
+            yearFrom: z.number().int().optional().describe("Filter documents from this year (inclusive)"),
+            yearTo: z.number().int().optional().describe("Filter documents up to this year (inclusive)"),
+            sortBy: z.enum(["year"]).optional().describe("Sort results by this field"),
+        },
+    },
+    {
+        source: "organizations",
+        description: "Search research organizations in the Dimensions database. Returns universities, research institutes, hospitals, and companies with research output.",
+        applyConvenienceFilters: (builder, args) => {
+            if (typeof args.orgType === "string") {
+                builder.where("types", "=", args.orgType);
+            }
+            if (typeof args.country === "string") {
+                builder.where("country_name", "=", args.country);
+            }
+        },
+        extraInputSchema: {
+            orgType: z
+                .string()
+                .optional()
+                .describe("Filter by organization type (e.g., 'Education', 'Healthcare', 'Company')"),
+            country: z
+                .string()
+                .optional()
+                .describe("Filter by country (e.g., 'United States', 'Germany')"),
+            sortBy: z.enum(["name"]).optional().describe("Sort results by this field"),
+        },
+    },
+];
+//# sourceMappingURL=search-entity-metadata.js.map

package/dist/mcp/tools/search-entity-metadata.js.map

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

package/dist/mcp/tools/search-input.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared Zod input schemas for structured search and batch fetch tools.
+ * @module mcp/tools/search-input
+ */
+import { z } from "zod";
+/** Pagination parameters shared by search_* and fetch_search_pages. */
+export declare const PAGINATION_INPUT_SCHEMA: {
+    readonly skip: z.ZodOptional<z.ZodNumber>;
+    readonly page: z.ZodOptional<z.ZodNumber>;
+};
+/** Core search parameters shared by search_* tools. */
+export declare const SHARED_SEARCH_INPUT: {
+    readonly fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    readonly filters: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodEnum<{
+            "=": "=";
+            "!=": "!=";
+            "<": "<";
+            ">": ">";
+            "<=": "<=";
+            ">=": ">=";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>, z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodLiteral<"in">;
+        value: z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodPipe<z.ZodNumber, z.ZodTransform<number[], number>>, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>]>;
+    }, z.core.$strip>, z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodLiteral<"is_empty">;
+    }, z.core.$strip>, z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodLiteral<"is_not_empty">;
+    }, z.core.$strip>], "operator">>>;
+    readonly confirmLargeFetch: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    readonly skip: z.ZodOptional<z.ZodNumber>;
+    readonly page: z.ZodOptional<z.ZodNumber>;
+    readonly query: z.ZodString;
+    readonly limit: z.ZodDefault<z.ZodNumber>;
+};
+/** Output schema fields for paginated search responses. */
+export declare const PAGINATION_OUTPUT_SCHEMA: {
+    readonly pagination: z.ZodOptional<z.ZodObject<{
+        pageSize: z.ZodNumber;
+        skip: z.ZodNumber;
+        page: z.ZodNumber;
+        nextSkip: z.ZodNullable<z.ZodNumber>;
+        maxPageSize: z.ZodNumber;
+        maxTotalRecords: z.ZodNumber;
+        maxPagesRemaining: z.ZodNumber;
+        estimatedRequestsToFetchAll: z.ZodNumber;
+        estimatedMinutesToFetchAll: z.ZodNumber;
+    }, z.core.$strip>>;
+    readonly largeResultWarning: z.ZodOptional<z.ZodString>;
+    readonly policyNotice: z.ZodOptional<z.ZodString>;
+};
+//# sourceMappingURL=search-input.d.ts.map

package/dist/mcp/tools/search-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-input.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/search-input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,uEAAuE;AACvE,eAAO,MAAM,uBAAuB;;;CAmB1B,CAAC;AAEX,uDAAuD;AACvD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BtB,CAAC;AAEX,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;CAuB3B,CAAC"}

package/dist/mcp/tools/search-input.js

@@ -0,0 +1,76 @@
+/**
+ * Shared Zod input schemas for structured search and batch fetch tools.
+ * @module mcp/tools/search-input
+ */
+import { z } from "zod";
+import { ExtendedWhereFilterSchema, SCHEMA_LIMITS } from "../../dsl/index.js";
+/** Pagination parameters shared by search_* and fetch_search_pages. */
+export const PAGINATION_INPUT_SCHEMA = {
+    skip: z
+        .number()
+        .int()
+        .min(0)
+        .max(SCHEMA_LIMITS.maxOffset - 1)
+        .optional()
+        .describe(`Records to skip (0-based). Mutually exclusive with page. Max window: ${SCHEMA_LIMITS.maxOffset} total records.`),
+    page: z
+        .number()
+        .int()
+        .min(0)
+        .max(SCHEMA_LIMITS.maxPages - 1)
+        .optional()
+        .describe(`Page index (0-based). Equivalent to skip = page × limit. Max page ${SCHEMA_LIMITS.maxPages - 1}.`),
+};
+/** Core search parameters shared by search_* tools. */
+export const SHARED_SEARCH_INPUT = {
+    query: z
+        .string()
+        .describe("Search query terms (omit with filters-only search if the API allows)"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(SCHEMA_LIMITS.maxLimit)
+        .default(100)
+        .describe(`Maximum results to return (max ${SCHEMA_LIMITS.maxLimit}, default 100)`),
+    ...PAGINATION_INPUT_SCHEMA,
+    fields: z
+        .array(z.string())
+        .optional()
+        .describe("Fields to return. Accepts aliases or DSL names. Use dimensions://fields/{entity} for the full list."),
+    filters: z
+        .array(ExtendedWhereFilterSchema)
+        .optional()
+        .describe("Additional where-clause filters"),
+    confirmLargeFetch: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Required when skip≥5000, page≥5, or limit=1000 with skip>0. Acknowledges Dimensions reasonable-use policy (dimensions://schema/policy)."),
+};
+/** Output schema fields for paginated search responses. */
+export const PAGINATION_OUTPUT_SCHEMA = {
+    pagination: z
+        .object({
+        pageSize: z.number(),
+        skip: z.number(),
+        page: z.number(),
+        nextSkip: z.number().nullable(),
+        maxPageSize: z.number(),
+        maxTotalRecords: z.number(),
+        maxPagesRemaining: z.number(),
+        estimatedRequestsToFetchAll: z.number(),
+        estimatedMinutesToFetchAll: z.number(),
+    })
+        .optional()
+        .describe("Pagination metadata when results span multiple pages"),
+    largeResultWarning: z
+        .string()
+        .optional()
+        .describe("Soft warning when totalCount exceeds 10,000 — narrow filters first"),
+    policyNotice: z
+        .string()
+        .optional()
+        .describe("Reasonable-use reminder when results are truncated or very large"),
+};
+//# sourceMappingURL=search-input.js.map

package/dist/mcp/tools/search-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-input.js","sourceRoot":"","sources":["../../../src/mcp/tools/search-input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE9E,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,aAAa,CAAC,SAAS,GAAG,CAAC,CAAC;SAChC,QAAQ,EAAE;SACV,QAAQ,CACP,wEAAwE,aAAa,CAAC,SAAS,iBAAiB,CACjH;IACH,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,aAAa,CAAC,QAAQ,GAAG,CAAC,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CACP,qEAAqE,aAAa,CAAC,QAAQ,GAAG,CAAC,GAAG,CACnG;CACK,CAAC;AAEX,uDAAuD;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,CAAC,sEAAsE,CAAC;IACnF,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC;SAC3B,OAAO,CAAC,GAAG,CAAC;SACZ,QAAQ,CAAC,kCAAkC,aAAa,CAAC,QAAQ,gBAAgB,CAAC;IACrF,GAAG,uBAAuB;IAC1B,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CACP,qGAAqG,CACtG;IACH,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,yBAAyB,CAAC;SAChC,QAAQ,EAAE;SACV,QAAQ,CAAC,iCAAiC,CAAC;IAC9C,iBAAiB,EAAE,CAAC;SACjB,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,yIAAyI,CAC1I;CACK,CAAC;AAEX,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,UAAU,EAAE,CAAC;SACV,MAAM,CAAC;QACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC/B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;QAC3B,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE;QAC7B,2BAA2B,EAAE,CAAC,CAAC,MAAM,EAAE;QACvC,0BAA0B,EAAE,CAAC,CAAC,MAAM,EAAE;KACvC,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,sDAAsD,CAAC;IACnE,kBAAkB,EAAE,CAAC;SAClB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,oEAAoE,CAAC;IACjF,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kEAAkE,CAAC;CACvE,CAAC"}