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

package/dist/mcp/batch-fetch.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Multi-page search fetch helpers (aggregate and file export).
+ * @module mcp/batch-fetch
+ */
+import type { DimensionsClient } from "../dsl/index.js";
+import { type StructuredEntityType } from "../dsl/index.js";
+import { type ExportFormat } from "./export-format.js";
+/** Sidecar metadata written beside export files. */
+export interface BatchExportMeta {
+    readonly queryHash: string;
+    readonly entityType: StructuredEntityType;
+    readonly format: ExportFormat;
+    readonly columns?: readonly string[];
+    readonly lastSkip: number;
+    readonly pagesDone: number;
+    readonly recordsWritten: number;
+    readonly totalCount: number;
+    readonly pageSize: number;
+    readonly updatedAt: string;
+}
+/** Summary returned from aggregate multi-page fetch. */
+export interface AggregateFetchSummary {
+    readonly pagesFetched: number;
+    readonly recordsFetched: number;
+    readonly totalCount: number;
+    readonly ids: string[];
+    readonly idsTruncated: boolean;
+    readonly totalFundingUsd?: number;
+}
+/**
+ * Computes a short hash of the search definition (excluding skip/limit).
+ * @param dsl - Full DSL query string
+ * @returns 16-character hex hash prefix
+ */
+export declare function queryHashFromDsl(dsl: string): string;
+/**
+ * Reads export sidecar metadata if present.
+ * @param metaPath - Path to `.meta.json` sidecar
+ * @returns Parsed metadata or undefined
+ */
+export declare function readExportMeta(metaPath: string): Promise<BatchExportMeta | undefined>;
+/**
+ * Writes export sidecar metadata.
+ * @param metaPath - Path to `.meta.json` sidecar
+ * @param meta - Metadata to persist
+ */
+export declare function writeExportMeta(metaPath: string, meta: BatchExportMeta): Promise<void>;
+/**
+ * Fetches multiple pages and returns an aggregate summary (no full row payloads).
+ * @param client - Dimensions client
+ * @param entityType - Entity source name
+ * @param buildDsl - Factory for DSL given skip and page size
+ * @param options - Batch parameters
+ * @returns Aggregate summary
+ */
+export declare function runAggregateFetch(client: DimensionsClient, entityType: StructuredEntityType, buildDsl: (skip: number, limit: number) => string, options: {
+    startPage: number;
+    maxPages: number;
+    pageSize: number;
+    maxRecords?: number;
+}): Promise<AggregateFetchSummary>;
+/**
+ * Streams multiple pages to a JSONL or CSV file with resume metadata.
+ * @param client - Dimensions client
+ * @param entityType - Entity source name
+ * @param buildDsl - Factory for DSL given skip and page size
+ * @param outputPath - Destination file path
+ * @param options - Batch, format, and resume parameters
+ * @returns Export result summary
+ */
+export declare function runFileFetch(client: DimensionsClient, entityType: StructuredEntityType, buildDsl: (skip: number, limit: number) => string, outputPath: string, options: {
+    startPage: number;
+    maxPages: number;
+    pageSize: number;
+    maxRecords?: number;
+    queryHash: string;
+    format: ExportFormat;
+    preferredFields?: readonly string[];
+    resumeFromMeta?: boolean;
+}): Promise<{
+    outputPath: string;
+    metaPath: string;
+    format: ExportFormat;
+    recordsWritten: number;
+    pagesFetched: number;
+    totalCount: number;
+    resumed: boolean;
+}>;
+//# sourceMappingURL=batch-fetch.d.ts.map

package/dist/mcp/batch-fetch.d.ts.map

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

package/dist/mcp/batch-fetch.js

