Siigo MCP Server

Instructions

Implementation Reference

• src/siigo-client.ts:91-93 (handler)

  The core handler function that performs the POST request to Siigo API endpoint /v1/customers to create a customer.
  async createCustomer(customer: SiigoCustomer): Promise<SiigoApiResponse<SiigoCustomer>> { return this.makeRequest<SiigoCustomer>('POST', '/v1/customers', customer); }
• src/index.ts:866-876 (handler)

  MCP tool execution handler in the server that delegates to SiigoClient.createCustomer and formats the response.
  private async handleCreateCustomer(args: any) { const result = await this.siigoClient.createCustomer(args.customer); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/index.ts:297-335 (schema)

  Tool definition including the input schema (JSON Schema) for validating tool arguments.
  { name: 'siigo_create_customer', description: 'Create a new customer', inputSchema: { type: 'object', properties: { customer: { type: 'object', description: 'Customer data', properties: { person_type: { type: 'string', enum: ['Person', 'Company'] }, id_type: { type: 'string', description: 'ID type code' }, identification: { type: 'string', description: 'Customer identification' }, name: { type: 'array', items: { type: 'string' }, description: 'Customer names' }, address: { type: 'object', properties: { address: { type: 'string' }, city: { type: 'object', properties: { country_code: { type: 'string' }, state_code: { type: 'string' }, city_code: { type: 'string' }, }, required: ['country_code', 'state_code', 'city_code'], }, }, required: ['address', 'city'], }, phones: { type: 'array', items: { type: 'object' } }, contacts: { type: 'array', items: { type: 'object' } }, }, required: ['person_type', 'id_type', 'identification', 'name', 'address', 'phones', 'contacts'], }, }, required: ['customer'], }, },
• src/index.ts:77-78 (registration)

  Dispatch case in the CallToolRequest handler that routes to the specific tool handler.
  case 'siigo_create_customer': return await this.handleCreateCustomer(args);
• src/types.ts:15-57 (schema)

  TypeScript interface defining the full SiigoCustomer structure used in the API calls.
  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 for making authenticated API requests to Siigo, used by createCustomer.
  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}`); } }