create-contact

Instructions

Implementation Reference

• src/tools/create/create-contact.tool.ts:7-64 (handler)

  Primary handler for the 'create-contact' tool: defines the tool name, description, Zod input schema, and the async execution function that handles contact creation, error cases, deep link generation, and response formatting.

  const CreateContactTool = CreateXeroTool(
    "create-contact",
    "Create a contact in Xero.\
    When a contact is created, a deep link to the contact in Xero is returned. \
    This deep link can be used to view the contact in Xero directly. \
    This link should be displayed to the user.",
    {
      name: z.string(),
      email: z.string().email().optional(),
      phone: z.string().optional(),
    },
    async ({ name, email, phone }) => {
      try {
        const response = await createXeroContact(name, email, phone);
        if (response.isError) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error creating contact: ${response.error}`,
              },
            ],
          };
        }
  
        const contact = response.result;
  
        const deepLink = contact.contactID
          ? await getDeepLink(DeepLinkType.CONTACT, contact.contactID)
          : null;
  
        return {
          content: [
            {
              type: "text" as const,
              text: [
                `Contact created: ${contact.name} (ID: ${contact.contactID})`,
                deepLink ? `Link to view: ${deepLink}` : null,
              ]
                .filter(Boolean)
                .join("\n"),
            },
          ],
        };
      } catch (error) {
        const err = ensureError(error);
  
        return {
          content: [
            {
              type: "text" as const,
              text: `Error creating contact: ${err.message}`,
            },
          ],
        };
      }
    },
  );

• src/tools/create/index.ts:13-25 (registration)

  Registers 'create-contact' tool by importing CreateContactTool and including it in the CreateTools array, which is exported and later used for MCP server tool registration.

  export const CreateTools = [
    CreateContactTool,
    CreateCreditNoteTool,
    CreateManualJournalTool,
    CreateInvoiceTool,
    CreateQuoteTool,
    CreatePaymentTool,
    CreateItemTool,
    CreateBankTransactionTool,
    CreatePayrollTimesheetTool,
    CreateTrackingCategoryTool,
    CreateTrackingOptionsTool
  ];

• src/tools/tool-factory.ts:17-19 (registration)

  Top-level registration: iterates over CreateTools (including create-contact), instantiates each tool factory, and registers them on the MCP server using server.tool(name, description, schema, handler).

  CreateTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );

• src/handlers/create-xero-contact.handler.ts:43-67 (helper)

  Core helper function that orchestrates contact creation: calls internal createContact API wrapper, handles success/error responses in XeroClientResponse format.

  export async function createXeroContact(
    name: string,
    email?: string,
    phone?: string,
  ): Promise<XeroClientResponse<Contact>> {
    try {
      const createdContact = await createContact(name, email, phone);
  
      if (!createdContact) {
        throw new Error("Contact creation failed.");
      }
  
      return {
        result: createdContact,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  }

• src/handlers/create-xero-contact.handler.ts:7-38 (helper)

  Low-level helper that constructs Contact object and calls Xero API to create contacts.

  async function createContact(
    name: string,
    email?: string,
    phone?: string,
  ): Promise<Contact | undefined> {
    await xeroClient.authenticate();
  
    const contact: Contact = {
      name,
      emailAddress: email,
      phones: phone
        ? [
            {
              phoneNumber: phone,
              phoneType: Phone.PhoneTypeEnum.MOBILE,
            },
          ]
        : undefined,
    };
  
    const response = await xeroClient.accountingApi.createContacts(
      xeroClient.tenantId,
      {
        contacts: [contact],
      }, //contacts
      true, //summarizeErrors
      undefined, //idempotencyKey
      getClientHeaders(), // options
    );
  
    return response.body.contacts?.[0];
  }