@cyanheads/brapi-mcp-server 0.3.5

package/dist/mcp-server/tools/shared/find-helpers.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Shared building blocks for `find_*` tools — Zod fragments for
+ * common inputs (alias, loadLimit, extraFilters), utilities to merge named
+ * filters with the passthrough map, a generic distribution aggregator, and
+ * the dataset-spillover handler that turns a "too many rows" result into a
+ * DatasetStore handle.
+ *
+ * @module mcp-server/tools/shared/find-helpers
+ */
+import { type Context, z } from '@cyanheads/mcp-ts-core';
+import type { ServerConfig } from '../../../config/server-config.js';
+import type { BrapiClient, BrapiEnvelope, BrapiPagination, BrapiRequestOptions, ResolvedAuth } from '../../../services/brapi-client/index.js';
+import type { DatasetMetadata, DatasetStore } from '../../../services/dataset-store/index.js';
+import type { RegisteredServer } from '../../../services/server-registry/index.js';
+/** True when the thrown value is an upstream 404 surfaced by the BrAPI client. */
+export declare function isUpstreamNotFound(err: unknown): boolean;
+/** Upper cap on how many rows we'll pull for DatasetStore spillover per call. */
+export declare const MAX_SPILLOVER_ROWS = 50000;
+/** Hard cap on how many BrAPI pages we'll traverse when building a dataset. */
+export declare const MAX_SPILLOVER_PAGES = 50;
+export declare const AliasInput: z.ZodOptional<z.ZodString>;
+export declare const LoadLimitInput: z.ZodOptional<z.ZodNumber>;
+export declare const ExtraFiltersInput: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+/**
+ * Merge named params with the user-supplied extraFilters map. Named params
+ * win on conflict; conflicts are surfaced as warnings.
+ */
+export declare function mergeFilters(named: Record<string, unknown>, extra: Record<string, unknown> | undefined, warnings: string[]): Record<string, unknown>;
+/** Build request options with optional auth. */
+export declare function buildRequestOptions(connection: RegisteredServer, params?: BrapiRequestOptions['params']): BrapiRequestOptions;
+/**
+ * Compute a frequency distribution for one field across a result set.
+ * Accepts a field accessor that may return a scalar or array; arrays are
+ * exploded. Returns `{value -> count}` sorted by count desc.
+ */
+export declare function computeDistribution<T>(rows: readonly T[], accessor: (row: T) => string | readonly string[] | undefined | null): Record<string, number>;
+/** Cheap sanity-render for a distributions block in markdown. */
+export declare function renderDistributions(distributions: Record<string, Record<string, number>>): string;
+export interface LoadedRows<T> {
+    /** True when we pulled a single page and the server has more. */
+    hasMore: boolean;
+    /** Pages actually consumed — useful for telemetry. */
+    pagesFetched: number;
+    rows: T[];
+    /** Total rows advertised by the server (may be larger than `rows.length`). */
+    totalCount?: number;
+}
+/**
+ * Pull rows up to `loadLimit` on a single page. If the server reports more
+ * rows than the limit, leave the rest behind — callers decide whether to
+ * spill via `spillToDataset`.
+ */
+export declare function loadInitialPage<T>(client: BrapiClient, connection: RegisteredServer, path: string, filters: Record<string, unknown>, loadLimit: number, ctx: Context): Promise<LoadedRows<T>>;
+export interface SpillInput<T> {
+    client: BrapiClient;
+    connection: RegisteredServer;
+    ctx: Context;
+    filters: Record<string, unknown>;
+    /** First-page rows already loaded. Avoids a re-fetch. */
+    firstPage: T[];
+    loadLimit: number;
+    path: string;
+    source: string;
+    store: DatasetStore;
+    /** Total reported by the server on the first page. */
+    totalCount: number;
+}
+export interface SpillResult<T> {
+    dataset: DatasetMetadata;
+    /** All rows that were persisted — used for distributions. */
+    fullRows: T[];
+    pagesFetched: number;
+}
+/**
+ * Shape of the dataset handle returned inline by `find_*` tools. Drops the
+ * provenance fields (source/baseUrl/query) since those are internal and
+ * available via `brapi_manage_dataset summary`.
+ */
+export declare const DatasetHandleSchema: z.ZodObject<{
+    datasetId: z.ZodString;
+    rowCount: z.ZodNumber;
+    sizeBytes: z.ZodNumber;
+    columns: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    maxRows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type DatasetHandle = z.infer<typeof DatasetHandleSchema>;
+/**
+ * Render a DatasetHandle as bullet lines, matching the existing find_* tool
+ * format. Centralized so the truncated/maxRows fields surface consistently.
+ */
+export declare function renderDatasetHandle(handle: DatasetHandle): string[];
+/** Project a `DatasetMetadata` to the in-context handle shape. */
+export declare function toDatasetHandle(metadata: DatasetMetadata): DatasetHandle;
+export interface MaybeSpillInput<T> {
+    client: BrapiClient;
+    connection: RegisteredServer;
+    ctx: Context;
+    filters: Record<string, unknown>;
+    firstPage: LoadedRows<T>;
+    loadLimit: number;
+    path: string;
+    source: string;
+    store: DatasetStore;
+}
+export interface MaybeSpillResult<T> {
+    dataset?: DatasetHandle;
+    /** Full row set if a spillover happened, otherwise the first-page rows. */
+    fullRows: T[];
+}
+/**
+ * Wrap `spillToDataset` with the "only spill when hasMore and totalCount >
+ * loadLimit" guard that every `find_*` tool replicates. When no spillover is
+ * needed, returns the first-page rows untouched. When it is, persists the
+ * union to DatasetStore and returns both the full set and the handle.
+ */
+export declare function maybeSpill<T extends Record<string, unknown>>(input: MaybeSpillInput<T>): Promise<MaybeSpillResult<T>>;
+/**
+ * Pull every remaining page up to MAX_SPILLOVER_* caps, then persist the
+ * union to DatasetStore. Returns the dataset metadata plus the full row set
+ * (so callers can compute honest distributions from the whole result).
+ */
+export declare function spillToDataset<T extends Record<string, unknown>>(input: SpillInput<T>): Promise<SpillResult<T>>;
+/** BrAPI list endpoints return `{data: T[], ...}`. Some omit the wrapper. */
+export interface BrapiListResult<T> {
+    data?: T[];
+    [key: string]: unknown;
+}
+export declare function extractRows<T>(result: BrapiListResult<T> | T[]): T[];
+/** Return the input as a non-empty string, or undefined. Used in distribution accessors. */
+export declare function asString(value: unknown): string | undefined;
+/** Return the input as a non-empty string array, or undefined. */
+export declare function asStringArray(value: unknown): string[] | undefined;
+/**
+ * Compose a refinement hint for a too-large result set. Picks the highest-
+ * cardinality non-empty distribution to suggest as a narrower. Returns
+ * undefined when the result set fits under `loadLimit`.
+ */
+export declare function buildRefinementHint(totalCount: number, loadLimit: number, distributions: Record<string, Record<string, number>>): string | undefined;
+export type { BrapiEnvelope, BrapiPagination, ResolvedAuth, ServerConfig };
+//# sourceMappingURL=find-helpers.d.ts.map

package/dist/mcp-server/tools/shared/find-helpers.d.ts.map

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

package/dist/mcp-server/tools/shared/find-helpers.js

@@ -0,0 +1,319 @@
+/**
+ * @fileoverview Shared building blocks for `find_*` tools — Zod fragments for
+ * common inputs (alias, loadLimit, extraFilters), utilities to merge named
+ * filters with the passthrough map, a generic distribution aggregator, and
+ * the dataset-spillover handler that turns a "too many rows" result into a
+ * DatasetStore handle.
+ *
+ * @module mcp-server/tools/shared/find-helpers
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+/** True when the thrown value is an upstream 404 surfaced by the BrAPI client. */
+export function isUpstreamNotFound(err) {
+    return err instanceof McpError && err.code === JsonRpcErrorCode.NotFound;
+}
+/** Upper cap on how many rows we'll pull for DatasetStore spillover per call. */
+export const MAX_SPILLOVER_ROWS = 50_000;
+/** Hard cap on how many BrAPI pages we'll traverse when building a dataset. */
+export const MAX_SPILLOVER_PAGES = 50;
+export const AliasInput = z
+    .string()
+    .regex(/^[a-zA-Z0-9_-]+$/)
+    .optional()
+    .describe('Connection alias registered via brapi_connect. Omit to use the default connection.');
+export const LoadLimitInput = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Override the in-context row cap (BRAPI_LOAD_LIMIT). Rows beyond the cap return as a dataset handle.');
+export const ExtraFiltersInput = z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe('Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.');
+/**
+ * Merge named params with the user-supplied extraFilters map. Named params
+ * win on conflict; conflicts are surfaced as warnings.
+ */
+export function mergeFilters(named, extra, warnings) {
+    if (!extra)
+        return pruneUndefined(named);
+    const merged = {};
+    for (const [key, value] of Object.entries(extra)) {
+        if (value === undefined)
+            continue;
+        merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(named)) {
+        if (value === undefined)
+            continue;
+        if (key in merged && !deepEqual(merged[key], value)) {
+            warnings.push(`extraFilters.${key} was overridden by the named param (named params take precedence).`);
+        }
+        merged[key] = value;
+    }
+    return merged;
+}
+function pruneUndefined(record) {
+    const pruned = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined)
+            pruned[key] = value;
+    }
+    return pruned;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Build request options with optional auth. */
+export function buildRequestOptions(connection, params) {
+    const opts = {};
+    if (connection.resolvedAuth)
+        opts.auth = connection.resolvedAuth;
+    if (params)
+        opts.params = params;
+    return opts;
+}
+/**
+ * Compute a frequency distribution for one field across a result set.
+ * Accepts a field accessor that may return a scalar or array; arrays are
+ * exploded. Returns `{value -> count}` sorted by count desc.
+ */
+export function computeDistribution(rows, accessor) {
+    const counts = new Map();
+    for (const row of rows) {
+        const value = accessor(row);
+        if (value === undefined || value === null)
+            continue;
+        const values = Array.isArray(value) ? value : [value];
+        for (const v of values) {
+            if (typeof v !== 'string' || v.length === 0)
+                continue;
+            counts.set(v, (counts.get(v) ?? 0) + 1);
+        }
+    }
+    return Object.fromEntries([...counts.entries()].sort(([, a], [, b]) => b - a));
+}
+/** Cheap sanity-render for a distributions block in markdown. */
+export function renderDistributions(distributions) {
+    const lines = [];
+    for (const [field, counts] of Object.entries(distributions)) {
+        const entries = Object.entries(counts);
+        if (entries.length === 0)
+            continue;
+        const summary = entries
+            .slice(0, 5)
+            .map(([value, count]) => `${value} (${count})`)
+            .join(', ');
+        const suffix = entries.length > 5 ? `, …+${entries.length - 5} more` : '';
+        lines.push(`- **${field}:** ${summary}${suffix}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Pull rows up to `loadLimit` on a single page. If the server reports more
+ * rows than the limit, leave the rest behind — callers decide whether to
+ * spill via `spillToDataset`.
+ */
+export async function loadInitialPage(client, connection, path, filters, loadLimit, ctx) {
+    const params = {
+        ...filters,
+    };
+    params.pageSize = loadLimit;
+    const envelope = await client.get(connection.baseUrl, path, ctx, buildRequestOptions(connection, params));
+    const rows = extractRows(envelope.result);
+    const pagination = envelope.metadata?.pagination;
+    const totalCount = pagination?.totalCount;
+    const hasMore = typeof totalCount === 'number' && totalCount > rows.length && totalCount > 0;
+    const result = { rows, hasMore, pagesFetched: 1 };
+    if (totalCount !== undefined)
+        result.totalCount = totalCount;
+    return result;
+}
+/**
+ * Shape of the dataset handle returned inline by `find_*` tools. Drops the
+ * provenance fields (source/baseUrl/query) since those are internal and
+ * available via `brapi_manage_dataset summary`.
+ */
+export const DatasetHandleSchema = z.object({
+    datasetId: z.string().describe('Use with brapi_manage_dataset to page or export.'),
+    rowCount: z.number().int().nonnegative().describe('Number of rows persisted in the dataset.'),
+    sizeBytes: z.number().int().nonnegative().describe('Serialized size of the dataset in bytes.'),
+    columns: z
+        .array(z.string().describe('Column name from the persisted rows.'))
+        .describe('Full column list of the persisted rows.'),
+    createdAt: z.string().describe('ISO 8601 timestamp the dataset was created.'),
+    expiresAt: z.string().describe('ISO 8601 timestamp after which the dataset will be purged.'),
+    truncated: z
+        .boolean()
+        .optional()
+        .describe('True when the dataset hit a row cap before exhausting upstream.'),
+    maxRows: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Cap that was applied at create time, when truncation occurred.'),
+});
+/**
+ * Render a DatasetHandle as bullet lines, matching the existing find_* tool
+ * format. Centralized so the truncated/maxRows fields surface consistently.
+ */
+export function renderDatasetHandle(handle) {
+    const lines = [
+        `- datasetId: \`${handle.datasetId}\``,
+        `- rowCount: ${handle.rowCount}`,
+        `- sizeBytes: ${handle.sizeBytes}`,
+        `- columns: ${handle.columns.join(', ')}`,
+        `- createdAt: ${handle.createdAt}`,
+        `- expiresAt: ${handle.expiresAt}`,
+    ];
+    if (handle.truncated)
+        lines.push(`- truncated: true`);
+    if (typeof handle.maxRows === 'number')
+        lines.push(`- maxRows: ${handle.maxRows}`);
+    return lines;
+}
+/** Project a `DatasetMetadata` to the in-context handle shape. */
+export function toDatasetHandle(metadata) {
+    const handle = {
+        datasetId: metadata.datasetId,
+        rowCount: metadata.rowCount,
+        sizeBytes: metadata.sizeBytes,
+        columns: metadata.columns,
+        createdAt: metadata.createdAt,
+        expiresAt: metadata.expiresAt,
+    };
+    if (metadata.truncated)
+        handle.truncated = true;
+    if (typeof metadata.maxRows === 'number')
+        handle.maxRows = metadata.maxRows;
+    return handle;
+}
+/**
+ * Wrap `spillToDataset` with the "only spill when hasMore and totalCount >
+ * loadLimit" guard that every `find_*` tool replicates. When no spillover is
+ * needed, returns the first-page rows untouched. When it is, persists the
+ * union to DatasetStore and returns both the full set and the handle.
+ */
+export async function maybeSpill(input) {
+    const { firstPage } = input;
+    if (!firstPage.hasMore ||
+        firstPage.totalCount === undefined ||
+        firstPage.totalCount <= input.loadLimit) {
+        return { fullRows: firstPage.rows };
+    }
+    const spill = await spillToDataset({
+        store: input.store,
+        client: input.client,
+        connection: input.connection,
+        path: input.path,
+        filters: input.filters,
+        source: input.source,
+        loadLimit: input.loadLimit,
+        ctx: input.ctx,
+        firstPage: firstPage.rows,
+        totalCount: firstPage.totalCount,
+    });
+    return {
+        fullRows: spill.fullRows,
+        dataset: toDatasetHandle(spill.dataset),
+    };
+}
+/**
+ * Pull every remaining page up to MAX_SPILLOVER_* caps, then persist the
+ * union to DatasetStore. Returns the dataset metadata plus the full row set
+ * (so callers can compute honest distributions from the whole result).
+ */
+export async function spillToDataset(input) {
+    const remainingTarget = Math.min(input.totalCount, MAX_SPILLOVER_ROWS);
+    const pageSize = input.loadLimit;
+    const totalPages = Math.min(Math.ceil(remainingTarget / pageSize), MAX_SPILLOVER_PAGES);
+    const rows = [...input.firstPage];
+    let pagesFetched = 1;
+    // Page 0 is already fetched by caller; continue from page 1.
+    for (let page = 1; page < totalPages; page++) {
+        if (rows.length >= remainingTarget)
+            break;
+        if (input.ctx.signal.aborted)
+            break;
+        const params = {
+            ...input.filters,
+        };
+        params.pageSize = pageSize;
+        params.page = page;
+        const envelope = await input.client.get(input.connection.baseUrl, input.path, input.ctx, buildRequestOptions(input.connection, params));
+        const pageRows = extractRows(envelope.result);
+        rows.push(...pageRows);
+        pagesFetched += 1;
+        if (pageRows.length < pageSize)
+            break;
+    }
+    const reachedRowCap = rows.length >= remainingTarget && input.totalCount > rows.length;
+    const reachedPageCap = pagesFetched >= MAX_SPILLOVER_PAGES && input.totalCount > rows.length;
+    const truncated = reachedRowCap || reachedPageCap;
+    const createInput = {
+        source: input.source,
+        baseUrl: input.connection.baseUrl,
+        query: input.filters,
+        rows,
+    };
+    if (truncated) {
+        createInput.truncated = true;
+        createInput.maxRows = MAX_SPILLOVER_ROWS;
+    }
+    const dataset = await input.store.create(input.ctx, createInput);
+    return { dataset, fullRows: rows, pagesFetched };
+}
+export function extractRows(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result && Array.isArray(result.data))
+        return result.data;
+    return [];
+}
+/** Return the input as a non-empty string, or undefined. Used in distribution accessors. */
+export function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** Return the input as a non-empty string array, or undefined. */
+export function asStringArray(value) {
+    if (!Array.isArray(value))
+        return;
+    return value.filter((v) => typeof v === 'string' && v.length > 0);
+}
+/**
+ * Compose a refinement hint for a too-large result set. Picks the highest-
+ * cardinality non-empty distribution to suggest as a narrower. Returns
+ * undefined when the result set fits under `loadLimit`.
+ */
+export function buildRefinementHint(totalCount, loadLimit, distributions) {
+    if (totalCount <= loadLimit)
+        return;
+    let best;
+    for (const [field, counts] of Object.entries(distributions)) {
+        const entries = Object.entries(counts);
+        if (entries.length < 2)
+            continue;
+        const top = entries[0];
+        if (!top)
+            continue;
+        const [topValue, count] = top;
+        if (!best || entries.length > best.cardinality) {
+            best = { field, topValue, count, cardinality: entries.length };
+        }
+    }
+    if (!best) {
+        return `${totalCount} rows exceed loadLimit=${loadLimit}. Add more specific filters or raise loadLimit.`;
+    }
+    return `${totalCount} rows exceed loadLimit=${loadLimit}. The ${best.field} distribution spans ${best.cardinality} values — narrowing to \`${best.topValue}\` would cut to ~${best.count} rows.`;
+}
+//# sourceMappingURL=find-helpers.js.map

