@agenticmail/enterprise 0.3.2 → 0.4.0

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

@@ -0,0 +1,354 @@
+/**
+ * MCP Skill Adapter — Workday
+ *
+ * Maps Workday REST API endpoints to MCP tool handlers.
+ * Covers worker management, organization lookup, and time-off balances.
+ *
+ * The tenant name is read from ctx.skillConfig.tenant
+ * and used to build the dynamic base URL.
+ *
+ * Workday API docs: https://community.workday.com/sites/default/files/file-hosting/restapi/
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+/** Resolve the Workday base URL from skill config */
+function wdUrl(ctx: ToolExecutionContext): string {
+  const tenant = ctx.skillConfig.tenant;
+  if (!tenant) {
+    throw new Error('Workday tenant is required in skillConfig (e.g. { tenant: "mycompany" })');
+  }
+  return `https://${tenant}.workday.com/api/v1`;
+}
+
+function workdayError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const msg = data.error_description || data.error || data.message || err.message;
+      return { content: `Workday API error: ${msg}`, isError: true };
+    }
+    return { content: `Workday API error: ${err.message}`, isError: true };
+  }
+  return { content: `Workday API error: ${String(err)}`, isError: true };
+}
+
+/** Format a Workday worker for display */
+function formatWorker(worker: any): string {
+  const descriptor = worker.descriptor || '(no name)';
+  const id = worker.id || worker.workerId || 'N/A';
+  const email = worker.primaryWorkEmail || worker.email || '';
+  const emailPart = email ? ` <${email}>` : '';
+  const position = worker.primaryPosition?.descriptor || worker.jobTitle || '';
+  const posPart = position ? ` -- ${position}` : '';
+  return `${descriptor}${emailPart}${posPart} (ID: ${id})`;
+}
+
+// ─── Tool: workday_list_workers ─────────────────────────
+
+const listWorkers: ToolHandler = {
+  description:
+    'List workers from Workday. Returns a paginated list of all workers in the organization.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Maximum number of workers to return (default 20, max 100)',
+      },
+      offset: {
+        type: 'number',
+        description: 'Offset for pagination (default 0)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wdUrl(ctx);
+
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 20),
+        offset: String(params.offset ?? 0),
+      };
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/workers`,
+        query,
+      });
+
+      const workers: any[] = result.data || [];
+      const total = result.total ?? workers.length;
+
+      if (workers.length === 0) {
+        return { content: 'No workers found.' };
+      }
+
+      const lines = workers.map((w: any) => formatWorker(w));
+
+      return {
+        content: `Found ${total} workers (showing ${workers.length}):\n${lines.join('\n')}`,
+        metadata: { count: workers.length, total },
+      };
+    } catch (err) {
+      return workdayError(err);
+    }
+  },
+};
+
+// ─── Tool: workday_get_worker ───────────────────────────
+
+const getWorker: ToolHandler = {
+  description:
+    'Get detailed information about a specific Workday worker by their ID. Returns name, position, department, manager, and contact info.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      worker_id: {
+        type: 'string',
+        description: 'The Workday worker ID',
+      },
+    },
+    required: ['worker_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wdUrl(ctx);
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/workers/${params.worker_id}`,
+      });
+
+      const details = [
+        `Name: ${result.descriptor || 'N/A'}`,
+        `Worker ID: ${result.id || params.worker_id}`,
+        `Email: ${result.primaryWorkEmail || 'N/A'}`,
+        `Position: ${result.primaryPosition?.descriptor || 'N/A'}`,
+        `Department: ${result.primaryPosition?.businessUnit?.descriptor || 'N/A'}`,
+        `Manager: ${result.manager?.descriptor || 'N/A'}`,
+        `Location: ${result.primaryWorkLocation?.descriptor || 'N/A'}`,
+        `Hire Date: ${result.hireDate || 'N/A'}`,
+        `Status: ${result.workerStatus?.descriptor || 'N/A'}`,
+      ].join('\n');
+
+      return {
+        content: `Worker Details:\n${details}`,
+        metadata: {
+          workerId: params.worker_id,
+          name: result.descriptor,
+          email: result.primaryWorkEmail,
+        },
+      };
+    } catch (err) {
+      return workdayError(err);
+    }
+  },
+};
+
+// ─── Tool: workday_search_workers ───────────────────────
+
+const searchWorkers: ToolHandler = {
+  description:
+    'Search for workers in Workday by name, email, or other criteria. Returns matching worker records.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search query string (searches name, email, worker ID)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results (default 20, max 100)',
+      },
+    },
+    required: ['query'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wdUrl(ctx);
+
+      const result = await ctx.apiExecutor.request({
+        method: 'POST',
+        url: `${baseUrl}/workers/search`,
+        body: {
+          query: params.query,
+          limit: params.limit ?? 20,
+        },
+      });
+
+      const workers: any[] = result.data || [];
+      const total = result.total ?? workers.length;
+
+      if (workers.length === 0) {
+        return { content: `No workers found matching "${params.query}".` };
+      }
+
+      const lines = workers.map((w: any) => formatWorker(w));
+
+      return {
+        content: `Found ${total} workers matching "${params.query}" (showing ${workers.length}):\n${lines.join('\n')}`,
+        metadata: { count: workers.length, total, query: params.query },
+      };
+    } catch (err) {
+      return workdayError(err);
+    }
+  },
+};
+
+// ─── Tool: workday_list_organizations ───────────────────
+
+const listOrganizations: ToolHandler = {
+  description:
+    'List organizations (departments, cost centers, divisions) in Workday. Useful for understanding the org structure.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      type: {
+        type: 'string',
+        enum: ['department', 'cost_center', 'division', 'company'],
+        description: 'Organization type to filter by (optional)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results (default 50)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wdUrl(ctx);
+
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 50),
+      };
+      if (params.type) query.type = params.type;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/organizations`,
+        query,
+      });
+
+      const orgs: any[] = result.data || [];
+      if (orgs.length === 0) {
+        return { content: 'No organizations found.' };
+      }
+
+      const lines = orgs.map((org: any) => {
+        const name = org.descriptor || org.name || '(unnamed)';
+        const type = org.organizationType?.descriptor || org.type || 'N/A';
+        const head = org.leader?.descriptor ? ` -- Head: ${org.leader.descriptor}` : '';
+        return `${name} (${type})${head} (ID: ${org.id})`;
+      });
+
+      return {
+        content: `Found ${orgs.length} organizations:\n${lines.join('\n')}`,
+        metadata: { count: orgs.length },
+      };
+    } catch (err) {
+      return workdayError(err);
+    }
+  },
+};
+
+// ─── Tool: workday_get_time_off_balance ─────────────────
+
+const getTimeOffBalance: ToolHandler = {
+  description:
+    'Get time-off balance information for a specific Workday worker. Shows available balances across different time-off plans.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      worker_id: {
+        type: 'string',
+        description: 'The Workday worker ID',
+      },
+      as_of_date: {
+        type: 'string',
+        description: 'Balance as of this date in YYYY-MM-DD format (default: today)',
+      },
+    },
+    required: ['worker_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wdUrl(ctx);
+
+      const query: Record<string, string> = {};
+      if (params.as_of_date) query.asOfDate = params.as_of_date;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/workers/${params.worker_id}/timeOff/balances`,
+        query,
+      });
+
+      const balances: any[] = result.data || [];
+      if (balances.length === 0) {
+        return {
+          content: `No time-off balances found for worker #${params.worker_id}.`,
+          metadata: { workerId: params.worker_id },
+        };
+      }
+
+      const lines = balances.map((b: any) => {
+        const planName = b.timeOffPlan?.descriptor || b.name || 'Unknown Plan';
+        const balance = b.balance ?? 'N/A';
+        const unit = b.unit?.descriptor || 'days';
+        return `${planName}: ${balance} ${unit}`;
+      });
+
+      return {
+        content: `Time-off balances for worker #${params.worker_id}:\n${lines.join('\n')}`,
+        metadata: {
+          workerId: params.worker_id,
+          planCount: balances.length,
+        },
+      };
+    } catch (err) {
+      return workdayError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const workdayAdapter: SkillAdapter = {
+  skillId: 'workday',
+  name: 'Workday',
+  // Base URL is dynamic based on tenant; tools use ctx.apiExecutor.request() with full URLs
+  baseUrl: 'https://TENANT.workday.com/api/v1',
+  auth: {
+    type: 'oauth2',
+    provider: 'workday',
+  },
+  tools: {
+    workday_list_workers: listWorkers,
+    workday_get_worker: getWorker,
+    workday_search_workers: searchWorkers,
+    workday_list_organizations: listOrganizations,
+    workday_get_time_off_balance: getTimeOffBalance,
+  },
+  configSchema: {
+    tenant: {
+      type: 'string' as const,
+      label: 'Workday Tenant',
+      description: 'Your Workday tenant name (e.g. "mycompany" for mycompany.workday.com)',
+      required: true,
+      placeholder: 'mycompany',
+    },
+  },
+  rateLimits: {
+    requestsPerSecond: 5,
+    burstLimit: 10,
+  },
+};

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

@@ -0,0 +1,349 @@
+/**
+ * MCP Skill Adapter — Wrike
+ *
+ * Maps Wrike API v4 endpoints to MCP tool handlers.
+ * Covers task listing, creation, updating, and folder/project browsing.
+ *
+ * Wrike API docs: https://developers.wrike.com/api/v4
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function wrikeError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const detail = data.errorDescription || data.error || err.message;
+      return { content: `Wrike API error: ${detail}`, isError: true };
+    }
+    return { content: `Wrike API error: ${err.message}`, isError: true };
+  }
+  return { content: `Wrike API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: wrike_list_tasks ─────────────────────────────
+
+const listTasks: ToolHandler = {
+  description:
+    'List tasks in Wrike. Optionally filter by folder, status, or custom fields.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      folderId: {
+        type: 'string',
+        description: 'Folder or project ID to list tasks from (optional — omit for all tasks)',
+      },
+      status: {
+        type: 'string',
+        enum: ['Active', 'Completed', 'Deferred', 'Cancelled'],
+        description: 'Filter by task status (optional)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of tasks to return (default 100)',
+      },
+      sortField: {
+        type: 'string',
+        enum: ['CreatedDate', 'UpdatedDate', 'CompletedDate', 'DueDate', 'Status'],
+        description: 'Field to sort by (optional)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        pageSize: String(params.limit ?? 100),
+      };
+      if (params.status) query.status = params.status;
+      if (params.sortField) query.sortField = params.sortField;
+
+      const path = params.folderId
+        ? `/folders/${params.folderId}/tasks`
+        : '/tasks';
+
+      const result = await ctx.apiExecutor.get(path, query);
+
+      const tasks: any[] = result.data || [];
+      if (tasks.length === 0) {
+        return { content: 'No tasks found.' };
+      }
+
+      const lines = tasks.map((t: any) => {
+        const assignees = (t.responsibleIds || []).length;
+        const status = t.status || 'unknown';
+        const due = t.dates?.due || 'no due date';
+        return `${t.id}: ${t.title} [${status}] — ${assignees} assignee(s) — due: ${due}`;
+      });
+
+      return {
+        content: `Found ${tasks.length} tasks:\n${lines.join('\n')}`,
+        metadata: { count: tasks.length },
+      };
+    } catch (err) {
+      return wrikeError(err);
+    }
+  },
+};
+
+// ─── Tool: wrike_create_task ────────────────────────────
+
+const createTask: ToolHandler = {
+  description:
+    'Create a new task in a Wrike folder or project. Specify title, description, assignees, and dates.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      folderId: {
+        type: 'string',
+        description: 'Folder or project ID to create the task in',
+      },
+      title: {
+        type: 'string',
+        description: 'Task title',
+      },
+      description: {
+        type: 'string',
+        description: 'Task description (optional)',
+      },
+      status: {
+        type: 'string',
+        enum: ['Active', 'Completed', 'Deferred', 'Cancelled'],
+        description: 'Initial task status (default "Active")',
+      },
+      responsibles: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Array of user IDs to assign (optional)',
+      },
+      dates: {
+        type: 'object',
+        properties: {
+          start: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+          due: { type: 'string', description: 'Due date (YYYY-MM-DD)' },
+        },
+        description: 'Task dates (optional)',
+      },
+      priority: {
+        type: 'string',
+        enum: ['High', 'Normal', 'Low'],
+        description: 'Task priority (optional)',
+      },
+    },
+    required: ['folderId', 'title'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = { title: params.title };
+      if (params.description) body.description = params.description;
+      if (params.status) body.status = params.status;
+      if (params.responsibles?.length) body.responsibles = params.responsibles;
+      if (params.dates) body.dates = params.dates;
+      if (params.priority) body.priority = params.priority;
+
+      const result = await ctx.apiExecutor.post(`/folders/${params.folderId}/tasks`, body);
+
+      const task = result.data?.[0] || result;
+
+      return {
+        content: `Task created: ${task.title} (ID: ${task.id})\nPermalink: ${task.permalink || 'N/A'}`,
+        metadata: { id: task.id, title: task.title, permalink: task.permalink },
+      };
+    } catch (err) {
+      return wrikeError(err);
+    }
+  },
+};
+
+// ─── Tool: wrike_list_folders ───────────────────────────
+
+const listFolders: ToolHandler = {
+  description:
+    'List folders and projects in Wrike. Optionally filter within a specific parent folder.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      folderId: {
+        type: 'string',
+        description: 'Parent folder ID to list children of (optional — omit for root folders)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const path = params.folderId
+        ? `/folders/${params.folderId}/folders`
+        : '/folders';
+
+      const result = await ctx.apiExecutor.get(path);
+
+      const folders: any[] = result.data || [];
+      if (folders.length === 0) {
+        return { content: 'No folders found.' };
+      }
+
+      const lines = folders.map((f: any) => {
+        const scope = f.scope || '';
+        const childCount = f.childIds?.length ?? 0;
+        return `${f.id}: ${f.title}${scope ? ` [${scope}]` : ''} — ${childCount} children`;
+      });
+
+      return {
+        content: `Found ${folders.length} folders:\n${lines.join('\n')}`,
+        metadata: { count: folders.length },
+      };
+    } catch (err) {
+      return wrikeError(err);
+    }
+  },
+};
+
+// ─── Tool: wrike_list_projects ──────────────────────────
+
+const listProjects: ToolHandler = {
+  description:
+    'List all projects in Wrike. Returns project names, statuses, and owner info.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      spaceId: {
+        type: 'string',
+        description: 'Space ID to filter projects (optional)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const path = params.spaceId
+        ? `/spaces/${params.spaceId}/folders`
+        : '/folders';
+
+      const query: Record<string, string> = { project: 'true' };
+
+      const result = await ctx.apiExecutor.get(path, query);
+
+      const projects: any[] = (result.data || []).filter((f: any) => f.project);
+      if (projects.length === 0) {
+        return { content: 'No projects found.' };
+      }
+
+      const lines = projects.map((p: any) => {
+        const status = p.project?.status || 'unknown';
+        const owner = p.project?.ownerIds?.length ? `${p.project.ownerIds.length} owner(s)` : 'no owner';
+        return `${p.id}: ${p.title} [${status}] — ${owner}`;
+      });
+
+      return {
+        content: `Found ${projects.length} projects:\n${lines.join('\n')}`,
+        metadata: { count: projects.length },
+      };
+    } catch (err) {
+      return wrikeError(err);
+    }
+  },
+};
+
+// ─── Tool: wrike_update_task ────────────────────────────
+
+const updateTask: ToolHandler = {
+  description:
+    'Update an existing Wrike task. Change title, description, status, assignees, or dates.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      taskId: {
+        type: 'string',
+        description: 'The Wrike task ID to update',
+      },
+      title: {
+        type: 'string',
+        description: 'New task title',
+      },
+      description: {
+        type: 'string',
+        description: 'New task description',
+      },
+      status: {
+        type: 'string',
+        enum: ['Active', 'Completed', 'Deferred', 'Cancelled'],
+        description: 'New task status',
+      },
+      addResponsibles: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'User IDs to add as assignees',
+      },
+      removeResponsibles: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'User IDs to remove from assignees',
+      },
+      dates: {
+        type: 'object',
+        properties: {
+          start: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+          due: { type: 'string', description: 'Due date (YYYY-MM-DD)' },
+        },
+        description: 'Updated task dates',
+      },
+      priority: {
+        type: 'string',
+        enum: ['High', 'Normal', 'Low'],
+        description: 'New task priority',
+      },
+    },
+    required: ['taskId'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {};
+      if (params.title !== undefined) body.title = params.title;
+      if (params.description !== undefined) body.description = params.description;
+      if (params.status !== undefined) body.status = params.status;
+      if (params.addResponsibles?.length) body.addResponsibles = params.addResponsibles;
+      if (params.removeResponsibles?.length) body.removeResponsibles = params.removeResponsibles;
+      if (params.dates) body.dates = params.dates;
+      if (params.priority !== undefined) body.priority = params.priority;
+
+      const result = await ctx.apiExecutor.put(`/tasks/${params.taskId}`, body);
+
+      const task = result.data?.[0] || result;
+
+      return {
+        content: `Task ${task.id} updated: ${task.title} [${task.status || 'unknown'}]`,
+        metadata: { id: task.id, title: task.title, status: task.status },
+      };
+    } catch (err) {
+      return wrikeError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const wrikeAdapter: SkillAdapter = {
+  skillId: 'wrike',
+  name: 'Wrike',
+  baseUrl: 'https://www.wrike.com/api/v4',
+  auth: {
+    type: 'oauth2',
+    provider: 'wrike',
+  },
+  tools: {
+    wrike_list_tasks: listTasks,
+    wrike_create_task: createTask,
+    wrike_list_folders: listFolders,
+    wrike_list_projects: listProjects,
+    wrike_update_task: updateTask,
+  },
+  rateLimits: {
+    requestsPerSecond: 10,
+    burstLimit: 20,
+  },
+};