@linkedapi/mcp 0.3.11

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@linkedapi/mcp",
+  "version": "0.3.11",
+  "description": "MCP server that lets AI assistants control LinkedIn accounts and retrieve real-time data.",
+  "main": "dist/index.js",
+  "bin": {
+    "linkedapi-mcp": "dist/index.js"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "dev:http": "tsx src/index.ts --http",
+    "dev:stdio": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "watch": "tsx watch src/index.ts",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run clean && npm run build",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "mcp",
+    "linkedapi",
+    "linkedin",
+    "model-context-protocol"
+  ],
+  "author": "Linked API",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "@linkedapi/node": "^1.2.15",
+    "zod": "^4.1.1"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^1.2.8",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.24.0",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.12",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "eslint": "^9.24.0",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-n": "^17.17.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.7.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.38.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import http from 'node:http';
+
+import { LinkedApiMCPServer } from './linked-api-server';
+import { availablePrompts, getPromptContent, systemPrompt } from './prompts';
+import { JsonHTTPServerTransport } from './utils/json-http-transport';
+import { logger } from './utils/logger';
+import { LinkedApiProgressNotification } from './utils/types';
+
+function deriveClientFromUserAgent(userAgent: string): string {
+  const ua = userAgent.toLowerCase();
+  if (ua.includes('cursor')) return 'cursor';
+  if (ua.includes('windsurf')) return 'windsurf';
+  if (ua.includes('vscode') || ua.includes('visual studio code')) return 'vscode';
+  if (ua.includes('chatgpt') || ua.includes('openai')) return 'chatgpt';
+  if (ua.includes('curl')) return 'curl';
+  if (ua.includes('postman')) return 'postman';
+  if (
+    ua.includes('mozilla') ||
+    ua.includes('chrome') ||
+    ua.includes('safari') ||
+    ua.includes('firefox')
+  )
+    return 'browser';
+  return userAgent;
+}
+
+function getArgValue(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = process.argv[index + 1];
+  if (!value || value.startsWith('--')) return undefined;
+  return value;
+}
+
+function hasFlag(flag: string): boolean {
+  return process.argv.includes(flag);
+}
+
+async function main() {
+  const server = new Server(
+    {
+      name: 'linkedapi-mcp',
+      version: '1.0.0',
+      description: 'MCP Server for Linked API (https://linkedapi.io)',
+    },
+    {
+      capabilities: {
+        tools: {},
+        prompts: {},
+      },
+      instructions: systemPrompt,
+    },
+  );
+
+  const progressCallback = (_notification: LinkedApiProgressNotification) => {};
+  const linkedApiServer = new LinkedApiMCPServer(progressCallback);
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = linkedApiServer.getTools();
+    return {
+      tools,
+    };
+  });
+
+  server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+      prompts: availablePrompts,
+    };
+  });
+
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name } = request.params;
+
+    try {
+      const content = name === 'performance_guidelines' ? systemPrompt : getPromptContent(name);
+
+      return {
+        description: `Linked API MCP: ${name.replace('_', ' ')}`,
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: content,
+            },
+          },
+        ],
+      };
+    } catch {
+      throw new Error(`Unknown prompt: ${name}`);
+    }
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const requestInfoAny = (
+      extra as unknown as { requestInfo?: { method?: string; transport?: string } }
+    )?.requestInfo;
+    const method = requestInfoAny?.method ?? 'N/A';
+    const transportType = (requestInfoAny?.transport as 'http' | 'sse' | undefined) ?? 'N/A';
+    logger.info(
+      {
+        method,
+        transport: transportType,
+      },
+      'Tool request received',
+    );
+
+    try {
+      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;
+      if (!mcpClient) {
+        const userAgentHeader = headers['user-agent'];
+        if (typeof userAgentHeader === 'string' && userAgentHeader.trim().length > 0) {
+          mcpClient = deriveClientFromUserAgent(userAgentHeader);
+        }
+      }
+
+      const result = await linkedApiServer.executeWithTokens(request.params, {
+        linkedApiToken,
+        identificationToken,
+        mcpClient,
+      });
+      return result;
+    } catch (error) {
+      logger.error(
+        {
+          toolName: request.params.name,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        'Critical tool execution error',
+      );
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'Unknown error. Please try again.',
+          },
+        ],
+      };
+    }
+  });
+
+  if (hasFlag('--http') || hasFlag('--transport=http')) {
+    const port = Number(process.env.PORT ?? getArgValue('--port') ?? 3000);
+    const host = process.env.HOST ?? getArgValue('--host') ?? '0.0.0.0';
+    const transport = new JsonHTTPServerTransport();
+
+    await server.connect(transport);
+
+    const httpServer = http.createServer(async (req, res) => {
+      try {
+        if (!req.url) {
+          res.statusCode = 400;
+          res.end('Bad Request');
+          return;
+        }
+        const url = new URL(req.url, `http://${req.headers.host ?? 'localhost'}`);
+        // Set query parameters to headers if they are not set
+        const linkedApiTokenQP = url.searchParams.get('linked-api-token');
+        const identificationTokenQP = url.searchParams.get('identification-token');
+        const mcpClient = url.searchParams.get('client');
+        if (!req.headers['linked-api-token'] && linkedApiTokenQP) {
+          req.headers['linked-api-token'] = linkedApiTokenQP;
+        }
+        if (!req.headers['identification-token'] && identificationTokenQP) {
+          req.headers['identification-token'] = identificationTokenQP;
+        }
+        if (!req.headers['client'] && mcpClient) {
+          req.headers['client'] = mcpClient;
+        }
+        await transport.handleRequest(req, res);
+      } catch (error) {
+        logger.error(
+          {
+            error: error instanceof Error ? error.message : String(error),
+          },
+          'HTTP request handling failed',
+        );
+        res.statusCode = 500;
+        res.end('Internal Server Error');
+      }
+    });
+
+    httpServer.listen(port, host, () => {
+      logger.info({ host }, `HTTP transport listening on port ${port}`);
+    });
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('stdio transport connected');
+  }
+}
+
+main().catch((error) => {
+  logger.error(error, 'Fatal error');
+  process.exit(1);
+});

