@agenticmail/enterprise 0.3.2 → 0.4.0

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

@@ -0,0 +1,386 @@
+/**
+ * MCP Skill Adapter — Drift
+ *
+ * Maps Drift Conversational Marketing API endpoints to MCP tool handlers.
+ * Covers conversations, messages, and contacts for conversational marketing.
+ *
+ * Drift API docs: https://devdocs.drift.com/docs
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function driftError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const msg = data.error?.message || data.message || err.message;
+      const type = data.error?.type || '';
+      return { content: `Drift API error${type ? ` [${type}]` : ''}: ${msg}`, isError: true };
+    }
+    return { content: `Drift API error: ${err.message}`, isError: true };
+  }
+  return { content: `Drift API error: ${String(err)}`, isError: true };
+}
+
+/** Format a Drift conversation for display */
+function formatConversation(convo: any): string {
+  const id = convo.id || 'unknown';
+  const status = convo.status || 'unknown';
+  const createdAt = convo.createdAt
+    ? new Date(convo.createdAt).toISOString().slice(0, 16)
+    : '';
+  const updatedAt = convo.updatedAt
+    ? new Date(convo.updatedAt).toISOString().slice(0, 16)
+    : '';
+  const contactId = convo.contactId || 'unknown';
+  const inboxId = convo.inboxId ? `inbox: ${convo.inboxId}` : '';
+  return `#${id} -- ${status} -- contact: ${contactId}${inboxId ? ` -- ${inboxId}` : ''} -- created: ${createdAt}, updated: ${updatedAt}`;
+}
+
+/** Format a Drift contact for display */
+function formatContact(contact: any): string {
+  const attrs = contact.attributes || contact;
+  const name = attrs.name || [attrs.firstName, attrs.lastName].filter(Boolean).join(' ') || '(no name)';
+  const email = attrs.email || '(no email)';
+  const phone = attrs.phone || '';
+  const company = attrs.company || attrs.companyName || '';
+  const phonePart = phone ? ` -- ${phone}` : '';
+  const companyPart = company ? ` @ ${company}` : '';
+  return `${name} <${email}>${companyPart}${phonePart} (ID: ${contact.id})`;
+}
+
+/** Format a Drift message for display */
+function formatMessage(msg: any): string {
+  const type = msg.type || 'unknown';
+  const author = msg.author?.type === 'contact'
+    ? `contact:${msg.author.id}`
+    : msg.author?.type === 'user'
+      ? `agent:${msg.author.id}`
+      : msg.author?.type || 'bot';
+  const body = msg.body ? msg.body.substring(0, 100) + (msg.body.length > 100 ? '...' : '') : '(no body)';
+  const created = msg.createdAt
+    ? new Date(msg.createdAt).toISOString().slice(0, 16)
+    : '';
+  return `[${type}] ${author}: ${body} -- ${created} (ID: ${msg.id})`;
+}
+
+// ─── Tool: drift_list_conversations ─────────────────────
+
+const listConversations: ToolHandler = {
+  description:
+    'List conversations from Drift. Returns conversation IDs, statuses, and contact information.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      status: {
+        type: 'string',
+        enum: ['open', 'closed', 'pending', 'bulk_sent'],
+        description: 'Filter by conversation status',
+      },
+      limit: {
+        type: 'number',
+        description: 'Max conversations to return (default 25, max 50)',
+      },
+      next: {
+        type: 'string',
+        description: 'Pagination cursor from a previous response',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 25),
+      };
+      if (params.status) query.status = params.status;
+      if (params.next) query.next = params.next;
+
+      const result = await ctx.apiExecutor.get('/conversations', query);
+
+      const conversations: any[] = result.data || [];
+      if (conversations.length === 0) {
+        return { content: 'No conversations found.' };
+      }
+
+      const lines = conversations.map((c: any) => formatConversation(c));
+      const pagination = result.pagination || {};
+
+      return {
+        content: `Found ${conversations.length} conversations:\n${lines.join('\n')}${pagination.next ? '\n\n(More available)' : ''}`,
+        metadata: {
+          count: conversations.length,
+          hasMore: !!pagination.next,
+          next: pagination.next,
+        },
+      };
+    } catch (err) {
+      return driftError(err);
+    }
+  },
+};
+
+// ─── Tool: drift_send_message ───────────────────────────
+
+const sendMessage: ToolHandler = {
+  description:
+    'Send a message in a Drift conversation. Can send as a user (agent) or post a chat message.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      conversation_id: {
+        type: 'number',
+        description: 'The conversation ID to send the message in',
+      },
+      body: {
+        type: 'string',
+        description: 'Message body text',
+      },
+      type: {
+        type: 'string',
+        enum: ['chat', 'private_note'],
+        description: 'Message type: "chat" for a visible message, "private_note" for an internal note (default: "chat")',
+      },
+      user_id: {
+        type: 'number',
+        description: 'Agent user ID sending the message (required for agent replies)',
+      },
+    },
+    required: ['conversation_id', 'body'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        body: params.body,
+        type: params.type || 'chat',
+      };
+      if (params.user_id) body.userId = params.user_id;
+
+      const result = await ctx.apiExecutor.post(
+        `/conversations/${params.conversation_id}/messages`,
+        body,
+      );
+
+      const msg = result.data || result;
+      const msgType = params.type || 'chat';
+      return {
+        content: `${msgType === 'private_note' ? 'Private note' : 'Message'} sent in conversation #${params.conversation_id} (message ID: ${msg.id || 'sent'})`,
+        metadata: {
+          conversationId: params.conversation_id,
+          messageId: msg.id,
+          type: msgType,
+        },
+      };
+    } catch (err) {
+      return driftError(err);
+    }
+  },
+};
+
+// ─── Tool: drift_list_contacts ──────────────────────────
+
+const listContacts: ToolHandler = {
+  description:
+    'List contacts from Drift. Returns contact names, emails, and companies.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      email: {
+        type: 'string',
+        description: 'Filter by email address',
+      },
+      limit: {
+        type: 'number',
+        description: 'Max contacts to return (default 25)',
+      },
+      cursor: {
+        type: 'string',
+        description: 'Pagination cursor from a previous response',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      // If filtering by email, use the lookup endpoint
+      if (params.email) {
+        const result = await ctx.apiExecutor.get('/contacts', { email: params.email });
+
+        const contacts: any[] = result.data || [];
+        if (contacts.length === 0) {
+          return { content: `No contacts found with email "${params.email}".` };
+        }
+
+        const lines = contacts.map((c: any) => formatContact(c));
+        return {
+          content: `Found ${contacts.length} contacts:\n${lines.join('\n')}`,
+          metadata: { count: contacts.length },
+        };
+      }
+
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 25),
+      };
+      if (params.cursor) query.cursor = params.cursor;
+
+      const result = await ctx.apiExecutor.get('/contacts', query);
+
+      const contacts: any[] = result.data || [];
+      if (contacts.length === 0) {
+        return { content: 'No contacts found.' };
+      }
+
+      const lines = contacts.map((c: any) => formatContact(c));
+      const pagination = result.pagination || {};
+
+      return {
+        content: `Found ${contacts.length} contacts:\n${lines.join('\n')}${pagination.next ? '\n\n(More available)' : ''}`,
+        metadata: { count: contacts.length, hasMore: !!pagination.next },
+      };
+    } catch (err) {
+      return driftError(err);
+    }
+  },
+};
+
+// ─── Tool: drift_get_conversation ───────────────────────
+
+const getConversation: ToolHandler = {
+  description:
+    'Get detailed information about a specific Drift conversation, including its messages.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      conversation_id: {
+        type: 'number',
+        description: 'The conversation ID to retrieve',
+      },
+    },
+    required: ['conversation_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const result = await ctx.apiExecutor.get(`/conversations/${params.conversation_id}`);
+
+      const convo = result.data;
+      if (!convo) {
+        return { content: `Conversation ${params.conversation_id} not found.` };
+      }
+
+      const details: string[] = [];
+      details.push(`Conversation #${convo.id}`);
+      details.push(`Status: ${convo.status || 'unknown'}`);
+      details.push(`Contact: ${convo.contactId || 'unknown'}`);
+      if (convo.inboxId) details.push(`Inbox: ${convo.inboxId}`);
+      if (convo.createdAt) details.push(`Created: ${new Date(convo.createdAt).toISOString().slice(0, 16)}`);
+      if (convo.updatedAt) details.push(`Updated: ${new Date(convo.updatedAt).toISOString().slice(0, 16)}`);
+
+      // Fetch messages
+      const msgsResult = await ctx.apiExecutor.get(`/conversations/${params.conversation_id}/messages`);
+
+      const messages: any[] = msgsResult.data?.messages || msgsResult.data || [];
+      if (messages.length > 0) {
+        const msgLines = messages.slice(0, 20).map((m: any) => formatMessage(m));
+        details.push(`\nMessages (${messages.length} total, showing up to 20):\n${msgLines.join('\n')}`);
+      }
+
+      return {
+        content: details.join('\n'),
+        metadata: {
+          conversationId: convo.id,
+          status: convo.status,
+          messageCount: messages.length,
+        },
+      };
+    } catch (err) {
+      return driftError(err);
+    }
+  },
+};
+
+// ─── Tool: drift_create_contact ─────────────────────────
+
+const createContact: ToolHandler = {
+  description:
+    'Create a new contact in Drift. Provide at least an email address.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      email: {
+        type: 'string',
+        description: 'Contact email address',
+      },
+      name: {
+        type: 'string',
+        description: 'Contact full name',
+      },
+      phone: {
+        type: 'string',
+        description: 'Phone number',
+      },
+      company: {
+        type: 'string',
+        description: 'Company name',
+      },
+      custom_attributes: {
+        type: 'object',
+        description: 'Custom attributes as key-value pairs',
+      },
+    },
+    required: ['email'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const attributes: Record<string, any> = {
+        email: params.email,
+      };
+      if (params.name) attributes.name = params.name;
+      if (params.phone) attributes.phone = params.phone;
+      if (params.company) attributes.company = params.company;
+      if (params.custom_attributes) {
+        Object.assign(attributes, params.custom_attributes);
+      }
+
+      const result = await ctx.apiExecutor.post('/contacts', { attributes });
+
+      const contact = result.data || result;
+      return {
+        content: `Contact created: ${formatContact(contact)}`,
+        metadata: {
+          contactId: contact.id,
+          email: params.email,
+        },
+      };
+    } catch (err) {
+      return driftError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const driftAdapter: SkillAdapter = {
+  skillId: 'drift',
+  name: 'Drift Conversational Marketing',
+  baseUrl: 'https://driftapi.com',
+  auth: {
+    type: 'oauth2',
+    provider: 'drift',
+  },
+  tools: {
+    drift_list_conversations: listConversations,
+    drift_send_message: sendMessage,
+    drift_list_contacts: listContacts,
+    drift_get_conversation: getConversation,
+    drift_create_contact: createContact,
+  },
+  rateLimits: {
+    requestsPerSecond: 10,
+    burstLimit: 20,
+  },
+};

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

@@ -0,0 +1,315 @@
+/**
+ * MCP Skill Adapter — Dropbox
+ *
+ * Maps Dropbox API v2 endpoints to MCP tool handlers.
+ * Dropbox uses POST for all endpoints, including listing and search.
+ *
+ * Dropbox API docs: https://www.dropbox.com/developers/documentation/http/documentation
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function dropboxError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      // Dropbox errors use error_summary and error fields
+      if (data.error_summary) {
+        return { content: `Dropbox API error: ${data.error_summary}`, isError: true };
+      }
+      if (data.error && typeof data.error === 'object' && data.error['.tag']) {
+        return { content: `Dropbox API error: ${data.error['.tag']}`, isError: true };
+      }
+    }
+    return { content: `Dropbox API error: ${err.message}`, isError: true };
+  }
+  return { content: `Dropbox API error: ${String(err)}`, isError: true };
+}
+
+/**
+ * Format a file/folder entry from Dropbox metadata.
+ */
+function formatEntry(entry: any): string {
+  const tag = entry['.tag'] || 'unknown';
+  const name = entry.name || 'Untitled';
+  const path = entry.path_display || entry.path_lower || '';
+
+  if (tag === 'file') {
+    const size = entry.size != null ? ` (${formatSize(entry.size)})` : '';
+    const modified = entry.client_modified
+      ? ` modified ${entry.client_modified.slice(0, 16)}`
+      : '';
+    return `[file] ${name}${size}${modified} -- ${path}`;
+  }
+
+  return `[${tag}] ${name} -- ${path}`;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+// ─── Tool: dropbox_list_folder ──────────────────────────
+
+const listFolder: ToolHandler = {
+  description:
+    'List files and folders in a Dropbox directory. Provide the folder path (use "" for root).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Folder path (e.g. "/Documents", "/Photos/2024" or "" for root)',
+      },
+      recursive: {
+        type: 'boolean',
+        description: 'If true, list all contents recursively (default false)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of entries to return (default 100)',
+      },
+    },
+    required: ['path'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        path: params.path,
+        recursive: params.recursive ?? false,
+        limit: params.limit ?? 100,
+        include_media_info: false,
+        include_mounted_folders: true,
+      };
+
+      const result = await ctx.apiExecutor.post('/files/list_folder', body);
+      const entries: any[] = result.entries || [];
+      const hasMore = result.has_more ?? false;
+
+      if (entries.length === 0) {
+        return { content: `Folder "${params.path || '/'}" is empty.` };
+      }
+
+      const lines = entries.map(formatEntry);
+      const moreNote = hasMore ? '\n(more entries available -- use cursor for pagination)' : '';
+
+      return {
+        content: `Found ${entries.length} entries in "${params.path || '/'}":\n${lines.join('\n')}${moreNote}`,
+        metadata: {
+          count: entries.length,
+          has_more: hasMore,
+          cursor: result.cursor,
+          path: params.path,
+        },
+      };
+    } catch (err) {
+      return dropboxError(err);
+    }
+  },
+};
+
+// ─── Tool: dropbox_search ───────────────────────────────
+
+const searchFiles: ToolHandler = {
+  description:
+    'Search for files and folders in Dropbox by name or content. Returns matching entries with paths and metadata.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search query string',
+      },
+      path: {
+        type: 'string',
+        description: 'Restrict search to this folder path (optional)',
+      },
+      max_results: {
+        type: 'number',
+        description: 'Maximum number of results (default 25, max 100)',
+      },
+      file_extensions: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Filter by file extensions (e.g. ["pdf", "docx"])',
+      },
+    },
+    required: ['query'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        query: params.query,
+        options: {
+          max_results: params.max_results ?? 25,
+          file_status: { '.tag': 'active' },
+        },
+      };
+
+      if (params.path) {
+        body.options.path = params.path;
+      }
+      if (params.file_extensions?.length) {
+        body.options.file_extensions = params.file_extensions;
+      }
+
+      const result = await ctx.apiExecutor.post('/files/search_v2', body);
+      const matches: any[] = result.matches || [];
+      const hasMore = result.has_more ?? false;
+
+      if (matches.length === 0) {
+        return { content: `No results found for: "${params.query}"` };
+      }
+
+      const lines = matches.map((m: any) => {
+        const metadata = m.metadata?.metadata || m.metadata || {};
+        return formatEntry(metadata);
+      });
+
+      const moreNote = hasMore ? '\n(more results available)' : '';
+
+      return {
+        content: `Found ${matches.length} results for "${params.query}":\n${lines.join('\n')}${moreNote}`,
+        metadata: {
+          count: matches.length,
+          has_more: hasMore,
+          query: params.query,
+        },
+      };
+    } catch (err) {
+      return dropboxError(err);
+    }
+  },
+};
+
+// ─── Tool: dropbox_create_folder ────────────────────────
+
+const createFolder: ToolHandler = {
+  description:
+    'Create a new folder in Dropbox. Provide the full path for the new folder.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Full path for the new folder (e.g. "/Projects/New Project")',
+      },
+      autorename: {
+        type: 'boolean',
+        description: 'If true, automatically rename if a folder with the same name exists (default false)',
+      },
+    },
+    required: ['path'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        path: params.path,
+        autorename: params.autorename ?? false,
+      };
+
+      const result = await ctx.apiExecutor.post('/files/create_folder_v2', body);
+      const metadata = result.metadata || {};
+
+      return {
+        content: `Folder created: "${metadata.name}" at ${metadata.path_display || params.path}`,
+        metadata: {
+          id: metadata.id,
+          name: metadata.name,
+          path_display: metadata.path_display,
+        },
+      };
+    } catch (err) {
+      return dropboxError(err);
+    }
+  },
+};
+
+// ─── Tool: dropbox_upload_file ──────────────────────────
+
+const dropboxUploadFile: ToolHandler = {
+  description: 'Upload a text file to Dropbox. Specify the destination path and file content.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Destination path including filename (e.g. "/Documents/report.txt")',
+      },
+      content: {
+        type: 'string',
+        description: 'Text content of the file',
+      },
+      mode: {
+        type: 'string',
+        enum: ['add', 'overwrite'],
+        description: 'Write mode: "add" (default, fail if exists) or "overwrite"',
+      },
+    },
+    required: ['path', 'content'],
+    additionalProperties: false,
+  },
+
+  async execute(params, ctx): Promise<ToolResult> {
+    try {
+      const apiArg = JSON.stringify({
+        path: params.path,
+        mode: params.mode || 'add',
+        autorename: true,
+        mute: false,
+      });
+
+      const result = await ctx.apiExecutor.request({
+        method: 'POST',
+        url: 'https://content.dropboxapi.com/2/files/upload',
+        headers: {
+          'Dropbox-API-Arg': apiArg,
+        },
+        rawBody: new TextEncoder().encode(params.content),
+        rawContentType: 'application/octet-stream',
+      });
+
+      const name = result.name || params.path;
+      const size = result.size || 0;
+      const displayPath = result.path_display || params.path;
+
+      return {
+        content: `Uploaded: ${name} (${formatSize(size)}) at ${displayPath}`,
+        metadata: { id: result.id, path: displayPath, size },
+      };
+    } catch (err) {
+      return dropboxError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const dropboxAdapter: SkillAdapter = {
+  skillId: 'dropbox-storage',
+  name: 'Dropbox',
+  baseUrl: 'https://api.dropboxapi.com/2',
+  auth: {
+    type: 'oauth2',
+    provider: 'dropbox',
+    headerPrefix: 'Bearer',
+  },
+  defaultHeaders: {
+    'Content-Type': 'application/json',
+  },
+  tools: {
+    dropbox_list_folder: listFolder,
+    dropbox_search: searchFiles,
+    dropbox_create_folder: createFolder,
+    dropbox_upload_file: dropboxUploadFile,
+  },
+  rateLimits: { requestsPerSecond: 10, burstLimit: 25 },
+};