@cyanheads/brapi-mcp-server 0.3.5

package/dist/mcp-server/tools/definitions/brapi-raw-search.tool.js

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview `brapi_raw_search` — last-resort passthrough to any BrAPI
+ * `POST /search/{noun}` endpoint with async-search polling handled
+ * transparently. Returns the raw upstream envelope once the search completes.
+ * Emits a routing nudge when a curated goal-shaped tool covers the noun.
+ *
+ * @module mcp-server/tools/definitions/brapi-raw-search.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getBrapiClient, } from '../../../services/brapi-client/index.js';
+import { DEFAULT_ALIAS, getServerRegistry } from '../../../services/server-registry/index.js';
+import { AliasInput, buildRequestOptions } from '../shared/find-helpers.js';
+import { suggestForSearch } from '../shared/raw-routing-hints.js';
+const PaginationSchema = z
+    .object({
+    currentPage: z.number().describe('0-indexed page number the server returned.'),
+    pageSize: z.number().describe('Rows per page.'),
+    totalCount: z.number().describe('Total rows matching the query across all pages.'),
+    totalPages: z.number().describe('Total pages at the current pageSize.'),
+})
+    .passthrough()
+    .optional()
+    .describe('BrAPI pagination block. Absent when the endpoint does not paginate.');
+const OutputSchema = z.object({
+    alias: z.string().describe('Alias of the registered BrAPI connection the call used.'),
+    noun: z.string().describe('The `/search/{noun}` segment the body was posted to.'),
+    kind: z
+        .enum(['sync', 'async'])
+        .describe('Whether the server returned inline results or we polled an async search.'),
+    searchResultsDbId: z
+        .string()
+        .optional()
+        .describe('Populated when the server returned an async searchResultsDbId.'),
+    metadata: z
+        .object({
+        pagination: PaginationSchema,
+    })
+        .passthrough()
+        .describe('BrAPI envelope metadata (pagination and any additional upstream fields).'),
+    result: z.unknown().describe('Raw BrAPI `result` value — whatever shape the endpoint returns.'),
+    suggestion: z
+        .string()
+        .optional()
+        .describe('Emitted when a curated goal-shaped tool covers this search.'),
+});
+export const brapiRawSearch = tool('brapi_raw_search', {
+    description: 'Passthrough to any BrAPI POST /search/{noun} endpoint, returning the resolved envelope (async polling resolved upstream). Raw passthrough — no distributions, foreign-key resolution, or dataset spillover applied.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        alias: AliasInput,
+        noun: z
+            .string()
+            .min(1)
+            .regex(/^[a-zA-Z0-9_-]+$/)
+            .describe('Search noun — e.g. "observations", "calls", "germplasm".'),
+        body: z
+            .record(z.string(), z.unknown())
+            .describe('Filter body passed verbatim to POST /search/{noun}.'),
+    }),
+    output: OutputSchema,
+    async handler(input, ctx) {
+        const registry = getServerRegistry();
+        const client = getBrapiClient();
+        const connection = await registry.get(ctx, input.alias ?? DEFAULT_ALIAS);
+        const requestOptions = {};
+        if (connection.resolvedAuth)
+            requestOptions.auth = connection.resolvedAuth;
+        const response = await client.postSearch(connection.baseUrl, input.noun, input.body, ctx, requestOptions);
+        let envelope;
+        let kind;
+        let searchResultsDbId;
+        if (response.kind === 'sync') {
+            envelope = response.envelope;
+            kind = 'sync';
+        }
+        else {
+            searchResultsDbId = response.searchResultsDbId;
+            envelope = await client.getSearchResults(connection.baseUrl, input.noun, response.searchResultsDbId, ctx, buildRequestOptions(connection));
+            kind = 'async';
+        }
+        const result = {
+            alias: connection.alias,
+            noun: input.noun,
+            kind,
+            metadata: buildMetadata(envelope.metadata),
+            result: envelope.result,
+        };
+        if (searchResultsDbId !== undefined)
+            result.searchResultsDbId = searchResultsDbId;
+        const suggestion = suggestForSearch(input.noun);
+        if (suggestion)
+            result.suggestion = suggestion;
+        return result;
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`# POST /search/${result.noun} (${result.kind}) — \`${result.alias}\``);
+        if (result.searchResultsDbId) {
+            lines.push('');
+            lines.push(`**searchResultsDbId:** \`${result.searchResultsDbId}\``);
+        }
+        const pagination = result.metadata.pagination;
+        if (pagination) {
+            lines.push('');
+            lines.push(`**Pagination:** page ${pagination.currentPage} of ${pagination.totalPages}, pageSize=${pagination.pageSize}, totalCount=${pagination.totalCount}`);
+        }
+        if (result.suggestion) {
+            lines.push('');
+            lines.push(`**Suggestion:** ${result.suggestion}`);
+        }
+        lines.push('');
+        lines.push('## Raw result');
+        lines.push('```json');
+        lines.push(JSON.stringify(result.result, null, 2));
+        lines.push('```');
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+function buildMetadata(metadata) {
+    const pagination = metadata?.pagination;
+    if (pagination) {
+        return { pagination: { ...pagination } };
+    }
+    return {};
+}
+//# sourceMappingURL=brapi-raw-search.tool.js.map

