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

package/dist/mcp/resources/schema.js

@@ -0,0 +1,262 @@
+/**
+ * Dynamic MCP resources derived from runtime {@link SchemaStore}.
+ * @module mcp/resources/schema
+ */
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { buildUsagePolicy, SCHEMA_LIMITS, searchToolName, } from "../../dsl/index.js";
+import { DSL_DOCUMENTATION_URL, DSL_EXAMPLE_SOURCE_NAMES, DSL_EXAMPLES_BY_ENTITY, DSL_EXAMPLES_BY_SOURCE_URI, DSL_GENERAL_EXAMPLES, getDslExamplesForSource, } from "../examples/dsl-examples.js";
+import { buildReverseAliasMap } from "../middleware/field-aliases.js";
+/**
+ * Registers schema MCP resources from a loaded {@link SchemaStore}.
+ * @param server - MCP server instance
+ * @param context - Mutable schema context (handlers read latest store)
+ */
+export function registerSchemaResources(server, context) {
+    const schemaStore = () => context.store;
+    server.resource("schema-summary", "dimensions://schema/summary", {
+        description: "Compact Dimensions DSL schema overview (counts, resource URIs) — start here on cold-start",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(schemaStore().summary(), null, 2),
+            },
+        ],
+    }));
+    // Full schema
+    server.resource("schema-full", "dimensions://schema", {
+        description: "Full Dimensions DSL schema (all sources and auxiliary entities). Prefer dimensions://schema/summary for discovery.",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(schemaStore().raw, null, 2),
+            },
+        ],
+    }));
+    // Version
+    server.resource("schema-version", "dimensions://schema/version", {
+        description: "Dimensions DSL version",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify({ version: schemaStore().version, loadedAt: schemaStore().loadedAt.toISOString() }, null, 2),
+            },
+        ],
+    }));
+    // Limits (static until upstream `describe limits` exists)
+    server.resource("schema-limits", "dimensions://schema/limits", {
+        description: "Operational limits for Dimensions DSL queries",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(SCHEMA_LIMITS, null, 2),
+            },
+        ],
+    }));
+    server.resource("schema-policy", "dimensions://schema/policy", {
+        description: "Dimensions reasonable-use policy, MCP guardrails, and pagination recommendations",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(buildUsagePolicy(), null, 2),
+            },
+        ],
+    }));
+    server.resource("dsl-examples", "dimensions://examples", {
+        description: `Curated Dimensions DSL example queries. See official docs: ${DSL_DOCUMENTATION_URL}`,
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    documentation: DSL_DOCUMENTATION_URL,
+                    general: DSL_GENERAL_EXAMPLES,
+                    sources: DSL_EXAMPLE_SOURCE_NAMES,
+                    bySource: DSL_EXAMPLES_BY_SOURCE_URI,
+                    byEntity: DSL_EXAMPLES_BY_ENTITY,
+                }, null, 2),
+            },
+        ],
+    }));
+    server.resource("dsl-examples-by-source", new ResourceTemplate("dimensions://examples/{source}", {
+        list: async () => ({
+            resources: DSL_EXAMPLE_SOURCE_NAMES.map((source) => ({
+                uri: `dimensions://examples/${source}`,
+                name: `${source} DSL examples`,
+                description: `Curated DSL example queries for ${source}`,
+                mimeType: "application/json",
+            })),
+        }),
+        complete: {
+            source: (value) => DSL_EXAMPLE_SOURCE_NAMES.filter((name) => name.startsWith(value)),
+        },
+    }), {
+        description: "Per-source curated Dimensions DSL example queries",
+        mimeType: "application/json",
+    }, async (uri, { source }) => {
+        const sourceName = String(source);
+        const examples = getDslExamplesForSource(sourceName);
+        if (!examples) {
+            throw new Error(`No examples for source: ${sourceName}. Available: ${DSL_EXAMPLE_SOURCE_NAMES.join(", ")}`);
+        }
+        const structured = schemaStore().structuredEntityTypes();
+        const relatedResources = {
+            fields: `dimensions://fields/${sourceName}`,
+            schemaSource: `dimensions://schema/sources/${sourceName}`,
+        };
+        if (structured.includes(sourceName)) {
+            relatedResources.searchTool = searchToolName(sourceName);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        source: sourceName,
+                        documentation: DSL_DOCUMENTATION_URL,
+                        examples,
+                        relatedResources,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    const sourceNames = () => schemaStore().sourceNames();
+    server.resource("schema-sources", new ResourceTemplate("dimensions://schema/sources/{sourceName}", {
+        list: async () => ({
+            resources: sourceNames().map((name) => ({
+                uri: `dimensions://schema/sources/${name}`,
+                name: `${name} schema`,
+                description: `Schema for source ${name}`,
+                mimeType: "application/json",
+            })),
+        }),
+        complete: {
+            sourceName: (value) => sourceNames().filter((name) => name.startsWith(value)),
+        },
+    }), {
+        description: "Per-source Dimensions DSL schema",
+        mimeType: "application/json",
+    }, async (uri, { sourceName }) => {
+        const source = schemaStore().getSource(String(sourceName));
+        if (!source) {
+            throw new Error(`Unknown source: ${sourceName}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(source, null, 2),
+                },
+            ],
+        };
+    });
+    const entityNames = () => schemaStore().entityNames();
+    server.resource("schema-entities", new ResourceTemplate("dimensions://schema/entities/{entityName}", {
+        list: async () => ({
+            resources: entityNames().map((name) => ({
+                uri: `dimensions://schema/entities/${name}`,
+                name: `${name} entity schema`,
+                description: `Auxiliary entity schema for ${name}`,
+                mimeType: "application/json",
+            })),
+        }),
+        complete: {
+            entityName: (value) => entityNames().filter((name) => name.startsWith(value)),
+        },
+    }), {
+        description: "Auxiliary entity schema for dot-notation filters",
+        mimeType: "application/json",
+    }, async (uri, { entityName }) => {
+        const entity = schemaStore().getEntity(String(entityName));
+        if (!entity) {
+            throw new Error(`Unknown entity: ${entityName}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(entity, null, 2),
+                },
+            ],
+        };
+    });
+    // Compatibility view for structured search tools
+    const entityTypes = () => schemaStore().structuredEntityTypes();
+    server.resource("fields", new ResourceTemplate("dimensions://fields/{entityType}", {
+        list: async () => ({
+            resources: entityTypes().map((et) => ({
+                uri: `dimensions://fields/${et}`,
+                name: `${et} fields`,
+                description: `Filterable fields for ${et}`,
+                mimeType: "application/json",
+            })),
+        }),
+        complete: {
+            entityType: (value) => entityTypes().filter((et) => et.startsWith(value)),
+        },
+    }), {
+        description: "Filterable fields and aliases for a Dimensions entity type",
+        mimeType: "application/json",
+    }, async (uri, { entityType }) => {
+        const entity = String(entityType);
+        if (!entityTypes().includes(entity)) {
+            throw new Error(`Unknown entity type: ${entity}`);
+        }
+        const source = schemaStore().getSource(entity);
+        if (!source) {
+            throw new Error(`No schema loaded for entity type: ${entity}`);
+        }
+        const reverseAliases = buildReverseAliasMap(entity);
+        const augmentedFields = {};
+        for (const [fieldName, field] of Object.entries(source.fields)) {
+            if (field.is_filter !== true) {
+                continue;
+            }
+            const description = field.description ?? field.type;
+            const aliases = reverseAliases.get(fieldName);
+            augmentedFields[fieldName] = aliases ? { description, aliases } : { description };
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        entityType: entity,
+                        fields: augmentedFields,
+                        facets: schemaStore().facetFields(entity),
+                        metrics: schemaStore().metrics(entity),
+                        searchIndexes: schemaStore().searchIndexes(entity),
+                        fieldsets: schemaStore().fieldsets(entity),
+                        dslExamples: {
+                            basicSearch: `search ${entity} for "your query" return ${entity} limit 10`,
+                            withFields: `search ${entity} for "your query" return ${entity}[id+title] limit 10`,
+                            withFilter: `search ${entity} for "your query" where year >= 2020 return ${entity} limit 10`,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=schema.js.map

package/dist/mcp/resources/schema.js.map

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

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

@@ -0,0 +1,10 @@
+/**
+ * Mutable schema context shared across MCP resources and tools.
+ * @module schema/context
+ */
+import type { SchemaStore } from "../../dsl/index.js";
+/** Mutable holder so refresh can update the active store without re-registering resources. */
+export type SchemaContext = {
+    store: SchemaStore;
+};
+//# sourceMappingURL=context.d.ts.map

package/dist/mcp/schema/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/mcp/schema/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,WAAW,CAAC;CACpB,CAAC"}

package/dist/mcp/schema/context.js

@@ -0,0 +1,6 @@
+/**
+ * Mutable schema context shared across MCP resources and tools.
+ * @module schema/context
+ */
+export {};
+//# sourceMappingURL=context.js.map

package/dist/mcp/schema/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/mcp/schema/context.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

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

@@ -0,0 +1,8 @@
+/**
+ * Runtime schema loading and access for the MCP server.
+ * @module schema
+ */
+export type { DescribeField, DescribeSchemaResponse, DescribeVersionResponse, EntityDescribe, LoadSchemaOptions, SchemaCacheEntry, SchemaCacheEnvelope, SchemaLoadSource, SchemaSourceSummary, SchemaStoreMetadata, SchemaSummary, SourceDescribe, StructuredEntityType, } from "../../dsl/index.js";
+export { buildSchemaSummary, clearSchemaCache, createSchemaStoreFromResponse, DEFAULT_SCHEMA_CACHE_TTL_MS, extractDescribeSchema, extractDescribeVersion, getCachedSchemaStore, getOrLoadSchema, loadSchema, SCHEMA_LIMITS, SCHEMA_RESOURCE_URIS, SchemaStore, STRUCTURED_ENTITY_TYPES, searchResultKey, searchToolName, } from "../../dsl/index.js";
+export type { SchemaContext } from "./context.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/mcp/schema/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,6BAA6B,EAC7B,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,uBAAuB,EACvB,eAAe,EACf,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/mcp/schema/index.js

@@ -0,0 +1,6 @@
+/**
+ * Runtime schema loading and access for the MCP server.
+ * @module schema
+ */
+export { buildSchemaSummary, clearSchemaCache, createSchemaStoreFromResponse, DEFAULT_SCHEMA_CACHE_TTL_MS, extractDescribeSchema, extractDescribeVersion, getCachedSchemaStore, getOrLoadSchema, loadSchema, SCHEMA_LIMITS, SCHEMA_RESOURCE_URIS, SchemaStore, STRUCTURED_ENTITY_TYPES, searchResultKey, searchToolName, } from "../../dsl/index.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/mcp/schema/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,6BAA6B,EAC7B,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,uBAAuB,EACvB,eAAe,EACf,cAAc,GACf,MAAM,oBAAoB,CAAC"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Dimensions Analytics MCP server for the Dimensions Analytics API.
+ * Provides tools for searching and querying the Dimensions database.
+ * @module mcp/server
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type HostedEnvConfig } from "../client/index.js";
+import type { DimensionsClient } from "../dsl/index.js";
+import { clearSchemaCache, loadSchema, type SchemaStore } from "../dsl/schema/index.js";
+import type { SchemaContext } from "./schema/context.js";
+/**
+ * Configuration options for the MCP server.
+ */
+export interface McpServerConfig {
+    /** Dimensions API key (required for local stdio) */
+    apiKey?: string;
+    /** Base URL for the Dimensions API (local public backend) */
+    baseUrl?: string;
+    /** Pre-loaded schema store (for tests; skips live describe fetch) */
+    schemaStore?: SchemaStore;
+    /** Deployment mode override */
+    deploymentMode?: "local" | "hosted";
+    /** Hosted deployment env (required when deploymentMode is hosted) */
+    hosted?: HostedEnvConfig;
+    /** Resolved user email for hosted dsl-service (per session) */
+    userEmail?: string;
+    /** Client IP to forward to dsl-service and auth.json */
+    clientIp?: string;
+}
+/**
+ * Builds server instructions from loaded schema.
+ */
+export declare function buildServerInstructions(schemaStore: SchemaStore): string;
+/**
+ * Warms the shared schema cache for hosted deployment (call once at process startup).
+ */
+export declare function warmHostedSchemaCache(hosted: HostedEnvConfig): Promise<SchemaStore>;
+/**
+ * Creates and configures the MCP server.
+ */
+export declare function createMcpServerAsync(config?: McpServerConfig): Promise<{
+    server: McpServer;
+    client: DimensionsClient;
+    schemaContext: SchemaContext;
+    schemaStore: SchemaStore;
+}>;
+export interface McpServerHandle {
+    readonly close: () => Promise<void>;
+}
+/**
+ * Starts the MCP server with the given transport (defaults to stdio).
+ */
+export declare function startMcpServer(injectedTransport?: Transport, config?: McpServerConfig): Promise<McpServerHandle>;
+export { clearSchemaCache, loadSchema, McpServer };
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE/E,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,oBAAoB,CAAC;AAEhF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,gBAAgB,EAEhB,UAAU,EACV,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAUzD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+BAA+B;IAC/B,cAAc,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,qEAAqE;IACrE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA4BD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAqCxE;AAmCD;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAGzF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,GAAE,eAAoB,GAAG,OAAO,CAAC;IAChF,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;CAC1B,CAAC,CA8CD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,iBAAiB,CAAC,EAAE,SAAS,EAC7B,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAmB1B;AAED,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC"}

package/dist/mcp/server.js

@@ -0,0 +1,168 @@
+/**
+ * Dimensions Analytics MCP server for the Dimensions Analytics API.
+ * Provides tools for searching and querying the Dimensions database.
+ * @module mcp/server
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import pkg from "../../package.json" with { type: "json" };
+import { loadDeploymentConfig } from "../client/index.js";
+import { createBootstrapDimensionsClient, createDimensionsClient } from "../dsl/create-client.js";
+import { clearSchemaCache, getOrLoadSchema, loadSchema, } from "../dsl/schema/index.js";
+import { registerSchemaResources } from "./resources/schema.js";
+import { getSharedSchemaStore } from "./shared-schema.js";
+import { registerAnalyticsTools } from "./tools/analytics.js";
+import { registerFetchSearchPagesTools } from "./tools/fetch-search-pages.js";
+import { registerFunctionTools } from "./tools/functions.js";
+import { registerLookupTools } from "./tools/lookup.js";
+import { registerQueryTools } from "./tools/query.js";
+import { registerSchemaTools, validateFieldAliases } from "./tools/schema.js";
+import { registerSearchTools } from "./tools/search.js";
+/**
+ * Reads a positive integer from an environment variable with a default fallback.
+ */
+function readIntEnv(raw, fallback, min) {
+    if (raw == null || raw.trim() === "")
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value >= min ? value : fallback;
+}
+function resolveDeployment(config) {
+    if (config.deploymentMode) {
+        return {
+            mode: config.deploymentMode,
+            hosted: config.hosted,
+        };
+    }
+    const loaded = loadDeploymentConfig();
+    if (loaded.deploymentMode === "hosted") {
+        return { mode: "hosted", hosted: loaded };
+    }
+    return { mode: "local" };
+}
+/**
+ * Builds server instructions from loaded schema.
+ */
+export function buildServerInstructions(schemaStore) {
+    const version = schemaStore.version ? ` DSL ${schemaStore.version}.` : "";
+    const paginationNote = process.env.DEPLOYMENT_MODE === "hosted"
+        ? "search_* supports skip/page; fetch_search_pages is not available on hosted MCP;"
+        : "search_* / fetch_search_pages: skip/page (max 1000/page, 50 pages, 50000 records);";
+    return [
+        `Dimensions Analytics API — scholarly research data.${version}`,
+        [
+            "Workflow:",
+            "(1) Discover schema — read dimensions://schema/summary, dimensions://fields/{entity}, dimensions://examples/{source}, or describe_schema;",
+            "(2) Search — search_* for keyword discovery with filters; get_by_doi, get_by_pmid, get_by_id for known identifiers;",
+            "(3) Analyze — facet_query, aggregate_query, citation_trend, funding_trend;",
+            "(4) Drill down — get_by_id, search_* with filters (e.g. researchers.id, research_orgs.id), facet_query for top researchers at an org.",
+        ].join(" "),
+        [
+            "Routing:",
+            "search_researchers matches names only — topic→researcher uses facet_query (entityType publications, facetField researchers);",
+            "search_grants funderOrgName needs exact Dimensions names (NCI/NSF acronyms resolve; discover funders via facet_query/aggregate_query on facetField funder_orgs);",
+            "search_organizations for institution lookup — prefer GRID id in filters when the name is ambiguous;",
+            "facet_query supports yearFrom/yearTo for year-scoped facets.",
+        ].join(" "),
+        [
+            "Query construction:",
+            "for ranked publication search (e.g. most-cited since 2020), use search_publications with query, yearFrom, sortBy (times_cited or total_citations), limit — do not hand-write execute_dsl;",
+            "use execute_dsl for boolean concept groups and DSL special functions;",
+            "use execute_dsl only when structured tools are insufficient; DSL order is return ... sort by FIELD order limit N (never limit before sort).",
+        ].join(" "),
+        [
+            "Pagination & policy:",
+            "read dimensions://schema/policy before large pulls;",
+            paginationNote,
+            "confirmLargeFetch required for deep pagination (skip≥5000, page≥5) and batch pulls (>5 pages);",
+            "facets max 1000 buckets, no skip; ~30 requests/min client rate limit.",
+        ].join(" "),
+    ].join("\n\n");
+}
+function registerAllTools(server, client, schemaStore, schemaContext, deploymentMode) {
+    registerSchemaResources(server, schemaContext);
+    registerSearchTools(server, client, schemaStore);
+    if (deploymentMode === "local") {
+        registerFetchSearchPagesTools(server, client, schemaStore);
+    }
+    registerLookupTools(server, client);
+    registerQueryTools(server, client, schemaStore);
+    registerFunctionTools(server, client);
+    registerAnalyticsTools(server, client, schemaStore);
+    registerSchemaTools(server, client, schemaContext);
+}
+async function loadSchemaForServer(client, config, deploymentMode) {
+    if (config.schemaStore) {
+        return config.schemaStore;
+    }
+    if (deploymentMode === "hosted") {
+        return getSharedSchemaStore(client);
+    }
+    return getOrLoadSchema(client, process.env.SCHEMA_CACHE_PATH);
+}
+/**
+ * Warms the shared schema cache for hosted deployment (call once at process startup).
+ */
+export async function warmHostedSchemaCache(hosted) {
+    const client = createBootstrapDimensionsClient(hosted);
+    return getSharedSchemaStore(client);
+}
+/**
+ * Creates and configures the MCP server.
+ */
+export async function createMcpServerAsync(config = {}) {
+    const { mode, hosted } = resolveDeployment(config);
+    const client = createDimensionsClient({
+        mode,
+        hosted: hosted ?? config.hosted,
+        apiKey: config.apiKey ?? process.env.DIMENSIONS_API_KEY,
+        userEmail: config.userEmail,
+        clientIp: config.clientIp,
+        baseUrl: config.baseUrl ?? process.env.DIMENSIONS_BASE_URL,
+        maxRetries: readIntEnv(process.env.DIMENSIONS_MAX_RETRIES, 3, 0),
+        retryDelay: readIntEnv(process.env.DIMENSIONS_RETRY_DELAY_MS, 1000, 1),
+        rateLimitPerMinute: readIntEnv(process.env.DIMENSIONS_RATE_LIMIT_PER_MINUTE, 30, 1),
+    });
+    const schemaStore = await loadSchemaForServer(client, config, mode);
+    client.attachSchemaStore(schemaStore);
+    const schemaContext = { store: schemaStore };
+    validateFieldAliases(schemaStore);
+    const startedAt = Date.now();
+    console.error(`Schema loaded: ${schemaStore.stats().sourceCount} sources, ${schemaStore.stats().entityCount} entities` +
+        (schemaStore.version ? `, DSL ${schemaStore.version}` : "") +
+        (schemaStore.stale ? " (stale cache)" : "") +
+        ` [${schemaStore.loadSource}]` +
+        ` (${Date.now() - startedAt}ms)`);
+    const server = new McpServer({
+        name: "dimensions",
+        version: pkg.version,
+    }, {
+        capabilities: {
+            logging: {},
+        },
+        instructions: buildServerInstructions(schemaStore),
+    });
+    registerAllTools(server, client, schemaStore, schemaContext, mode);
+    return { server, client, schemaContext, schemaStore };
+}
+/**
+ * Starts the MCP server with the given transport (defaults to stdio).
+ */
+export async function startMcpServer(injectedTransport, config = {}) {
+    const { server } = await createMcpServerAsync(config);
+    const transport = injectedTransport ?? new StdioServerTransport();
+    server.server.onerror = (error) => console.error(`MCP server error: ${error.message}`);
+    if (!injectedTransport) {
+        server.server.onclose = () => {
+            process.exit(0);
+        };
+    }
+    await server.connect(transport);
+    return {
+        close: async () => {
+            await server.close();
+        },
+    };
+}
+export { clearSchemaCache, loadSchema, McpServer };
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

package/dist/mcp/shared-schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Process-wide describe schema cache for hosted deployment.
+ * @module mcp/shared-schema
+ */
+import type { DimensionsClient } from "../dsl/index.js";
+import { type SchemaStore } from "../dsl/schema/index.js";
+/**
+ * Returns a shared SchemaStore, loading from cache/API on first call.
+ */
+export declare function getSharedSchemaStore(client: DimensionsClient): Promise<SchemaStore>;
+/** Clears the in-memory shared schema (tests). */
+export declare function clearSharedSchemaStore(): void;
+//# sourceMappingURL=shared-schema.d.ts.map

package/dist/mcp/shared-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schema.d.ts","sourceRoot":"","sources":["../../src/mcp/shared-schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAK3E;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAazF;AAED,kDAAkD;AAClD,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}

package/dist/mcp/shared-schema.js

@@ -0,0 +1,28 @@
+/**
+ * Process-wide describe schema cache for hosted deployment.
+ * @module mcp/shared-schema
+ */
+import { getOrLoadSchema } from "../dsl/schema/index.js";
+let sharedSchemaStore;
+let sharedSchemaPromise;
+/**
+ * Returns a shared SchemaStore, loading from cache/API on first call.
+ */
+export async function getSharedSchemaStore(client) {
+    if (sharedSchemaStore) {
+        return sharedSchemaStore;
+    }
+    if (!sharedSchemaPromise) {
+        sharedSchemaPromise = getOrLoadSchema(client, process.env.SCHEMA_CACHE_PATH).then((store) => {
+            sharedSchemaStore = store;
+            return store;
+        });
+    }
+    return sharedSchemaPromise;
+}
+/** Clears the in-memory shared schema (tests). */
+export function clearSharedSchemaStore() {
+    sharedSchemaStore = undefined;
+    sharedSchemaPromise = undefined;
+}
+//# sourceMappingURL=shared-schema.js.map

package/dist/mcp/shared-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-schema.js","sourceRoot":"","sources":["../../src/mcp/shared-schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAoB,MAAM,wBAAwB,CAAC;AAE3E,IAAI,iBAA0C,CAAC;AAC/C,IAAI,mBAAqD,CAAC;AAE1D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAAwB;IACjE,IAAI,iBAAiB,EAAE,CAAC;QACtB,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACzB,mBAAmB,GAAG,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YAC1F,iBAAiB,GAAG,KAAK,CAAC;YAC1B,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,GAAG,SAAS,CAAC;IAC9B,mBAAmB,GAAG,SAAS,CAAC;AAClC,CAAC"}

package/dist/mcp/tools/analytics-filters.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared filter helpers for analytics tools (facet_query, aggregate_query).
+ * @module mcp/tools/analytics-filters
+ */
+import type { EntityType, QueryBuilder } from "../../dsl/index.js";
+import { type ExtendedWhereFilterInput } from "../../dsl/index.js";
+/**
+ * Applies year range and extended where filters to an analytics query builder.
+ * @param builder - Query builder for the target entity
+ * @param entityType - Entity being analyzed
+ * @param args - Tool arguments with optional yearFrom, yearTo, filters
+ */
+export declare function applyAnalyticsFilters(builder: QueryBuilder, entityType: EntityType, args: {
+    yearFrom?: number;
+    yearTo?: number;
+    filters?: readonly ExtendedWhereFilterInput[];
+}): void;
+//# sourceMappingURL=analytics-filters.d.ts.map

package/dist/mcp/tools/analytics-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-filters.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/analytics-filters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAgB,KAAK,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAYjF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;CAC/C,GACA,IAAI,CAaN"}