@isomorph.ai/app-sdk 1.37.0 → 1.38.1

package/README.md

@@ -627,3 +627,28 @@ subfolders, shortcuts and native Google documents are excluded. No historical ba
 Background read consent is required. Existing file-read size limits still apply. Provider
 subscriptions and real upload acceptance must be verified after deployment. Retries retain
 one durable job run; accounting/email side effects still need their own idempotency keys.
+
+
+### Selected MCP tools (server actions and jobs)
+
+Connect a compatible MCP server in Integrations, then select the app's tools with
+`isomorph integrations tools select`. This writes accepted descriptors into the
+existing `.isomorph/integrations.json`; `isomorph check` verifies literal usage.
+
+```ts
+const result = await isomorph.integrations.execute('finance', {
+  operation: 'mcp.tool.call', resource: 'server',
+  input: { tool: 'Invoices.Read', arguments: { id: invoiceId } },
+});
+const tools = await isomorph.integrations.tools('finance', {
+  tools: ['Invoices.Read', 'Invoices.Create'],
+  runId: persistedWorkflowId,
+});
+```
+
+Use the provider's exact selected tool names. The helper loads accepted schemas
+locally and returns AI SDK tools; it does not rediscover provider tools. For writes,
+keep the workflow run ID and tool-call ID stable across retries. Direct writes
+must supply their own persisted UUID `idempotencyKey`. A tool marked read-only
+does not require a key. An incomplete replay requires reconciliation, not a new
+write. Account consent and app permissions are enforced by the platform.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { McpCallRequest, McpCallResult, McpToolsOptions } from './mcp-tools.js';
+export type { McpCallRequest, McpCallResult, McpToolDescriptor, McpSelectedTool, McpToolsOptions, McpAgentTool } from './mcp-tools.js';
 import { type IsomorphUserRole } from './user-role.js';
 export type { IsomorphUserRole } from './user-role.js';
 export type IsomorphErrorCategory = 'AUTH_REQUIRED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION_FAILED' | 'RATE_LIMITED' | 'UNAVAILABLE' | 'INTERNAL';
@@ -1232,7 +1234,7 @@ export type ZohoBooksRequest = {
         lineItems: BooksInvoiceLineInput[];
     };
 };