@@ -0,0 +1,178 @@
+/**
+ * Multi-page search fetch helpers (aggregate and file export).
+ * @module mcp/batch-fetch
+ */
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { AGGREGATE_ID_CAP, parseEntityResponse, SCHEMA_LIMITS, } from "../dsl/index.js";
+import { formatRowsForExport } from "./export-format.js";
+/**
+ * Computes a short hash of the search definition (excluding skip/limit).
+ * @param dsl - Full DSL query string
+ * @returns 16-character hex hash prefix
+ */
+export function queryHashFromDsl(dsl) {
+    const normalized = dsl.replace(/\bskip \d+\b/g, "").replace(/\blimit \d+\b/g, "limit");
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+/**
+ * Reads export sidecar metadata if present.
+ * @param metaPath - Path to `.meta.json` sidecar
+ * @returns Parsed metadata or undefined
+ */
+export async function readExportMeta(metaPath) {
+    try {
+        const raw = await readFile(metaPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Writes export sidecar metadata.
+ * @param metaPath - Path to `.meta.json` sidecar
+ * @param meta - Metadata to persist
+ */
+export async function writeExportMeta(metaPath, meta) {
+    await mkdir(dirname(metaPath), { recursive: true });
+    await writeFile(metaPath, JSON.stringify(meta, null, 2), "utf8");
+}
+/**
+ * Fetches multiple pages and returns an aggregate summary (no full row payloads).
+ * @param client - Dimensions client
+ * @param entityType - Entity source name
+ * @param buildDsl - Factory for DSL given skip and page size
+ * @param options - Batch parameters
+ * @returns Aggregate summary
+ */
+export async function runAggregateFetch(client, entityType, buildDsl, options) {
+    const ids = [];
+    let recordsFetched = 0;
+    let pagesFetched = 0;
+    let totalCount = 0;
+    let totalFundingUsd = 0;
+    let hasFunding = false;
+    for (let p = options.startPage; p < options.startPage + options.maxPages; p++) {
+        const skip = p * options.pageSize;
+        if (skip + options.pageSize > SCHEMA_LIMITS.maxOffset)
+            break;
+        const dsl = buildDsl(skip, options.pageSize);
+        const response = (await client.rawQuery(dsl));
+        const parsed = parseEntityResponse(response, entityType);
+        if (pagesFetched === 0) {
+            totalCount = parsed.totalCount;
+        }
+        for (const row of parsed.data) {
+            if (typeof row.id === "string" && ids.length < AGGREGATE_ID_CAP) {
+                ids.push(row.id);
+            }
+            if (entityType === "grants" && typeof row.funding_usd === "number") {
+                totalFundingUsd += row.funding_usd;
+                hasFunding = true;
+            }
+            recordsFetched++;
+            if (options.maxRecords !== undefined && recordsFetched >= options.maxRecords) {
+                break;
+            }
+        }
+        pagesFetched++;
+        if (parsed.data.length < options.pageSize)
+            break;
+        if (options.maxRecords !== undefined && recordsFetched >= options.maxRecords)
+            break;
+    }
+    return {
+        pagesFetched,
+        recordsFetched,
+        totalCount,
+        ids,
+        idsTruncated: recordsFetched > ids.length,
+        ...(hasFunding ? { totalFundingUsd } : {}),
+    };
+}
+/**
+ * Streams multiple pages to a JSONL or CSV file with resume metadata.
+ * @param client - Dimensions client
+ * @param entityType - Entity source name
+ * @param buildDsl - Factory for DSL given skip and page size
+ * @param outputPath - Destination file path
+ * @param options - Batch, format, and resume parameters
+ * @returns Export result summary
+ */
+export async function runFileFetch(client, entityType, buildDsl, outputPath, options) {
+    const metaPath = `${outputPath}.meta.json`;
+    let startPage = options.startPage;
+    let recordsWritten = 0;
+    let resumed = false;
+    let csvColumns;
+    if (options.resumeFromMeta) {
+        const existing = await readExportMeta(metaPath);
+        if (existing?.queryHash === options.queryHash &&
+            existing.entityType === entityType &&
+            existing.format === options.format) {
+            startPage = Math.floor(existing.lastSkip / options.pageSize) + 1;
+            recordsWritten = existing.recordsWritten;
+            csvColumns = existing.columns ? [...existing.columns] : undefined;
+            resumed = true;
+        }
+    }
+    await mkdir(dirname(outputPath), { recursive: true });
+    let pagesFetched = 0;
+    let totalCount = 0;
+    for (let p = startPage; p < startPage + options.maxPages; p++) {
+        const skip = p * options.pageSize;
+        if (skip + options.pageSize > SCHEMA_LIMITS.maxOffset)
+            break;
+        const dsl = buildDsl(skip, options.pageSize);
+        const response = (await client.rawQuery(dsl));
+        const parsed = parseEntityResponse(response, entityType);
+        if (pagesFetched === 0 && !resumed) {
+            totalCount = parsed.totalCount;
+        }
+        else if (totalCount === 0) {
+            totalCount = parsed.totalCount;
+        }
+        const rows = parsed.data;
+        const { text, columns } = formatRowsForExport(rows, options.format, {
+            columns: csvColumns,
+            preferredFields: options.preferredFields,
+            includeHeader: options.format === "csv" && recordsWritten === 0 && rows.length > 0,
+        });
+        if (options.format === "csv" && columns.length > 0) {
+            csvColumns = columns;
+        }
+        if (text.length > 0) {
+            await appendFile(outputPath, text, "utf8");
+        }
+        recordsWritten += rows.length;
+        pagesFetched++;
+        await writeExportMeta(metaPath, {
+            queryHash: options.queryHash,
+            entityType,
+            format: options.format,
+            ...(csvColumns?.length ? { columns: csvColumns } : {}),
+            lastSkip: skip,
+            pagesDone: p + 1,
+            recordsWritten,
+            totalCount,
+            pageSize: options.pageSize,
+            updatedAt: new Date().toISOString(),
+        });
+        if (rows.length < options.pageSize)
+            break;
+        if (options.maxRecords !== undefined && recordsWritten >= options.maxRecords)
+            break;
+    }
+    return {
+        outputPath,
+        metaPath,
+        format: options.format,
+        recordsWritten,
+        pagesFetched,
+        totalCount,
+        resumed,
+    };
+}
+//# sourceMappingURL=batch-fetch.js.map

package/dist/mcp/batch-fetch.js.map

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

package/dist/mcp/examples/dsl-examples.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Curated DSL examples for MCP resources (from public Dimensions DSL documentation patterns).
+ * @module examples/dsl-examples
+ */
+/** URI template for per-source example resources. */
+export declare const DSL_EXAMPLES_BY_SOURCE_URI = "dimensions://examples/{source}";
+/** Example queries keyed by entity type. */
+export declare const DSL_EXAMPLES_BY_ENTITY: Record<string, readonly string[]>;
+/** General DSL patterns (describe, functions, pagination). */
+export declare const DSL_GENERAL_EXAMPLES: readonly ["describe version", "describe schema", "describe source publications", "extract_concepts(text: \"CRISPR gene editing enables precise DNA modification\")", "classify(text: \"Stem cell therapy for diabetes\", system: \"for\")"];
+/** Link to official DSL documentation. */
+export declare const DSL_DOCUMENTATION_URL = "https://docs.dimensions.ai/dsl/";
+/** Source names that have curated per-source example resources. */
+export declare const DSL_EXAMPLE_SOURCE_NAMES: string[];
+/**
+ * Returns curated DSL examples for a source, if defined.
+ * @param source - Dimensions source name (e.g. `publications`)
+ * @returns Example query strings or undefined
+ */
+export declare function getDslExamplesForSource(source: string): readonly string[] | undefined;
+//# sourceMappingURL=dsl-examples.d.ts.map

package/dist/mcp/examples/dsl-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl-examples.d.ts","sourceRoot":"","sources":["../../../src/mcp/examples/dsl-examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qDAAqD;AACrD,eAAO,MAAM,0BAA0B,mCAAmC,CAAC;AAE3E,4CAA4C;AAC5C,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAgCpE,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,6OAMvB,CAAC;AAEX,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,oCAAoC,CAAC;AAEvE,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,UAA6C,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAErF"}

package/dist/mcp/examples/dsl-examples.js

@@ -0,0 +1,61 @@
+/**
+ * Curated DSL examples for MCP resources (from public Dimensions DSL documentation patterns).
+ * @module examples/dsl-examples
+ */
+/** URI template for per-source example resources. */
+export const DSL_EXAMPLES_BY_SOURCE_URI = "dimensions://examples/{source}";
+/** Example queries keyed by entity type. */
+export const DSL_EXAMPLES_BY_ENTITY = {
+    publications: [
+        'search publications for "machine learning" return publications[id+title+doi] limit 10',
+        'search publications for "CRISPR" where year >= 2020 return publications[id+title+times_cited+year] sort by times_cited desc limit 25',
+        'search publications in title_only for "gene therapy" return publications[basics] limit 10',
+        "search publications return publications facet journal limit 20",
+    ],
+    grants: [
+        'search grants for "cancer immunotherapy" return grants limit 10',
+        'search grants where funder_org_name = "National Institutes of Health" return grants[basics] limit 10',
+        "search grants return grants aggregate funding_usd",
+    ],
+    patents: [
+        'search patents for "lithium battery" return patents limit 10',
+        "search patents where year >= 2018 return patents[id+title] limit 20",
+    ],
+    clinical_trials: [
+        'search clinical_trials for "diabetes" return clinical_trials limit 10',
+        'search clinical_trials where phase = "Phase 3" return clinical_trials limit 10',
+    ],
+    datasets: ['search datasets for "climate model" return datasets limit 10'],
+    policy_documents: [
+        'search policy_documents for "renewable energy" return policy_documents limit 10',
+    ],
+    researchers: [
+        'search researchers where last_name = "Smith" return researchers limit 10',
+        "search researchers where total_publications > 100 return researchers limit 10",
+    ],
+    organizations: [
+        'search organizations for "Stanford" return organizations limit 10',
+        'search organizations where country = "United States" return organizations limit 10',
+    ],
+};
+/** General DSL patterns (describe, functions, pagination). */
+export const DSL_GENERAL_EXAMPLES = [
+    "describe version",
+    "describe schema",
+    "describe source publications",
+    'extract_concepts(text: "CRISPR gene editing enables precise DNA modification")',
+    'classify(text: "Stem cell therapy for diabetes", system: "for")',
+];
+/** Link to official DSL documentation. */
+export const DSL_DOCUMENTATION_URL = "https://docs.dimensions.ai/dsl/";
+/** Source names that have curated per-source example resources. */
+export const DSL_EXAMPLE_SOURCE_NAMES = Object.keys(DSL_EXAMPLES_BY_ENTITY).sort();
+/**
+ * Returns curated DSL examples for a source, if defined.
+ * @param source - Dimensions source name (e.g. `publications`)
+ * @returns Example query strings or undefined
+ */
+export function getDslExamplesForSource(source) {
+    return DSL_EXAMPLES_BY_ENTITY[source];
+}
+//# sourceMappingURL=dsl-examples.js.map

package/dist/mcp/examples/dsl-examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl-examples.js","sourceRoot":"","sources":["../../../src/mcp/examples/dsl-examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAE3E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAsC;IACvE,YAAY,EAAE;QACZ,uFAAuF;QACvF,sIAAsI;QACtI,2FAA2F;QAC3F,gEAAgE;KACjE;IACD,MAAM,EAAE;QACN,iEAAiE;QACjE,sGAAsG;QACtG,mDAAmD;KACpD;IACD,OAAO,EAAE;QACP,8DAA8D;QAC9D,qEAAqE;KACtE;IACD,eAAe,EAAE;QACf,uEAAuE;QACvE,gFAAgF;KACjF;IACD,QAAQ,EAAE,CAAC,8DAA8D,CAAC;IAC1E,gBAAgB,EAAE;QAChB,iFAAiF;KAClF;IACD,WAAW,EAAE;QACX,0EAA0E;QAC1E,+EAA+E;KAChF;IACD,aAAa,EAAE;QACb,mEAAmE;QACnE,oFAAoF;KACrF;CACF,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,kBAAkB;IAClB,iBAAiB;IACjB,8BAA8B;IAC9B,gFAAgF;IAChF,iEAAiE;CACzD,CAAC;AAEX,0CAA0C;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,iCAAiC,CAAC;AAEvE,mEAAmE;AACnE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,IAAI,EAAE,CAAC;AAEnF;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/dist/mcp/examples/usage-scenarios.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool routing for natural-language prompts in docs/USAGE.md.
+ * @module examples/usage-scenarios
+ */
+export interface UsageScenario {
+    /** Stable id for tests */
+    id: string;
+    /** Short goal label (matches USAGE table) */
+    goal: string;
+    /** Example user prompt */
+    prompt: string;
+    /** Structured MCP tool agents should call */
+    tool: string;
+    /** Tool arguments (validated in usage-scenarios.test.ts) */
+    args: Record<string, unknown>;
+    /** Substrings expected in DSL passed to rawQuery (when applicable) */
+    dslContains?: string[];
+}
+export declare const USAGE_SCENARIOS: readonly UsageScenario[];
+//# sourceMappingURL=usage-scenarios.d.ts.map

package/dist/mcp/examples/usage-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-scenarios.d.ts","sourceRoot":"","sources":["../../../src/mcp/examples/usage-scenarios.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAoK1C,CAAC"}

package/dist/mcp/examples/usage-scenarios.js

@@ -0,0 +1,169 @@
+/**
+ * Tool routing for natural-language prompts in docs/USAGE.md.
+ * @module examples/usage-scenarios
+ */
+export const USAGE_SCENARIOS = [
+    {
+        id: "top-publications",
+        goal: "Top papers on a topic",
+        prompt: "Find the 20 most-cited publications on CRISPR gene editing since 2020.",
+        tool: "search_publications",
+        args: {
+            query: "CRISPR gene editing",
+            yearFrom: 2020,
+            sortBy: "total_citations",
+            limit: 20,
+            fields: ["id", "title", "doi", "year", "total_citations"],
+        },
+        dslContains: [
+            "search publications",
+            "CRISPR gene editing",
+            "year >= 2020",
+            "sort by times_cited desc",
+            "limit 20",
+        ],
+    },
+    {
+        id: "nih-grants",
+        goal: "Grants from a funder",
+        prompt: "Search NIH grants about cancer immunotherapy started after 2020, limit 25.",
+        tool: "search_grants",
+        args: {
+            query: "cancer immunotherapy",
+            startYearFrom: 2020,
+            funderOrgName: "National Cancer Institute",
+            limit: 25,
+            fields: ["id", "title", "funding_usd", "funder_name", "start_year"],
+        },
+        dslContains: [
+            "search grants",
+            "cancer immunotherapy",
+            "start_year >= 2020",
+            'funder_org_name = "National Cancer Institute"',
+            "limit 25",
+        ],
+    },
+    {
+        id: "researchers-by-topic",
+        goal: "Who works on a topic",
+        prompt: "Who are the top researchers working on quantum computing?",
+        tool: "facet_query",
+        args: {
+            entityType: "publications",
+            facetField: "researchers",
+            query: "quantum computing",
+            limit: 10,
+        },
+        dslContains: ["search publications", "quantum computing", "return researchers"],
+    },
+    {
+        id: "researchers-by-name",
+        goal: "Find researchers by name",
+        prompt: "Search researchers named Jennifer Doudna, sort by publication count.",
+        tool: "search_researchers",
+        args: {
+            query: "Jennifer Doudna",
+            sortBy: "total_publications",
+            limit: 10,
+            fields: ["id", "first_name", "last_name", "total_publications"],
+        },
+        dslContains: ["search researchers", "Jennifer Doudna", "sort by total_publications"],
+    },
+    {
+        id: "doi-lookup",
+        goal: "Known paper",
+        prompt: "Look up DOI 10.1038/nature12373 and show title, citations, and journal.",
+        tool: "get_by_doi",
+        args: {
+            doi: "10.1038/nature12373",
+            fields: ["id", "title", "times_cited", "journal"],
+        },
+        dslContains: ["10.1038/nature12373"],
+    },
+    {
+        id: "author-publications",
+        goal: "Researcher publications",
+        prompt: "List recent publications by Jennifer Doudna.",
+        tool: "search_publications",
+        args: {
+            query: "Jennifer Doudna",
+            sortBy: "total_citations",
+            limit: 10,
+            fields: ["id", "title", "year", "total_citations", "journal"],
+        },
+        dslContains: ["search publications", "Jennifer Doudna", "limit 10"],
+    },
+    {
+        id: "org-publications",
+        goal: "Institution output",
+        prompt: "Show highly cited publications from Stanford University.",
+        tool: "search_publications",
+        args: {
+            filters: [{ field: "research_orgs.id", operator: "=", value: "grid.168010.e" }],
+            sortBy: "total_citations",
+            limit: 25,
+            fields: ["id", "title", "year", "total_citations"],
+        },
+        dslContains: ['research_orgs.id = "grid.168010.e"', "sort by times_cited"],
+    },
+    {
+        id: "facet-journals-since-year",
+        goal: "Topic breakdown",
+        prompt: "Which journals publish the most machine learning research since 2020?",
+        tool: "facet_query",
+        args: {
+            entityType: "publications",
+            facetField: "journal",
+            query: "machine learning",
+            yearFrom: 2020,
+            limit: 20,
+        },
+        dslContains: ["machine learning", "year >= 2020", "return journal"],
+    },
+    {
+        id: "funding-leaders",
+        goal: "Funding leaders",
+        prompt: "Which funders have the most grant funding on climate adaptation?",
+        tool: "aggregate_query",
+        args: {
+            entityType: "grants",
+            facetField: "funder_orgs",
+            indicators: ["funding"],
+            query: "climate adaptation",
+            sortBy: "funding",
+            sortOrder: "desc",
+            limit: 10,
+        },
+        dslContains: ["search grants", "climate adaptation", "return funder_orgs aggregate funding"],
+    },
+    {
+        id: "citation-trend",
+        goal: "Citations over time",
+        prompt: "Citation trend for large language model publications from 2018 to 2024.",
+        tool: "citation_trend",
+        args: {
+            query: "large language model",
+            startYear: 2018,
+            endYear: 2024,
+        },
+        dslContains: ["large language model", "citations_per_year(2018, 2024)"],
+    },
+    {
+        id: "build-complex-query",
+        goal: "Build a complex query",
+        prompt: "Run a DSL query for publications: include CRISPR or gene editing, exclude animal models, year ≥ 2020.",
+        tool: "execute_dsl",
+        args: {
+            dsl: 'search publications for "CRISPR" or for "gene editing" not for "animal model" where year >= 2020 return publications[id,title,doi,times_cited] sort by times_cited desc limit 20',
+        },
+        dslContains: [
+            "search publications",
+            "CRISPR",
+            "gene editing",
+            "animal model",
+            "year >= 2020",
+            "limit 20",
+        ],
+    },
+];
+//# sourceMappingURL=usage-scenarios.js.map

package/dist/mcp/examples/usage-scenarios.js.map

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

package/dist/mcp/export-format.d.ts

@@ -0,0 +1,43 @@
+/**
+ * File export formatting for batch search results (JSONL and CSV).
+ * @module mcp/export-format
+ */
+/** Supported on-disk export formats for fetch_search_pages file mode. */
+export type ExportFormat = "jsonl" | "csv";
+/**
+ * Resolves export format from an explicit choice or output path extension.
+ * @param outputPath - Destination file path
+ * @param explicit - Optional format override
+ * @returns Resolved format (defaults to JSONL)
+ */
+export declare function resolveExportFormat(outputPath: string, explicit?: ExportFormat): ExportFormat;
+/**
+ * Escapes a single CSV cell value.
+ * @param value - Cell value
+ * @returns CSV-safe string
+ */
+export declare function escapeCsvCell(value: unknown): string;
+/**
+ * Derives stable CSV column order from rows and optional preferred field list.
+ * @param rows - Result rows
+ * @param preferredFields - Field order from the search `fields` argument
+ * @param existing - Columns from a resumed export
+ * @returns Ordered column names
+ */
+export declare function deriveCsvColumns(rows: Record<string, unknown>[], preferredFields?: readonly string[], existing?: readonly string[]): string[];
+/**
+ * Formats result rows for file export.
+ * @param rows - Records to write
+ * @param format - Target format
+ * @param options - CSV column and header options
+ * @returns Serialized text and resolved CSV columns
+ */
+export declare function formatRowsForExport(rows: Record<string, unknown>[], format: ExportFormat, options?: {
+    columns?: readonly string[];
+    preferredFields?: readonly string[];
+    includeHeader?: boolean;
+}): {
+    text: string;
+    columns: string[];
+};
+//# sourceMappingURL=export-format.d.ts.map

package/dist/mcp/export-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-format.d.ts","sourceRoot":"","sources":["../../src/mcp/export-format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,CAAC;AAE3C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,CAG7F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYpD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,EACnC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,EAAE,CAqBV;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,aAAa,CAAC,EAAE,OAAO,CAAC;CACpB,GACL;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAyBrC"}