xero_payments_get

Instructions

Implementation Reference

• src/domains/payments.ts:31-45 (schema)

  Schema/definition for the 'xero_payments_get' tool. Defines the tool name, description, and inputSchema requiring a 'paymentId' (UUID string).

  {
    name: "xero_payments_get",
    description:
      "Get detailed information about a specific payment by its ID.",
    inputSchema: {
      type: "object",
      properties: {
        paymentId: {
          type: "string",
          description: "The unique payment ID (UUID)",
        },
      },
      required: ["paymentId"],
    },
  },

• src/domains/payments.ts:104-110 (handler)

  Handler function for 'xero_payments_get'. Extracts paymentId from args, calls client.get('Payments/{paymentId}'), and returns the JSON response.

  case "xero_payments_get": {
    const { paymentId } = args as { paymentId: string };
    const response = await client.get(`Payments/${paymentId}`);
    return {
      content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
    };
  }

• src/index.ts:177-198 (registration)

  Tools list registration: getAllDomainTools() collects paymentTools (which includes xero_payments_get) and registers them with the MCP server via ListToolsRequestSchema handler.

  function createMcpServer(): Server {
    const server = new Server(
      {
        name: "xero-mcp",
        version: "1.0.0",
      },
      {
        capabilities: {
          tools: {},
        },
      }
    );
  
    setServerRef(server);
  
    /**
     * Handle ListTools requests - always returns ALL tools
     */
    server.setRequestHandler(ListToolsRequestSchema, async () => {
      const domainTools = getAllDomainTools();
      return { tools: [navigateTool, statusTool, backTool, ...domainTools] };
    });

• src/index.ts:260-263 (registration)

  Tool call routing: the CallToolRequestSchema handler routes 'xero_payments_' prefixed tool names to handlePaymentTool(), which contains the xero_payments_get case.

  }
  if (name.startsWith("xero_payments_")) {
    return await handlePaymentTool(name, toolArgs);
  }

• src/utils/client.ts:29-146 (helper)

  XeroClient class used by the handler. The get() method (lines 83-85) makes authenticated GET requests to the Xero API, called by the xero_payments_get handler.

  class XeroClient {
    private config: XeroClientConfig;
  
    constructor(config: XeroClientConfig) {
      this.config = config;
    }
  
    /**
     * Make an authenticated request to the Xero API
     */
    private async request(
      method: string,
      path: string,
      params?: Record<string, string>,
      body?: unknown
    ): Promise<unknown> {
      let url = `${XERO_API_BASE}/${path}`;
      if (params && Object.keys(params).length > 0) {
        const searchParams = new URLSearchParams(params);
        url += `?${searchParams.toString()}`;
      }
  
      const headers: Record<string, string> = {
        Authorization: `Bearer ${this.config.accessToken}`,
        "xero-tenant-id": this.config.tenantId,
        "Content-Type": "application/json",
        Accept: "application/json",
      };
  
      const options: RequestInit = { method, headers };
      if (body !== undefined) {
        options.body = JSON.stringify(body);
      }
  
      const response = await fetch(url, options);
  
      if (!response.ok) {
        const responseBody = await response.text();
        throw new Error(
          `Xero API error ${method} /${path} (${response.status}): ${responseBody}`
        );
      }
  
      // Handle 204 No Content
      if (response.status === 204) {
        return null;
      }
  
      return response.json();
    }
  
    /**
     * GET request
     */
    async get(path: string, params?: Record<string, string>): Promise<unknown> {
      return this.request("GET", path, params);
    }
  
    /**
     * POST request
     */
    async post(path: string, body: unknown): Promise<unknown> {
      return this.request("POST", path, undefined, body);
    }
  
    /**
     * PUT request
     */
    async put(path: string, body: unknown): Promise<unknown> {
      return this.request("PUT", path, undefined, body);
    }
  
    /**
     * DELETE request
     */
    async delete(path: string): Promise<unknown> {
      return this.request("DELETE", path);
    }
  
    /**
     * Fetch all pages of a paginated endpoint.
     * Xero uses 1-based page numbers and returns 100 items per page.
     * Returns the combined items from all pages.
     */
    async getPaginated(
      path: string,
      params?: Record<string, string>,
      responseKey?: string
    ): Promise<unknown[]> {
      const allItems: unknown[] = [];
      let page = 1;
      let hasMore = true;
  
      while (hasMore) {
        const response = (await this.get(path, {
          ...params,
          page: String(page),
        })) as Record<string, unknown>;
  
        // Xero wraps responses in a key matching the resource name
        const items = responseKey
          ? (response[responseKey] as unknown[])
          : (Object.values(response).find((v) => Array.isArray(v)) as
              | unknown[]
              | undefined);
  
        if (items && items.length > 0) {
          allItems.push(...items);
          hasMore = items.length >= XERO_PAGE_SIZE;
          page++;
        } else {
          hasMore = false;
        }
      }
  
      return allItems;
    }
  }