hs_search_contacts

Instructions

Implementation Reference

• src/tools/contacts.ts:10-13 (schema)

  Schema definition for hs_search_contacts: accepts 'query' (string) and optional 'limit' (1-100, default 20).

  export const SearchContactsSchema = z.object({
    query: z.string().describe("Full-text search string (name, email, company, etc.)"),
    limit: z.number().int().min(1).max(100).default(20).optional(),
  });

• src/tools/contacts.ts:15-22 (handler)

  Handler function that calls HubSpot /crm/v3/objects/contacts/search POST API with full-text query, limit, configured properties, and descending sort by lastmodifieddate.

  export async function searchContacts(args: z.infer<typeof SearchContactsSchema>) {
    return hubspot("/crm/v3/objects/contacts/search", "POST", {
      query: args.query,
      limit: args.limit ?? 20,
      properties: CONTACT_PROPS.split(","),
      sorts: [{ propertyName: "lastmodifieddate", direction: "DESCENDING" }],
    });
  }

• src/index.ts:82-87 (registration)

  Registration of hs_search_contacts tool on the MCP server with description, schema shape, and async handler wrapping searchContacts.

  server.tool(
    "hs_search_contacts",
    "Full-text search across contacts by name, email, company, or any indexed field.",
    SearchContactsSchema.shape,
    async (args) => { try { return ok(await searchContacts(args)); } catch (e) { return err(e); } },
  );

• src/index.ts:6-14 (helper)

  Import of SearchContactsSchema and searchContacts from contacts.ts into the registration file.

  // Contacts
  import {
    SearchContactsSchema, searchContacts,
    GetContactSchema, getContact,
    ContactByEmailSchema, contactByEmail,
    RecentContactsSchema, recentContacts,
    CreateContactSchema, createContact,
    UpdateContactSchema, updateContact,
  } from "./tools/contacts.js";

• src/client.ts:16-48 (helper)

  The hubspot() HTTP client used by searchContacts to make API calls to HubSpot.

  export async function hubspot<T = unknown>(
    path: string,
    method: "GET" | "POST" | "PATCH" | "DELETE" = "GET",
    body?: unknown,
    params?: Record<string, string | number | boolean>,
  ): Promise<T> {
    const token = getToken();
  
    let url = `${BASE_URL}${path}`;
    if (params && method === "GET") {
      const qs = new URLSearchParams(
        Object.entries(params).map(([k, v]) => [k, String(v)]),
      ).toString();
      if (qs) url += `?${qs}`;
    }
  
    const res = await fetch(url, {
      method,
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      ...(body && method !== "GET" ? { body: JSON.stringify(body) } : {}),
    });
  
    if (!res.ok) {
      const text = await res.text().catch(() => res.statusText);
      throw new HubSpotError(`HubSpot API error (${res.status}): ${text}`, res.status);
    }
  
    if (res.status === 204) return undefined as T;
    return (await res.json()) as T;
  }