@linkedapi/mcp 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedapi/mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server that lets AI assistants control LinkedIn accounts and retrieve real-time data.",
   "main": "dist/index.js",
   "bin": {

package/src/index.ts

@@ -17,6 +17,9 @@ import { LinkedApiProgressNotification } from './utils/types';
 
 function deriveClientFromUserAgent(userAgent: string): string {
   const ua = userAgent.toLowerCase();
+  if (ua.includes('codex')) return 'codex';
+  if (ua.includes('claude-code') || ua.includes('claude code')) return 'claude-code';
+  if (ua.includes('claude') || ua.includes('anthropic')) return 'claude';
   if (ua.includes('cursor')) return 'cursor';
   if (ua.includes('windsurf')) return 'windsurf';
   if (ua.includes('vscode') || ua.includes('visual studio code')) return 'vscode';
@@ -33,6 +36,14 @@ function deriveClientFromUserAgent(userAgent: string): string {
   return userAgent;
 }
 
+function normalizeHeaderValue(value: string | Array<string> | undefined): string | undefined {
+  if (Array.isArray(value)) {
+    return value.find((item) => item.trim().length > 0)?.trim();
+  }
+  const normalizedValue = value?.trim();
+  return normalizedValue && normalizedValue.length > 0 ? normalizedValue : undefined;
+}
+
 function getArgValue(flag: string): string | undefined {
   const index = process.argv.indexOf(flag);
   if (index === -1) return undefined;
@@ -61,8 +72,7 @@ async function main() {
     },
   );
 
-  const progressCallback = (_notification: LinkedApiProgressNotification) => {};
-  const linkedApiServer = new LinkedApiMCPServer(progressCallback);
+  const linkedApiServer = new LinkedApiMCPServer();
 
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     const tools = linkedApiServer.getTools();
@@ -118,22 +128,49 @@ async function main() {
       const localLinkedApiToken = process.env.LINKED_API_TOKEN;
       const localIdentificationToken = process.env.IDENTIFICATION_TOKEN;
       const headers = extra?.requestInfo?.headers ?? {};
-      const linkedApiToken = (headers['linked-api-token'] ?? localLinkedApiToken ?? '') as string;
-      const identificationToken = (headers['identification-token'] ??
-        localIdentificationToken ??
-        '') as string;
-      let mcpClient = (headers['client'] ?? '') as string;
+      const linkedApiToken =
+        normalizeHeaderValue(headers['linked-api-token']) ?? localLinkedApiToken ?? '';
+      const identificationToken =
+        normalizeHeaderValue(headers['identification-token']) ?? localIdentificationToken ?? '';
+      let mcpClient = normalizeHeaderValue(headers['client']) ?? '';
       if (!mcpClient) {
-        const userAgentHeader = headers['user-agent'];
-        if (typeof userAgentHeader === 'string' && userAgentHeader.trim().length > 0) {
+        const userAgentHeader = normalizeHeaderValue(headers['user-agent']);
+        if (userAgentHeader) {
           mcpClient = deriveClientFromUserAgent(userAgentHeader);
         }
       }
+      const progressCallback = (notification: LinkedApiProgressNotification): void => {
+        const { progressToken, progress, total, message } = notification;
+        if (progressToken === undefined) {
+          return;
+        }
+
+        void extra
+          .sendNotification({
+            method: 'notifications/progress',
+            params: {
+              progressToken,
+              progress,
+              total,
+              message,
+            },
+          })
+          .catch((error: unknown) => {
+            logger.warn(
+              {
+                toolName: request.params.name,
+                error: error instanceof Error ? error.message : String(error),
+              },
+              'Failed to send MCP progress notification',
+            );
+          });
+      };
 
       const result = await linkedApiServer.executeWithTokens(request.params, {
         linkedApiToken,
         identificationToken,
         mcpClient,
+        progressCallback,
       });
       return result;
     } catch (error) {

package/src/linked-api-server.ts

@@ -12,22 +12,47 @@ import {
   LinkedApiProgressNotification,
 } from './utils/types';
 
+const BACKGROUND_WORKFLOW_DESCRIPTION =
+  `Linked API actions are queued into a cloud-browser workflow and may take several minutes. This is normal LinkedIn automation behavior, not a failed request. If the response contains workflowId and operationName, do not retry this tool; call get_workflow_result with those exact values until the final result is returned.` as const;
+const NON_WORKFLOW_TOOL_NAMES = new Set<string>(['get_workflow_result', 'get_api_usage'] as const);
+const NOOP_PROGRESS_CALLBACK = (_notification: LinkedApiProgressNotification): void => {};
+
+interface TExecuteWithTokensOptions extends TLinkedApiConfig {
+  mcpClient: string;
+  progressCallback?: (notification: LinkedApiProgressNotification) => void;
+}
+
 export class LinkedApiMCPServer {
   private tools: LinkedApiTools;
 
-  constructor(progressCallback: (notification: LinkedApiProgressNotification) => void) {
-    this.tools = new LinkedApiTools(progressCallback);
+  constructor() {
+    this.tools = new LinkedApiTools();
   }
 
   public getTools(): Tool[] {
-    const linkedApiTools = this.tools.tools.map((tool) => tool.getTool());
+    const linkedApiTools = this.tools.tools.map((tool) => {
+      const definition = tool.getTool();
+      if (NON_WORKFLOW_TOOL_NAMES.has(definition.name)) {
+        return definition;
+      }
+
+      return {
+        ...definition,
+        description: `${definition.description}\n\n${BACKGROUND_WORKFLOW_DESCRIPTION}`,
+      };
+    });
     const adminTools = this.tools.adminTools.map((tool) => tool.getTool());
     return [...linkedApiTools, ...adminTools];
   }
 
   public async executeWithTokens(
     request: ExtendedCallToolRequest['params'],
-    { linkedApiToken, identificationToken, mcpClient }: TLinkedApiConfig & { mcpClient: string },
+    {
+      linkedApiToken,
+      identificationToken,
+      mcpClient,
+      progressCallback = NOOP_PROGRESS_CALLBACK,
+    }: TExecuteWithTokensOptions,
   ): Promise<CallToolResult> {
     const workflowTimeout = defineRequestTimeoutInSeconds(mcpClient) * 1000;
     logger.info(
@@ -46,22 +71,41 @@ export class LinkedApiMCPServer {
     try {
       const adminTool = this.tools.adminToolByName(toolName);
       if (adminTool) {
-        const admin = new LinkedApiAdmin({ linkedApiToken,
-client: 'mcp' });
+        const admin = new LinkedApiAdmin({
+          linkedApiToken,
+          client: 'mcp',
+        });
         const params = adminTool.validate(args);
-        const result = await adminTool.execute({ admin,
-args: params });
+        const result = await adminTool.execute({
+          admin,
+          args: params,
+        });
         const duration = this.calculateDuration(startTime);
-        logger.info({ toolName,
-duration,
-data: result }, 'Tool execution successful');
+        logger.info(
+          {
+            toolName,
+            duration,
+            data: result,
+          },
+          'Tool execution successful',
+        );
         if (result === undefined) {
-          return { content: [{ type: 'text' as const,
-text: 'Completed' }] };
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: 'Completed',
+              },
+            ],
+          };
         }
         return {
-          content: [{ type: 'text' as const,
-text: JSON.stringify(result, null, 2) }],
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
         };
       }
 
@@ -82,9 +126,10 @@ text: JSON.stringify(result, null, 2) }],
       const params = tool.validate(args);
       const { data, errors } = await tool.execute({
         linkedapi,
-        args: params,
+        args: params as never,
         workflowTimeout,
         progressToken,
+        progressCallback,
       });
       const endTime = Date.now();
       const duration = `${((endTime - startTime) / 1000).toFixed(2)} seconds`;
@@ -98,6 +143,7 @@ text: JSON.stringify(result, null, 2) }],
           'Tool execution failed',
         );
         return {
+          isError: true,
           content: [
             {
               type: 'text' as const,
@@ -151,6 +197,8 @@ text: JSON.stringify(result, null, 2) }],
               text: JSON.stringify(body, null, 2),
             },
           ],
+          structuredContent: body,
+          isError: error.type !== 'workflowTimeout',
         };
       }
       const errorMessage = error instanceof Error ? error.message : String(error);