package/dist/mcp-server/tools/shared/find-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-helpers.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/shared/find-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAgB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAgB3E,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,CAAC,QAAQ,CAAC;AAC3E,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,KAAK,CAAC,kBAAkB,CAAC;KACzB,QAAQ,EAAE;KACV,QAAQ,CAAC,oFAAoF,CAAC,CAAC;AAElG,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,EAAE;KACR,GAAG,EAAE;KACL,QAAQ,EAAE;KACV,QAAQ,EAAE;KACV,QAAQ,CACP,qGAAqG,CACtG,CAAC;AAEJ,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;KAC/B,QAAQ,EAAE;KACV,QAAQ,CACP,qKAAqK,CACtK,CAAC;AAEJ;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,KAA8B,EAC9B,KAA0C,EAC1C,QAAkB;IAElB,IAAI,CAAC,KAAK;QAAE,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,GAAG,IAAI,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;YACpD,QAAQ,CAAC,IAAI,CACX,gBAAgB,GAAG,oEAAoE,CACxF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CAAC,MAA+B;IACrD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,CAAU,EAAE,CAAU;IACvC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,mBAAmB,CACjC,UAA4B,EAC5B,MAAsC;IAEtC,MAAM,IAAI,GAAwB,EAAE,CAAC;IACrC,IAAI,UAAU,CAAC,YAAY;QAAE,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,YAAY,CAAC;IACjE,IAAI,MAAM;QAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAkB,EAClB,QAAmE;IAEnE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACtD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACtD,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,mBAAmB,CAAC,aAAqD;IACvF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,MAAM,OAAO,GAAG,OAAO;aACpB,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;aACX,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,KAAK,KAAK,GAAG,CAAC;aAC9C,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,OAAO,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAYD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAmB,EACnB,UAA4B,EAC5B,IAAY,EACZ,OAAgC,EAChC,SAAiB,EACjB,GAAY;IAEZ,MAAM,MAAM,GAAkC;QAC5C,GAAI,OAGF;KACH,CAAC;IACF,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;IAC5B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAC/B,UAAU,CAAC,OAAO,EAClB,IAAI,EACJ,GAAG,EACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,CACxC,CAAC;IACF,MAAM,IAAI,GAAG,WAAW,CAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IACjD,MAAM,UAAU,GAAG,UAAU,EAAE,UAAU,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,GAAG,CAAC,CAAC;IAC7F,MAAM,MAAM,GAAkB,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IACjE,IAAI,UAAU,KAAK,SAAS;QAAE,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;IAC7D,OAAO,MAAM,CAAC;AAChB,CAAC;AAwBD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IAClF,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IAC7F,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IAC9F,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC,CAAC;SAClE,QAAQ,CAAC,yCAAyC,CAAC;IACtD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IAC7E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4DAA4D,CAAC;IAC5F,SAAS,EAAE,CAAC;SACT,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CAAC,iEAAiE,CAAC;IAC9E,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,gEAAgE,CAAC;CAC9E,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACvD,MAAM,KAAK,GAAG;QACZ,kBAAkB,MAAM,CAAC,SAAS,IAAI;QACtC,eAAe,MAAM,CAAC,QAAQ,EAAE;QAChC,gBAAgB,MAAM,CAAC,SAAS,EAAE;QAClC,cAAc,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACzC,gBAAgB,MAAM,CAAC,SAAS,EAAE;QAClC,gBAAgB,MAAM,CAAC,SAAS,EAAE;KACnC,CAAC;IACF,IAAI,MAAM,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACtD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACnF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAAC,QAAyB;IACvD,MAAM,MAAM,GAAkB;QAC5B,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS;KAC9B,CAAC;IACF,IAAI,QAAQ,CAAC,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;IAChD,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ;QAAE,MAAM,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IAC5E,OAAO,MAAM,CAAC;AAChB,CAAC;AAoBD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAyB;IAEzB,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAC5B,IACE,CAAC,SAAS,CAAC,OAAO;QAClB,SAAS,CAAC,UAAU,KAAK,SAAS;QAClC,SAAS,CAAC,UAAU,IAAI,KAAK,CAAC,SAAS,EACvC,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;IACtC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC;QACjC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,SAAS,EAAE,SAAS,CAAC,IAAI;QACzB,UAAU,EAAE,SAAS,CAAC,UAAU;KACjC,CAAC,CAAC;IACH,OAAO;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAoB;IAEpB,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC;IACjC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC,EAAE,mBAAmB,CAAC,CAAC;IAExF,MAAM,IAAI,GAAQ,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,6DAA6D;IAC7D,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC;QAC7C,IAAI,IAAI,CAAC,MAAM,IAAI,eAAe;YAAE,MAAM;QAC1C,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM;QACpC,MAAM,MAAM,GAAkC;YAC5C,GAAI,KAAK,CAAC,OAGR;SACH,CAAC;QACF,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC3B,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CACrC,KAAK,CAAC,UAAU,CAAC,OAAO,EACxB,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,GAAG,EACT,mBAAmB,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,CAC9C,CAAC;QACF,MAAM,QAAQ,GAAG,WAAW,CAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QACvB,YAAY,IAAI,CAAC,CAAC;QAClB,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAQ;YAAE,MAAM;IACxC,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,IAAI,eAAe,IAAI,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IACvF,MAAM,cAAc,GAAG,YAAY,IAAI,mBAAmB,IAAI,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7F,MAAM,SAAS,GAAG,aAAa,IAAI,cAAc,CAAC;IAElD,MAAM,WAAW,GAAuB;QACtC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO;QACjC,KAAK,EAAE,KAAK,CAAC,OAAO;QACpB,IAAI;KACL,CAAC;IACF,IAAI,SAAS,EAAE,CAAC;QACd,WAAW,CAAC,SAAS,GAAG,IAAI,CAAC;QAC7B,WAAW,CAAC,OAAO,GAAG,kBAAkB,CAAC;IAC3C,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAEjE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;AACnD,CAAC;AAQD,MAAM,UAAU,WAAW,CAAI,MAAgC;IAC7D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACzC,IAAI,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAC7D,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO;IAClC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAkB,EAClB,SAAiB,EACjB,aAAqD;IAErD,IAAI,UAAU,IAAI,SAAS;QAAE,OAAO;IACpC,IAAI,IAAyF,CAAC;IAC9F,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QACjC,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC;QAC9B,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAC/C,IAAI,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACjE,CAAC;IACH,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,GAAG,UAAU,0BAA0B,SAAS,iDAAiD,CAAC;IAC3G,CAAC;IACD,OAAO,GAAG,UAAU,0BAA0B,SAAS,SAAS,IAAI,CAAC,KAAK,uBAAuB,IAAI,CAAC,WAAW,4BAA4B,IAAI,CAAC,QAAQ,oBAAoB,IAAI,CAAC,KAAK,QAAQ,CAAC;AACnM,CAAC"}

