resolve_person_batch

Instructions

Implementation Reference

• src/tools.ts:171-212 (registration)

  The tool 'resolve_person_batch' is registered via server.tool() call on line 172 within the registerTools() function. The registration includes the tool name, description, Zod schema for inputs (items array of person resolution requests, max 200), and the async handler function.

  // ─── 4. resolve_person_batch ─────────────────────────────────────
  server.tool(
    "resolve_person_batch",
    "Resolve multiple people to AnchorIDs in a single call (max 200). " +
      "Each item needs a client_ref for correlation and at least one identifying field. " +
      "Ambiguous matches return status needs_review with candidate AnchorIDs.",
    {
      items: z
        .array(
          z.object({
            client_ref: z.string().describe("Your reference ID for correlation"),
            email: z.string().optional(),
            name: z.string().optional(),
            company_entity_id: z.string().optional(),
            company_domain: z.string().optional(),
            identifiers: z
              .object({
                slack_user_id: z.string().optional(),
                google_user_id: z.string().optional(),
                salesforce_contact_id: z.string().optional(),
                hubspot_contact_id: z.string().optional(),
                phone: z.string().optional(),
              })
              .optional(),
            min_confidence: z.number().min(0).max(1).optional(),
          }),
        )
        .max(200)
        .describe("Array of person resolution requests"),
    },
    async (input) => {
      try {
        const data = await api.post(
          "/resolve/person:batch",
          input as Record<string, unknown>,
        );
        return jsonContent(data);
      } catch (e) {
        return errorContent(e);
      }
    },
  );

• src/tools.ts:201-211 (handler)

  The handler for 'resolve_person_batch' (lines 201-211) is an async function that posts the input to '/resolve/person:batch' via the ApiClient, returning JSON content on success or error content on failure. It catches errors and delegates formatting to helper functions.

  async (input) => {
    try {
      const data = await api.post(
        "/resolve/person:batch",
        input as Record<string, unknown>,
      );
      return jsonContent(data);
    } catch (e) {
      return errorContent(e);
    }
  },

• src/tools.ts:177-200 (schema)

  The input schema for 'resolve_person_batch' uses Zod to define an 'items' array (max 200 items). Each item requires a 'client_ref' string and has optional fields: email, name, company_entity_id, company_domain, identifiers (slack_user_id, google_user_id, salesforce_contact_id, hubspot_contact_id, phone), and min_confidence.

  {
    items: z
      .array(
        z.object({
          client_ref: z.string().describe("Your reference ID for correlation"),
          email: z.string().optional(),
          name: z.string().optional(),
          company_entity_id: z.string().optional(),
          company_domain: z.string().optional(),
          identifiers: z
            .object({
              slack_user_id: z.string().optional(),
              google_user_id: z.string().optional(),
              salesforce_contact_id: z.string().optional(),
              hubspot_contact_id: z.string().optional(),
              phone: z.string().optional(),
            })
            .optional(),
          min_confidence: z.number().min(0).max(1).optional(),
        }),
      )
      .max(200)
      .describe("Array of person resolution requests"),
  },

• src/tools.ts:18-22 (helper)

  The jsonContent() helper function formats successful API responses as MCP tool text content. Used by the handler to return results.

  function jsonContent(data: unknown) {
    return {
      content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
    };
  }

• src/tools.ts:25-42 (helper)

  The errorContent() helper function formats errors (especially ApiError instances) as MCP tool error content with isError flag. Used by the handler for error reporting.

  function errorContent(err: unknown) {
    if (err instanceof ApiError) {
      const payload = {
        error: err.message,
        status_code: err.status_code,
        request_id: err.request_id,
        details: err.details,
      };
      return {
        content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
        isError: true,
      };
    }
    return {
      content: [{ type: "text" as const, text: (err as Error).message ?? String(err) }],
      isError: true,
    };
  }