resolve_company

Instructions

Implementation Reference

• src/tools.ts:47-82 (registration)

  Registration of the 'resolve_company' tool on the MCP server via server.tool(). This is where the tool name, description, input schema, and handler are all registered together.

  // ─── 1. resolve_company ──────────────────────────────────────────
  server.tool(
    "resolve_company",
    "Resolve a company to an AnchorID using domain, name, city/state, " +
      "or external identifiers. Returns status (resolved | needs_review | not_found), " +
      "confidence score, the canonical AnchorID, match reasons, and any ambiguous candidates.",
    {
      domain: z.string().optional().describe("Company domain (e.g. acme.com)"),
      name: z.string().optional().describe("Company name"),
      city: z.string().optional().describe("City for geo-matching"),
      state: z.string().optional().describe("State for geo-matching"),
      identifiers: z
        .object({
          stripe_customer_id: z.string().optional(),
          salesforce_account_id: z.string().optional(),
          hubspot_company_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/company", input as Record<string, unknown>);
        return jsonContent(data);
      } catch (e) {
        return errorContent(e);
      }
    },
  );

• src/tools.ts:53-73 (schema)

  Input schema for 'resolve_company' using Zod validation. Defines optional fields: domain, name, city, state, identifiers (stripe_customer_id, salesforce_account_id, hubspot_company_id, phone), and min_confidence (0-1).

  {
    domain: z.string().optional().describe("Company domain (e.g. acme.com)"),
    name: z.string().optional().describe("Company name"),
    city: z.string().optional().describe("City for geo-matching"),
    state: z.string().optional().describe("State for geo-matching"),
    identifiers: z
      .object({
        stripe_customer_id: z.string().optional(),
        salesforce_account_id: z.string().optional(),
        hubspot_company_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:74-82 (handler)

  Handler function for 'resolve_company'. Calls the API client's post method to /resolve/company with the input, and returns JSON content or error content.

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

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

  Helper function jsonContent() used by the handler to format successful API responses as MCP text content.

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

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

  Helper function errorContent() used by the handler to format errors as MCP error content with structured metadata.

  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,
    };
  }