package/dist/mcp-server/tools/shared/orientation-envelope.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Shared builder for the BrAPI orientation envelope returned
+ * by both `brapi_connect` (inlined after registration) and
+ * `brapi_server_info` (on-demand). Pulls from CapabilityRegistry and the
+ * active ServerRegistry entry, then layers in cheap opportunistic counts via
+ * `pageSize=0` probes. Counts degrade silently — a server that doesn't
+ * honor the probe just omits the field rather than failing the whole call.
+ *
+ * @module mcp-server/tools/shared/orientation-envelope
+ */
+import { type Context, z } from '@cyanheads/mcp-ts-core';
+import type { BrapiClient } from '../../../services/brapi-client/index.js';
+import type { CapabilityRegistry } from '../../../services/capability-registry/index.js';
+import type { RegisteredServer } from '../../../services/server-registry/index.js';
+export declare const ServerIdentitySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    organizationName: z.ZodOptional<z.ZodString>;
+    organizationURL: z.ZodOptional<z.ZodString>;
+    documentationURL: z.ZodOptional<z.ZodString>;
+    contactEmail: z.ZodOptional<z.ZodString>;
+    brapiVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const OrientationAuthSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        none: "none";
+        sgn: "sgn";
+        oauth2: "oauth2";
+        api_key: "api_key";
+        bearer: "bearer";
+    }>;
+    headerName: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const OrientationCapabilitiesSchema: z.ZodObject<{
+    supportedCount: z.ZodNumber;
+    supported: z.ZodArray<z.ZodString>;
+    notableGaps: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const OrientationContentSchema: z.ZodObject<{
+    crops: z.ZodArray<z.ZodString>;
+    studyCount: z.ZodOptional<z.ZodNumber>;
+    germplasmCount: z.ZodOptional<z.ZodNumber>;
+    programCount: z.ZodOptional<z.ZodNumber>;
+    locationCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const OrientationEnvelopeSchema: z.ZodObject<{
+    alias: z.ZodString;
+    baseUrl: z.ZodString;
+    server: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        organizationName: z.ZodOptional<z.ZodString>;
+        organizationURL: z.ZodOptional<z.ZodString>;
+        documentationURL: z.ZodOptional<z.ZodString>;
+        contactEmail: z.ZodOptional<z.ZodString>;
+        brapiVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    auth: z.ZodObject<{
+        mode: z.ZodEnum<{
+            none: "none";
+            sgn: "sgn";
+            oauth2: "oauth2";
+            api_key: "api_key";
+            bearer: "bearer";
+        }>;
+        headerName: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    capabilities: z.ZodObject<{
+        supportedCount: z.ZodNumber;
+        supported: z.ZodArray<z.ZodString>;
+        notableGaps: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    content: z.ZodObject<{
+        crops: z.ZodArray<z.ZodString>;
+        studyCount: z.ZodOptional<z.ZodNumber>;
+        germplasmCount: z.ZodOptional<z.ZodNumber>;
+        programCount: z.ZodOptional<z.ZodNumber>;
+        locationCount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    notes: z.ZodArray<z.ZodString>;
+    fetchedAt: z.ZodString;
+}, z.core.$strip>;
+export type OrientationEnvelope = z.infer<typeof OrientationEnvelopeSchema>;
+export interface BuildEnvelopeDeps {
+    client: BrapiClient;
+    registry: CapabilityRegistry;
+}
+/**
+ * Compose the orientation envelope for a connected server. Runs the
+ * CapabilityRegistry profile (cached after the first call) plus a parallel
+ * set of cheap `pageSize=0` probes for totals.
+ */
+export declare function buildOrientationEnvelope(ctx: Context, connection: RegisteredServer, deps: BuildEnvelopeDeps): Promise<OrientationEnvelope>;
+export declare function formatOrientationEnvelope(envelope: OrientationEnvelope): string;
+//# sourceMappingURL=orientation-envelope.d.ts.map

package/dist/mcp-server/tools/shared/orientation-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orientation-envelope.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/shared/orientation-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,kCAAkC,CAAC;AACzF,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAsB5E,eAAO,MAAM,oBAAoB;;;;;;;;iBAUmD,CAAC;AAErF,eAAO,MAAM,qBAAqB;;;;;;;;;;iBAQ0C,CAAC;AAE7E,eAAO,MAAM,6BAA6B;;;;iBAciD,CAAC;AAE5F,eAAO,MAAM,wBAAwB;;;;;;iBA8B2D,CAAC;AAEjG,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAapC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAwD9B;AAqDD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CA6D/E"}