resolve_person

Instructions

Implementation Reference

• src/tools.ts:126-169 (registration)

  Registration of the 'resolve_person' tool on the MCP server via server.tool(), including Zod schema definition for inputs (email, name, company_entity_id, company_domain, identifiers, min_confidence) and the handler callback.

  // ─── 3. resolve_person ───────────────────────────────────────────
  server.tool(
    "resolve_person",
    "Resolve a person to an AnchorID using email, name, company domain, " +
      "or external identifiers (Slack/Google user IDs). " +
      "Returns status (resolved | needs_review | not_found), " +
      "confidence score, the canonical AnchorID, match reasons, and any ambiguous candidates.",
    {
      email: z.string().optional().describe("Person's email address"),
      name: z.string().optional().describe("Person's full name"),
      company_entity_id: z
        .string()
        .optional()
        .describe("Resolved company AnchorID (UUID) for name+company matching"),
      company_domain: z
        .string()
        .optional()
        .describe("Company domain for name+company matching"),
      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()
        .describe("External system identifiers"),
      min_confidence: z
        .number()
        .min(0)
        .max(1)
        .optional()
        .describe("Minimum confidence threshold (0-1)"),
    },
    async (input) => {
      try {
        const data = await api.post("/resolve/person", input as Record<string, unknown>);
        return jsonContent(data);
      } catch (e) {
        return errorContent(e);
      }
    },
  );

• src/tools.ts:161-168 (handler)

  Handler function for resolve_person: calls api.post('/resolve/person', input) and returns the JSON response, with error handling via try/catch.

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

• src/tools.ts:133-160 (schema)

  Zod input schema for resolve_person defining 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 (0-1).

  {
    email: z.string().optional().describe("Person's email address"),
    name: z.string().optional().describe("Person's full name"),
    company_entity_id: z
      .string()
      .optional()
      .describe("Resolved company AnchorID (UUID) for name+company matching"),
    company_domain: z
      .string()
      .optional()
      .describe("Company domain for name+company matching"),
    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()
      .describe("External system identifiers"),
    min_confidence: z
      .number()
      .min(0)
      .max(1)
      .optional()
      .describe("Minimum confidence threshold (0-1)"),
  },

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

  Helper functions jsonContent and errorContent used by the handler to format API responses as MCP tool content.

  /** Format the API response as MCP tool content. */
  function jsonContent(data: unknown) {
    return {
      content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
    };
  }
  
  /** Format an error as MCP tool content (isError flag). */
  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,
    };
  }

• src/api-client.ts:63-71 (helper)

  The ApiClient.post method that the handler delegates to, sending a POST request to the AnchorID REST API at /api/v1/resolve/person.

  async post<T = unknown>(path: string, body: Record<string, unknown>): Promise<T> {
    const requestId = this.generateRequestId();
    const res = await fetch(`${this.baseUrl}/api/v1${path}`, {
      method: "POST",
      headers: this.headers(requestId),
      body: JSON.stringify(body),
    });
    return this.parse<T>(res, requestId);
  }