package/src/linked-api-tools.ts

@@ -1,3 +1,6 @@
+import LinkedApi, { TMappedResponse } from '@linkedapi/node';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
 import { AdminConnectAccountTool } from './tools/admin-connect-account.js';
 import { AdminDisconnectAccountTool } from './tools/admin-disconnect-account.js';
 import { AdminGetAccountsTool } from './tools/admin-get-accounts.js';
@@ -36,45 +39,63 @@ import { SendConnectionRequestTool } from './tools/send-connection-request.js';
 import { SendMessageTool } from './tools/send-message.js';
 import { WithdrawConnectionRequestTool } from './tools/withdraw-connection-request.js';
 import { AdminTool } from './utils/admin-tool.js';
-import { LinkedApiTool } from './utils/linked-api-tool.js';
 import { LinkedApiProgressNotification } from './utils/types.js';
 
+interface TRegisteredLinkedApiTool {
+  readonly name: string;
+  getTool(): Tool;
+  validate(args: unknown): unknown;
+  execute({
+    linkedapi,
+    args,
+    workflowTimeout,
+    progressToken,
+    progressCallback,
+  }: {
+    linkedapi: LinkedApi;
+    args: never;
+    workflowTimeout: number;
+    progressToken?: string | number;
+    progressCallback: (progress: LinkedApiProgressNotification) => void;
+  }): Promise<TMappedResponse<unknown>>;
+}
+
 export class LinkedApiTools {
-  public readonly tools: ReadonlyArray<LinkedApiTool<unknown, unknown>>;
+  public readonly tools: ReadonlyArray<TRegisteredLinkedApiTool>;
   public readonly adminTools: ReadonlyArray<AdminTool<unknown, unknown>>;
 
-  constructor(progressCallback: (progress: LinkedApiProgressNotification) => void) {
+  constructor() {
     this.tools = [
       // Standard tools
-      new SendMessageTool(progressCallback),
-      new GetConversationTool(progressCallback),
-      new CheckConnectionStatusTool(progressCallback),
-      new RetrieveConnectionsTool(progressCallback),
-      new SendConnectionRequestTool(progressCallback),
-      new WithdrawConnectionRequestTool(progressCallback),
-      new RetrievePendingRequestsTool(progressCallback),
-      new RemoveConnectionTool(progressCallback),
-      new SearchCompaniesTool(progressCallback),
-      new SearchPeopleTool(progressCallback),
-      new FetchCompanyTool(progressCallback),
-      new FetchPersonTool(progressCallback),
-      new FetchPostTool(progressCallback),
-      new ReactToPostTool(progressCallback),
-      new CommentOnPostTool(progressCallback),
-      new CreatePostTool(progressCallback),
-      new RetrieveSSITool(progressCallback),
-      new RetrievePerformanceTool(progressCallback),
+      new SendMessageTool(),
+      new GetConversationTool(),
+      new CheckConnectionStatusTool(),
+      new RetrieveConnectionsTool(),
+      new SendConnectionRequestTool(),
+      new WithdrawConnectionRequestTool(),
+      new RetrievePendingRequestsTool(),
+      new RemoveConnectionTool(),
+      new SearchCompaniesTool(),
+      new SearchPeopleTool(),
+      new FetchCompanyTool(),
+      new FetchPersonTool(),
+      new FetchPostTool(),
+      new ReactToPostTool(),
+      new CommentOnPostTool(),
+      new CreatePostTool(),
+      new RetrieveSSITool(),
+      new RetrievePerformanceTool(),
       // Sales Navigator tools
-      new NvSendMessageTool(progressCallback),
-      new NvGetConversationTool(progressCallback),
-      new NvSearchCompaniesTool(progressCallback),
-      new NvSearchPeopleTool(progressCallback),
-      new NvFetchCompanyTool(progressCallback),
-      new NvFetchPersonTool(progressCallback),
+      new NvSendMessageTool(),
+      new NvGetConversationTool(),
+      new NvSearchCompaniesTool(),
+      new NvSearchPeopleTool(),
+      new NvFetchCompanyTool(),
+      new NvFetchPersonTool(),
       // Other tools
-      new ExecuteCustomWorkflowTool(progressCallback),
-      new GetWorkflowResultTool(progressCallback),
-      new GetApiUsageTool(progressCallback),
+      new ExecuteCustomWorkflowTool(),
+      new GetWorkflowResultTool(),
+      new GetApiUsageTool(),
     ];
 
     this.adminTools = [
@@ -91,7 +112,7 @@ export class LinkedApiTools {
     ];
   }
 
-  public toolByName(name: string): LinkedApiTool<unknown, unknown> | undefined {
+  public toolByName(name: string): TRegisteredLinkedApiTool | undefined {
     return this.tools.find((tool) => tool.name === name);
   }
 

package/src/tools/comment-on-post.ts

@@ -16,7 +16,8 @@ export class CommentOnPostTool extends OperationTool<TCommentOnPostParams, unkno
   public override getTool(): Tool {
     return {
       name: this.name,
-      description: 'Allows you to leave a comment on a post (st.commentOnPost action).',
+      description:
+        'Allows you to leave a comment on a post (st.commentOnPost action). If this workflow is still running, do not retry this tool; retrying can post duplicate comments.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/tools/create-post.ts

@@ -26,7 +26,7 @@ export class CreatePostTool extends OperationTool<TCreatePostParams, unknown> {
     return {
       name: this.name,
       description:
-        'Creates a new LinkedIn post with optional media attachments (st.createPost action).',
+        'Creates a new LinkedIn post with optional media attachments (st.createPost action). If this workflow is still running, do not retry this tool; retrying can create duplicate posts.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/tools/execute-custom-workflow.ts

@@ -17,7 +17,8 @@ export class ExecuteCustomWorkflowTool extends OperationTool<
   public override getTool(): Tool {
     return {
       name: this.name,
-      description: 'Execute a custom workflow definition',
+      description:
+        'Execute a custom workflow definition. If this workflow is still running, do not retry this tool; retrying can duplicate any write actions inside the custom workflow.',
       inputSchema: {
         type: 'object',
         properties: { definition: { type: 'object' } },

package/src/tools/get-conversation.ts

@@ -1,8 +1,14 @@
-import LinkedApi, { TConversationPollResult, TMappedResponse } from '@linkedapi/node';
+import LinkedApi, {
+  LinkedApiWorkflowTimeoutError,
+  TConversationPollResult,
+  TMappedResponse,
+} from '@linkedapi/node';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import z from 'zod';
 
+import { executeWithProgress } from '../utils/execute-with-progress.js';
 import { LinkedApiTool } from '../utils/linked-api-tool.js';
+import { LinkedApiProgressNotification } from '../utils/types.js';
 
 export class GetConversationTool extends LinkedApiTool<
   { personUrl: string; since?: string },
@@ -17,18 +23,36 @@ export class GetConversationTool extends LinkedApiTool<
   public override async execute({
     linkedapi,
     args: { personUrl, since },
+    workflowTimeout,
+    progressToken,
+    progressCallback,
   }: {
     linkedapi: LinkedApi;
     args: { personUrl: string; since?: string };
     workflowTimeout: number;
     progressToken?: string | number;
+    progressCallback: (progress: LinkedApiProgressNotification) => void;
   }): Promise<TMappedResponse<TConversationPollResult>> {
     const conversations = await this.getConversation(linkedapi, personUrl, since);
     if (conversations.errors.length === 0) {
       return conversations;
     }
-    const workflowId = await linkedapi.syncConversation.execute({ personUrl });
-    await linkedapi.syncConversation.result(workflowId);
+    try {
+      await executeWithProgress({
+        progressCallback,
+        operation: linkedapi.syncConversation,
+        workflowTimeout,
+        params: { personUrl },
+        progressToken,
+      });
+    } catch (error) {
+      if (error instanceof LinkedApiWorkflowTimeoutError) {
+        error.message = `${error.message}
+
+After get_workflow_result completes this sync workflow, call get_conversation again with the same personUrl to read the synchronized messages.`;
+      }
+      throw error;
+    }
     return await this.getConversation(linkedapi, personUrl, since);
   }
 

package/src/tools/get-workflow-result.ts

@@ -4,6 +4,7 @@ import z from 'zod';
 
 import { executeWithProgress } from '../utils/execute-with-progress.js';
 import { LinkedApiTool } from '../utils/linked-api-tool.js';
+import { LinkedApiProgressNotification } from '../utils/types.js';
 
 interface IGetWorkflowResultParams {
   workflowId: string;
@@ -22,16 +23,21 @@ export class GetWorkflowResultTool extends LinkedApiTool<IGetWorkflowResultParam
     args: { workflowId, operationName },
     workflowTimeout,
     progressToken,
+    progressCallback,
   }: {
     linkedapi: LinkedApi;
     args: IGetWorkflowResultParams;
     workflowTimeout: number;
     progressToken?: string | number;
+    progressCallback: (progress: LinkedApiProgressNotification) => void;
   }): Promise<TMappedResponse<unknown>> {
     const operation = linkedapi.operations.find(
       (operation) => operation.operationName === operationName,
     )!;
-    return await executeWithProgress(this.progressCallback, operation, workflowTimeout, {
+    return await executeWithProgress({
+      progressCallback,
+      operation,
+      workflowTimeout,
       workflowId,
       progressToken,
     });
@@ -47,12 +53,13 @@ export class GetWorkflowResultTool extends LinkedApiTool<IGetWorkflowResultParam
         properties: {
           workflowId: {
             type: 'string',
-            description: 'The workflow ID provided in the background workflow status message',
+            description:
+              'Required. The workflow ID provided in the background workflow status message.',
           },
           operationName: {
             type: 'string',
             description:
-              'Optional function name for proper type restoration (provided in background workflow status if available)',
+              'Required. The operationName provided in the background workflow status message. Use the exact value so the result can be restored correctly.',
           },
         },
         required: ['workflowId', 'operationName'],

package/src/tools/nv-get-conversation.ts

@@ -1,8 +1,14 @@
-import LinkedApi, { TConversationPollResult, TMappedResponse } from '@linkedapi/node';
+import LinkedApi, {
+  LinkedApiWorkflowTimeoutError,
+  TConversationPollResult,
+  TMappedResponse,
+} from '@linkedapi/node';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import z from 'zod';
 
+import { executeWithProgress } from '../utils/execute-with-progress.js';
 import { LinkedApiTool } from '../utils/linked-api-tool.js';
+import { LinkedApiProgressNotification } from '../utils/types.js';
 
 export class NvGetConversationTool extends LinkedApiTool<
   { personUrl: string; since?: string },
@@ -17,18 +23,36 @@ export class NvGetConversationTool extends LinkedApiTool<
   public override async execute({
     linkedapi,
     args: { personUrl, since },
+    workflowTimeout,
+    progressToken,
+    progressCallback,
   }: {
     linkedapi: LinkedApi;
     args: { personUrl: string; since?: string };
     workflowTimeout: number;
     progressToken?: string | number;
+    progressCallback: (progress: LinkedApiProgressNotification) => void;
   }): Promise<TMappedResponse<TConversationPollResult>> {
     const conversations = await this.getConversation(linkedapi, personUrl, since);
     if (conversations.errors.length === 0) {
       return conversations;
     }
-    const workflowId = await linkedapi.nvSyncConversation.execute({ personUrl });
-    await linkedapi.nvSyncConversation.result(workflowId);
+    try {
+      await executeWithProgress({
+        progressCallback,
+        operation: linkedapi.nvSyncConversation,
+        workflowTimeout,
+        params: { personUrl },
+        progressToken,
+      });
+    } catch (error) {
+      if (error instanceof LinkedApiWorkflowTimeoutError) {
+        error.message = `${error.message}
+
+After get_workflow_result completes this sync workflow, call nv_get_conversation again with the same personUrl to read the synchronized messages.`;
+      }
+      throw error;
+    }
     return await this.getConversation(linkedapi, personUrl, since);
   }
 

package/src/tools/nv-send-message.ts

@@ -17,7 +17,7 @@ export class NvSendMessageTool extends OperationTool<TNvSendMessageParams, unkno
     return {
       name: this.name,
       description:
-        'Allows you to send a message to a person in Sales Navigator (nv.sendMessage action)',
+        'Allows you to send a message to a person in Sales Navigator (nv.sendMessage action). If this workflow is still running, do not retry this tool; retrying can send duplicate Sales Navigator messages to the same person.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/tools/react-to-post.ts

@@ -17,7 +17,7 @@ export class ReactToPostTool extends OperationTool<TReactToPostParams, unknown>
     return {
       name: this.name,
       description:
-        'Allows you to react to a post using any available reaction type (st.reactToPost action).',
+        'Allows you to react to a post using any available reaction type (st.reactToPost action). If this workflow is still running, do not retry this tool; retrying can queue duplicate reaction attempts.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/tools/remove-connection.ts

@@ -15,7 +15,7 @@ export class RemoveConnectionTool extends OperationTool<TRemoveConnectionParams,
     return {
       name: this.name,
       description:
-        'Allows you to remove a person from your connections (st.removeConnection action).',
+        'Allows you to remove a person from your connections (st.removeConnection action). If this workflow is still running, do not retry this tool; retrying can queue duplicate removal attempts for the same person.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/tools/send-connection-request.ts

@@ -20,7 +20,7 @@ export class SendConnectionRequestTool extends OperationTool<
     return {
       name: this.name,
       description:
-        'Allows you to send a connection request to a person (st.sendConnectionRequest action).',
+        'Allows you to send a connection request to a person (st.sendConnectionRequest action). If this workflow is still running, do not retry this tool; retrying can queue duplicate connection request attempts for the same person.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/tools/send-message.ts

@@ -15,7 +15,8 @@ export class SendMessageTool extends OperationTool<TSendMessageParams, unknown>
   public override getTool(): Tool {
     return {
       name: this.name,
-      description: 'Allows you to send a message to a person (st.sendMessage action).',
+      description:
+        'Allows you to send a message to a person (st.sendMessage action). If this workflow is still running, do not retry this tool; retrying can send duplicate messages to the same person.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/tools/withdraw-connection-request.ts

@@ -19,7 +19,7 @@ export class WithdrawConnectionRequestTool extends OperationTool<
     return {
       name: this.name,
       description:
-        'Allows you to withdraw the connection request sent to a person (st.withdrawConnectionRequest action).',
+        'Allows you to withdraw the connection request sent to a person (st.withdrawConnectionRequest action). If this workflow is still running, do not retry this tool; retrying can queue duplicate withdrawal attempts for the same person.',
       inputSchema: {
         type: 'object',
         properties: {

package/src/utils/define-request-timeout.ts

@@ -1,16 +1,28 @@
 export function defineRequestTimeoutInSeconds(mcpClient: string): number {
-  const bigTimeout = 600;
+  const BIG_TIMEOUT = 600 as const;
+  const normalizedMcpClient = mcpClient.trim().toLowerCase();
 
-  console.error('mcpClient', mcpClient);
-  switch (mcpClient) {
+  switch (normalizedMcpClient) {
+    case 'codex':
+    case 'codex-cli':
+    case 'codex-desktop':
+    case 'openai-codex':
+      return BIG_TIMEOUT;
+    case 'claude-code':
+    case 'claude_code':
+    case 'claude code':
+      return BIG_TIMEOUT;
     case 'claude':
+    case 'claude-desktop':
+    case 'anthropic':
       return 180;
     case 'chatgpt':
+    case 'openai':
       return 50;
     case 'cursor':
     case 'vscode':
     case 'windsurf':
-      return bigTimeout;
+      return BIG_TIMEOUT;
     default:
       return 60;
   }