@linkedapi/mcp 1.0.0 → 1.0.1

package/src/utils/execute-with-progress.ts

@@ -2,23 +2,33 @@ import { LinkedApiWorkflowTimeoutError, Operation, TMappedResponse } from '@link
 
 import { LinkedApiProgressNotification } from './types';
 
-export async function executeWithProgress<TParams, TResult>(
-  progressCallback: (progress: LinkedApiProgressNotification) => void,
-  operation: Operation<TParams, TResult>,
-  workflowTimeout: number,
-  {
-    params,
-    workflowId,
-    progressToken,
-  }: { params?: TParams; workflowId?: string; progressToken?: string | number } = {},
-): Promise<TMappedResponse<TResult>> {
+const WORKFLOW_PROGRESS_TOTAL = 100 as const;
+const MIN_PROGRESS_INTERVAL = 10000 as const;
+
+interface TExecuteWithProgressOptions<TParams, TResult> {
+  progressCallback: (progress: LinkedApiProgressNotification) => void;
+  operation: Operation<TParams, TResult>;
+  workflowTimeout: number;
+  params?: TParams;
+  workflowId?: string;
+  progressToken?: string | number;
+}
+
+export async function executeWithProgress<TParams, TResult>({
+  progressCallback,
+  operation,
+  workflowTimeout,
+  params,
+  workflowId,
+  progressToken,
+}: TExecuteWithProgressOptions<TParams, TResult>): Promise<TMappedResponse<TResult>> {
   let progress = 0;
 
   progressCallback({
     progressToken,
     progress,
-    total: 100,
-    message: `Starting workflow ${operation.operationName}...`,
+    total: WORKFLOW_PROGRESS_TOTAL,
+    message: `Starting Linked API workflow ${operation.operationName}. The action may enter the cloud-browser queue and take several minutes.`,
   });
 
   const interval = setInterval(
@@ -32,16 +42,22 @@ export async function executeWithProgress<TParams, TResult>(
       progressCallback({
         progressToken,
         progress,
-        total: 100,
-        message: `Executing workflow ${operation.operationName}...`,
+        total: WORKFLOW_PROGRESS_TOTAL,
+        message: `Waiting for workflow ${operation.operationName}. Linked API is still processing it in the background.`,
       });
     },
-    Math.max(workflowTimeout / 20, 10000),
+    Math.max(workflowTimeout / 20, MIN_PROGRESS_INTERVAL),
   );
 
   try {
     if (!workflowId) {
       workflowId = await operation.execute(params as TParams);
+      progressCallback({
+        progressToken,
+        progress,
+        total: WORKFLOW_PROGRESS_TOTAL,
+        message: `Workflow ${operation.operationName} is queued or running in the background. workflowId: ${workflowId}.`,
+      });
     }
     const result = await operation.result(workflowId, {
       timeout: workflowTimeout,
@@ -50,8 +66,8 @@ export async function executeWithProgress<TParams, TResult>(
 
     progressCallback({
       progressToken,
-      progress: 100,
-      total: 100,
+      progress: WORKFLOW_PROGRESS_TOTAL,
+      total: WORKFLOW_PROGRESS_TOTAL,
       message: `Workflow ${operation.operationName} completed successfully`,
     });
 
@@ -66,8 +82,10 @@ export async function executeWithProgress<TParams, TResult>(
   }
 }
 
-function generateTimeoutError(error: LinkedApiWorkflowTimeoutError) {
-  const restoreMessage = `Workflow is running in the background. Continue listening for updates.
+function generateTimeoutError(error: LinkedApiWorkflowTimeoutError): LinkedApiWorkflowTimeoutError {
+  const restoreMessage = `Workflow is still running in Linked API's cloud-browser queue or background worker.
+
+This is not a failure. The original tool already started the workflow, so retrying it can create duplicate queued work.
 
 ACTION REQUIRED (MCP CLIENT):
 - Do not retry the original tool; the workflow is already running

package/src/utils/handle-linked-api-error.ts

@@ -2,13 +2,24 @@ import { LinkedApiError, LinkedApiWorkflowTimeoutError } from '@linkedapi/node';
 
 import { authenticationPrompt } from '../prompts';
 
-export function handleLinkedApiError(error: LinkedApiError): object {
+export function handleLinkedApiError(error: LinkedApiError): Record<string, unknown> {
   if (error instanceof LinkedApiWorkflowTimeoutError) {
     const { message, workflowId, operationName } = error;
     return {
+      status: 'workflow_running',
       message,
       workflowId,
       operationName,
+      nextAction: {
+        tool: 'get_workflow_result',
+        arguments: {
+          workflowId,
+          operationName,
+        },
+        repeatUntil: 'final data is returned or the tool returns Completed',
+      },
+      userMessage:
+        'Linked API is still working through the cloud-browser workflow. I will keep checking the existing workflow instead of starting a duplicate request.',
     };
   }
   switch (error.type) {

package/src/utils/json-http-transport.ts

@@ -77,12 +77,13 @@ export class JsonHTTPServerTransport implements Transport {
   }
 
   async send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void> {
+    const isResponse = isJSONRPCResponse(message) || isJSONRPCError(message);
     let relatedId = options?.relatedRequestId;
-    if (isJSONRPCResponse(message) || isJSONRPCError(message)) {
+    if (isResponse) {
       relatedId = message.id;
     }
-    // If a related HTTP connection is pending, complete it with JSON
-    if (relatedId !== undefined) {
+    // If a related HTTP connection is pending, only final responses complete it.
+    if (isResponse && relatedId !== undefined) {
       const connId = this.requestIdToConn.get(relatedId);
       if (connId) {
         const ctx = this.connections.get(connId);

package/src/utils/linked-api-tool.ts

@@ -5,14 +5,17 @@ import z from 'zod';
 
 import { executeWithProgress } from './execute-with-progress';
 
+interface TLinkedApiToolExecuteOptions<TParams> {
+  linkedapi: LinkedApi;
+  args: TParams;
+  workflowTimeout: number;
+  progressToken?: string | number;
+  progressCallback: (progress: LinkedApiProgressNotification) => void;
+}
+
 export abstract class LinkedApiTool<TParams, TResult> {
   public abstract readonly name: string;
   protected abstract readonly schema: z.ZodSchema;
-  protected readonly progressCallback: (progress: LinkedApiProgressNotification) => void;
-
-  constructor(progressCallback: (progress: LinkedApiProgressNotification) => void) {
-    this.progressCallback = progressCallback;
-  }
 
   public abstract getTool(): Tool;
 
@@ -25,12 +28,8 @@ export abstract class LinkedApiTool<TParams, TResult> {
     args,
     workflowTimeout,
     progressToken,
-  }: {
-    linkedapi: LinkedApi;
-    args: TParams;
-    workflowTimeout: number;
-    progressToken?: string | number;
-  }): Promise<TMappedResponse<TResult>>;
+    progressCallback,
+  }: TLinkedApiToolExecuteOptions<TParams>): Promise<TMappedResponse<TResult>>;
 }
 
 export abstract class OperationTool<TParams, TResult> extends LinkedApiTool<TParams, TResult> {
@@ -41,16 +40,15 @@ export abstract class OperationTool<TParams, TResult> extends LinkedApiTool<TPar
     args,
     workflowTimeout,
     progressToken,
-  }: {
-    linkedapi: LinkedApi;
-    args: TParams;
-    workflowTimeout: number;
-    progressToken?: string | number;
-  }): Promise<TMappedResponse<TResult>> {
+    progressCallback,
+  }: TLinkedApiToolExecuteOptions<TParams>): Promise<TMappedResponse<TResult>> {
     const operation = linkedapi.operations.find(
       (operation) => operation.operationName === this.operationName,
     )! as Operation<TParams, TResult>;
-    return executeWithProgress(this.progressCallback, operation, workflowTimeout, {
+    return executeWithProgress({
+      progressCallback,
+      operation,
+      workflowTimeout,
       params: args,
       progressToken,
     });