@cyanheads/brapi-mcp-server 0.3.5

package/dist/services/brapi-client/brapi-client.js

@@ -0,0 +1,320 @@
+/**
+ * @fileoverview Low-level HTTP client for BrAPI v2 servers. Handles URL
+ * construction, header assembly, JSON envelope parsing, retry with exponential
+ * backoff, and the async-search poll loop
+ * (`POST /search/{noun}` → `searchResultsDbId` → `GET /search/{noun}/{id}`).
+ * Stateless across connections — callers pass `baseUrl` and resolved auth per
+ * call; connection state is owned by `ServerRegistry` (added in a later phase).
+ *
+ * @module services/brapi-client/brapi-client
+ */
+import { forbidden, internalError, JsonRpcErrorCode, McpError, notFound, rateLimited, serviceUnavailable, unauthorized, validationError, } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
+/**
+ * The framework's `Context` and `RequestContext` are structurally compatible
+ * at runtime — framework docs confirm passing `Context` to `fetchWithTimeout`
+ * and `withRetry` is safe. The types diverge only under
+ * `exactOptionalPropertyTypes` (Context marks some fields as `| undefined`).
+ * One cast, one place.
+ */
+const asRequestContext = (ctx) => ctx;
+const defaultFetcher = (url, timeoutMs, context, options) => fetchWithTimeout(url, timeoutMs, asRequestContext(context), options);
+export class BrapiClient {
+    serverConfig;
+    fetcher;
+    constructor(serverConfig, fetcher = defaultFetcher) {
+        this.serverConfig = serverConfig;
+        this.fetcher = fetcher;
+    }
+    /** GET /{path} with optional query params and auth. */
+    get(baseUrl, path, ctx, options = {}) {
+        return withRetry(async () => {
+            const response = await this.doFetch(this.buildUrl(baseUrl, path, options.params), ctx, { method: 'GET', headers: this.buildHeaders(options.auth) }, options.timeoutMs);
+            return this.parseEnvelope(response);
+        }, {
+            operation: `brapi.get ${path}`,
+            context: asRequestContext(ctx),
+            maxRetries: this.serverConfig.retryMaxAttempts,
+            baseDelayMs: this.serverConfig.retryBaseDelayMs,
+            signal: ctx.signal,
+        });
+    }
+    /**
+     * GET /{path} returning raw bytes — used for image content and other binary
+     * payloads. Honors the same retry policy as `get()`. The `accept` option
+     * overrides the default `image/*`.
+     */
+    getBinary(baseUrl, path, ctx, options = {}) {
+        return withRetry(async () => {
+            const headers = this.buildHeaders(options.auth);
+            headers.Accept = options.accept ?? 'image/*';
+            const response = await this.doFetch(this.buildUrl(baseUrl, path, options.params), ctx, { method: 'GET', headers }, options.timeoutMs);
+            const buffer = await response.arrayBuffer();
+            const contentType = response.headers.get('Content-Type') ?? 'application/octet-stream';
+            return { bytes: new Uint8Array(buffer), contentType };
+        }, {
+            operation: `brapi.getBinary ${path}`,
+            context: asRequestContext(ctx),
+            maxRetries: this.serverConfig.retryMaxAttempts,
+            baseDelayMs: this.serverConfig.retryBaseDelayMs,
+            signal: ctx.signal,
+        });
+    }
+    /**
+     * Fetch binary bytes from an arbitrary URL — used as a fallback when a
+     * BrAPI server doesn't expose `/images/{id}/imagecontent` but the image's
+     * metadata carries an `imageURL` (CDN, S3, etc.). No auth is attached; the
+     * assumption is that these URLs are publicly reachable. Still honors the
+     * private-IP guard and request timeout.
+     */
+    async fetchBinaryUrl(url, ctx, accept = 'image/*') {
+        const response = await this.doFetch(url, ctx, { method: 'GET', headers: { Accept: accept } }, this.serverConfig.requestTimeoutMs);
+        const buffer = await response.arrayBuffer();
+        const contentType = response.headers.get('Content-Type') ?? 'application/octet-stream';
+        return { bytes: new Uint8Array(buffer), contentType };
+    }
+    /**
+     * POST /search/{noun}. Returns a discriminated union — `sync` when the
+     * server returns full results inline, `async` when it returns a
+     * `searchResultsDbId` the caller must poll via `getSearchResults`.
+     */
+    postSearch(baseUrl, noun, body, ctx, options = {}) {
+        return withRetry(async () => {
+            const response = await this.doFetch(this.buildUrl(baseUrl, `/search/${noun}`), ctx, {
+                method: 'POST',
+                headers: {
+                    ...this.buildHeaders(options.auth),
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(body),
+            }, options.timeoutMs);
+            const envelope = await this.parseEnvelope(response);
+            const asyncId = extractAsyncId(envelope);
+            if (asyncId !== undefined) {
+                return { kind: 'async', searchResultsDbId: asyncId };
+            }
+            return { kind: 'sync', envelope: envelope };
+        }, {
+            operation: `brapi.postSearch ${noun}`,
+            context: asRequestContext(ctx),
+            maxRetries: this.serverConfig.retryMaxAttempts,
+            baseDelayMs: this.serverConfig.retryBaseDelayMs,
+            signal: ctx.signal,
+        });
+    }
+    /**
+     * POST /{path} with a JSON body. Used for write endpoints (e.g. creating
+     * observations). Same retry + classification policy as `get()`. The body is
+     * serialized as JSON and `Content-Type: application/json` is forced.
+     */
+    post(baseUrl, path, body, ctx, options = {}) {
+        return this.sendJson('POST', baseUrl, path, body, ctx, options);
+    }
+    /**
+     * PUT /{path} with a JSON body. Used for upsert / update endpoints. BrAPI
+     * routes update calls (`PUT /observations`, `PUT /germplasm`) through this.
+     */
+    put(baseUrl, path, body, ctx, options = {}) {
+        return this.sendJson('PUT', baseUrl, path, body, ctx, options);
+    }
+    sendJson(method, baseUrl, path, body, ctx, options = {}) {
+        return withRetry(async () => {
+            const response = await this.doFetch(this.buildUrl(baseUrl, path, options.params), ctx, {
+                method,
+                headers: {
+                    ...this.buildHeaders(options.auth),
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(body),
+            }, options.timeoutMs);
+            return this.parseEnvelope(response);
+        }, {
+            operation: `brapi.${method.toLowerCase()} ${path}`,
+            context: asRequestContext(ctx),
+            maxRetries: this.serverConfig.retryMaxAttempts,
+            baseDelayMs: this.serverConfig.retryBaseDelayMs,
+            signal: ctx.signal,
+        });
+    }
+    /**
+     * Poll `GET /search/{noun}/{searchResultsDbId}`. Returns the envelope once
+     * the server replies with 200. 202 means "still processing" — the method
+     * sleeps `searchPollIntervalMs` and retries until `searchPollTimeoutMs`.
+     */
+    async getSearchResults(baseUrl, noun, searchResultsDbId, ctx, options = {}) {
+        const url = this.buildUrl(baseUrl, `/search/${noun}/${encodeURIComponent(searchResultsDbId)}`);
+        const pollTimeoutMs = this.serverConfig.searchPollTimeoutMs;
+        const pollIntervalMs = this.serverConfig.searchPollIntervalMs;
+        const startedAt = Date.now();
+        for (;;) {
+            if (ctx.signal.aborted) {
+                throw internalError('Async search polling aborted by caller', {
+                    noun,
+                    searchResultsDbId,
+                });
+            }
+            if (Date.now() - startedAt > pollTimeoutMs) {
+                throw serviceUnavailable(`Async search ${noun}/${searchResultsDbId} timed out after ${pollTimeoutMs}ms`, { noun, searchResultsDbId, pollTimeoutMs });
+            }
+            const response = await this.doFetch(url, ctx, { method: 'GET', headers: this.buildHeaders(options.auth) }, options.timeoutMs);
+            if (response.status === 202) {
+                await sleep(pollIntervalMs, ctx);
+                continue;
+            }
+            return this.parseEnvelope(response);
+        }
+    }
+    async doFetch(url, ctx, init, timeoutMs) {
+        try {
+            return await this.fetcher(url, timeoutMs ?? this.serverConfig.requestTimeoutMs, ctx, {
+                ...init,
+                signal: ctx.signal,
+                rejectPrivateIPs: !this.serverConfig.allowPrivateIps,
+            });
+        }
+        catch (err) {
+            reclassifyHttpError(err);
+            throw err;
+        }
+    }
+    buildUrl(baseUrl, path, params) {
+        const trimmedBase = baseUrl.replace(/\/$/, '');
+        const prefixedPath = path.startsWith('/') ? path : `/${path}`;
+        const url = new URL(`${trimmedBase}${prefixedPath}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value === undefined)
+                    continue;
+                if (Array.isArray(value)) {
+                    for (const v of value)
+                        url.searchParams.append(key, String(v));
+                }
+                else {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    buildHeaders(auth) {
+        const headers = { Accept: 'application/json' };
+        if (auth) {
+            headers[auth.headerName] = auth.headerValue;
+        }
+        return headers;
+    }
+    async parseEnvelope(response) {
+        const text = await response.text();
+        if (!text) {
+            throw validationError('BrAPI returned an empty response body', {
+                httpStatus: response.status,
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (cause) {
+            throw serviceUnavailable('BrAPI returned non-JSON response', { bodyPreview: text.slice(0, 500), httpStatus: response.status }, { cause });
+        }
+        if (!isEnvelope(parsed)) {
+            throw validationError('BrAPI response did not match v2 envelope shape', {
+                received: parsed,
+                httpStatus: response.status,
+            });
+        }
+        return parsed;
+    }
+}
+/**
+ * Map the `ServiceUnavailable` thrown by `fetchWithTimeout` to the correct
+ * non-transient code when the underlying HTTP status is a 4xx. 429 is promoted
+ * to `RateLimited` so the default retry policy still kicks in; 5xx stays as
+ * `ServiceUnavailable` (also retryable). Network-level errors, which have no
+ * `statusCode`, pass through untouched.
+ */
+function reclassifyHttpError(err) {
+    if (!(err instanceof McpError))
+        return;
+    if (err.code !== JsonRpcErrorCode.ServiceUnavailable)
+        return;
+    const status = extractHttpStatus(err);
+    if (status === undefined)
+        return;
+    if (status >= 500)
+        return;
+    const data = asRecord(err.data) ?? {};
+    if (status === 429) {
+        throw rateLimited(err.message, { ...data, reason: 'upstream_rate_limited' });
+    }
+    if (status === 401)
+        throw unauthorized(err.message, { ...data, reason: 'upstream_unauthorized' });
+    if (status === 403)
+        throw forbidden(err.message, { ...data, reason: 'upstream_forbidden' });
+    if (status === 404)
+        throw notFound(err.message, { ...data, reason: 'upstream_not_found' });
+    throw validationError(err.message, { ...data, reason: 'upstream_bad_request' });
+}
+function extractHttpStatus(err) {
+    const data = asRecord(err.data);
+    if (!data)
+        return;
+    const status = data.statusCode;
+    return typeof status === 'number' ? status : undefined;
+}
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return;
+    return value;
+}
+function isEnvelope(value) {
+    return typeof value === 'object' && value !== null && 'metadata' in value && 'result' in value;
+}
+/**
+ * Some BrAPI servers embed `searchResultsDbId` inside the `result` object on
+ * an otherwise empty payload. Detect that case.
+ */
+function extractAsyncId(envelope) {
+    const result = envelope.result;
+    if (typeof result !== 'object' || result === null)
+        return;
+    const id = result.searchResultsDbId;
+    if (typeof id !== 'string')
+        return;
+    const data = result.data;
+    if (Array.isArray(data) && data.length > 0)
+        return;
+    return id;
+}
+function sleep(ms, ctx) {
+    return new Promise((resolve, reject) => {
+        if (ctx.signal.aborted) {
+            reject(internalError('Sleep aborted by caller'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            ctx.signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(internalError('Sleep aborted by caller'));
+        };
+        ctx.signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+let _client;
+export function initBrapiClient(serverConfig, fetcher) {
+    _client = new BrapiClient(serverConfig, fetcher);
+}
+export function getBrapiClient() {
+    if (!_client) {
+        throw new Error('BrapiClient not initialized — call initBrapiClient() in setup()');
+    }
+    return _client;
+}
+/** Test-only — clears the singleton so successive suites start clean. */
+export function resetBrapiClient() {
+    _client = undefined;
+}
+//# sourceMappingURL=brapi-client.js.map

package/dist/services/brapi-client/brapi-client.js.map

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

package/dist/services/brapi-client/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Public API barrel for the BrapiClient service.
+ *
+ * @module services/brapi-client
+ */
+export type { Fetcher } from './brapi-client.js';
+export { BrapiClient, getBrapiClient, initBrapiClient, resetBrapiClient, } from './brapi-client.js';
+export type { BinaryResponse, BrapiAuth, BrapiEnvelope, BrapiMetadata, BrapiPagination, BrapiRequestOptions, BrapiStatus, ResolvedAuth, SearchResponse, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/brapi-client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/brapi-client/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EACL,WAAW,EACX,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/services/brapi-client/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Public API barrel for the BrapiClient service.
+ *
+ * @module services/brapi-client
+ */
+export { BrapiClient, getBrapiClient, initBrapiClient, resetBrapiClient, } from './brapi-client.js';
+//# sourceMappingURL=index.js.map

package/dist/services/brapi-client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/brapi-client/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,WAAW,EACX,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/services/brapi-client/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Shared types for the BrapiClient service — envelope shape,
+ * request options, auth config, and search response variants.
+ *
+ * @module services/brapi-client/types
+ */
+/** BrAPI v2 standard response envelope. */
+export interface BrapiEnvelope<T> {
+    metadata: BrapiMetadata;
+    result: T;
+}
+export interface BrapiMetadata {
+    datafiles?: unknown[];
+    pagination?: BrapiPagination;
+    status?: BrapiStatus[];
+}
+export interface BrapiPagination {
+    currentPage: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+}
+export interface BrapiStatus {
+    message: string;
+    messageType: 'INFO' | 'WARNING' | 'ERROR';
+}
+/**
+ * Configured auth for a BrAPI connection. `sgn` and `oauth2` are resolved to
+ * a bearer token before being handed to the client; `api_key` and `none` are
+ * used verbatim.
+ */
+export type BrapiAuth = {
+    mode: 'none';
+} | {
+    mode: 'sgn';
+    username: string;
+    password: string;
+} | {
+    mode: 'oauth2';
+    clientId: string;
+    clientSecret: string;
+    tokenUrl?: string;
+} | {
+    mode: 'api_key';
+    apiKey: string;
+    headerName?: string;
+} | {
+    mode: 'bearer';
+    token: string;
+};
+/** Resolved auth header ready to attach to a request. */
+export interface ResolvedAuth {
+    /** ISO 8601 timestamp — caller may refresh before this. */
+    expiresAt?: string;
+    headerName: string;
+    headerValue: string;
+}
+export interface BrapiRequestOptions {
+    auth?: ResolvedAuth;
+    /** Query params. Arrays are repeated per BrAPI convention. */
+    params?: Record<string, string | number | boolean | readonly (string | number)[] | undefined>;
+    /** Override the config default timeout. */
+    timeoutMs?: number;
+}
+/**
+ * POST /search/{noun} returns either full results inline, or a
+ * `searchResultsDbId` that the caller polls via getSearchResults.
+ */
+export type SearchResponse<T> = {
+    kind: 'sync';
+    envelope: BrapiEnvelope<T>;
+} | {
+    kind: 'async';
+    searchResultsDbId: string;
+};
+/** Raw bytes returned from a binary fetch (e.g. image content). */
+export interface BinaryResponse {
+    bytes: Uint8Array;
+    /** `Content-Type` header as reported by the server; falls back to octet-stream. */
+    contentType: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/brapi-client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/brapi-client/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,CAAC,CAAC;CACX;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC;IAC9F,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/services/brapi-client/types.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Shared types for the BrapiClient service — envelope shape,
+ * request options, auth config, and search response variants.
+ *
+ * @module services/brapi-client/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/brapi-client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/brapi-client/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/services/brapi-filters/catalog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Static BrAPI v2.1 filter catalog. Covers the endpoints the
+ * goal-shaped tools target plus the common escape-hatch nouns. Agents use
+ * this via `brapi_describe_filters` to discover valid filter names before
+ * constructing `extraFilters` on `find_*` tools. Catalog entries reflect the
+ * BrAPI v2.1 spec — individual servers may implement subsets; filter failures
+ * surface through the upstream 400 body, not a static check.
+ *
+ * @module services/brapi-filters/catalog
+ */
+import type { FilterCatalog } from './types.js';
+export declare function getFilterCatalog(endpoint: string): FilterCatalog | undefined;
+export declare function listFilterEndpoints(): string[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/services/brapi-filters/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/services/brapi-filters/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,YAAY,CAAC;AAmelE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAI5E;AAED,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C"}