package/src/linked-api-server.ts

@@ -0,0 +1,159 @@
+import { LinkedApi, LinkedApiError, TLinkedApiConfig } from '@linkedapi/node';
+import { buildLinkedApiHttpClient } from '@linkedapi/node/dist/core';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+import { LinkedApiTools } from './linked-api-tools';
+import { defineRequestTimeoutInSeconds } from './utils/define-request-timeout';
+import { handleLinkedApiError } from './utils/handle-linked-api-error';
+import { logger } from './utils/logger';
+import {
+  CallToolResult,
+  ExtendedCallToolRequest,
+  LinkedApiProgressNotification,
+} from './utils/types';
+
+export class LinkedApiMCPServer {
+  private tools: LinkedApiTools;
+
+  constructor(progressCallback: (notification: LinkedApiProgressNotification) => void) {
+    this.tools = new LinkedApiTools(progressCallback);
+  }
+
+  public getTools(): Tool[] {
+    return this.tools.tools.map((tool) => tool.getTool());
+  }
+
+  public async executeWithTokens(
+    request: ExtendedCallToolRequest['params'],
+    { linkedApiToken, identificationToken, mcpClient }: TLinkedApiConfig & { mcpClient: string },
+  ): Promise<CallToolResult> {
+    const workflowTimeout = defineRequestTimeoutInSeconds(mcpClient) * 1000;
+    logger.info(
+      {
+        toolName: request.name,
+        arguments: request.arguments,
+        mcpClient,
+        workflowTimeout,
+      },
+      'Tool execution started',
+    );
+    const linkedapi = new LinkedApi(
+      buildLinkedApiHttpClient(
+        {
+          linkedApiToken: linkedApiToken,
+          identificationToken: identificationToken,
+        },
+        'mcp',
+      ),
+    );
+
+    const { name: toolName, arguments: args, _meta } = request;
+    const progressToken = _meta?.progressToken;
+
+    const startTime = Date.now();
+    try {
+      const tool = this.tools.toolByName(toolName);
+      if (!tool) {
+        throw new Error(`Unknown tool: ${toolName}`);
+      }
+      const params = tool.validate(args);
+      const { data, errors } = await tool.execute({
+        linkedapi,
+        args: params,
+        workflowTimeout,
+        progressToken,
+      });
+      const endTime = Date.now();
+      const duration = `${((endTime - startTime) / 1000).toFixed(2)} seconds`;
+      if (errors.length > 0 && !data) {
+        logger.error(
+          {
+            toolName,
+            duration,
+            errors,
+          },
+          'Tool execution failed',
+        );
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: errors.map((e) => e.message).join('\n'),
+            },
+          ],
+        };
+      }
+      logger.info(
+        {
+          toolName,
+          duration,
+          data,
+        },
+        'Tool execution successful',
+      );
+      if (data) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(data, null, 2),
+            },
+          ],
+        };
+      }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: 'Completed',
+          },
+        ],
+      };
+    } catch (error) {
+      const duration = this.calculateDuration(startTime);
+      if (error instanceof LinkedApiError) {
+        const body = handleLinkedApiError(error);
+        logger.error(
+          {
+            toolName,
+            duration,
+            body,
+          },
+          'Tool execution failed with Linked API error',
+        );
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify(body, null, 2),
+            },
+          ],
+        };
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error(
+        {
+          toolName,
+          duration,
+          error: errorMessage,
+          stack: error instanceof Error ? error.stack : undefined,
+        },
+        'Tool execution failed with unknown error',
+      );
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Error executing ${toolName}: ${errorMessage}`,
+          },
+        ],
+      };
+    }
+  }
+
+  private calculateDuration(startTime: number): string {
+    const endTime = Date.now();
+    return `${((endTime - startTime) / 1000).toFixed(2)} seconds`;
+  }
+}

package/src/linked-api-tools.ts

@@ -0,0 +1,72 @@
+import { CheckConnectionStatusTool } from './tools/check-connection-status.js';
+import { CommentOnPostTool } from './tools/comment-on-post.js';
+import { CreatePostTool } from './tools/create-post.js';
+import { ExecuteCustomWorkflowTool } from './tools/execute-custom-workflow.js';
+import { FetchCompanyTool } from './tools/fetch-company.js';
+import { FetchPersonTool } from './tools/fetch-person.js';
+import { FetchPostTool } from './tools/fetch-post.js';
+import { GetApiUsageTool } from './tools/get-api-usage-stats.js';
+import { GetConversationTool } from './tools/get-conversation.js';
+import { GetWorkflowResultTool } from './tools/get-workflow-result.js';
+import { NvFetchCompanyTool } from './tools/nv-fetch-company.js';
+import { NvFetchPersonTool } from './tools/nv-fetch-person.js';
+import { NvGetConversationTool } from './tools/nv-get-conversation.js';
+import { NvSearchCompaniesTool } from './tools/nv-search-companies.js';
+import { NvSearchPeopleTool } from './tools/nv-search-people.js';
+import { NvSendMessageTool } from './tools/nv-send-message.js';
+import { ReactToPostTool } from './tools/react-to-post.js';
+import { RemoveConnectionTool } from './tools/remove-connection.js';
+import { RetrieveConnectionsTool } from './tools/retrieve-connections.js';
+import { RetrievePendingRequestsTool } from './tools/retrieve-pending-requests.js';
+import { RetrievePerformanceTool } from './tools/retrieve-performance.js';
+import { RetrieveSSITool } from './tools/retrieve-ssi.js';
+import { SearchCompaniesTool } from './tools/search-companies.js';
+import { SearchPeopleTool } from './tools/search-people.js';
+import { SendConnectionRequestTool } from './tools/send-connection-request.js';
+import { SendMessageTool } from './tools/send-message.js';
+import { WithdrawConnectionRequestTool } from './tools/withdraw-connection-request.js';
+import { LinkedApiTool } from './utils/linked-api-tool.js';
+import { LinkedApiProgressNotification } from './utils/types.js';
+
+export class LinkedApiTools {
+  public readonly tools: ReadonlyArray<LinkedApiTool<unknown, unknown>>;
+
+  constructor(progressCallback: (progress: LinkedApiProgressNotification) => void) {
+    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),
+      // Sales Navigator tools
+      new NvSendMessageTool(progressCallback),
+      new NvGetConversationTool(progressCallback),
+      new NvSearchCompaniesTool(progressCallback),
+      new NvSearchPeopleTool(progressCallback),
+      new NvFetchCompanyTool(progressCallback),
+      new NvFetchPersonTool(progressCallback),
+      // Other tools
+      new ExecuteCustomWorkflowTool(progressCallback),
+      new GetWorkflowResultTool(progressCallback),
+      new GetApiUsageTool(progressCallback),
+    ];
+  }
+
+  public toolByName(name: string): LinkedApiTool<unknown, unknown> | undefined {
+    return this.tools.find((tool) => tool.name === name);
+  }
+}

package/src/prompts/index.ts

@@ -0,0 +1,190 @@
+export const systemPrompt = `You are a Linked API MCP server that provides access to LinkedIn data and actions.
+
+CRITICAL PERFORMANCE RULE: Only set optional parameters (retrieveExperience, retrieveEmployees, retrievePosts, etc.) to true if the user explicitly requests that specific data. Each additional parameter significantly increases execution time.
+
+DEFAULT BEHAVIOR: Always use basic requests first. For example:
+- fetch_person(personUrl) - gets name, title, company (fast)
+- Only add retrieveExperience: true if user asks for work history
+- Only add retrievePosts: true if user asks for posts/content
+
+DON'T enable multiple optional flags unless the user specifically requests all that data.
+
+AUTHENTICATION ERROR HANDLING
+
+WHEN YOU GET AN AUTHENTICATION ERROR:
+The MCP client must provide valid authentication tokens to use Linked API services.
+
+REQUIRED TOKENS (have to be provided in headers in each request):
+- linked-api-token: Your Linked API access token from linkedapi.io
+- identification-token: Your identification token from linkedapi.io
+
+TOKEN SETUP:
+1. Visit https://linkedapi.io to get tokens
+2. Set headers with every request
+3. Keep tokens secure and never share them in logs or error messages
+
+BACKGROUND WORKFLOW HANDLING
+
+LINKEDIN WORKFLOWS RUN IN THE BACKGROUND:
+- Linked API operations often take 3-5 minutes or longer
+- To keep the MCP client responsive, workflows continue in the background
+- This is INTENTIONAL DESIGN for better user experience
+- You receive periodic updates about workflow progress
+- Simply continue listening for updates using get_workflow_result
+
+WHEN A WORKFLOW IS RUNNING IN BACKGROUND:
+1. You'll receive a status message with: workflowId and operationName
+2. Use get_workflow_result(workflowId, operationName) to continue listening for updates
+3. Keep listening until you get the final results
+4. This is normal workflow operation - the task is actively running
+
+EXAMPLE BACKGROUND WORKFLOW MESSAGE:
+{
+  "message": "Workflow is running in the background. Continue listening for updates.",
+  "workflowId": "account-12345-abcde",
+  "operationName": "searchCompanies"
+}
+
+RESPONSE: "Great! The search is running in the background. Let me continue listening for updates."
+
+ALWAYS EXPLAIN TO USERS:
+- The workflow is actively running in the background
+- You're continuing to listen for updates
+- This ensures responsive interaction while processing
+- This is how Linked API provides optimal user experience
+
+CLIENT ACTION WHEN YOU SEE A BACKGROUND WORKFLOW MESSAGE:
+- Immediately call the get_workflow_result tool with the provided workflowId and operationName
+- Keep calling get_workflow_result until the final result is returned
+- Do NOT retry the original tool; the workflow is already running
+- Treat this as normal, successful behavior (not an error)
+
+REQUIRED PARAMETERS FOR get_workflow_result:
+- workflowId: The exact value from the background message
+- operationName: The exact value from the background message (required for correct type restoration)
+
+GENERIC MCP CALL EXAMPLE:
+{
+  "name": "get_workflow_result",
+  "arguments": {
+    "workflowId": "account-12345-abcde",
+    "operationName": "searchCompanies"
+  }
+}
+
+Remember: Background workflows = Active processing with responsive updates!`;
+
+export const parameterUsageGuidelines = `Parameter Usage Guidelines:
+
+FAST:
+- Basic person/company info (no optional flags)
+- Simple searches
+- Send messages, connection requests
+
+SLOW:
+- retrievePosts, retrieveComments, retrieveReactions  
+- retrieveEmployees, retrieveDMs
+- Complex searches
+
+VERY SLOW:
+- Multiple optional flags together
+- Large employee lists
+- Extensive post history
+
+Only enable what the user explicitly requests.`;
+
+export const backgroundWorkflowPrompt = `LINKED API BACKGROUND WORKFLOWS GUIDE
+
+IMPORTANT: Background workflows are NORMAL and OPTIMAL behavior!
+
+WHY WORKFLOWS RUN IN BACKGROUND:
+- Linked API operations are naturally slow (5+ minutes)
+- MCP client stays responsive by running workflows in background
+- This is INTENTIONAL DESIGN for better user experience
+- Your operation continues processing while you get updates
+
+WHAT TO DO WHEN WORKFLOW RUNS IN BACKGROUND:
+1. Look for workflowId and operationName in the status message
+2. Immediately call get_workflow_result(workflowId, operationName) to continue listening
+3. Repeat get_workflow_result until you get final results
+4. Do NOT re-run the original tool; the workflow is already executing
+5. Treat this as normal, successful operation (not an error)
+
+EXAMPLE BACKGROUND WORKFLOW MESSAGE:
+{
+  "message": "Workflow is running in the background. Continue listening for updates.",
+  "workflowId": "account-12345-abcde", 
+  "operationName": "searchCompanies"
+}
+
+CORRECT RESPONSE:
+"Perfect! The search is running in the background. Let me continue listening by calling get_workflow_result with the provided parameters."
+
+GENERIC MCP CALL TO CONTINUE LISTENING:
+{
+  "name": "get_workflow_result",
+  "arguments": {
+    "workflowId": "account-12345-abcde",
+    "operationName": "searchCompanies"
+  }
+}
+
+INCORRECT RESPONSE:
+"Sorry, there was an error. The search failed."
+
+REMEMBER:
+✅ Background workflows = Active processing (operation is running)
+❌ Background workflows ≠ Errors (operation is not broken)
+🔄 Always continue listening for workflow updates
+⏱️ Linked API uses background processing for optimal UX
+
+COMMON MISTAKES TO AVOID:
+- Retrying the original tool instead of calling get_workflow_result
+- Omitting operationName (it is required)
+- Treating the background message as a failure instead of an active process`;
+
+export const authenticationPrompt = `AUTHENTICATION REQUIREMENTS:
+- MCP clients must provide valid authentication tokens to use Linked API services
+- linked-api-token: Main Linked API access token from linkedapi.io
+- identification-token: Account identification token from linkedapi.io
+
+TOKEN SETUP:
+1. Visit https://linkedapi.io to get tokens
+2. Set headers with every request in MCP client configuration
+3. Keep tokens secure and never share them in logs or error messages
+
+More information: https://linkedapi.io/mcp/installation/`;
+
+export const availablePrompts = [
+  {
+    name: 'performance_guidelines',
+    description: 'Get performance optimization guidelines for Linked API MCP tools',
+  },
+  {
+    name: 'parameter_usage',
+    description: 'Learn when to use optional parameters in Linked API requests',
+  },
+  {
+    name: 'background_workflows',
+    description: 'Learn how Linked API background workflows provide optimal UX',
+  },
+  {
+    name: 'authentication_requirements',
+    description: 'Learn how to authenticate with Linked API MCP',
+  },
+];
+
+export function getPromptContent(name: string): string {
+  switch (name) {
+    case 'performance_guidelines':
+      return systemPrompt;
+    case 'parameter_usage':
+      return parameterUsageGuidelines;
+    case 'background_workflows':
+      return backgroundWorkflowPrompt;
+    case 'authentication_requirements':
+      return authenticationPrompt;
+    default:
+      throw new Error(`Unknown prompt: ${name}`);
+  }
+}