-export type IntegrationRequest = ZohoBooksRequest | ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | WarehouseTableAppendRequest | PhoneSmsListRequest | PhoneNumberGetRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest | CalendarCalendarListRequest | CalendarEventListRequest | CalendarEventReadRequest | CalendarEventCreateRequest | CalendarEventUpdateRequest | CalendarEventCancelRequest | DriveFileListRequest | DriveFileSearchRequest | DriveFileReadRequest | DriveFileUploadRequest | DriveFolderCreateRequest | DocsDocumentReadRequest | DocsDocumentCreateRequest | DocsDocumentAppendRequest | DocsTextReplaceRequest | SheetsSpreadsheetReadRequest | SheetsValuesReadRequest | SheetsValuesAppendRequest | SheetsValuesUpdateRequest | SheetsValuesClearRequest | SheetsSpreadsheetCreateRequest | OutlookMessageListRequest | OutlookMessageReadRequest | OutlookAttachmentReadRequest | OutlookMessageSendRequest | OutlookMessageReplyRequest | OutlookEventListRequest | OutlookEventReadRequest | OutlookEventCreateRequest | OutlookEventUpdateRequest | OutlookEventCancelRequest | OneDriveFileListRequest | OneDriveFileSearchRequest | OneDriveFileReadRequest | OneDriveFileUploadRequest | OneDriveFolderCreateRequest | ExcelWorksheetListRequest | ExcelRangeReadRequest | ExcelRangeUpdateRequest | ExcelTableListRequest | ExcelRowAddRequest | ExcelWorksheetAddRequest | TeamsMessageListRequest | TeamsMessagePostRequest | TeamsReplyPostRequest;
+export type IntegrationRequest = McpCallRequest | ZohoBooksRequest | ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | WarehouseTableAppendRequest | PhoneSmsListRequest | PhoneNumberGetRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest | CalendarCalendarListRequest | CalendarEventListRequest | CalendarEventReadRequest | CalendarEventCreateRequest | CalendarEventUpdateRequest | CalendarEventCancelRequest | DriveFileListRequest | DriveFileSearchRequest | DriveFileReadRequest | DriveFileUploadRequest | DriveFolderCreateRequest | DocsDocumentReadRequest | DocsDocumentCreateRequest | DocsDocumentAppendRequest | DocsTextReplaceRequest | SheetsSpreadsheetReadRequest | SheetsValuesReadRequest | SheetsValuesAppendRequest | SheetsValuesUpdateRequest | SheetsValuesClearRequest | SheetsSpreadsheetCreateRequest | OutlookMessageListRequest | OutlookMessageReadRequest | OutlookAttachmentReadRequest | OutlookMessageSendRequest | OutlookMessageReplyRequest | OutlookEventListRequest | OutlookEventReadRequest | OutlookEventCreateRequest | OutlookEventUpdateRequest | OutlookEventCancelRequest | OneDriveFileListRequest | OneDriveFileSearchRequest | OneDriveFileReadRequest | OneDriveFileUploadRequest | OneDriveFolderCreateRequest | ExcelWorksheetListRequest | ExcelRangeReadRequest | ExcelRangeUpdateRequest | ExcelTableListRequest | ExcelRowAddRequest | ExcelWorksheetAddRequest | TeamsMessageListRequest | TeamsMessagePostRequest | TeamsReplyPostRequest;
 export type IntegrationOperation = IntegrationRequest['operation'];
 export interface SlackMessage {
     id: string;
@@ -1726,7 +1728,7 @@ export interface TeamsMessagePostResult {
     id: string;
     webUrl: string;
 }
-export type IntegrationResult<R extends IntegrationRequest> = R extends {
+export type IntegrationResult<R extends IntegrationRequest> = R extends McpCallRequest ? McpCallResult : R extends {
     operation: 'zohobooks.contact.list';
 } ? {
     booksContacts: {
@@ -2057,6 +2059,7 @@ export declare function createClient(options?: ClientOptions): {
         page: (path?: string) => Promise<void>;
     };
     integrations: {
+        tools: (connection: string, options: McpToolsOptions) => Promise<Record<string, import("./mcp-tools.js").McpAgentTool>>;
         execute: <R extends IntegrationRequest>(connection: string, request: R) => Promise<IntegrationResult<R>>;
         connect: (connection: string) => Promise<IntegrationConnectResult>;
         disconnect: (connection: string) => Promise<IntegrationDisconnectResult>;

package/dist/index.js

@@ -459,6 +459,28 @@ export function createClient(options = {}) {
         return user;
     };
     const transport = new Transport(options, () => notifyIdentity(null));
+    const executeIntegration = (connection, request) => {
+        // The contract's per-operation rules, refused here before any request
+        // is made, with the platform's own sentence and the field named — so
+        // `isomorph check` (which runs retained journeys through this client)
+        // and the deployed app fail the same way at build time, not at runtime.
+        const checked = validateIntegrationExecuteInput(request.operation, request.input);
+        const problem = (request.operation === 'warehouse.table.append' ? warehouseAppendProblem(request) : undefined)
+            ?? (!checked.ok ? checked.problem
+                : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined);
+        if (problem) {
+            return Promise.reject(new IsomorphError('VALIDATION_FAILED', problem.message, undefined, { code: 'INPUT_INVALID', field: problem.field }));
+        }
+        // Exactly the contract's fields go on the wire: metadata declares which
+        // operations accept `mode`; identity and stray fields are not sent.
+        // phone.number.get takes no input, but the contract keeps `input`
+        // required on the wire (ADR 0029), so an omitted one goes out as {}.
+        const { operation, resource, input: given, idempotencyKey, mode } = request;
+        const input = given === undefined && operation === 'phone.number.get' ? {} : given;
+        return transport.json('/_harbour/integrations/execute', {
+            method: 'POST', body: JSON.stringify({ connection, operation, ...(operation !== 'service.request' ? { resource } : {}), ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(IntegrationOperations[operation]?.declaredMode && mode !== undefined ? { mode } : {}) }),
+        });
+    };
     const socketFactory = options.websocket ?? ((url) => defaultSocketFactory(url, options.identity));
     const refreshIdentity = () => {
         if (refreshInFlight)
@@ -805,28 +827,11 @@ export function createClient(options = {}) {
             }),
         },
         integrations: {
-            execute: (connection, request) => {
-                // The contract's per-operation rules, refused here before any request
-                // is made, with the platform's own sentence and the field named — so
-                // `isomorph check` (which runs retained journeys through this client)
-                // and the deployed app fail the same way at build time, not at runtime.
-                const checked = validateIntegrationExecuteInput(request.operation, request.input);
-                const problem = (request.operation === 'warehouse.table.append' ? warehouseAppendProblem(request) : undefined)
-                    ?? (!checked.ok ? checked.problem
-                        : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined);
-                if (problem) {
-                    return Promise.reject(new IsomorphError('VALIDATION_FAILED', problem.message, undefined, { code: 'INPUT_INVALID', field: problem.field }));
-                }
-                // Exactly the contract's fields go on the wire: metadata declares which
-                // operations accept `mode`; identity and stray fields are not sent.
-                // phone.number.get takes no input, but the contract keeps `input`
-                // required on the wire (ADR 0029), so an omitted one goes out as {}.
-                const { operation, resource, input: given, idempotencyKey, mode } = request;
-                const input = given === undefined && operation === 'phone.number.get' ? {} : given;
-                return transport.json('/_harbour/integrations/execute', {
-                    method: 'POST', body: JSON.stringify({ connection, operation, ...(operation !== 'service.request' ? { resource } : {}), ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(IntegrationOperations[operation]?.declaredMode && mode !== undefined ? { mode } : {}) }),
-                });
+            tools: async (connection, options) => {
+                const { createMcpTools } = await import('./mcp-tools.js');
+                return createMcpTools(connection, options, request => executeIntegration(connection, request));
             },
+            execute: executeIntegration,
             // In a browser the consent returns the person to this page (without its
             // fragment); governance accepts it only as a registered page of this app
             // (ADR 0030). Outside a browser there is no page, and none is sent.

package/dist/integration-execute-input-rules.d.ts

@@ -2556,6 +2556,21 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "mcp.tool.call": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly tool: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly arguments: {
+                readonly kind: "object";
+                readonly required: true;
+            };
+        };
+    };
 };
 export type IntegrationExecuteOperation = keyof typeof IntegrationExecuteInputRules;
 /** The upper bound of one integer input as a literal type: integrationExecuteInputMaximum('slack.channel.history', 'limit') is 15. */

package/dist/integration-execute-input-rules.js

@@ -792,6 +792,13 @@ export const IntegrationExecuteInputRules = {
             documentId: { kind: "string", required: true, minLength: 0, maxLength: 32, pattern: "^[0-9]{1,32}$" },
         },
     },
+    "mcp.tool.call": {
+        idempotencyKey: false,
+        fields: {
+            tool: { kind: "string", required: true, minLength: 1, maxLength: 128 },
+            arguments: { kind: "object", required: true },
+        },
+    },
 };
 /** The upper bound of one integer input as a literal type: integrationExecuteInputMaximum('slack.channel.history', 'limit') is 15. */
 export function integrationExecuteInputMaximum(operation, field) {

package/dist/integration-operations.d.ts

@@ -665,4 +665,12 @@ export declare const IntegrationOperations: {
         readonly declaredMode: false;
         readonly idempotencyKey: false;
     };
+    readonly "mcp.tool.call": {
+        readonly kind: "mcp";
+        readonly identities: readonly ["user"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+        readonly runtimeIdempotency: true;
+    };
 };

package/dist/integration-operations.js

@@ -860,5 +860,15 @@ export const IntegrationOperations = {
         "readOnly": true,
         "declaredMode": false,
         "idempotencyKey": false
+    },
+    "mcp.tool.call": {
+        "kind": "mcp",
+        "identities": [
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": false,
+        "runtimeIdempotency": true
     }
 };

package/dist/mcp-tools.d.ts

@@ -0,0 +1,53 @@
+export interface McpToolDescriptor {
+    name: string;
+    description?: string;
+    title?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        [key: string]: unknown;
+    };
+}
+export interface McpSelectedTool {
+    name: string;
+    contractHash: string;
+    descriptor: McpToolDescriptor;
+}
+export interface McpCallRequest {
+    operation: 'mcp.tool.call';
+    resource: 'server';
+    mode?: 'user';
+    input: {
+        tool: string;
+        arguments: Record<string, unknown>;
+    };
+    idempotencyKey?: string;
+}
+export interface McpCallResult {
+    mcp: {
+        content?: Array<Record<string, unknown>>;
+        structuredContent?: Record<string, unknown>;
+        isError?: boolean;
+        replay?: {
+            complete: boolean;
+            summary?: string;
+        };
+    };
+}
+export interface McpToolsOptions {
+    tools: readonly string[];
+    runId: string;
+}
+/** The schema object belongs to the optional AI SDK and carries its private brand.
+ * Keep that implementation type out of ordinary clients' declaration graph. */
+export interface McpAgentTool {
+    description?: string;
+    inputSchema: any;
+    execute(input: Record<string, unknown>, context: {
+        toolCallId: string;
+    }): Promise<McpCallResult['mcp']>;
+}
+type Execute = (request: McpCallRequest) => Promise<McpCallResult>;
+export declare function createMcpTools(connection: string, options: McpToolsOptions, execute: Execute): Promise<Record<string, McpAgentTool>>;
+export {};

package/dist/mcp-tools.js

@@ -0,0 +1,51 @@
+async function digest(parts) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(parts))));
+}
+function hex(bytes) {
+    return Array.from(bytes, value => value.toString(16).padStart(2, '0')).join('');
+}
+async function invocationKey(runId, tool, callId) {
+    const bytes = (await digest([runId, tool, callId])).slice(0, 16);
+    bytes[6] = (bytes[6] & 15) | 128;
+    bytes[8] = (bytes[8] & 63) | 128;
+    const value = hex(bytes);
+    return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
+export async function createMcpTools(connection, options, execute) {
+    if (typeof window !== 'undefined' && typeof window.document !== 'undefined')
+        throw new Error('MCP agent tools run in actions or jobs.');
+    if (!options.runId || !Array.isArray(options.tools) || options.tools.length < 1 || options.tools.length > 64 || new Set(options.tools).size !== options.tools.length)
+        throw new Error('MCP tools need a durable runId and 1–64 unique selected tool names.');
+    const [{ readFile }, { resolve }, { jsonSchema }] = await Promise.all([import('node:fs/promises'), import('node:path'), import('ai')]);
+    const root = process.env.ISOMORPH_APP_ROOT || process.cwd();
+    const declaration = JSON.parse(await readFile(resolve(root, '.isomorph/integrations.json'), 'utf8'));
+    const source = declaration.connections[connection];
+    if (declaration.schema !== 'isomorph.app-integrations/2.0' || source?.kind !== 'mcp' || !source.mcp)
+        throw new Error('This MCP connection is not declared for the app. Run the integration selection and checks.');
+    const allowed = new Map(source.mcp.tools.map(tool => [tool.name, tool]));
+    const result = {};
+    for (const name of options.tools) {
+        const selected = allowed.get(name);
+        if (!selected || selected.descriptor.name !== name)
+            throw new Error(`MCP tool ${name} is not declared for this app.`);
+        const descriptor = selected.descriptor;
+        const alias = `mcp_${hex((await digest([connection, name])).slice(0, 20))}`;
+        result[alias] = {
+            description: descriptor.description ?? descriptor.title ?? name,
+            inputSchema: jsonSchema(descriptor.inputSchema),
+            execute: async (input, context) => {
+                const readOnly = descriptor.annotations?.readOnlyHint === true;
+                if (!readOnly && !context.toolCallId)
+                    throw new Error('MCP writes need a persisted toolCallId. Do not retry a write with a new invocation ID.');
+                const response = await execute({
+                    operation: 'mcp.tool.call', resource: 'server', mode: 'user', input: { tool: name, arguments: input },
+                    ...(!readOnly ? { idempotencyKey: await invocationKey(options.runId, name, context.toolCallId) } : {}),
+                });
+                if (response.mcp.replay?.complete === false)
+                    throw new Error('This MCP action already completed, but its result was not retained. Reconcile the provider record before continuing; do not repeat the action.');
+                return response.mcp;
+            },
+        };
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.37.0",
+  "version": "1.38.1",
   "type": "module",
   "repository": {
     "type": "git",