@agenticmail/enterprise 0.3.2 → 0.4.0

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

@@ -0,0 +1,358 @@
+/**
+ * MCP Skill Adapter — ADP Workforce
+ *
+ * Maps ADP API endpoints to MCP tool handlers.
+ * Covers workers, payroll, organizational units, and benefits.
+ *
+ * ADP API docs: https://developers.adp.com/articles/api
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function adpError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      // ADP returns { confirmMessage: { ... }, error: { ... } }
+      const errorObj = data.error || data;
+      const msg = errorObj.message || errorObj.userMessage || err.message;
+      const code = errorObj.code ? ` [${errorObj.code}]` : '';
+      return { content: `ADP API error${code}: ${msg}`, isError: true };
+    }
+    return { content: `ADP API error: ${err.message}`, isError: true };
+  }
+  return { content: `ADP API error: ${String(err)}`, isError: true };
+}
+
+/** Format an ADP worker for display */
+function formatWorker(worker: any): string {
+  const person = worker.person || {};
+  const name = person.legalName
+    ? [person.legalName.givenName, person.legalName.familyName1].filter(Boolean).join(' ')
+    : '(no name)';
+  const email = person.communication?.emails?.[0]?.emailUri || '(no email)';
+  const assignment = worker.workerDates ? '' : '';
+  const status = worker.workerStatus?.statusCode?.codeValue || 'N/A';
+  const id = worker.workerID?.idValue || worker.associateOID || 'N/A';
+  return `${name} <${email}> -- Status: ${status} (ID: ${id})`;
+}
+
+// ─── Tool: adp_list_workers ─────────────────────────────
+
+const listWorkers: ToolHandler = {
+  description:
+    'List workers from ADP Workforce. Returns a paginated list of all workers with basic information.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      top: {
+        type: 'number',
+        description: 'Maximum number of workers to return (default 25, max 100)',
+      },
+      skip: {
+        type: 'number',
+        description: 'Number of records to skip for pagination (default 0)',
+      },
+      filter: {
+        type: 'string',
+        description: 'OData filter expression (e.g. "workers/workerStatus/statusCode/codeValue eq \'Active\'")',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        '$top': String(params.top ?? 25),
+        '$skip': String(params.skip ?? 0),
+      };
+      if (params.filter) query['$filter'] = params.filter;
+
+      const result = await ctx.apiExecutor.get('/hr/v2/workers', query);
+
+      const workers: any[] = result.workers || [];
+      if (workers.length === 0) {
+        return { content: 'No workers found.' };
+      }
+
+      const lines = workers.map((w: any) => formatWorker(w));
+
+      return {
+        content: `Found ${workers.length} workers:\n${lines.join('\n')}`,
+        metadata: { count: workers.length },
+      };
+    } catch (err) {
+      return adpError(err);
+    }
+  },
+};
+
+// ─── Tool: adp_get_worker ───────────────────────────────
+
+const getWorker: ToolHandler = {
+  description:
+    'Get detailed information about a specific ADP worker by their associate OID.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      associate_oid: {
+        type: 'string',
+        description: 'The ADP associate OID (unique worker identifier)',
+      },
+    },
+    required: ['associate_oid'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const result = await ctx.apiExecutor.get(`/hr/v2/workers/${params.associate_oid}`);
+
+      const worker = result.workers?.[0] || result;
+      const person = worker.person || {};
+      const legalName = person.legalName || {};
+      const name = [legalName.givenName, legalName.familyName1].filter(Boolean).join(' ') || '(no name)';
+      const email = person.communication?.emails?.[0]?.emailUri || 'N/A';
+      const phone = person.communication?.phones?.[0]?.dialNumber || 'N/A';
+
+      const assignment = worker.workerAssignments?.[0] || {};
+      const details = [
+        `Name: ${name}`,
+        `Email: ${email}`,
+        `Phone: ${phone}`,
+        `Job Title: ${assignment.jobTitle || 'N/A'}`,
+        `Department: ${assignment.homeOrganizationalUnit?.nameLong || 'N/A'}`,
+        `Location: ${assignment.homeWorkLocation?.nameCode?.longName || 'N/A'}`,
+        `Manager: ${assignment.reportsTo?.[0]?.reportsToWorkerName?.formattedName || 'N/A'}`,
+        `Hire Date: ${worker.workerDates?.originalHireDate || 'N/A'}`,
+        `Status: ${worker.workerStatus?.statusCode?.codeValue || 'N/A'}`,
+        `Worker Type: ${assignment.workerTypeCode?.longName || 'N/A'}`,
+      ].join('\n');
+
+      return {
+        content: `Worker Details:\n${details}`,
+        metadata: {
+          associateOid: params.associate_oid,
+          name,
+          email,
+        },
+      };
+    } catch (err) {
+      return adpError(err);
+    }
+  },
+};
+
+// ─── Tool: adp_get_payroll ──────────────────────────────
+
+const getPayroll: ToolHandler = {
+  description:
+    'Get payroll information from ADP. Returns pay statements for a specific worker or a summary of recent payroll runs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      associate_oid: {
+        type: 'string',
+        description: 'The ADP associate OID to get pay statements for',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Filter pay statements starting after this date (YYYY-MM-DD)',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Filter pay statements ending before this date (YYYY-MM-DD)',
+      },
+      top: {
+        type: 'number',
+        description: 'Maximum number of statements to return (default 10)',
+      },
+    },
+    required: ['associate_oid'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        '$top': String(params.top ?? 10),
+      };
+      if (params.start_date) query['$filter'] = `payDate ge '${params.start_date}'`;
+      if (params.end_date) {
+        const existing = query['$filter'] || '';
+        query['$filter'] = existing
+          ? `${existing} and payDate le '${params.end_date}'`
+          : `payDate le '${params.end_date}'`;
+      }
+
+      const result = await ctx.apiExecutor.get(
+        `/payroll/v1/workers/${params.associate_oid}/pay-distributions`,
+        query,
+      );
+
+      const statements: any[] = result.payDistributions || result.payStatements || [];
+      if (statements.length === 0) {
+        return { content: `No payroll data found for worker ${params.associate_oid}.` };
+      }
+
+      const lines = statements.map((s: any) => {
+        const payDate = s.payDate || 'N/A';
+        const grossPay = s.grossPayAmount?.amountValue ? `$${Number(s.grossPayAmount.amountValue).toLocaleString()}` : 'N/A';
+        const netPay = s.netPayAmount?.amountValue ? `$${Number(s.netPayAmount.amountValue).toLocaleString()}` : 'N/A';
+        const period = s.payPeriod
+          ? `${s.payPeriod.startDate || 'N/A'} to ${s.payPeriod.endDate || 'N/A'}`
+          : 'N/A';
+        return `Pay Date: ${payDate} -- Period: ${period} -- Gross: ${grossPay} -- Net: ${netPay}`;
+      });
+
+      return {
+        content: `Payroll for worker ${params.associate_oid}:\n${lines.join('\n')}`,
+        metadata: {
+          associateOid: params.associate_oid,
+          statementCount: statements.length,
+        },
+      };
+    } catch (err) {
+      return adpError(err);
+    }
+  },
+};
+
+// ─── Tool: adp_list_org_units ───────────────────────────
+
+const listOrgUnits: ToolHandler = {
+  description:
+    'List organizational units from ADP. Returns departments, divisions, cost centers, and other org structures.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      type: {
+        type: 'string',
+        enum: ['department', 'division', 'cost_center', 'location'],
+        description: 'Type of organizational unit to list',
+      },
+      top: {
+        type: 'number',
+        description: 'Maximum number of results (default 50)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        '$top': String(params.top ?? 50),
+      };
+      if (params.type) query.typeCode = params.type;
+
+      const result = await ctx.apiExecutor.get('/core/v1/organization-departments', query);
+
+      const units: any[] = result.organizationDepartments || result.data || [];
+      if (units.length === 0) {
+        return { content: 'No organizational units found.' };
+      }
+
+      const lines = units.map((unit: any) => {
+        const name = unit.nameLong || unit.nameShort || unit.name || '(unnamed)';
+        const code = unit.departmentCode?.codeValue || unit.code || 'N/A';
+        const type = unit.typeCode?.longName || unit.type || 'N/A';
+        const head = unit.headWorker?.formattedName || 'N/A';
+        return `${name} (${code}) -- Type: ${type} -- Head: ${head}`;
+      });
+
+      return {
+        content: `Found ${units.length} organizational units:\n${lines.join('\n')}`,
+        metadata: { count: units.length },
+      };
+    } catch (err) {
+      return adpError(err);
+    }
+  },
+};
+
+// ─── Tool: adp_get_benefits ─────────────────────────────
+
+const getBenefits: ToolHandler = {
+  description:
+    'Get benefit enrollment information for a specific ADP worker. Returns active benefits, coverage, and plan details.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      associate_oid: {
+        type: 'string',
+        description: 'The ADP associate OID',
+      },
+    },
+    required: ['associate_oid'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const result = await ctx.apiExecutor.get(
+        `/benefits/v1/workers/${params.associate_oid}/benefit-enrollments`,
+      );
+
+      const enrollments: any[] = result.benefitEnrollments || [];
+      if (enrollments.length === 0) {
+        return {
+          content: `No benefit enrollments found for worker ${params.associate_oid}.`,
+          metadata: { associateOid: params.associate_oid },
+        };
+      }
+
+      const lines = enrollments.map((e: any) => {
+        const planName = e.benefitPlanName || e.planName || 'Unknown Plan';
+        const type = e.benefitType?.longName || e.type || 'N/A';
+        const status = e.enrollmentStatus?.codeValue || 'N/A';
+        const coverage = e.coverageLevelCode?.longName || 'N/A';
+        const cost = e.employeeCost?.amountValue ? `$${Number(e.employeeCost.amountValue).toLocaleString()}/period` : 'N/A';
+        return `${planName} (${type}) -- Status: ${status} -- Coverage: ${coverage} -- Cost: ${cost}`;
+      });
+
+      return {
+        content: `Benefits for worker ${params.associate_oid}:\n${lines.join('\n')}`,
+        metadata: {
+          associateOid: params.associate_oid,
+          enrollmentCount: enrollments.length,
+        },
+      };
+    } catch (err) {
+      return adpError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const adpAdapter: SkillAdapter = {
+  skillId: 'adp',
+  name: 'ADP Workforce',
+  baseUrl: 'https://api.adp.com',
+  auth: {
+    type: 'oauth2',
+    provider: 'adp',
+    headerPrefix: 'Bearer',
+  },
+  tools: {
+    adp_list_workers: listWorkers,
+    adp_get_worker: getWorker,
+    adp_get_payroll: getPayroll,
+    adp_list_org_units: listOrgUnits,
+    adp_get_benefits: getBenefits,
+  },
+  configSchema: {
+    environment: {
+      type: 'select' as const,
+      label: 'Environment',
+      description: 'Select the ADP environment to connect to',
+      options: [
+        { label: 'Production', value: 'prod' },
+        { label: 'Sandbox', value: 'sandbox' },
+      ],
+    },
+  },
+  rateLimits: {
+    requestsPerSecond: 5,
+    burstLimit: 10,
+  },
+};

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

@@ -0,0 +1,273 @@
+/**
+ * MCP Skill Adapter — Airtable
+ *
+ * Maps Airtable REST API endpoints to MCP tool handlers.
+ * Airtable paths follow the pattern /{baseId}/{tableIdOrName} for record operations.
+ *
+ * Airtable API docs: https://airtable.com/developers/web/api/introduction
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function airtableError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const errObj = data.error;
+      if (errObj && typeof errObj === 'object') {
+        const message = errObj.message || errObj.type || 'unknown error';
+        return { content: `Airtable API error: ${message}`, isError: true };
+      }
+      if (data.message) {
+        return { content: `Airtable API error: ${data.message}`, isError: true };
+      }
+    }
+    return { content: `Airtable API error: ${err.message}`, isError: true };
+  }
+  return { content: `Airtable API error: ${String(err)}`, isError: true };
+}
+
+/**
+ * Format a record's fields into a human-readable string.
+ */
+function formatFields(fields: Record<string, any>): string {
+  return Object.entries(fields)
+    .map(([key, val]) => {
+      const display = Array.isArray(val) ? val.join(', ') : String(val ?? '');
+      return `${key}: ${display}`;
+    })
+    .join(', ');
+}
+
+// ─── Tool: airtable_list_records ────────────────────────
+
+const listRecords: ToolHandler = {
+  description:
+    'List records from an Airtable table. Provide the base ID and table name or ID. Optionally filter with a formula, sort, or limit results.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      baseId: {
+        type: 'string',
+        description: 'Airtable base ID (e.g. "appXXXXXXXXXX")',
+      },
+      tableIdOrName: {
+        type: 'string',
+        description: 'Table ID or name (e.g. "Tasks" or "tblXXXXXXXXXX")',
+      },
+      filterByFormula: {
+        type: 'string',
+        description: 'Airtable formula to filter records (e.g. "{Status} = \'Done\'")',
+      },
+      maxRecords: {
+        type: 'number',
+        description: 'Maximum number of records to return (default 100)',
+      },
+      sort: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            field: { type: 'string' },
+            direction: { type: 'string', enum: ['asc', 'desc'] },
+          },
+        },
+        description: 'Sort configuration (e.g. [{"field": "Created", "direction": "desc"}])',
+      },
+      view: {
+        type: 'string',
+        description: 'View name or ID to filter by (optional)',
+      },
+    },
+    required: ['baseId', 'tableIdOrName'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {};
+
+      if (params.filterByFormula) query.filterByFormula = params.filterByFormula;
+      if (params.maxRecords) query.maxRecords = String(params.maxRecords);
+      if (params.view) query.view = params.view;
+
+      // Sort params need special handling for query string format
+      if (params.sort?.length) {
+        params.sort.forEach((s: any, i: number) => {
+          query[`sort[${i}][field]`] = s.field;
+          if (s.direction) query[`sort[${i}][direction]`] = s.direction;
+        });
+      }
+
+      const path = `/${params.baseId}/${encodeURIComponent(params.tableIdOrName)}`;
+      const result = await ctx.apiExecutor.get(path, query);
+      const records: any[] = result.records || [];
+
+      if (records.length === 0) {
+        return { content: 'No records found.' };
+      }
+
+      const lines = records.map((r: any) => {
+        const fields = formatFields(r.fields || {});
+        return `${r.id}: ${fields}`;
+      });
+
+      return {
+        content: `Found ${records.length} records:\n${lines.join('\n')}`,
+        metadata: {
+          count: records.length,
+          baseId: params.baseId,
+          table: params.tableIdOrName,
+          offset: result.offset,
+        },
+      };
+    } catch (err) {
+      return airtableError(err);
+    }
+  },
+};
+
+// ─── Tool: airtable_create_record ───────────────────────
+
+const createRecord: ToolHandler = {
+  description:
+    'Create a new record in an Airtable table. Provide the base ID, table name, and field values.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      baseId: {
+        type: 'string',
+        description: 'Airtable base ID (e.g. "appXXXXXXXXXX")',
+      },
+      tableIdOrName: {
+        type: 'string',
+        description: 'Table ID or name',
+      },
+      fields: {
+        type: 'object',
+        description: 'Field values for the new record (e.g. {"Name": "Task 1", "Status": "Todo", "Priority": "High"})',
+      },
+      typecast: {
+        type: 'boolean',
+        description: 'If true, Airtable will try to coerce string values to the correct cell type (default false)',
+      },
+    },
+    required: ['baseId', 'tableIdOrName', 'fields'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const path = `/${params.baseId}/${encodeURIComponent(params.tableIdOrName)}`;
+      const body: Record<string, any> = {
+        fields: params.fields,
+      };
+
+      if (params.typecast) body.typecast = true;
+
+      const result = await ctx.apiExecutor.post(path, body);
+
+      const fieldsSummary = formatFields(result.fields || {});
+
+      return {
+        content: `Record created (ID: ${result.id}): ${fieldsSummary}`,
+        metadata: {
+          id: result.id,
+          baseId: params.baseId,
+          table: params.tableIdOrName,
+          fields: result.fields,
+        },
+      };
+    } catch (err) {
+      return airtableError(err);
+    }
+  },
+};
+
+// ─── Tool: airtable_update_record ───────────────────────
+
+const updateRecord: ToolHandler = {
+  description:
+    'Update an existing record in an Airtable table. Provide the base ID, table name, record ID, and the fields to update.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      baseId: {
+        type: 'string',
+        description: 'Airtable base ID (e.g. "appXXXXXXXXXX")',
+      },
+      tableIdOrName: {
+        type: 'string',
+        description: 'Table ID or name',
+      },
+      recordId: {
+        type: 'string',
+        description: 'ID of the record to update (e.g. "recXXXXXXXXXX")',
+      },
+      fields: {
+        type: 'object',
+        description: 'Field values to update (only specified fields are changed)',
+      },
+      typecast: {
+        type: 'boolean',
+        description: 'If true, Airtable will try to coerce string values to the correct cell type (default false)',
+      },
+    },
+    required: ['baseId', 'tableIdOrName', 'recordId', 'fields'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const path = `/${params.baseId}/${encodeURIComponent(params.tableIdOrName)}/${params.recordId}`;
+      const body: Record<string, any> = {
+        fields: params.fields,
+      };
+
+      if (params.typecast) body.typecast = true;
+
+      const result = await ctx.apiExecutor.patch(path, body);
+
+      const fieldsSummary = formatFields(result.fields || {});
+
+      return {
+        content: `Record ${result.id} updated: ${fieldsSummary}`,
+        metadata: {
+          id: result.id,
+          baseId: params.baseId,
+          table: params.tableIdOrName,
+          fields: result.fields,
+        },
+      };
+    } catch (err) {
+      return airtableError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const airtableAdapter: SkillAdapter = {
+  skillId: 'airtable-bases',
+  name: 'Airtable',
+  baseUrl: 'https://api.airtable.com/v0',
+  auth: {
+    type: 'oauth2',
+    provider: 'airtable',
+    headerPrefix: 'Bearer',
+  },
+  tools: {
+    airtable_list_records: listRecords,
+    airtable_create_record: createRecord,
+    airtable_update_record: updateRecord,
+  },
+  rateLimits: { requestsPerSecond: 5, burstLimit: 10 },
+  configSchema: {
+    baseId: {
+      type: 'string' as const,
+      label: 'Airtable Base ID',
+      description: 'Default Airtable base ID (starts with "app")',
+      required: false,
+      placeholder: 'appXXXXXXXXXXXXXX',
+    },
+  },
+};