@agenticmail/enterprise 0.3.2 → 0.4.0

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

@@ -0,0 +1,315 @@
+/**
+ * MCP Skill Adapter — Asana
+ *
+ * Maps Asana REST API endpoints to MCP tool handlers.
+ * Provides task and project management capabilities.
+ *
+ * Asana API docs: https://developers.asana.com/reference/rest-api-reference
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function asanaError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const errors: any[] = data.errors || [];
+      if (errors.length > 0) {
+        const messages = errors.map((e: any) => e.message || String(e));
+        return { content: `Asana API error: ${messages.join('; ')}`, isError: true };
+      }
+    }
+    return { content: `Asana API error: ${err.message}`, isError: true };
+  }
+  return { content: `Asana API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: asana_create_task ────────────────────────────
+
+const createTask: ToolHandler = {
+  description:
+    'Create a new task in Asana. Specify the workspace or project, task name, and optional details like assignee, due date, and notes.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Task name / title',
+      },
+      projects: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Array of project GIDs to add this task to',
+      },
+      workspace: {
+        type: 'string',
+        description: 'Workspace GID (required if projects is not provided)',
+      },
+      assignee: {
+        type: 'string',
+        description: 'Assignee GID or email address',
+      },
+      due_on: {
+        type: 'string',
+        description: 'Due date in YYYY-MM-DD format',
+      },
+      notes: {
+        type: 'string',
+        description: 'Plain-text task description / notes',
+      },
+    },
+    required: ['name'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const taskData: Record<string, any> = {
+        name: params.name,
+      };
+
+      if (params.projects?.length) taskData.projects = params.projects;
+      if (params.workspace) taskData.workspace = params.workspace;
+      if (params.assignee) taskData.assignee = params.assignee;
+      if (params.due_on) taskData.due_on = params.due_on;
+      if (params.notes) taskData.notes = params.notes;
+
+      const result = await ctx.apiExecutor.post('/tasks', { data: taskData });
+      const task = result.data;
+
+      const assigneeInfo = task.assignee ? ` (assigned to ${task.assignee.name || task.assignee.gid})` : '';
+      const dueInfo = task.due_on ? ` due ${task.due_on}` : '';
+
+      return {
+        content: `Task created: "${task.name}" (GID: ${task.gid})${assigneeInfo}${dueInfo}`,
+        metadata: {
+          gid: task.gid,
+          name: task.name,
+          permalink_url: task.permalink_url,
+        },
+      };
+    } catch (err) {
+      return asanaError(err);
+    }
+  },
+};
+
+// ─── Tool: asana_list_tasks ─────────────────────────────
+
+const listTasks: ToolHandler = {
+  description:
+    'List tasks from an Asana project or assigned to a user. Provide either a project GID or an assignee with a workspace.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      project: {
+        type: 'string',
+        description: 'Project GID to list tasks from',
+      },
+      assignee: {
+        type: 'string',
+        description: 'Assignee GID or "me" (requires workspace to be set)',
+      },
+      workspace: {
+        type: 'string',
+        description: 'Workspace GID (required when filtering by assignee)',
+      },
+      completed_since: {
+        type: 'string',
+        description: 'Only return tasks completed after this date (ISO 8601) or "now" for incomplete tasks only',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of tasks to return (default 50)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 50),
+        opt_fields: 'name,assignee.name,due_on,completed,permalink_url',
+      };
+
+      if (params.project) query.project = params.project;
+      if (params.assignee) query.assignee = params.assignee;
+      if (params.workspace) query.workspace = params.workspace;
+      if (params.completed_since) query.completed_since = params.completed_since;
+
+      const result = await ctx.apiExecutor.get('/tasks', query);
+      const tasks: any[] = result.data || [];
+
+      if (tasks.length === 0) {
+        return { content: 'No tasks found matching the criteria.' };
+      }
+
+      const lines = tasks.map((t: any) => {
+        const status = t.completed ? '[done]' : '[open]';
+        const assignee = t.assignee?.name || 'Unassigned';
+        const due = t.due_on ? ` due ${t.due_on}` : '';
+        return `${status} ${t.name} (${t.gid}) -- ${assignee}${due}`;
+      });
+
+      return {
+        content: `Found ${tasks.length} tasks:\n${lines.join('\n')}`,
+        metadata: { count: tasks.length },
+      };
+    } catch (err) {
+      return asanaError(err);
+    }
+  },
+};
+
+// ─── Tool: asana_update_task ────────────────────────────
+
+const updateTask: ToolHandler = {
+  description:
+    'Update an existing Asana task. You can change the name, assignee, due date, completion status, or notes.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      task_gid: {
+        type: 'string',
+        description: 'GID of the task to update',
+      },
+      name: {
+        type: 'string',
+        description: 'New task name',
+      },
+      assignee: {
+        type: 'string',
+        description: 'New assignee GID or email',
+      },
+      due_on: {
+        type: 'string',
+        description: 'New due date (YYYY-MM-DD) or null to clear',
+      },
+      completed: {
+        type: 'boolean',
+        description: 'Mark task as complete (true) or incomplete (false)',
+      },
+      notes: {
+        type: 'string',
+        description: 'New plain-text description / notes',
+      },
+    },
+    required: ['task_gid'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const taskData: Record<string, any> = {};
+
+      if (params.name !== undefined) taskData.name = params.name;
+      if (params.assignee !== undefined) taskData.assignee = params.assignee;
+      if (params.due_on !== undefined) taskData.due_on = params.due_on;
+      if (params.completed !== undefined) taskData.completed = params.completed;
+      if (params.notes !== undefined) taskData.notes = params.notes;
+
+      const result = await ctx.apiExecutor.put(`/tasks/${params.task_gid}`, { data: taskData });
+      const task = result.data;
+
+      const changes: string[] = [];
+      if (params.name !== undefined) changes.push(`name -> "${params.name}"`);
+      if (params.assignee !== undefined) changes.push(`assignee -> ${params.assignee}`);
+      if (params.due_on !== undefined) changes.push(`due -> ${params.due_on}`);
+      if (params.completed !== undefined) changes.push(params.completed ? 'marked complete' : 'marked incomplete');
+      if (params.notes !== undefined) changes.push('notes updated');
+
+      return {
+        content: `Task ${task.gid} updated: ${changes.join(', ')}`,
+        metadata: {
+          gid: task.gid,
+          name: task.name,
+          completed: task.completed,
+        },
+      };
+    } catch (err) {
+      return asanaError(err);
+    }
+  },
+};
+
+// ─── Tool: asana_list_projects ──────────────────────────
+
+const listProjects: ToolHandler = {
+  description:
+    'List projects in an Asana workspace or team. Returns project names, GIDs, and statuses.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      workspace: {
+        type: 'string',
+        description: 'Workspace GID to list projects from',
+      },
+      team: {
+        type: 'string',
+        description: 'Team GID to filter projects by team',
+      },
+      archived: {
+        type: 'boolean',
+        description: 'Include archived projects (default false)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of projects to return (default 50)',
+      },
+    },
+    required: ['workspace'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        workspace: params.workspace,
+        limit: String(params.limit ?? 50),
+        opt_fields: 'name,archived,color,current_status.title,current_status.color',
+      };
+
+      if (params.team) query.team = params.team;
+      if (params.archived !== undefined) query.archived = String(params.archived);
+
+      const result = await ctx.apiExecutor.get('/projects', query);
+      const projects: any[] = result.data || [];
+
+      if (projects.length === 0) {
+        return { content: 'No projects found in this workspace.' };
+      }
+
+      const lines = projects.map((p: any) => {
+        const archived = p.archived ? ' [archived]' : '';
+        const status = p.current_status?.title ? ` -- ${p.current_status.title}` : '';
+        return `${p.name} (${p.gid})${archived}${status}`;
+      });
+
+      return {
+        content: `Found ${projects.length} projects:\n${lines.join('\n')}`,
+        metadata: { count: projects.length },
+      };
+    } catch (err) {
+      return asanaError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const asanaAdapter: SkillAdapter = {
+  skillId: 'asana-tasks',
+  name: 'Asana',
+  baseUrl: 'https://app.asana.com/api/1.0',
+  auth: {
+    type: 'oauth2',
+    provider: 'asana',
+    headerPrefix: 'Bearer',
+  },
+  tools: {
+    asana_create_task: createTask,
+    asana_list_tasks: listTasks,
+    asana_update_task: updateTask,
+    asana_list_projects: listProjects,
+  },
+  rateLimits: { requestsPerSecond: 1, burstLimit: 10 },
+};

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

@@ -0,0 +1,386 @@
+/**
+ * MCP Skill Adapter — Auth0
+ *
+ * Maps Auth0 Management API v2 endpoints to MCP tool handlers.
+ * Covers user management, connection listing, client listing, and user blocking.
+ *
+ * The Auth0 domain is dynamic, resolved from ctx.skillConfig.domain.
+ *
+ * Auth0 Management API docs: https://auth0.com/docs/api/management/v2
+ */
+
+import type {
+  SkillAdapter,
+  ToolHandler,
+  ToolResult,
+  ToolExecutionContext,
+} from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+/** Resolve the Auth0 Management API base URL from skill config domain. */
+function auth0Url(ctx: ToolExecutionContext): string {
+  const domain = ctx.skillConfig.domain || 'example.auth0.com';
+  // Ensure domain includes auth0.com
+  const fullDomain = domain.includes('.') ? domain : `${domain}.auth0.com`;
+  return `https://${fullDomain}/api/v2`;
+}
+
+function auth0Error(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const statusCode = data.statusCode || '';
+      const errorType = data.error || '';
+      const message = data.message || data.error_description || err.message;
+      return {
+        content: `Auth0 API error (${statusCode} ${errorType}): ${message}`,
+        isError: true,
+      };
+    }
+    return { content: `Auth0 API error: ${err.message}`, isError: true };
+  }
+  return { content: `Auth0 API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: auth0_list_users ─────────────────────────────
+
+const listUsers: ToolHandler = {
+  description:
+    'List Auth0 users. Optionally search using Lucene query syntax or filter by connection.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      q: {
+        type: 'string',
+        description: 'Lucene query string (e.g. "email:*@example.com" or "name:John")',
+      },
+      connection: {
+        type: 'string',
+        description: 'Filter by connection name (e.g. "Username-Password-Authentication")',
+      },
+      per_page: {
+        type: 'number',
+        description: 'Number of users per page (default 20, max 100)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (0-indexed)',
+      },
+      sort: {
+        type: 'string',
+        description: 'Sort field and order (e.g. "created_at:-1" for newest first)',
+      },
+    },
+    additionalProperties: false,
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = auth0Url(ctx);
+      const query: Record<string, string> = {
+        per_page: String(params.per_page ?? 20),
+        page: String(params.page ?? 0),
+        include_totals: 'true',
+      };
+      if (params.q) query.q = params.q;
+      if (params.connection) query.connection = params.connection;
+      if (params.sort) query.sort = params.sort;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/users`,
+        query,
+      });
+
+      const users: any[] = result.users || (Array.isArray(result) ? result : []);
+      const total = result.total || users.length;
+
+      if (users.length === 0) {
+        return {
+          content: 'No users found.',
+          metadata: { userCount: 0, total: 0 },
+        };
+      }
+
+      const lines = users.map((u: any) => {
+        const name = u.name || u.email || 'unknown';
+        const email = u.email || 'no email';
+        const logins = u.logins_count ?? 0;
+        const lastLogin = u.last_login ? new Date(u.last_login).toLocaleString() : 'never';
+        const blocked = u.blocked ? ' [BLOCKED]' : '';
+        return `• ${name} (${email}) — logins: ${logins}, last login: ${lastLogin}${blocked} (ID: ${u.user_id})`;
+      });
+
+      return {
+        content: `Found ${users.length} of ${total} user(s):\n\n${lines.join('\n')}`,
+        metadata: { userCount: users.length, total },
+      };
+    } catch (err) {
+      return auth0Error(err);
+    }
+  },
+};
+
+// ─── Tool: auth0_get_user ───────────────────────────────
+
+const getUser: ToolHandler = {
+  description:
+    'Retrieve details of a specific Auth0 user by their user_id. Returns profile, identities, and metadata.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      user_id: {
+        type: 'string',
+        description: 'The Auth0 user ID (e.g. "auth0|507f1f77bcf86cd799439011")',
+      },
+    },
+    required: ['user_id'],
+    additionalProperties: false,
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = auth0Url(ctx);
+      const user = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/users/${encodeURIComponent(params.user_id)}`,
+      });
+
+      const identities = (user.identities || []).map((id: any) => {
+        return `${id.provider}/${id.connection}`;
+      }).join(', ') || 'none';
+
+      const content = [
+        `User: ${user.name || 'N/A'} (ID: ${user.user_id})`,
+        `Email: ${user.email || 'N/A'} (verified: ${user.email_verified ? 'yes' : 'no'})`,
+        `Nickname: ${user.nickname || 'N/A'}`,
+        `Picture: ${user.picture || 'N/A'}`,
+        `Blocked: ${user.blocked ? 'Yes' : 'No'}`,
+        `Login count: ${user.logins_count ?? 0}`,
+        `Last login: ${user.last_login ? new Date(user.last_login).toLocaleString() : 'never'}`,
+        `Last IP: ${user.last_ip || 'N/A'}`,
+        `Created: ${user.created_at ? new Date(user.created_at).toLocaleString() : 'unknown'}`,
+        `Identities: ${identities}`,
+      ].join('\n');
+
+      return {
+        content,
+        metadata: {
+          userId: user.user_id,
+          email: user.email,
+          blocked: user.blocked,
+        },
+      };
+    } catch (err) {
+      return auth0Error(err);
+    }
+  },
+};
+
+// ─── Tool: auth0_list_connections ────────────────────────
+
+const listConnections: ToolHandler = {
+  description:
+    'List Auth0 connections (identity providers). Returns connection names, strategies, and enabled clients.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      strategy: {
+        type: 'string',
+        description: 'Filter by strategy type (e.g. "auth0", "google-oauth2", "samlp")',
+      },
+      per_page: {
+        type: 'number',
+        description: 'Number of connections per page (default 20, max 100)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (0-indexed)',
+      },
+    },
+    additionalProperties: false,
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = auth0Url(ctx);
+      const query: Record<string, string> = {
+        per_page: String(params.per_page ?? 20),
+        page: String(params.page ?? 0),
+      };
+      if (params.strategy) query.strategy = params.strategy;
+
+      const connections: any[] = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/connections`,
+        query,
+      });
+
+      if (!Array.isArray(connections) || connections.length === 0) {
+        return {
+          content: 'No connections found.',
+          metadata: { connectionCount: 0 },
+        };
+      }
+
+      const lines = connections.map((c: any) => {
+        const enabledClients = (c.enabled_clients || []).length;
+        return `• ${c.name} (ID: ${c.id}) — strategy: ${c.strategy || 'unknown'}, enabled clients: ${enabledClients}`;
+      });
+
+      return {
+        content: `Found ${connections.length} connection(s):\n\n${lines.join('\n')}`,
+        metadata: { connectionCount: connections.length },
+      };
+    } catch (err) {
+      return auth0Error(err);
+    }
+  },
+};
+
+// ─── Tool: auth0_list_clients ───────────────────────────
+
+const listClients: ToolHandler = {
+  description:
+    'List Auth0 clients (applications). Returns client names, IDs, app types, and callback URLs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      per_page: {
+        type: 'number',
+        description: 'Number of clients per page (default 20, max 100)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (0-indexed)',
+      },
+      app_type: {
+        type: 'string',
+        enum: ['native', 'spa', 'regular_web', 'non_interactive'],
+        description: 'Filter by application type',
+      },
+    },
+    additionalProperties: false,
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = auth0Url(ctx);
+      const query: Record<string, string> = {
+        per_page: String(params.per_page ?? 20),
+        page: String(params.page ?? 0),
+        include_totals: 'true',
+      };
+      if (params.app_type) query.app_type = params.app_type;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/clients`,
+        query,
+      });
+
+      const clients: any[] = result.clients || (Array.isArray(result) ? result : []);
+      const total = result.total || clients.length;
+
+      if (clients.length === 0) {
+        return {
+          content: 'No clients found.',
+          metadata: { clientCount: 0, total: 0 },
+        };
+      }
+
+      const lines = clients.map((c: any) => {
+        const appType = c.app_type || 'unknown';
+        const callbacks = (c.callbacks || []).length;
+        const isGlobal = c.global ? ' [GLOBAL]' : '';
+        return `• ${c.name} (ID: ${c.client_id}) — type: ${appType}, callbacks: ${callbacks}${isGlobal}`;
+      });
+
+      return {
+        content: `Found ${clients.length} of ${total} client(s):\n\n${lines.join('\n')}`,
+        metadata: { clientCount: clients.length, total },
+      };
+    } catch (err) {
+      return auth0Error(err);
+    }
+  },
+};
+
+// ─── Tool: auth0_block_user ─────────────────────────────
+
+const blockUser: ToolHandler = {
+  description:
+    'Block or unblock an Auth0 user by setting the blocked flag. Blocked users cannot log in.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      user_id: {
+        type: 'string',
+        description: 'The Auth0 user ID to block or unblock',
+      },
+      blocked: {
+        type: 'boolean',
+        description: 'Set to true to block the user, false to unblock (default true)',
+      },
+    },
+    required: ['user_id'],
+    additionalProperties: false,
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = auth0Url(ctx);
+      const blocked = params.blocked !== false;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'PATCH',
+        path: undefined,
+        url: `${baseUrl}/users/${encodeURIComponent(params.user_id)}`,
+        body: { blocked },
+      });
+
+      const action = blocked ? 'blocked' : 'unblocked';
+      return {
+        content: `User ${params.user_id} has been ${action} successfully.`,
+        metadata: {
+          userId: params.user_id,
+          blocked,
+          action,
+        },
+      };
+    } catch (err) {
+      return auth0Error(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const auth0Adapter: SkillAdapter = {
+  skillId: 'auth0',
+  name: 'Auth0',
+  // Base URL is dynamic from ctx.skillConfig.domain; tools use full URLs
+  baseUrl: 'https://example.auth0.com/api/v2',
+  auth: {
+    type: 'token',
+    headerPrefix: 'Bearer',
+  },
+  tools: {
+    auth0_list_users: listUsers,
+    auth0_get_user: getUser,
+    auth0_list_connections: listConnections,
+    auth0_list_clients: listClients,
+    auth0_block_user: blockUser,
+  },
+  rateLimits: { requestsPerSecond: 10, burstLimit: 20 },
+  configSchema: {
+    domain: {
+      type: 'string' as const,
+      label: 'Auth0 Domain',
+      description: 'Your Auth0 tenant domain',
+      required: true,
+      placeholder: 'myapp.auth0.com',
+    },
+  },
+};