package/dist/mcp-server/tools/definitions/brapi-raw-search.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-raw-search.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/brapi-raw-search.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/brapi-server-info.tool.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview `brapi_server_info` — on-demand orientation envelope for the
+ * active (or aliased) connection. Returns the same shape that `brapi_connect`
+ * inlines. Useful for refreshing capability data after a long session or
+ * when switching between registered aliases.
+ *
+ * @module mcp-server/tools/definitions/brapi-server-info.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const brapiServerInfo: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    alias: z.ZodOptional<z.ZodString>;
+    forceRefresh: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, 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>, undefined>;
+//# sourceMappingURL=brapi-server-info.tool.d.ts.map

package/dist/mcp-server/tools/definitions/brapi-server-info.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-server-info.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/brapi-server-info.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAUjD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAkC1B,CAAC"}

package/dist/mcp-server/tools/definitions/brapi-server-info.tool.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview `brapi_server_info` — on-demand orientation envelope for the
+ * active (or aliased) connection. Returns the same shape that `brapi_connect`
+ * inlines. Useful for refreshing capability data after a long session or
+ * when switching between registered aliases.
+ *
+ * @module mcp-server/tools/definitions/brapi-server-info.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getBrapiClient } from '../../../services/brapi-client/index.js';
+import { getCapabilityRegistry } from '../../../services/capability-registry/index.js';
+import { DEFAULT_ALIAS, getServerRegistry } from '../../../services/server-registry/index.js';
+import { buildOrientationEnvelope, formatOrientationEnvelope, OrientationEnvelopeSchema, } from '../shared/orientation-envelope.js';
+export const brapiServerInfo = tool('brapi_server_info', {
+    description: 'Return the full orientation envelope for a registered BrAPI connection — server identity, capabilities, content counts, and notes. Re-running refreshes the cached capability scan; pass an alias to read a non-default connection.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        alias: z
+            .string()
+            .regex(/^[a-zA-Z0-9_-]+$/)
+            .optional()
+            .describe('Connection alias. Omit to use the default connection from the most recent `brapi_connect` call.'),
+        forceRefresh: z
+            .boolean()
+            .default(false)
+            .describe('Bypass the cached capability profile and refetch from the server.'),
+    }),
+    output: OrientationEnvelopeSchema,
+    async handler(input, ctx) {
+        const registry = getServerRegistry();
+        const capabilities = getCapabilityRegistry();
+        const client = getBrapiClient();
+        const connection = await registry.get(ctx, input.alias ?? DEFAULT_ALIAS);
+        if (input.forceRefresh) {
+            await capabilities.invalidate(connection.baseUrl, ctx);
+        }
+        return buildOrientationEnvelope(ctx, connection, { registry: capabilities, client });
+    },
+    format: (result) => [{ type: 'text', text: formatOrientationEnvelope(result) }],
+});
+//# sourceMappingURL=brapi-server-info.tool.js.map

