@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/mcp/adapters/linkedin.adapter.ts

@@ -0,0 +1,331 @@
+/**
+ * MCP Skill Adapter — LinkedIn
+ *
+ * Maps LinkedIn REST API v2 endpoints to MCP tool handlers.
+ * Handles profile lookup, post creation, connections, people search, and company data.
+ *
+ * LinkedIn API docs: https://learn.microsoft.com/en-us/linkedin/
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function linkedinError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      // LinkedIn returns { message, serviceErrorCode, status }
+      const msg = data.message || data.error_description || err.message;
+      const code = data.serviceErrorCode || data.status || '';
+      const codePart = code ? ` [${code}]` : '';
+      return { content: `LinkedIn API error${codePart}: ${msg}`, isError: true };
+    }
+    return { content: `LinkedIn API error: ${err.message}`, isError: true };
+  }
+  return { content: `LinkedIn API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: linkedin_get_profile ─────────────────────────
+
+const getProfile: ToolHandler = {
+  description:
+    'Get the authenticated LinkedIn user\'s profile or another user\'s profile by URN. Returns name, headline, industry, and location.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      person_urn: {
+        type: 'string',
+        description: 'LinkedIn person URN (e.g. "urn:li:person:ABC123"). Omit to get the authenticated user\'s profile.',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      let result: any;
+      if (params.person_urn) {
+        const encodedUrn = encodeURIComponent(params.person_urn);
+        result = await ctx.apiExecutor.get(`/people/${encodedUrn}`, {
+          projection: '(id,firstName,lastName,headline,industryName,locationName,profilePicture)',
+        });
+      } else {
+        result = await ctx.apiExecutor.get('/me', {
+          projection: '(id,firstName,lastName,headline,industryName,locationName,profilePicture)',
+        });
+      }
+
+      const firstName = result.firstName?.localized?.en_US || result.localizedFirstName || '';
+      const lastName = result.lastName?.localized?.en_US || result.localizedLastName || '';
+      const headline = result.headline?.localized?.en_US || result.localizedHeadline || 'N/A';
+
+      const details = [
+        `Name: ${firstName} ${lastName}`,
+        `Headline: ${headline}`,
+        `Industry: ${result.industryName || 'N/A'}`,
+        `Location: ${result.locationName || 'N/A'}`,
+        `ID: ${result.id}`,
+      ].join('\n');
+
+      return {
+        content: `LinkedIn Profile:\n${details}`,
+        metadata: { id: result.id, name: `${firstName} ${lastName}` },
+      };
+    } catch (err) {
+      return linkedinError(err);
+    }
+  },
+};
+
+// ─── Tool: linkedin_create_post ─────────────────────────
+
+const createPost: ToolHandler = {
+  description:
+    'Create a new post on LinkedIn on behalf of the authenticated user. Supports text content and visibility settings.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      text: {
+        type: 'string',
+        description: 'The text content of the LinkedIn post',
+      },
+      visibility: {
+        type: 'string',
+        enum: ['PUBLIC', 'CONNECTIONS'],
+        description: 'Post visibility: "PUBLIC" (anyone) or "CONNECTIONS" (connections only). Default: "PUBLIC".',
+      },
+      author_urn: {
+        type: 'string',
+        description: 'Author URN (e.g. "urn:li:person:ABC123"). Required — typically the authenticated user\'s URN.',
+      },
+    },
+    required: ['text', 'author_urn'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body = {
+        author: params.author_urn,
+        lifecycleState: 'PUBLISHED',
+        specificContent: {
+          'com.linkedin.ugc.ShareContent': {
+            shareCommentary: {
+              text: params.text,
+            },
+            shareMediaCategory: 'NONE',
+          },
+        },
+        visibility: {
+          'com.linkedin.ugc.MemberNetworkVisibility': params.visibility || 'PUBLIC',
+        },
+      };
+
+      const result = await ctx.apiExecutor.post('/ugcPosts', body);
+
+      const postId = result.id || result['X-RestLi-Id'] || 'unknown';
+      return {
+        content: `LinkedIn post created successfully (ID: ${postId})\nText: ${params.text.substring(0, 100)}${params.text.length > 100 ? '...' : ''}`,
+        metadata: {
+          postId,
+          author: params.author_urn,
+          visibility: params.visibility || 'PUBLIC',
+        },
+      };
+    } catch (err) {
+      return linkedinError(err);
+    }
+  },
+};
+
+// ─── Tool: linkedin_list_connections ────────────────────
+
+const listConnections: ToolHandler = {
+  description:
+    'List the authenticated LinkedIn user\'s connections. Returns names and profile information.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      start: {
+        type: 'number',
+        description: 'Pagination start index (default 0)',
+      },
+      count: {
+        type: 'number',
+        description: 'Number of connections to return (default 50, max 500)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        start: String(params.start ?? 0),
+        count: String(params.count ?? 50),
+        q: 'viewer',
+      };
+
+      const result = await ctx.apiExecutor.get('/connections', query);
+
+      const connections: any[] = result.elements || [];
+      const total = result.paging?.total ?? connections.length;
+
+      if (connections.length === 0) {
+        return { content: 'No connections found.' };
+      }
+
+      const lines = connections.map((c: any) => {
+        const firstName = c.firstName?.localized?.en_US || c.localizedFirstName || '';
+        const lastName = c.lastName?.localized?.en_US || c.localizedLastName || '';
+        const headline = c.headline?.localized?.en_US || c.localizedHeadline || '';
+        const headlinePart = headline ? ` -- ${headline}` : '';
+        return `${firstName} ${lastName}${headlinePart} (ID: ${c.id || 'N/A'})`;
+      });
+
+      return {
+        content: `${total} total connections (showing ${connections.length}):\n${lines.join('\n')}`,
+        metadata: { count: connections.length, total },
+      };
+    } catch (err) {
+      return linkedinError(err);
+    }
+  },
+};
+
+// ─── Tool: linkedin_search_people ───────────────────────
+
+const searchPeople: ToolHandler = {
+  description:
+    'Search for people on LinkedIn by keyword. Returns matching profiles with names, headlines, and locations.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      keywords: {
+        type: 'string',
+        description: 'Search keywords (e.g. "software engineer San Francisco")',
+      },
+      start: {
+        type: 'number',
+        description: 'Pagination start index (default 0)',
+      },
+      count: {
+        type: 'number',
+        description: 'Number of results to return (default 25, max 50)',
+      },
+    },
+    required: ['keywords'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        keywords: params.keywords,
+        start: String(params.start ?? 0),
+        count: String(params.count ?? 25),
+      };
+
+      const result = await ctx.apiExecutor.get('/search/people', query);
+
+      const people: any[] = result.elements || [];
+      const total = result.paging?.total ?? people.length;
+
+      if (people.length === 0) {
+        return { content: `No people found matching "${params.keywords}".` };
+      }
+
+      const lines = people.map((p: any) => {
+        const name = p.title?.text || p.name || '(unknown)';
+        const headline = p.headline?.text || p.headline || '';
+        const location = p.subline?.text || p.location || '';
+        const headlinePart = headline ? ` -- ${headline}` : '';
+        const locationPart = location ? ` (${location})` : '';
+        return `${name}${headlinePart}${locationPart}`;
+      });
+
+      return {
+        content: `Found ${total} people matching "${params.keywords}" (showing ${people.length}):\n${lines.join('\n')}`,
+        metadata: { count: people.length, total, keywords: params.keywords },
+      };
+    } catch (err) {
+      return linkedinError(err);
+    }
+  },
+};
+
+// ─── Tool: linkedin_get_company ─────────────────────────
+
+const getCompany: ToolHandler = {
+  description:
+    'Get a LinkedIn company page by its organization ID. Returns company name, description, industry, employee count, and website.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      organization_id: {
+        type: 'string',
+        description: 'LinkedIn organization ID (numeric, e.g. "1234567")',
+      },
+    },
+    required: ['organization_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const result = await ctx.apiExecutor.get(
+        `/organizations/${params.organization_id}`,
+        {
+          projection: '(id,name,localizedName,vanityName,description,localizedDescription,industries,staffCountRange,websiteUrl,logoV2,locations)',
+        },
+      );
+
+      const name = result.localizedName || result.name || '(unnamed)';
+      const description = result.localizedDescription || result.description || 'N/A';
+      const industry = Array.isArray(result.industries) ? result.industries.join(', ') : 'N/A';
+      const staffRange = result.staffCountRange
+        ? `${result.staffCountRange.start ?? '?'}-${result.staffCountRange.end ?? '?'}`
+        : 'N/A';
+
+      const details = [
+        `Company: ${name}`,
+        `Vanity Name: ${result.vanityName || 'N/A'}`,
+        `Description: ${description.substring(0, 200)}${description.length > 200 ? '...' : ''}`,
+        `Industry: ${industry}`,
+        `Employees: ${staffRange}`,
+        `Website: ${result.websiteUrl || 'N/A'}`,
+        `ID: ${result.id || params.organization_id}`,
+      ].join('\n');
+
+      return {
+        content: `LinkedIn Company:\n${details}`,
+        metadata: {
+          organizationId: params.organization_id,
+          name,
+          vanityName: result.vanityName,
+        },
+      };
+    } catch (err) {
+      return linkedinError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const linkedinAdapter: SkillAdapter = {
+  skillId: 'linkedin',
+  name: 'LinkedIn',
+  baseUrl: 'https://api.linkedin.com/v2',
+  auth: {
+    type: 'oauth2',
+    provider: 'linkedin',
+  },
+  defaultHeaders: {
+    'X-Restli-Protocol-Version': '2.0.0',
+  },
+  tools: {
+    linkedin_get_profile: getProfile,
+    linkedin_create_post: createPost,
+    linkedin_list_connections: listConnections,
+    linkedin_search_people: searchPeople,
+    linkedin_get_company: getCompany,
+  },
+  rateLimits: { requestsPerSecond: 5, burstLimit: 10 },
+};

package/src/mcp/adapters/livechat.adapter.ts

@@ -0,0 +1,259 @@
+/**
+ * MCP Skill Adapter — LiveChat
+ *
+ * Maps LiveChat API v3.5 endpoints to MCP tool handlers.
+ * Supports chat listing, event sending, agent management, and chat retrieval.
+ *
+ * LiveChat API docs: https://developers.livechat.com/docs/messaging/agent-chat-api
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function livechatError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const detail = data.error?.message || data.error?.type || err.message;
+      return { content: `LiveChat API error: ${detail}`, isError: true };
+    }
+    return { content: `LiveChat API error: ${err.message}`, isError: true };
+  }
+  return { content: `LiveChat API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: livechat_list_chats ──────────────────────────
+
+const listChats: ToolHandler = {
+  description:
+    'List active and recent chats from LiveChat. Returns chat summaries with visitor names and last messages.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Maximum number of chats to return (default 20)',
+      },
+      sort_order: {
+        type: 'string',
+        enum: ['asc', 'desc'],
+        description: 'Sort order by date (default: "desc")',
+      },
+      filters: {
+        type: 'object',
+        description: 'Optional filters object (e.g. { "agent_ids": ["agent@example.com"] })',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        limit: params.limit ?? 20,
+        sort_order: params.sort_order || 'desc',
+      };
+      if (params.filters) body.filters = params.filters;
+
+      const result = await ctx.apiExecutor.post('/agent/action/list_chats', body);
+
+      const chats: any[] = result.chats_summary || result.chats || [];
+      if (chats.length === 0) {
+        return { content: 'No chats found.' };
+      }
+
+      const lines = chats.map((chat: any) => {
+        const id = chat.id || 'unknown';
+        const visitor = chat.users?.find((u: any) => u.type === 'customer');
+        const visitorName = visitor?.name || visitor?.email || 'Unknown visitor';
+        const lastEvent = chat.last_event_per_type?.message?.text?.slice(0, 80) || 'No recent message';
+        const agentCount = chat.users?.filter((u: any) => u.type === 'agent').length || 0;
+        return `${visitorName} — ${lastEvent} — ${agentCount} agent(s) — ID: ${id}`;
+      });
+
+      return {
+        content: `Found ${chats.length} chats:\n${lines.join('\n')}`,
+        metadata: { count: chats.length },
+      };
+    } catch (err) {
+      return livechatError(err);
+    }
+  },
+};
+
+// ─── Tool: livechat_send_event ──────────────────────────
+
+const sendEvent: ToolHandler = {
+  description:
+    'Send a message event to an active LiveChat conversation. The agent must be assigned to the chat.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      chat_id: {
+        type: 'string',
+        description: 'The ID of the chat to send the message to',
+      },
+      text: {
+        type: 'string',
+        description: 'The message text to send',
+      },
+      type: {
+        type: 'string',
+        enum: ['message', 'system_message'],
+        description: 'Event type (default: "message")',
+      },
+    },
+    required: ['chat_id', 'text'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body = {
+        chat_id: params.chat_id,
+        event: {
+          type: params.type || 'message',
+          text: params.text,
+        },
+      };
+
+      const result = await ctx.apiExecutor.post('/agent/action/send_event', body);
+
+      const eventId = result.event_id || 'unknown';
+      return {
+        content: `Message sent to chat ${params.chat_id} (event ID: ${eventId})`,
+        metadata: { eventId, chatId: params.chat_id },
+      };
+    } catch (err) {
+      return livechatError(err);
+    }
+  },
+};
+
+// ─── Tool: livechat_list_agents ─────────────────────────
+
+const listAgents: ToolHandler = {
+  description:
+    'List agents in the LiveChat account. Returns agent names, emails, and current availability status.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Maximum number of agents to return (default 25)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {};
+      if (params.limit) body.limit = params.limit;
+
+      const result = await ctx.apiExecutor.post('/agent/action/list_routing_statuses', body);
+
+      const agents: any[] = result || [];
+      if (agents.length === 0) {
+        return { content: 'No agents found.' };
+      }
+
+      const lines = agents.map((agent: any) => {
+        const status = agent.status || 'unknown';
+        const id = agent.agent_id || 'unknown';
+        return `${id} — Status: ${status}`;
+      });
+
+      return {
+        content: `Found ${agents.length} agents:\n${lines.join('\n')}`,
+        metadata: { count: agents.length },
+      };
+    } catch (err) {
+      return livechatError(err);
+    }
+  },
+};
+
+// ─── Tool: livechat_get_chat ────────────────────────────
+
+const getChat: ToolHandler = {
+  description:
+    'Get full details of a specific LiveChat conversation including all messages and participants.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      chat_id: {
+        type: 'string',
+        description: 'The ID of the chat to retrieve',
+      },
+      thread_id: {
+        type: 'string',
+        description: 'Specific thread ID within the chat (optional, returns latest thread if omitted)',
+      },
+    },
+    required: ['chat_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        chat_id: params.chat_id,
+      };
+      if (params.thread_id) body.thread_id = params.thread_id;
+
+      const result = await ctx.apiExecutor.post('/agent/action/get_chat', body);
+
+      const users = result.users || [];
+      const thread = result.thread || result.threads?.[0];
+      const events: any[] = thread?.events || [];
+
+      const participantLines = users.map((u: any) => {
+        return `  ${u.name || u.email || u.id} (${u.type || 'unknown'})`;
+      });
+
+      const messageSummary = events
+        .filter((e: any) => e.type === 'message')
+        .slice(-5)
+        .map((e: any) => {
+          const author = e.author_id || 'unknown';
+          const text = (e.text || '').slice(0, 120);
+          return `  [${author}]: ${text}`;
+        });
+
+      return {
+        content: [
+          `Chat: ${params.chat_id}`,
+          `Participants:`,
+          ...participantLines,
+          `Total events: ${events.length}`,
+          `Last messages:`,
+          ...messageSummary,
+        ].join('\n'),
+        metadata: {
+          chatId: params.chat_id,
+          userCount: users.length,
+          eventCount: events.length,
+        },
+      };
+    } catch (err) {
+      return livechatError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const livechatAdapter: SkillAdapter = {
+  skillId: 'livechat',
+  name: 'LiveChat',
+  baseUrl: 'https://api.livechatinc.com/v3.5',
+  auth: {
+    type: 'token',
+    headerPrefix: 'Bearer',
+  },
+  tools: {
+    livechat_list_chats: listChats,
+    livechat_send_event: sendEvent,
+    livechat_list_agents: listAgents,
+    livechat_get_chat: getChat,
+  },
+  rateLimits: { requestsPerSecond: 10, burstLimit: 20 },
+};