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

package/src/dsl/schema/store.ts

@@ -0,0 +1,253 @@
+/**
+ * In-memory schema store built from `describe schema` responses.
+ * @module schema/store
+ */
+
+import { STRUCTURED_ENTITY_TYPES, type StructuredEntityType } from "./structured-entities.js";
+import { buildSchemaSummary, type SchemaSummary } from "./summary.js";
+import type { DescribeSchemaResponse, EntityDescribe, SourceDescribe } from "./types.js";
+
+/** How the schema store was populated. */
+export type SchemaLoadSource = "api" | "cache";
+
+/** Optional metadata when constructing a {@link SchemaStore}. */
+export type SchemaStoreMetadata = {
+  readonly loadSource?: SchemaLoadSource;
+  readonly stale?: boolean;
+  readonly cachedAt?: Date;
+};
+
+/** Operational limits mirrored from upstream DSL constants. */
+export const SCHEMA_LIMITS = {
+  maxLimit: 1000,
+  maxOffset: 50000,
+  maxPages: 50,
+  maxFacetBuckets: 1000,
+  requestsPerMinute: 30,
+} as const;
+
+/**
+ * Read-only schema catalog with derived helper views for tools and clients.
+ */
+export class SchemaStore {
+  readonly #version: string | undefined;
+  readonly #loadedAt: Date;
+  readonly #loadSource: SchemaLoadSource;
+  readonly #stale: boolean;
+  readonly #cachedAt: Date | undefined;
+  readonly #sources: ReadonlyMap<string, SourceDescribe>;
+  readonly #entities: ReadonlyMap<string, EntityDescribe>;
+  readonly #raw: DescribeSchemaResponse;
+
+  /**
+   * @param response - Parsed `describe schema` payload
+   * @param version - Optional DSL version from `describe version`
+   * @param loadedAt - Timestamp when schema was loaded
+   * @param metadata - Cache/API provenance
+   */
+  constructor(
+    response: DescribeSchemaResponse,
+    version?: string,
+    loadedAt: Date = new Date(),
+    metadata: SchemaStoreMetadata = {},
+  ) {
+    this.#raw = response;
+    this.#version = version;
+    this.#loadedAt = loadedAt;
+    this.#loadSource = metadata.loadSource ?? "api";
+    this.#stale = metadata.stale ?? false;
+    this.#cachedAt = metadata.cachedAt;
+    this.#sources = new Map(Object.entries(response.sources ?? {}));
+    this.#entities = new Map(Object.entries(response.entities ?? {}));
+  }
+
+  /** Whether schema came from the API or disk cache. */
+  get loadSource(): SchemaLoadSource {
+    return this.#loadSource;
+  }
+
+  /** True when serving from cache after an API failure or expired TTL. */
+  get stale(): boolean {
+    return this.#stale;
+  }
+
+  /** When the on-disk cache was written, if known. */
+  get cachedAt(): Date | undefined {
+    return this.#cachedAt;
+  }
+
+  /** DSL version string, if known. */
+  get version(): string | undefined {
+    return this.#version;
+  }
+
+  /** When this store was populated. */
+  get loadedAt(): Date {
+    return this.#loadedAt;
+  }
+
+  /** Full describe payload. */
+  get raw(): DescribeSchemaResponse {
+    return this.#raw;
+  }
+
+  /** All source names. */
+  sourceNames(): readonly string[] {
+    return [...this.#sources.keys()].sort();
+  }
+
+  /** All auxiliary entity names. */
+  entityNames(): readonly string[] {
+    return [...this.#entities.keys()].sort();
+  }
+
+  /**
+   * Returns a source schema by name.
+   * @param name - Source name (e.g. `publications`)
+   * @returns Source schema or undefined
+   */
+  getSource(name: string): SourceDescribe | undefined {
+    return this.#sources.get(name);
+  }
+
+  /**
+   * Returns an auxiliary entity schema by name.
+   * @param name - Entity name (e.g. `journals`)
+   * @returns Entity schema or undefined
+   */
+  getEntity(name: string): EntityDescribe | undefined {
+    return this.#entities.get(name);
+  }
+
+  /**
+   * Filterable field names for a source.
+   * @param source - Source name
+   * @returns Field names where `is_filter` is true
+   */
+  filterableFields(source: string): readonly string[] {
+    const fields = this.#sources.get(source)?.fields ?? {};
+    return Object.entries(fields)
+      .filter(([, f]) => f.is_filter === true)
+      .map(([name]) => name)
+      .sort();
+  }
+
+  /**
+   * Facet field names for a source.
+   * @param source - Source name
+   * @returns Field names marked as facets or entity fields
+   */
+  facetFields(source: string): readonly string[] {
+    const fields = this.#sources.get(source)?.fields ?? {};
+    return Object.entries(fields)
+      .filter(([, f]) => f.is_facet === true || f.is_entity === true)
+      .map(([name]) => name)
+      .sort();
+  }
+
+  /**
+   * Search index names for a source.
+   * @param source - Source name
+   * @returns Search field/index names
+   */
+  searchIndexes(source: string): readonly string[] {
+    const raw = this.#sources.get(source)?.search_fields;
+    if (!raw) return [];
+    if (Array.isArray(raw)) return [...raw].sort();
+    return Object.keys(raw).sort();
+  }
+
+  /**
+   * Aggregation indicator names for a source.
+   * @param source - Source name
+   * @returns Metric names
+   */
+  metrics(source: string): readonly string[] {
+    const raw = this.#sources.get(source)?.metrics;
+    if (!raw) return [];
+    if (Array.isArray(raw)) return [...raw].sort();
+    return Object.keys(raw).sort();
+  }
+
+  /**
+   * Named fieldsets for a source.
+   * @param source - Source name
+   * @returns Fieldset name to field list map
+   */
+  fieldsets(source: string): Readonly<Record<string, readonly string[]>> {
+    return this.#sources.get(source)?.fieldsets ?? {};
+  }
+
+  /**
+   * Core entity types supported by structured search tools.
+   * @returns Structured sources that exist in the loaded describe schema
+   */
+  structuredEntityTypes(): readonly StructuredEntityType[] {
+    return STRUCTURED_ENTITY_TYPES.filter((entity) => this.#sources.has(entity));
+  }
+
+  /**
+   * Health/stats payload for `/health`.
+   * @returns Summary object
+   */
+  stats(): {
+    dslVersion: string | undefined;
+    sourceCount: number;
+    entityCount: number;
+    schemaLoadedAt: string;
+    loadSource: SchemaLoadSource;
+    stale: boolean;
+    cachedAt: string | undefined;
+  } {
+    return {
+      dslVersion: this.#version,
+      sourceCount: this.#sources.size,
+      entityCount: this.#entities.size,
+      schemaLoadedAt: this.#loadedAt.toISOString(),
+      loadSource: this.#loadSource,
+      stale: this.#stale,
+      cachedAt: this.#cachedAt?.toISOString(),
+    };
+  }
+
+  /**
+   * Compact overview for cold-start discovery (fields, facets, resource URIs).
+   * @returns Summary payload
+   */
+  summary(): SchemaSummary {
+    return buildSchemaSummary(this);
+  }
+
+  /**
+   * Comma-separated facet fields for tool descriptions.
+   * @param source - Source name
+   * @returns Hint string
+   */
+  facetFieldsHint(source: string): string {
+    return this.facetFields(source).join(", ") || "(none)";
+  }
+
+  /**
+   * Comma-separated metrics for tool descriptions.
+   * @param source - Source name
+   * @returns Hint string
+   */
+  metricsHint(source: string): string {
+    return this.metrics(source).join(", ") || "(none)";
+  }
+}
+
+/**
+ * Builds a {@link SchemaStore} from a describe response.
+ * @param response - `describe schema` JSON
+ * @param version - Optional DSL version
+ * @returns Schema store instance
+ */
+export function createSchemaStoreFromResponse(
+  response: DescribeSchemaResponse,
+  version?: string,
+  loadedAt?: Date,
+  metadata?: SchemaStoreMetadata,
+): SchemaStore {
+  return new SchemaStore(response, version, loadedAt, metadata);
+}

package/src/dsl/schema/structured-entities.ts

@@ -0,0 +1,44 @@
+/**
+ * Structured search entity types supported by search tools.
+ * @module schema/structured-entities
+ */
+
+/** Source names that have dedicated structured search tools. */
+export const STRUCTURED_ENTITY_TYPES = [
+  "publications",
+  "grants",
+  "researchers",
+  "patents",
+  "clinical_trials",
+  "datasets",
+  "policy_documents",
+  "organizations",
+] as const;
+
+/** A source with a structured search tool. */
+export type StructuredEntityType = (typeof STRUCTURED_ENTITY_TYPES)[number];
+
+/**
+ * Tool name for a structured entity.
+ * @param source - Dimensions source name
+ * @returns Tool name (e.g. `search_publications`)
+ */
+export function searchToolName(source: StructuredEntityType): string {
+  return `search_${source}`;
+}
+
+/**
+ * JSON result key for entity rows (camelCase where historical tools used it).
+ * @param source - Dimensions source name
+ * @returns Property name in tool output
+ */
+export function searchResultKey(source: StructuredEntityType): string {
+  switch (source) {
+    case "clinical_trials":
+      return "clinicalTrials";
+    case "policy_documents":
+      return "policyDocuments";
+    default:
+      return source;
+  }
+}

package/src/dsl/schema/summary.ts

@@ -0,0 +1,94 @@
+/**
+ * Compact schema summary for cold-start and agent discovery.
+ * @module schema/summary
+ */
+
+import { SCHEMA_LIMITS, type SchemaStore } from "./store.js";
+
+/** MCP resource URIs for drilling into the full schema. */
+export const SCHEMA_RESOURCE_URIS = {
+  full: "dimensions://schema",
+  summary: "dimensions://schema/summary",
+  version: "dimensions://schema/version",
+  limits: "dimensions://schema/limits",
+  policy: "dimensions://schema/policy",
+  fields: "dimensions://fields/{entityType}",
+  source: "dimensions://schema/sources/{sourceName}",
+  entity: "dimensions://schema/entities/{entityName}",
+  examples: "dimensions://examples",
+  examplesBySource: "dimensions://examples/{source}",
+} as const;
+
+/** Per-source counts derived from describe schema. */
+export type SchemaSourceSummary = {
+  readonly filterableFieldCount: number;
+  readonly facetFieldCount: number;
+  readonly searchIndexCount: number;
+  readonly metricCount: number;
+  readonly fieldsetNames: readonly string[];
+};
+
+/** Compact schema overview for agents and MCP tools. */
+export type SchemaSummary = {
+  readonly version: string | undefined;
+  readonly loadedAt: string;
+  readonly cachedAt: string | undefined;
+  readonly stale: boolean;
+  readonly loadSource: "api" | "cache";
+  readonly limits: typeof SCHEMA_LIMITS;
+  readonly stats: {
+    readonly sourceCount: number;
+    readonly entityCount: number;
+    readonly structuredEntityTypes: readonly string[];
+  };
+  readonly sources: Readonly<Record<string, SchemaSourceSummary>>;
+  readonly entities: readonly string[];
+  readonly resources: typeof SCHEMA_RESOURCE_URIS;
+  readonly hint: string;
+};
+
+/**
+ * Builds a compact schema summary from a loaded {@link SchemaStore}.
+ * @param store - Loaded schema store
+ * @returns Summary payload for tools and resources
+ */
+export function buildSchemaSummary(store: SchemaStore): SchemaSummary {
+  const sources: Record<string, SchemaSourceSummary> = {};
+  for (const name of store.sourceNames()) {
+    const fieldsets = store.fieldsets(name);
+    sources[name] = {
+      filterableFieldCount: store.filterableFields(name).length,
+      facetFieldCount: store.facetFields(name).length,
+      searchIndexCount: store.searchIndexes(name).length,
+      metricCount: store.metrics(name).length,
+      fieldsetNames: Object.keys(fieldsets).sort(),
+    };
+  }
+
+  const stats = store.stats();
+  const staleNote = store.stale
+    ? " (stale cache — call refresh_schema when the API is reachable)"
+    : "";
+
+  return {
+    version: store.version,
+    loadedAt: store.loadedAt.toISOString(),
+    cachedAt: store.cachedAt?.toISOString(),
+    stale: store.stale,
+    loadSource: store.loadSource,
+    limits: SCHEMA_LIMITS,
+    stats: {
+      sourceCount: stats.sourceCount,
+      entityCount: stats.entityCount,
+      structuredEntityTypes: store.structuredEntityTypes(),
+    },
+    sources,
+    entities: store.entityNames(),
+    resources: SCHEMA_RESOURCE_URIS,
+    hint:
+      `Use dimensions://fields/{entityType} for filterable fields and aliases. ` +
+      `Read dimensions://schema/policy before large paginated pulls. ` +
+      `Use dimensions://schema/sources/{name} or describe_schema with source/entity for detail. ` +
+      `Full raw describe: describe_schema with full=true or dimensions://schema.${staleNote}`,
+  };
+}

package/src/dsl/schema/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Types for Dimensions `describe` API responses.
+ * @module schema/types
+ */
+
+/** Field metadata from `describe schema` / `describe source`. */
+export type DescribeField = {
+  readonly type: string;
+  readonly description?: string;
+  readonly long_description?: string;
+  readonly is_entity?: boolean;
+  readonly is_filter?: boolean;
+  readonly is_facet?: boolean;
+  readonly is_multivalue?: boolean;
+};
+
+/** Per-source schema slice from `describe schema`. */
+export type SourceDescribe = {
+  readonly fields: Readonly<Record<string, DescribeField>>;
+  readonly fieldsets?: Readonly<Record<string, readonly string[]>>;
+  readonly metrics?: readonly string[];
+  readonly search_fields?: readonly string[];
+};
+
+/** Auxiliary entity schema from `describe schema`. */
+export type EntityDescribe = {
+  readonly fields: Readonly<Record<string, DescribeField>>;
+};
+
+/** Full response from `describe schema`. */
+export type DescribeSchemaResponse = {
+  readonly sources: Readonly<Record<string, SourceDescribe>>;
+  readonly entities: Readonly<Record<string, EntityDescribe>>;
+};
+
+/** Response from `describe version`. */
+export type DescribeVersionResponse = {
+  readonly version?: string;
+  readonly release?: string;
+};

package/src/dsl/schema/validation.ts

@@ -0,0 +1,56 @@
+/**
+ * Runtime validation helpers using {@link SchemaStore} when available.
+ * @module schema/validation
+ */
+
+import { ValidationError } from "../../client/index.js";
+import type { EntityType, SearchIndex } from "../types/vocabulary.js";
+import { VALID_ENTITIES, VALID_INDEXES } from "../types/vocabulary.js";
+import type { SchemaStore } from "./store.js";
+
+/**
+ * Validates a Dimensions source/entity name.
+ * @param schemaStore - Optional loaded describe schema
+ * @param entity - Source name (e.g. `publications`)
+ * @throws {ValidationError} When the source is unknown
+ */
+export function assertValidEntity(schemaStore: SchemaStore | undefined, entity: string): void {
+  if (schemaStore) {
+    if (!schemaStore.getSource(entity)) {
+      const known = schemaStore.sourceNames().join(", ");
+      throw new ValidationError(
+        `Unknown source: ${entity}${known ? `. Known sources: ${known}` : ""}`,
+      );
+    }
+    return;
+  }
+  if (!VALID_ENTITIES.includes(entity as EntityType)) {
+    throw new ValidationError(`Invalid entity type: ${entity}`);
+  }
+}
+
+/**
+ * Validates a search index for the current source.
+ * @param schemaStore - Optional loaded describe schema
+ * @param entity - Active source from {@link QueryBuilder.search}, if set
+ * @param index - Search index name
+ * @throws {ValidationError} When the index is unknown
+ */
+export function assertValidSearchIndex(
+  schemaStore: SchemaStore | undefined,
+  entity: string | null,
+  index: string,
+): void {
+  if (schemaStore && entity) {
+    const indexes = schemaStore.searchIndexes(entity);
+    if (indexes.length > 0 && !indexes.includes(index)) {
+      throw new ValidationError(
+        `Invalid search index "${index}" for ${entity}. Valid indexes: ${indexes.join(", ")}`,
+      );
+    }
+    return;
+  }
+  if (!VALID_INDEXES.includes(index as SearchIndex)) {
+    throw new ValidationError(`Invalid search index: ${index}`);
+  }
+}

package/src/dsl/types/buckets.ts

@@ -0,0 +1,22 @@
+/**
+ * Bucket types for Dimensions API facet results.
+ * @module types/buckets
+ */
+
+/**
+ * Base bucket with id and count (always present).
+ */
+export interface BaseBucket {
+  readonly id: string | number;
+  readonly count: number;
+}
+
+/**
+ * Bucket with dynamic aggregation indicator properties from the API.
+ */
+export type BucketWithAggregations<
+  TBucket extends BaseBucket = BaseBucket,
+  TIndicators extends readonly string[] = readonly string[],
+> = TBucket & {
+  readonly [K in TIndicators[number]]?: number;
+};

package/src/dsl/types/common.ts

@@ -0,0 +1,99 @@
+/**
+ * Common type definitions shared across Dimensions API entities.
+ * @module types/common
+ */
+
+/**
+ * Represents an author of a publication or other research output.
+ */
+export interface Author {
+  /** Dimensions author ID */
+  id?: string;
+  /** Author's first name */
+  first_name?: string;
+  /** Author's last name */
+  last_name?: string;
+  /** Author's full name (if first/last not available) */
+  full_name?: string;
+  /** ORCID identifier */
+  orcid?: string;
+  /** Author's institutional affiliations */
+  affiliations?: Affiliation[];
+}
+
+/**
+ * Represents an institutional affiliation.
+ */
+export interface Affiliation {
+  /** Dimensions affiliation ID */
+  id?: string;
+  /** Institution name */
+  name: string;
+  /** City where institution is located */
+  city?: string;
+  /** State/province where institution is located */
+  state?: string;
+  /** Country where institution is located */
+  country?: string;
+}
+
+/**
+ * Represents a research organization (university, institute, etc.).
+ */
+export interface ResearchOrg {
+  /** Dimensions organization ID */
+  id?: string;
+  /** Organization name */
+  name: string;
+  /** City where organization is located */
+  city?: string;
+  /** Country where organization is located */
+  country?: string;
+}
+
+/**
+ * Represents a funding organization.
+ */
+export interface FunderOrg {
+  /** Dimensions funder ID */
+  id?: string;
+  /** Funder name */
+  name: string;
+  /** Funder acronym (e.g., "NIH", "NSF") */
+  acronym?: string;
+  /** Country where funder is based */
+  country?: string;
+}
+
+/**
+ * Represents a category code (FOR, SDG, etc.).
+ */
+export interface CategoryCode {
+  /** Category code identifier */
+  id: string;
+  /** Category name */
+  name: string;
+}
+
+/**
+ * Represents a concept with its relevance score.
+ */
+export interface ConceptScore {
+  /** Concept name */
+  concept: string;
+  /** Relevance score */
+  relevance: number;
+}
+
+/**
+ * Represents a journal or publication venue.
+ */
+export interface Journal {
+  /** Dimensions journal ID */
+  id?: string;
+  /** Journal title */
+  title: string;
+}
+
+// Re-export QueryExecutor from core for backwards compatibility
+export type { QueryExecutor } from "../../client/index.js";

package/src/dsl/types/entities.ts

@@ -0,0 +1,43 @@
+/**
+ * Entity type definitions for Dimensions API responses.
+ *
+ * Best-effort TypeScript shapes for API result rows. Field names and availability
+ * come from live `describe schema` (see {@link SchemaStore}); these types are not
+ * validated at runtime.
+ *
+ * @module types/entities
+ */
+
+/**
+ * Base row returned by structured search — always includes `id`; other fields vary by source.
+ */
+export interface DimensionsEntityBase {
+  /** Dimensions record ID */
+  id: string;
+  /** Additional fields from the API (see describe schema / return clause) */
+  [key: string]: unknown;
+}
+
+/** @see DimensionsEntityBase */
+export type Publication = DimensionsEntityBase;
+
+/** @see DimensionsEntityBase */
+export type Grant = DimensionsEntityBase;
+
+/** @see DimensionsEntityBase */
+export type Researcher = DimensionsEntityBase;
+
+/** @see DimensionsEntityBase */
+export type Patent = DimensionsEntityBase;
+
+/** @see DimensionsEntityBase */
+export type ClinicalTrial = DimensionsEntityBase;
+
+/** @see DimensionsEntityBase */
+export type Dataset = DimensionsEntityBase;
+
+/** @see DimensionsEntityBase */
+export type PolicyDocument = DimensionsEntityBase;
+
+/** @see DimensionsEntityBase */
+export type Organization = DimensionsEntityBase;