package/dist/mcp-server/tools/definitions/brapi-server-info.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-server-info.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/brapi-server-info.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,mCAAmC,CAAC;AAE3C,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,mBAAmB,EAAE;IACvD,WAAW,EACT,qOAAqO;IACvO,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;IACzD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,KAAK,CAAC,kBAAkB,CAAC;aACzB,QAAQ,EAAE;aACV,QAAQ,CACP,iGAAiG,CAClG;QACH,YAAY,EAAE,CAAC;aACZ,OAAO,EAAE;aACT,OAAO,CAAC,KAAK,CAAC;aACd,QAAQ,CAAC,mEAAmE,CAAC;KACjF,CAAC;IACF,MAAM,EAAE,yBAAyB;IAEjC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;QACrC,MAAM,YAAY,GAAG,qBAAqB,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;QAEhC,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC;QAEzE,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACzD,CAAC;QAED,OAAO,wBAAwB,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,CAAC,MAAM,CAAC,EAAE,CAAC;CAChF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/brapi-submit-observations.tool.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview `brapi_submit_observations` — submit new or updated
+ * observations for a study. Two-phase write: `mode: 'preview'` validates rows
+ * against the study's observation variables and returns a routing breakdown
+ * (POST for new rows, PUT for rows carrying `observationDbId`); `mode: 'apply'`
+ * elicits confirmation when supported, fans the rows out to POST + PUT in
+ * parallel, then verifies the post-state with a cheap `pageSize=0` count.
+ * Additive write — no observation is destroyed by this tool.
+ *
+ * @module mcp-server/tools/definitions/brapi-submit-observations.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const brapiSubmitObservations: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    alias: z.ZodOptional<z.ZodString>;
+    studyDbId: z.ZodString;
+    observations: z.ZodArray<z.ZodObject<{
+        observationDbId: z.ZodOptional<z.ZodString>;
+        observationUnitDbId: z.ZodString;
+        observationVariableDbId: z.ZodString;
+        value: z.ZodString;
+        collector: z.ZodOptional<z.ZodString>;
+        observationTimeStamp: z.ZodOptional<z.ZodString>;
+        season: z.ZodOptional<z.ZodObject<{
+            seasonDbId: z.ZodOptional<z.ZodString>;
+            year: z.ZodOptional<z.ZodString>;
+            season: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        geoCoordinates: z.ZodOptional<z.ZodObject<{
+            type: z.ZodLiteral<"Feature">;
+            geometry: z.ZodObject<{
+                type: z.ZodLiteral<"Point">;
+                coordinates: z.ZodArray<z.ZodNumber>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        preview: "preview";
+        apply: "apply";
+    }>>;
+    force: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    alias: z.ZodString;
+    result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"preview">;
+        studyDbId: z.ZodString;
+        studyName: z.ZodOptional<z.ZodString>;
+        valid: z.ZodNumber;
+        invalid: z.ZodNumber;
+        routing: z.ZodObject<{
+            postCount: z.ZodNumber;
+            putCount: z.ZodNumber;
+        }, z.core.$strip>;
+        perRowWarnings: z.ZodArray<z.ZodObject<{
+            rowIndex: z.ZodNumber;
+            observationVariableDbId: z.ZodOptional<z.ZodString>;
+            observationUnitDbId: z.ZodOptional<z.ZodString>;
+            warning: z.ZodString;
+        }, z.core.$strip>>;
+        knownVariableCount: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"apply">;
+        studyDbId: z.ZodString;
+        studyName: z.ZodOptional<z.ZodString>;
+        posted: z.ZodArray<z.ZodObject<{
+            observationDbId: z.ZodOptional<z.ZodString>;
+            observationUnitDbId: z.ZodOptional<z.ZodString>;
+            observationVariableDbId: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        updated: z.ZodArray<z.ZodObject<{
+            observationDbId: z.ZodString;
+            observationUnitDbId: z.ZodOptional<z.ZodString>;
+            observationVariableDbId: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        studyObservationCount: z.ZodOptional<z.ZodNumber>;
+        latestObservationTimestamp: z.ZodOptional<z.ZodString>;
+        perRowWarnings: z.ZodArray<z.ZodObject<{
+            rowIndex: z.ZodNumber;
+            observationVariableDbId: z.ZodOptional<z.ZodString>;
+            observationUnitDbId: z.ZodOptional<z.ZodString>;
+            warning: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>], "mode">;
+}, z.core.$strip>, readonly [{
+    readonly reason: "observations_unsupported";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "BrAPI server does not advertise /observations";
+    readonly recovery: "Run brapi_server_info to inspect the advertised endpoints, or call brapi_connect with a different alias for a server that exposes /observations.";
+}, {
+    readonly reason: "study_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Upstream returned no study record for the requested studyDbId";
+    readonly recovery: "Verify the studyDbId on the target server, or run brapi_find_studies to discover valid IDs before retrying.";
+}, {
+    readonly reason: "post_unsupported";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "Server does not advertise POST on /observations but new rows were submitted";
+    readonly recovery: "Remove the rows that lack observationDbId (those are the new rows) before retrying, or connect to a different server that supports POST on /observations.";
+}, {
+    readonly reason: "put_unsupported";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "Server does not advertise PUT on /observations but update rows were submitted";
+    readonly recovery: "Connect to a different server that supports PUT on /observations — dropping observationDbId would route as POST and create duplicates instead of updating the existing rows.";
+}, {
+    readonly reason: "elicit_unavailable";
+    readonly code: JsonRpcErrorCode.Forbidden;
+    readonly when: "Apply mode invoked but client does not expose ctx.elicit and force was false";
+    readonly recovery: "Set force=true only with explicit user authorization, or use a client that supports elicitation.";
+}, {
+    readonly reason: "user_declined";
+    readonly code: JsonRpcErrorCode.Forbidden;
+    readonly when: "User declined the elicitation prompt for the apply write";
+    readonly recovery: "Re-run the tool when the user is ready to confirm the write.";
+}]>;
+//# sourceMappingURL=brapi-submit-observations.tool.d.ts.map

package/dist/mcp-server/tools/definitions/brapi-submit-observations.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-submit-observations.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/brapi-submit-observations.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA2C,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAkOjE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsSlC,CAAC"}