@adrata/adrata-mcp 1.0.0

package/tools/paper-tools.js

@@ -0,0 +1,563 @@
+import { z } from 'zod';
+
+const PAPER_DOC_TYPE = 'paper';
+const paperVisibility = z.enum(['workspace', 'owner_private']);
+
+const writeControls = {
+  dryRun: z.boolean().optional().describe('Defaults to true. Set false only after explicit user approval.'),
+  approved: z.boolean().optional().describe('Must be true for live writes.'),
+  reason: z.string().optional().describe('Audit reason for live writes.'),
+  idempotencyKey: z.string().optional().describe('Required for live writes.'),
+};
+
+const shareTier = z.enum(['public', 'internal', 'confidential', 'highly_confidential']);
+
+function requireLiveWrite(args, preview) {
+  if (args.dryRun !== false) {
+    return {
+      dryRun: true,
+      wouldSend: true,
+      requiredForLiveWrite: ['dryRun:false', 'approved:true', 'reason', 'idempotencyKey'],
+      preview,
+    };
+  }
+  if (args.approved !== true) throw new Error('live writes require approved:true');
+  if (!args.reason || !String(args.reason).trim()) throw new Error('live writes require a reason');
+  if (!args.idempotencyKey || !String(args.idempotencyKey).trim()) {
+    throw new Error('live writes require an idempotencyKey');
+  }
+  return null;
+}
+
+function mutationHeaders(args, buildMutationHeaders) {
+  return buildMutationHeaders({
+    reason: args.reason,
+    idempotencyKey: args.idempotencyKey,
+    actor: 'mcp-paper',
+  });
+}
+
+function cleanBody(fields) {
+  const body = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (value !== undefined) body[key] = value;
+  }
+  return body;
+}
+
+function paperAudit() {
+  return {
+    app: {
+      name: 'Paper',
+      bundleId: 'com.paper.desktop',
+      localCache: 'paper.docs.v1',
+      deepLinkScheme: 'paper://',
+      documentType: PAPER_DOC_TYPE,
+    },
+    coverage: [
+      {
+        surface: 'Documents',
+        appRoutes: ['GET /api/v1/documents?type=paper&limit=100', 'POST /api/v1/documents', 'PUT /api/v1/documents/{id}', 'DELETE /api/v1/documents/{id}'],
+        mcpTools: ['paper_list_documents', 'paper_get_document', 'paper_create_document', 'paper_update_document', 'paper_archive_document', 'paper_delete_document'],
+        status: 'covered',
+      },
+      {
+        surface: 'Secure sharing',
+        appRoutes: ['POST /api/v1/shares', 'GET /api/v1/shares', 'DELETE /api/v1/shares/{id}', 'GET /api/v1/shares/resolve/{token}'],
+        mcpTools: ['paper_create_share', 'paper_list_shares', 'paper_revoke_share', 'paper_resolve_share'],
+        status: 'covered',
+      },
+      {
+        surface: 'Tasks',
+        appRoutes: ['GET /api/v1/actions?viewMode=seller', 'POST /api/v1/actions', 'PATCH /api/v1/actions/{id}'],
+        mcpTools: ['paper_list_tasks', 'paper_create_task', 'paper_update_task'],
+        status: 'covered',
+      },
+      {
+        surface: 'Calendar',
+        appRoutes: ['GET /api/v2/events/calendar', 'POST /api/v1/events'],
+        mcpTools: ['paper_list_calendar_events', 'paper_create_calendar_event'],
+        status: 'covered',
+      },
+      {
+        surface: 'Email',
+        appRoutes: ['GET /api/v2/emails/threads', 'GET /api/v1/emails/threads/{id}', 'POST /api/v2/emails/direct'],
+        mcpTools: ['paper_list_email_threads', 'paper_get_email_thread', 'paper_send_email'],
+        status: 'covered',
+      },
+      {
+        surface: 'Company context',
+        appRoutes: ['GET /api/v1/companies/{id}'],
+        mcpTools: ['paper_get_company'],
+        status: 'covered',
+      },
+      {
+        surface: 'Mailbox OAuth connections',
+        appRoutes: ['GET /api/v1/oauth/email/providers', 'POST /api/v1/oauth/email/initiate', 'DELETE /api/v1/oauth/email/providers/{id}'],
+        mcpTools: [],
+        status: 'intentionally UI-led',
+        reason: 'OAuth initiation and disconnect affect live email/calendar integrations and should remain user-driven in Paper settings or Adrata auth flows.',
+      },
+      {
+        surface: 'Local-only cache',
+        storage: 'Chromium Local Storage LevelDB / paper.docs.v1',
+        mcpTools: [],
+        status: 'intentionally not covered',
+        reason: 'Direct cache writes bypass auth, sync reconciliation, audit, and conflict handling.',
+      },
+    ],
+  };
+}
+
+function adrataDesktopAudit() {
+  return {
+    app: {
+      name: 'Adrata',
+      bundleId: 'com.adrata.desktop',
+      deepLinkScheme: 'adrata://',
+      connectionModes: ['connect_workspace OAuth', 'ADRATA_OAUTH_TOKEN', 'Adrata CLI config'],
+    },
+    coverage: [
+      {
+        surface: 'Workspace connection',
+        mcpTools: ['connect_workspace', 'workspace_status', 'disconnect_workspace'],
+        status: 'covered',
+      },
+      {
+        surface: 'Adrata chat tool parity',
+        mcpTools: ['adrata_ai_tool_catalog', 'adrata_ai_tool_execute'],
+        status: 'covered',
+        reason: 'Uses the same governed AI CRM tool dispatcher as Adrata chat when a workspace is connected.',
+      },
+      {
+        surface: 'CRM and revenue records',
+        mcpTools: ['search_companies', 'get_company', 'create_company', 'update_company', 'search_people', 'get_person', 'search_opportunities', 'create_opportunity', 'list_actions', 'create_action', 'list_notes', 'create_note'],
+        status: 'covered',
+      },
+      {
+        surface: 'Build Pipeline',
+        mcpTools: ['list_external_pipelines', 'list_external_pipeline_members', 'import_external_pipeline_members', 'list_external_companies', 'import_external_companies', 'rank_companies_by_icp', 'check_batch_import_status', 'qualify_company', 'research_company', 'research_person', 'discover_prospects', 'get_next_contacts'],
+        status: 'covered',
+      },
+      {
+        surface: 'Win Pipeline',
+        mcpTools: ['get_account_read', 'rank_paths_to_power', 'recommend_deal_move', 'move_pipeline_card', 'get_access_score', 'get_path_to_power', 'find_intro_path', 'get_deal_coaching', 'get_forecast', 'schedule_meeting'],
+        status: 'covered',
+      },
+      {
+        surface: 'Low-level API bridge',
+        mcpTools: ['adrata_api_catalog', 'adrata_api_request'],
+        status: 'covered',
+        reason: 'Governed escape hatch with allowlisted API paths and dry-run write protection.',
+      },
+      {
+        surface: 'Mailbox OAuth connections',
+        mcpTools: [],
+        status: 'intentionally UI-led',
+        reason: 'Provider consent and disconnect flows affect live integrations and should stay user-driven.',
+      },
+    ],
+  };
+}
+
+export function registerPaperTools(server, { api, ok, buildMutationHeaders }) {
+  server.tool(
+    'paper_app_audit',
+    'Audit Paper app MCP coverage. Returns the Paper app API surfaces, local cache model, and which MCP tools cover them.',
+    {},
+    async () => ok(paperAudit()),
+  );
+
+  server.tool(
+    'adrata_desktop_app_audit',
+    'Audit Adrata desktop app MCP coverage. Returns which existing MCP tools cover Adrata desktop revenue, pipeline, and API surfaces.',
+    {},
+    async () => ok(adrataDesktopAudit()),
+  );
+
+  server.tool(
+    'paper_list_documents',
+    'List Paper documents from the active workspace. Paper documents are Adrata documents with type=paper.',
+    {
+      limit: z.number().int().min(1).max(100).default(100),
+      page: z.number().int().min(1).default(1),
+      status: z.string().optional(),
+      folderId: z.string().optional(),
+    },
+    async (args) => ok(await api('GET', '/api/v1/documents', {
+      params: {
+        type: PAPER_DOC_TYPE,
+        limit: args.limit,
+        page: args.page,
+        status: args.status,
+        folderId: args.folderId,
+      },
+    })),
+  );
+
+  server.tool(
+    'paper_get_document',
+    'Get a Paper document by id from the active workspace.',
+    { id: z.string() },
+    async (args) => ok(await api('GET', `/api/v1/documents/${encodeURIComponent(args.id)}`)),
+  );
+
+  server.tool(
+    'paper_create_document',
+    'Create a Paper document. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      id: z.string().optional().describe('Optional stable ULID/id for idempotent offline-friendly creation.'),
+      title: z.string().min(1),
+      content: z.string().optional().describe('HTML content. Paper stores this as local body on hydrate.'),
+      status: z.string().default('draft'),
+      visibility: paperVisibility.default('workspace'),
+      metadata: z.record(z.unknown()).optional(),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const payload = cleanBody({
+          id: args.id,
+          title: args.title,
+          content: args.content ?? '',
+          type: PAPER_DOC_TYPE,
+          status: args.status,
+          visibility: args.visibility,
+          metadata: {
+            source: 'mcp',
+            app: 'paper',
+            ...(args.metadata || {}),
+          },
+        });
+        const dry = requireLiveWrite(args, { method: 'POST', path: '/api/v1/documents', body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('POST', '/api/v1/documents', {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_update_document',
+    'Update a Paper document title/content/status/metadata. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      id: z.string(),
+      title: z.string().optional(),
+      content: z.string().optional(),
+      status: z.string().optional(),
+      metadata: z.record(z.unknown()).optional(),
+      expectedRevision: z.number().int().min(1),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const payload = cleanBody({
+          title: args.title,
+          content: args.content,
+          type: PAPER_DOC_TYPE,
+          status: args.status,
+          metadata: args.metadata,
+          expectedRevision: args.expectedRevision,
+        });
+        const path = `/api/v1/documents/${encodeURIComponent(args.id)}`;
+        const dry = requireLiveWrite(args, { method: 'PUT', path, body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('PUT', path, {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_delete_document',
+    'Delete a Paper document. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      id: z.string(),
+      expectedRevision: z.number().int().min(1),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const path = `/api/v1/documents/${encodeURIComponent(args.id)}`;
+        const params = { expectedRevision: args.expectedRevision };
+        const dry = requireLiveWrite(args, { method: 'DELETE', path, params });
+        if (dry) return ok(dry);
+        return ok(await api('DELETE', path, {
+          params,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_archive_document',
+    'Archive a Paper document without deleting it. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      id: z.string(),
+      expectedRevision: z.number().int().min(1),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const path = `/api/v1/documents/${encodeURIComponent(args.id)}`;
+        const payload = {
+          type: PAPER_DOC_TYPE,
+          status: 'archived',
+          expectedRevision: args.expectedRevision,
+        };
+        const dry = requireLiveWrite(args, { method: 'PUT', path, body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('PUT', path, {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_list_shares',
+    'List workspace share links, optionally filtered by Paper document/resource id.',
+    { resourceId: z.string().optional() },
+    async (args) => {
+      return ok(await api('GET', '/api/v1/shares', {
+        params: {
+          resourceType: 'document',
+          resourceId: args.resourceId,
+          limit: 100,
+          page: 1,
+        },
+      }));
+    },
+  );
+
+  server.tool(
+    'paper_create_share',
+    'Create a secure share link for a Paper document. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      documentId: z.string(),
+      tier: shareTier.default('internal'),
+      expiresAt: z.string().optional(),
+      allowedEmails: z.array(z.string()).optional(),
+      settings: z.record(z.unknown()).optional(),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const payload = cleanBody({
+          resourceType: 'document',
+          resourceId: args.documentId,
+          tier: args.tier,
+          expiresAt: args.expiresAt,
+          allowedEmails: args.allowedEmails,
+          settings: args.settings,
+        });
+        const dry = requireLiveWrite(args, { method: 'POST', path: '/api/v1/shares', body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('POST', '/api/v1/shares', {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_revoke_share',
+    'Revoke a Paper share link. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      shareId: z.string(),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const path = `/api/v1/shares/${encodeURIComponent(args.shareId)}`;
+        const dry = requireLiveWrite(args, { method: 'DELETE', path });
+        if (dry) return ok(dry);
+        return ok(await api('DELETE', path, {
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_resolve_share',
+    'Resolve a public Paper share token.',
+    { token: z.string() },
+    async (args) => ok(await api('GET', `/api/v1/shares/resolve/${encodeURIComponent(args.token)}`)),
+  );
+
+  server.tool(
+    'paper_list_tasks',
+    'List the seller task board used by Paper.',
+    { limit: z.number().int().min(1).max(200).default(200) },
+    async (args) => ok(await api('GET', '/api/v1/actions', {
+      params: {
+        viewMode: 'seller',
+        limit: args.limit,
+        sort_by: 'createdAt',
+        sort_order: 'desc',
+      },
+    })),
+  );
+
+  server.tool(
+    'paper_create_task',
+    'Create a Paper task/action. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      title: z.string().min(1),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const payload = { title: args.title, source: 'desktop' };
+        const dry = requireLiveWrite(args, { method: 'POST', path: '/api/v1/actions', body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('POST', '/api/v1/actions', {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_update_task',
+    'Update a Paper task/action title or status. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      id: z.string(),
+      title: z.string().optional(),
+      status: z.string().optional(),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const payload = cleanBody({ title: args.title, status: args.status });
+        const path = `/api/v1/actions/${encodeURIComponent(args.id)}`;
+        const dry = requireLiveWrite(args, { method: 'PATCH', path, body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('PATCH', path, {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_list_calendar_events',
+    'List Paper calendar events for a UTC ISO-8601 start/end window.',
+    {
+      start: z.string(),
+      end: z.string(),
+    },
+    async (args) => ok(await api('GET', '/api/v2/events/calendar', {
+      params: { start: args.start, end: args.end },
+    })),
+  );
+
+  server.tool(
+    'paper_create_calendar_event',
+    'Create a Paper calendar event. Live writes require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      title: z.string().min(1),
+      startTime: z.string(),
+      endTime: z.string(),
+      location: z.string().optional(),
+      attendees: z.array(z.string()).default([]),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const payload = cleanBody({
+          title: args.title,
+          startTime: args.startTime,
+          endTime: args.endTime,
+          location: args.location,
+          attendees: args.attendees.map((email) => ({ email })),
+        });
+        const dry = requireLiveWrite(args, { method: 'POST', path: '/api/v1/events', body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('POST', '/api/v1/events', {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_list_email_threads',
+    'List Paper inbox thread summaries.',
+    {},
+    async () => ok(await api('GET', '/api/v2/emails/threads')),
+  );
+
+  server.tool(
+    'paper_get_email_thread',
+    'Get messages for a Paper email thread.',
+    { threadId: z.string() },
+    async (args) => ok(await api('GET', `/api/v1/emails/threads/${encodeURIComponent(args.threadId)}`)),
+  );
+
+  server.tool(
+    'paper_send_email',
+    'Send an email from the rep connected mailbox. Live sends require dryRun:false, approved:true, reason, and idempotencyKey.',
+    {
+      to: z.array(z.string()).min(1),
+      subject: z.string().min(1),
+      body: z.string().min(1),
+      threadId: z.string().optional(),
+      ...writeControls,
+    },
+    async (args) => {
+      try {
+        const payload = cleanBody({
+          to: args.to,
+          subject: args.subject,
+          body: args.body,
+          threadId: args.threadId,
+        });
+        const dry = requireLiveWrite(args, { method: 'POST', path: '/api/v2/emails/direct', body: payload });
+        if (dry) return ok(dry);
+        return ok(await api('POST', '/api/v2/emails/direct', {
+          body: payload,
+          headers: mutationHeaders(args, buildMutationHeaders),
+        }));
+      } catch (err) {
+        return ok({ error: true, message: err.message });
+      }
+    },
+  );
+
+  server.tool(
+    'paper_get_company',
+    'Get the company context record Paper shows in calendar and workspace context rails.',
+    { id: z.string() },
+    async (args) => ok(await api('GET', `/api/v1/companies/${encodeURIComponent(args.id)}`)),
+  );
+}