Copper MCP

Instructions

Implementation Reference

• server.js:298-351 (handler)

  Registration and implementation of the 'list_activities' tool, including input schema definition and the handler function logic.

  server.tool(
    "list_activities",
    "Search Copper activities (meeting notes, calls, emails logged against contacts). Filter by parent record, activity type, or date range. Returns resolved parent names. Excludes system activities (assignee/status changes) by default.",
    {
      parent_type: z.enum(["person", "company", "lead", "opportunity", "project", "task"]).optional().describe("Filter by parent entity type"),
      parent_id: z.number().optional().describe("Filter by parent entity ID (requires parent_type)"),
      minimum_activity_date: z.number().optional().describe("Unix timestamp — only activities on or after this date"),
      maximum_activity_date: z.number().optional().describe("Unix timestamp — only activities on or before this date"),
      include_system: z.boolean().optional().describe("Include system activities like assignee/status changes (default: false)"),
      page_size: z.number().optional().describe("Results per page (default 20, max 200)"),
      page_number: z.number().optional().describe("Page number (default 1)"),
    },
    async ({ parent_type, parent_id, minimum_activity_date, maximum_activity_date, include_system, page_size, page_number }) => {
      const body = {};
      if (parent_type && parent_id) body.parent = { id: parent_id, type: parent_type };
      if (minimum_activity_date) body.minimum_activity_date = minimum_activity_date;
      if (maximum_activity_date) body.maximum_activity_date = maximum_activity_date;
      body.page_size = page_size || 200;
      body.page_number = page_number || 1;
  
      const results = await copperFetch("/activities/search", { method: "POST", body });
  
      // Filter out system activities unless explicitly requested
      const filtered = include_system
        ? results
        : results.filter((a) => a.type?.category === "user");
  
      // Resolve parent names
      const nameCache = new Map();
      const activities = await Promise.all(
        filtered.map(async (a) => {
          const parentType = a.parent?.type;
          const parentId = a.parent?.id;
          const parent_name = parentType && parentId
            ? await resolveParentName(parentType, parentId, nameCache)
            : null;
  
          return {
            id: a.id,
            parent: a.parent,
            parent_name,
            type: a.type,
            user_id: a.user_id,
            details: a.details,
            activity_date: a.activity_date,
            date_created: a.date_created,
            date_modified: a.date_modified,
          };
        })
      );
  
      return jsonResult(activities);
    }
  );