Siigo MCP Server

Instructions

Implementation Reference

• src/index.ts:854-864 (handler)

  MCP tool handler for 'siigo_get_customer' that extracts the customer ID from args, calls SiigoClient.getCustomer, and returns the JSON-stringified result as text content.

  private async handleGetCustomer(args: any) {
    const result = await this.siigoClient.getCustomer(args.id);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/siigo-client.ts:86-89 (handler)

  Core handler in SiigoClient that performs the authenticated GET request to the Siigo API endpoint `/v1/customers/{id}` using the generic makeRequest method.

  async getCustomer(id: string): Promise<SiigoApiResponse<SiigoCustomer>> {
    return this.makeRequest<SiigoCustomer>('GET', `/v1/customers/${id}`);
  }

• src/index.ts:286-296 (registration)

  Tool registration in getTools() method, including name, description, and input schema for validation.

  {
    name: 'siigo_get_customer',
    description: 'Get a specific customer by ID',
    inputSchema: {
      type: 'object',
      properties: {
        id: { type: 'string', description: 'Customer ID' },
      },
      required: ['id'],
    },
  },

• src/types.ts:15-57 (schema)

  TypeScript interface defining the structure of a Siigo customer object, used for type safety in the getCustomer response.

  export interface SiigoCustomer {
    id?: string;
    type?: 'Customer' | 'Supplier' | 'Other';
    person_type: 'Person' | 'Company';
    id_type: string;
    identification: string;
    check_digit?: string;
    name: string[];
    commercial_name?: string;
    branch_office?: number;
    active?: boolean;
    vat_responsible?: boolean;
    fiscal_responsibilities?: Array<{ code: string }>;
    address: {
      address: string;
      city: {
        country_code: string;
        state_code: string;
        city_code: string;
      };
      postal_code?: string;
    };
    phones: Array<{
      indicative?: string;
      number: string;
      extension?: string;
    }>;
    contacts: Array<{
      first_name: string;
      last_name: string;
      email: string;
      phone?: {
        indicative?: string;
        number?: string;
        extension?: string;
      };
    }>;
    comments?: string;
    related_users?: {
      seller_id?: number;
      collector_id?: number;
    };
  }

• src/siigo-client.ts:41-59 (helper)

  Generic helper method that handles authentication, makes the Axios HTTP request to Siigo API, and processes responses or errors uniformly.

  private async makeRequest<T>(method: string, endpoint: string, data?: any, params?: any): Promise<SiigoApiResponse<T>> {
    await this.authenticate();
  
    try {
      const response: AxiosResponse<SiigoApiResponse<T>> = await this.httpClient.request({
        method,
        url: endpoint,
        data,
        params,
      });
  
      return response.data;
    } catch (error: any) {
      if (error.response?.data) {
        return error.response.data;
      }
      throw new Error(`API request failed: ${error.message}`);
    }
  }