Description improvements

Author: KirillSergeevich

README.md

@@ -1,17 +1,26 @@
 Linked API MCP server connects your LinkedIn account to AI assistants like Claude, Cursor, and VS Code. Ask them to search for leads, send messages, analyze profiles, and much more – they'll handle it through our cloud browser, safely and automatically.
 
 ## Use cases
+
 - **Sales automation assistant**. Ask your AI to find leads, check their profiles, and draft personalized outreach. It can search for "software engineers at companies with 50-200 employees in San Francisco", analyze their backgrounds, and suggest connection messages that actually make sense.
 - **Recruitment assistant**. Let your assistant search for candidates with specific skills, review their experience, and send initial outreach. It handles the time-consuming parts while you focus on actually talking to people.
 - **Conversation assistant**. Your AI can read your existing LinkedIn conversations and help you respond naturally. It understands the context of your chats, suggests relevant replies, and can even send follow-up messages.
 - **Market research assistant**. Need competitor analysis? Your assistant can gather data about companies, their employees, and recent activities. Get insights about industry trends without spending hours on LinkedIn.
 
 ## Get started
+
 To start using Linked API MCP, spend 2 minutes reading these essential guides:
 
 1. [Installation](https://linkedapi.io/mcp/installation/) – set up MCP in Claude, Cursor, VS Code, or Windsurf.
 2. [Available tools](https://linkedapi.io/mcp/available-tools/) – explore all the LinkedIn tools your assistant can call.
 3. [Usage examples](https://linkedapi.io/mcp/usage-examples/) – see real-world examples to get you started quickly.
 
+## Long-running actions
+
+Linked API actions run through a cloud browser and are queued like normal automation. Many actions take several minutes, especially searches and profile fetches with optional data.
+
+If a tool returns `workflowId` and `operationName`, the action is still running. Do not retry the original tool because that can queue duplicate work. Call `get_workflow_result` with the exact `workflowId` and `operationName` until the final result is returned.
+
 ## License
+
 This project is licensed under the MIT – see the [LICENSE](https://github.com/Linked-API/linkedapi-mcp/blob/main/LICENSE) file for details.

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": {

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) {

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);

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);
   }
 

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: {

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: {

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' } },