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

package/src/mcp/resources/schema.ts

@@ -0,0 +1,364 @@
+/**
+ * Dynamic MCP resources derived from runtime {@link SchemaStore}.
+ * @module mcp/resources/schema
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  buildUsagePolicy,
+  type DescribeField,
+  type EntityType,
+  SCHEMA_LIMITS,
+  type SchemaStore,
+  type StructuredEntityType,
+  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";
+import type { SchemaContext } from "../schema/context.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: McpServer, context: SchemaContext): void {
+  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: Record<string, string> = {
+        fields: `dimensions://fields/${sourceName}`,
+        schemaSource: `dimensions://schema/sources/${sourceName}`,
+      };
+      if (structured.includes(sourceName as StructuredEntityType)) {
+        relatedResources.searchTool = searchToolName(sourceName as StructuredEntityType);
+      }
+
+      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) as 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: Record<string, { description: string; aliases?: string[] }> = {};
+      for (const [fieldName, field] of Object.entries(source.fields) as [string, DescribeField][]) {
+        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,
+            ),
+          },
+        ],
+      };
+    },
+  );
+}

package/src/mcp/schema/context.ts

@@ -0,0 +1,11 @@
+/**
+ * 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;
+};

package/src/mcp/schema/index.ts

@@ -0,0 +1,38 @@
+/**
+ * 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";

package/src/mcp/server.ts

@@ -0,0 +1,247 @@
+/**
+ * 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 type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import pkg from "../../package.json" with { type: "json" };
+import { type HostedEnvConfig, loadDeploymentConfig } from "../client/index.js";
+import { createBootstrapDimensionsClient, createDimensionsClient } from "../dsl/create-client.js";
+import type { DimensionsClient } from "../dsl/index.js";
+import {
+  clearSchemaCache,
+  getOrLoadSchema,
+  loadSchema,
+  type SchemaStore,
+} from "../dsl/schema/index.js";
+import { registerSchemaResources } from "./resources/schema.js";
+import type { SchemaContext } from "./schema/context.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";
+
+/**
+ * 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;
+}
+
+/**
+ * Reads a positive integer from an environment variable with a default fallback.
+ */
+function readIntEnv(raw: string | undefined, fallback: number, min: number): number {
+  if (raw == null || raw.trim() === "") return fallback;
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) && value >= min ? value : fallback;
+}
+
+function resolveDeployment(config: McpServerConfig): {
+  mode: "local" | "hosted";
+  hosted?: HostedEnvConfig;
+} {
+  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: SchemaStore): string {
+  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: McpServer,
+  client: DimensionsClient,
+  schemaStore: SchemaStore,
+  schemaContext: SchemaContext,
+  deploymentMode: "local" | "hosted",
+): void {
+  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: DimensionsClient,
+  config: McpServerConfig,
+  deploymentMode: "local" | "hosted",
+): Promise<SchemaStore> {
+  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: HostedEnvConfig): Promise<SchemaStore> {
+  const client = createBootstrapDimensionsClient(hosted);
+  return getSharedSchemaStore(client);
+}
+
+/**
+ * Creates and configures the MCP server.
+ */
+export async function createMcpServerAsync(config: McpServerConfig = {}): Promise<{
+  server: McpServer;
+  client: DimensionsClient;
+  schemaContext: SchemaContext;
+  schemaStore: SchemaStore;
+}> {
+  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: 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 };
+}
+
+export interface McpServerHandle {
+  readonly close: () => Promise<void>;
+}
+
+/**
+ * Starts the MCP server with the given transport (defaults to stdio).
+ */
+export async function startMcpServer(
+  injectedTransport?: Transport,
+  config: McpServerConfig = {},
+): Promise<McpServerHandle> {
+  const { server } = await createMcpServerAsync(config);
+  const transport = injectedTransport ?? new StdioServerTransport();
+
+  server.server.onerror = (error: 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 };

package/src/mcp/shared-schema.ts

@@ -0,0 +1,34 @@
+/**
+ * Process-wide describe schema cache for hosted deployment.
+ * @module mcp/shared-schema
+ */
+
+import type { DimensionsClient } from "../dsl/index.js";
+import { getOrLoadSchema, type SchemaStore } from "../dsl/schema/index.js";
+
+let sharedSchemaStore: SchemaStore | undefined;
+let sharedSchemaPromise: Promise<SchemaStore> | undefined;
+
+/**
+ * Returns a shared SchemaStore, loading from cache/API on first call.
+ */
+export async function getSharedSchemaStore(client: DimensionsClient): Promise<SchemaStore> {
+  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(): void {
+  sharedSchemaStore = undefined;
+  sharedSchemaPromise = undefined;
+}