GoHighLevel MCP Server

/** * GoHighLevel Store API Tools for MCP Server * Provides comprehensive tools for managing store shipping zones, rates, carriers, and settings */ import { // MCP Types MCPCreateShippingZoneParams, MCPListShippingZonesParams, MCPGetShippingZoneParams, MCPUpdateShippingZoneParams, MCPDeleteShippingZoneParams, MCPCreateShippingRateParams, MCPListShippingRatesParams, MCPGetShippingRateParams, MCPUpdateShippingRateParams, MCPDeleteShippingRateParams, MCPGetAvailableShippingRatesParams, MCPCreateShippingCarrierParams, MCPListShippingCarriersParams, MCPGetShippingCarrierParams, MCPUpdateShippingCarrierParams, MCPDeleteShippingCarrierParams, MCPCreateStoreSettingParams, MCPGetStoreSettingParams, // API Client Types GHLCreateShippingZoneRequest, GHLUpdateShippingZoneRequest, GHLGetShippingZonesRequest, GHLDeleteShippingZoneRequest, GHLCreateShippingRateRequest, GHLUpdateShippingRateRequest, GHLGetShippingRatesRequest, GHLDeleteShippingRateRequest, GHLGetAvailableShippingRatesRequest, GHLCreateShippingCarrierRequest, GHLUpdateShippingCarrierRequest, GHLGetShippingCarriersRequest, GHLDeleteShippingCarrierRequest, GHLCreateStoreSettingRequest, GHLGetStoreSettingRequest, GHLCountryCode, GHLStateCode } from '../types/ghl-types.js'; import { GHLApiClient } from '../clients/ghl-api-client.js'; import { Tool } from '@modelcontextprotocol/sdk/types.js'; export interface StoreToolResult { content: { type: 'text'; text: string; }[]; } export class StoreTools { constructor(private apiClient: GHLApiClient) {} /** * SHIPPING ZONES TOOLS */ /** * Create a new shipping zone */ async createShippingZone(params: MCPCreateShippingZoneParams): Promise<StoreToolResult> { try { const request: GHLCreateShippingZoneRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', name: params.name, countries: params.countries }; const response = await this.apiClient.createShippingZone(request); const zoneInfo = response.data?.data; if (!zoneInfo) { throw new Error('No shipping zone data returned from API'); } return { content: [{ type: 'text', text: `✅ **Shipping Zone Created Successfully** **Zone Details:** - **ID:** ${zoneInfo._id} - **Name:** ${zoneInfo.name} - **Countries:** ${zoneInfo.countries.length} country(ies) configured - **Created:** ${new Date(zoneInfo.createdAt).toLocaleString()} **Countries Configured:** ${zoneInfo.countries.map(country => { const states = country.states && country.states.length > 0 ? ` (${country.states.length} states)` : ' (All states)'; return `• ${country.code}${states}`; }).join('\n')} The shipping zone is now active and ready to use with shipping rates.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Creating Shipping Zone**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * List all shipping zones */ async listShippingZones(params: MCPListShippingZonesParams): Promise<StoreToolResult> { try { const request: GHLGetShippingZonesRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', limit: params.limit, offset: params.offset, withShippingRate: params.withShippingRate }; const response = await this.apiClient.listShippingZones(request); const zones = response.data?.data || []; if (zones.length === 0) { return { content: [{ type: 'text', text: `📦 **No Shipping Zones Found** No shipping zones are currently configured for this location. Create your first shipping zone to start managing shipping rates.` }] }; } return { content: [{ type: 'text', text: `📦 **Shipping Zones (${response.data?.total || zones.length} total)** ${zones.map((zone, index) => `**${index + 1}. ${zone.name}** - **ID:** ${zone._id} - **Countries:** ${zone.countries.length} configured - **Shipping Rates:** ${zone.shippingRates?.length || 0} - **Created:** ${new Date(zone.createdAt).toLocaleString()} ${zone.countries.map(country => { const states = country.states && country.states.length > 0 ? ` (${country.states.length} states)` : ' (All states)'; return ` • ${country.code}${states}`; }).join('\n')} `).join('\n')} 💡 Use the shipping zone IDs to manage specific zones or create shipping rates.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Listing Shipping Zones**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Get a specific shipping zone */ async getShippingZone(params: MCPGetShippingZoneParams): Promise<StoreToolResult> { try { const request: Omit<GHLGetShippingZonesRequest, 'limit' | 'offset'> = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', withShippingRate: params.withShippingRate }; const response = await this.apiClient.getShippingZone(params.shippingZoneId, request); const zone = response.data?.data; if (!zone) { throw new Error('Shipping zone not found'); } return { content: [{ type: 'text', text: `📦 **Shipping Zone Details** **Zone Information:** - **ID:** ${zone._id} - **Name:** ${zone.name} - **Created:** ${new Date(zone.createdAt).toLocaleString()} - **Updated:** ${new Date(zone.updatedAt).toLocaleString()} **Countries & Regions (${zone.countries.length}):** ${zone.countries.map(country => { const states = country.states && country.states.length > 0 ? `\n States: ${country.states.map(s => s.code).join(', ')}` : '\n States: All states included'; return `• **${country.code}**${states}`; }).join('\n')} ${zone.shippingRates ? `**Shipping Rates (${zone.shippingRates.length}):** ${zone.shippingRates.map((rate, index) => `${index + 1}. **${rate.name}** - Rate: ${rate.currency} ${rate.amount} - Condition: ${rate.conditionType} - Carrier Rate: ${rate.isCarrierRate ? 'Yes' : 'No'} `).join('\n')}` : ''} Use this zone ID to create shipping rates or update zone configuration.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Getting Shipping Zone**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Update a shipping zone */ async updateShippingZone(params: MCPUpdateShippingZoneParams): Promise<StoreToolResult> { try { const request: GHLUpdateShippingZoneRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; if (params.name) request.name = params.name; if (params.countries) request.countries = params.countries; const response = await this.apiClient.updateShippingZone(params.shippingZoneId, request); const zone = response.data?.data; if (!zone) { throw new Error('No shipping zone data returned from update'); } return { content: [{ type: 'text', text: `✅ **Shipping Zone Updated Successfully** **Updated Zone:** - **ID:** ${zone._id} - **Name:** ${zone.name} - **Countries:** ${zone.countries.length} configured - **Last Updated:** ${new Date(zone.updatedAt).toLocaleString()} **Current Countries:** ${zone.countries.map(country => { const states = country.states && country.states.length > 0 ? ` (${country.states.length} states)` : ' (All states)'; return `• ${country.code}${states}`; }).join('\n')} The shipping zone configuration has been updated successfully.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Updating Shipping Zone**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Delete a shipping zone */ async deleteShippingZone(params: MCPDeleteShippingZoneParams): Promise<StoreToolResult> { try { const request: GHLDeleteShippingZoneRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; const response = await this.apiClient.deleteShippingZone(params.shippingZoneId, request); return { content: [{ type: 'text', text: `✅ **Shipping Zone Deleted Successfully** **Zone ID:** ${params.shippingZoneId} The shipping zone and all associated shipping rates have been permanently deleted. This action cannot be undone. ⚠️ **Note:** Any existing orders using this shipping zone may be affected. Please ensure you have alternative shipping options configured.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Deleting Shipping Zone**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * SHIPPING RATES TOOLS */ /** * Get available shipping rates for an order */ async getAvailableShippingRates(params: MCPGetAvailableShippingRatesParams): Promise<StoreToolResult> { try { const request: GHLGetAvailableShippingRatesRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', country: params.country, address: params.address, totalOrderAmount: params.totalOrderAmount, totalOrderWeight: params.totalOrderWeight, source: params.source, products: params.products, couponCode: params.couponCode }; const response = await this.apiClient.getAvailableShippingRates(request); const rates = response.data?.data || []; if (rates.length === 0) { return { content: [{ type: 'text', text: `📦 **No Shipping Rates Available** No shipping rates are available for the specified order criteria: - **Country:** ${params.country} - **Order Amount:** $${params.totalOrderAmount} - **Order Weight:** ${params.totalOrderWeight} kg - **Products:** ${params.products.length} item(s) Please check your shipping zone configuration or contact support.` }] }; } return { content: [{ type: 'text', text: `📦 **Available Shipping Rates (${rates.length})** **Order Summary:** - **Country:** ${params.country} - **Order Amount:** $${params.totalOrderAmount} - **Order Weight:** ${params.totalOrderWeight} kg - **Products:** ${params.products.length} item(s) **Available Shipping Options:** ${rates.map((rate, index) => `**${index + 1}. ${rate.name}** - **Cost:** ${rate.currency} ${rate.amount}${rate.isCarrierRate ? ' (+ carrier fees)' : ''} - **Type:** ${rate.isCarrierRate ? 'Carrier Rate' : 'Fixed Rate'} - **Zone ID:** ${rate.shippingZoneId} - **Rate ID:** ${rate._id} ${rate.description ? `- **Description:** ${rate.description}` : ''} ${rate.shippingCarrierServices && rate.shippingCarrierServices.length > 0 ? `- **Services:** ${rate.shippingCarrierServices.map(s => s.name).join(', ')}` : ''} `).join('\n')} Select the appropriate shipping rate for checkout.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Getting Available Shipping Rates**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Create a shipping rate */ async createShippingRate(params: MCPCreateShippingRateParams): Promise<StoreToolResult> { try { const request: GHLCreateShippingRateRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', name: params.name, description: params.description, currency: params.currency, amount: params.amount, conditionType: params.conditionType, minCondition: params.minCondition, maxCondition: params.maxCondition, isCarrierRate: params.isCarrierRate, shippingCarrierId: params.shippingCarrierId, percentageOfRateFee: params.percentageOfRateFee, shippingCarrierServices: params.shippingCarrierServices }; const response = await this.apiClient.createShippingRate(params.shippingZoneId, request); const rate = response.data?.data; if (!rate) { throw new Error('No shipping rate data returned from API'); } return { content: [{ type: 'text', text: `✅ **Shipping Rate Created Successfully** **Rate Details:** - **ID:** ${rate._id} - **Name:** ${rate.name} - **Zone ID:** ${rate.shippingZoneId} - **Cost:** ${rate.currency} ${rate.amount} - **Condition Type:** ${rate.conditionType} ${rate.minCondition ? `- **Min Condition:** ${rate.minCondition}` : ''} ${rate.maxCondition ? `- **Max Condition:** ${rate.maxCondition}` : ''} - **Carrier Rate:** ${rate.isCarrierRate ? 'Yes' : 'No'} ${rate.description ? `- **Description:** ${rate.description}` : ''} - **Created:** ${new Date(rate.createdAt).toLocaleString()} ${rate.shippingCarrierServices && rate.shippingCarrierServices.length > 0 ? `**Carrier Services:** ${rate.shippingCarrierServices.map(service => `• ${service.name} (${service.value})`).join('\n')}` : ''} The shipping rate is now active and available for orders.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Creating Shipping Rate**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * List shipping rates for a zone */ async listShippingRates(params: MCPListShippingRatesParams): Promise<StoreToolResult> { try { const request: GHLGetShippingRatesRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', limit: params.limit, offset: params.offset }; const response = await this.apiClient.listShippingRates(params.shippingZoneId, request); const rates = response.data?.data || []; if (rates.length === 0) { return { content: [{ type: 'text', text: `📦 **No Shipping Rates Found** No shipping rates are configured for zone: ${params.shippingZoneId} Create shipping rates to enable shipping options for this zone.` }] }; } return { content: [{ type: 'text', text: `📦 **Shipping Rates for Zone ${params.shippingZoneId} (${response.data?.total || rates.length} total)** ${rates.map((rate, index) => `**${index + 1}. ${rate.name}** - **ID:** ${rate._id} - **Cost:** ${rate.currency} ${rate.amount} - **Condition:** ${rate.conditionType}${rate.minCondition ? ` (min: ${rate.minCondition})` : ''}${rate.maxCondition ? ` (max: ${rate.maxCondition})` : ''} - **Type:** ${rate.isCarrierRate ? 'Carrier Rate' : 'Fixed Rate'} - **Created:** ${new Date(rate.createdAt).toLocaleString()} ${rate.description ? `- **Description:** ${rate.description}` : ''} `).join('\n')} Use rate IDs to update or delete specific shipping rates.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Listing Shipping Rates**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Get a specific shipping rate */ async getShippingRate(params: MCPGetShippingRateParams): Promise<StoreToolResult> { try { const request: Omit<GHLGetShippingRatesRequest, 'limit' | 'offset'> = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; const response = await this.apiClient.getShippingRate( params.shippingZoneId, params.shippingRateId, request ); const rate = response.data?.data; if (!rate) { throw new Error('Shipping rate not found'); } return { content: [{ type: 'text', text: `📦 **Shipping Rate Details** **Rate Information:** - **ID:** ${rate._id} - **Name:** ${rate.name} - **Zone ID:** ${rate.shippingZoneId} - **Cost:** ${rate.currency} ${rate.amount} - **Condition Type:** ${rate.conditionType} ${rate.minCondition ? `- **Min Condition:** ${rate.minCondition}` : ''} ${rate.maxCondition ? `- **Max Condition:** ${rate.maxCondition}` : ''} - **Carrier Rate:** ${rate.isCarrierRate ? 'Yes' : 'No'} ${rate.percentageOfRateFee ? `- **Carrier Fee %:** ${rate.percentageOfRateFee}%` : ''} ${rate.description ? `- **Description:** ${rate.description}` : ''} - **Created:** ${new Date(rate.createdAt).toLocaleString()} - **Updated:** ${new Date(rate.updatedAt).toLocaleString()} ${rate.shippingCarrierServices && rate.shippingCarrierServices.length > 0 ? `**Carrier Services:** ${rate.shippingCarrierServices.map(service => `• **${service.name}** (${service.value})`).join('\n')}` : ''} Use this rate information to manage shipping configurations.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Getting Shipping Rate**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Update a shipping rate */ async updateShippingRate(params: MCPUpdateShippingRateParams): Promise<StoreToolResult> { try { const request: GHLUpdateShippingRateRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; // Only include provided parameters if (params.name !== undefined) request.name = params.name; if (params.description !== undefined) request.description = params.description; if (params.currency !== undefined) request.currency = params.currency; if (params.amount !== undefined) request.amount = params.amount; if (params.conditionType !== undefined) request.conditionType = params.conditionType; if (params.minCondition !== undefined) request.minCondition = params.minCondition; if (params.maxCondition !== undefined) request.maxCondition = params.maxCondition; if (params.isCarrierRate !== undefined) request.isCarrierRate = params.isCarrierRate; if (params.shippingCarrierId !== undefined) request.shippingCarrierId = params.shippingCarrierId; if (params.percentageOfRateFee !== undefined) request.percentageOfRateFee = params.percentageOfRateFee; if (params.shippingCarrierServices !== undefined) request.shippingCarrierServices = params.shippingCarrierServices; const response = await this.apiClient.updateShippingRate( params.shippingZoneId, params.shippingRateId, request ); const rate = response.data?.data; if (!rate) { throw new Error('No shipping rate data returned from update'); } return { content: [{ type: 'text', text: `✅ **Shipping Rate Updated Successfully** **Updated Rate:** - **ID:** ${rate._id} - **Name:** ${rate.name} - **Zone ID:** ${rate.shippingZoneId} - **Cost:** ${rate.currency} ${rate.amount} - **Condition Type:** ${rate.conditionType} ${rate.minCondition ? `- **Min Condition:** ${rate.minCondition}` : ''} ${rate.maxCondition ? `- **Max Condition:** ${rate.maxCondition}` : ''} - **Carrier Rate:** ${rate.isCarrierRate ? 'Yes' : 'No'} ${rate.description ? `- **Description:** ${rate.description}` : ''} - **Last Updated:** ${new Date(rate.updatedAt).toLocaleString()} The shipping rate configuration has been updated successfully.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Updating Shipping Rate**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Delete a shipping rate */ async deleteShippingRate(params: MCPDeleteShippingRateParams): Promise<StoreToolResult> { try { const request: GHLDeleteShippingRateRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; const response = await this.apiClient.deleteShippingRate( params.shippingZoneId, params.shippingRateId, request ); return { content: [{ type: 'text', text: `✅ **Shipping Rate Deleted Successfully** **Deleted Rate:** - **Zone ID:** ${params.shippingZoneId} - **Rate ID:** ${params.shippingRateId} The shipping rate has been permanently deleted. This action cannot be undone. ⚠️ **Note:** This shipping option will no longer be available for new orders.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Deleting Shipping Rate**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * SHIPPING CARRIERS TOOLS */ /** * Create a shipping carrier */ async createShippingCarrier(params: MCPCreateShippingCarrierParams): Promise<StoreToolResult> { try { const request: GHLCreateShippingCarrierRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', name: params.name, callbackUrl: params.callbackUrl, services: params.services, allowsMultipleServiceSelection: params.allowsMultipleServiceSelection }; const response = await this.apiClient.createShippingCarrier(request); const carrier = response.data?.data; if (!carrier) { throw new Error('No shipping carrier data returned from API'); } return { content: [{ type: 'text', text: `✅ **Shipping Carrier Created Successfully** **Carrier Details:** - **ID:** ${carrier._id} - **Name:** ${carrier.name} - **Callback URL:** ${carrier.callbackUrl} - **Multiple Services:** ${carrier.allowsMultipleServiceSelection ? 'Allowed' : 'Single Service Only'} - **Marketplace App ID:** ${carrier.marketplaceAppId} - **Created:** ${new Date(carrier.createdAt).toLocaleString()} ${carrier.services && carrier.services.length > 0 ? `**Available Services (${carrier.services.length}):** ${carrier.services.map(service => `• **${service.name}** (${service.value})`).join('\n')}` : '**No services configured**'} The shipping carrier is now available for creating carrier-based shipping rates.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Creating Shipping Carrier**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * List all shipping carriers */ async listShippingCarriers(params: MCPListShippingCarriersParams): Promise<StoreToolResult> { try { const request: GHLGetShippingCarriersRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; const response = await this.apiClient.listShippingCarriers(request); const carriers = response.data?.data || []; if (carriers.length === 0) { return { content: [{ type: 'text', text: `🚚 **No Shipping Carriers Found** No shipping carriers are currently configured for this location. Create shipping carriers to enable carrier-based shipping rates.` }] }; } return { content: [{ type: 'text', text: `🚚 **Shipping Carriers (${carriers.length})** ${carriers.map((carrier, index) => `**${index + 1}. ${carrier.name}** - **ID:** ${carrier._id} - **Callback URL:** ${carrier.callbackUrl} - **Multiple Services:** ${carrier.allowsMultipleServiceSelection ? 'Yes' : 'No'} - **Services:** ${carrier.services?.length || 0} configured - **Created:** ${new Date(carrier.createdAt).toLocaleString()} ${carrier.services && carrier.services.length > 0 ? ` **Services:** ${carrier.services.map(s => ` • ${s.name} (${s.value})`).join('\n')}` : ''} `).join('\n')} Use carrier IDs to create carrier-based shipping rates or manage carrier configurations.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Listing Shipping Carriers**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Get a specific shipping carrier */ async getShippingCarrier(params: MCPGetShippingCarrierParams): Promise<StoreToolResult> { try { const request: GHLGetShippingCarriersRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; const response = await this.apiClient.getShippingCarrier(params.shippingCarrierId, request); const carrier = response.data?.data; if (!carrier) { throw new Error('Shipping carrier not found'); } return { content: [{ type: 'text', text: `🚚 **Shipping Carrier Details** **Carrier Information:** - **ID:** ${carrier._id} - **Name:** ${carrier.name} - **Callback URL:** ${carrier.callbackUrl} - **Multiple Service Selection:** ${carrier.allowsMultipleServiceSelection ? 'Allowed' : 'Single Service Only'} - **Marketplace App ID:** ${carrier.marketplaceAppId} - **Created:** ${new Date(carrier.createdAt).toLocaleString()} - **Updated:** ${new Date(carrier.updatedAt).toLocaleString()} ${carrier.services && carrier.services.length > 0 ? `**Available Services (${carrier.services.length}):** ${carrier.services.map(service => `• **${service.name}** - Value: ${service.value} `).join('\n')}` : '**No services configured**'} Use this carrier to create dynamic shipping rates based on real-time carrier pricing.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Getting Shipping Carrier**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Update a shipping carrier */ async updateShippingCarrier(params: MCPUpdateShippingCarrierParams): Promise<StoreToolResult> { try { const request: GHLUpdateShippingCarrierRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; // Only include provided parameters if (params.name !== undefined) request.name = params.name; if (params.callbackUrl !== undefined) request.callbackUrl = params.callbackUrl; if (params.services !== undefined) request.services = params.services; if (params.allowsMultipleServiceSelection !== undefined) request.allowsMultipleServiceSelection = params.allowsMultipleServiceSelection; const response = await this.apiClient.updateShippingCarrier(params.shippingCarrierId, request); const carrier = response.data?.data; if (!carrier) { throw new Error('No shipping carrier data returned from update'); } return { content: [{ type: 'text', text: `✅ **Shipping Carrier Updated Successfully** **Updated Carrier:** - **ID:** ${carrier._id} - **Name:** ${carrier.name} - **Callback URL:** ${carrier.callbackUrl} - **Multiple Services:** ${carrier.allowsMultipleServiceSelection ? 'Allowed' : 'Single Service Only'} - **Last Updated:** ${new Date(carrier.updatedAt).toLocaleString()} ${carrier.services && carrier.services.length > 0 ? `**Services (${carrier.services.length}):** ${carrier.services.map(service => `• ${service.name} (${service.value})`).join('\n')}` : ''} The shipping carrier configuration has been updated successfully.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Updating Shipping Carrier**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Delete a shipping carrier */ async deleteShippingCarrier(params: MCPDeleteShippingCarrierParams): Promise<StoreToolResult> { try { const request: GHLDeleteShippingCarrierRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; const response = await this.apiClient.deleteShippingCarrier(params.shippingCarrierId, request); return { content: [{ type: 'text', text: `✅ **Shipping Carrier Deleted Successfully** **Carrier ID:** ${params.shippingCarrierId} The shipping carrier has been permanently deleted. This action cannot be undone. ⚠️ **Important:** Any shipping rates using this carrier will no longer function properly. Please update or remove associated shipping rates.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Deleting Shipping Carrier**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * STORE SETTINGS TOOLS */ /** * Create or update store settings */ async createStoreSetting(params: MCPCreateStoreSettingParams): Promise<StoreToolResult> { try { const request: GHLCreateStoreSettingRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location', shippingOrigin: params.shippingOrigin, storeOrderNotification: params.storeOrderNotification, storeOrderFulfillmentNotification: params.storeOrderFulfillmentNotification }; const response = await this.apiClient.createStoreSetting(request); const settings = response.data?.data; if (!settings) { throw new Error('No store settings data returned from API'); } return { content: [{ type: 'text', text: `✅ **Store Settings Created/Updated Successfully** **Settings ID:** ${settings._id} **Shipping Origin:** - **Name:** ${settings.shippingOrigin.name} - **Address:** ${settings.shippingOrigin.street1}${settings.shippingOrigin.street2 ? `, ${settings.shippingOrigin.street2}` : ''} - **City:** ${settings.shippingOrigin.city}, ${settings.shippingOrigin.state || ''} ${settings.shippingOrigin.zip} - **Country:** ${settings.shippingOrigin.country} ${settings.shippingOrigin.phone ? `- **Phone:** ${settings.shippingOrigin.phone}` : ''} ${settings.shippingOrigin.email ? `- **Email:** ${settings.shippingOrigin.email}` : ''} ${settings.storeOrderNotification ? `**Order Notifications:** - **Enabled:** ${settings.storeOrderNotification.enabled ? 'Yes' : 'No'} - **Subject:** ${settings.storeOrderNotification.subject} - **Template ID:** ${settings.storeOrderNotification.emailTemplateId}` : ''} ${settings.storeOrderFulfillmentNotification ? `**Fulfillment Notifications:** - **Enabled:** ${settings.storeOrderFulfillmentNotification.enabled ? 'Yes' : 'No'} - **Subject:** ${settings.storeOrderFulfillmentNotification.subject} - **Template ID:** ${settings.storeOrderFulfillmentNotification.emailTemplateId}` : ''} **Last Updated:** ${new Date(settings.updatedAt).toLocaleString()} Your store settings have been configured successfully.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Creating/Updating Store Settings**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Get store settings */ async getStoreSetting(params: MCPGetStoreSettingParams): Promise<StoreToolResult> { try { const request: GHLGetStoreSettingRequest = { altId: params.locationId || this.apiClient.getConfig().locationId, altType: 'location' }; const response = await this.apiClient.getStoreSetting(request); const settings = response.data?.data; if (!settings) { return { content: [{ type: 'text', text: `⚙️ **No Store Settings Found** No store settings are currently configured for this location. Create store settings to configure shipping origin and notification preferences.` }] }; } return { content: [{ type: 'text', text: `⚙️ **Store Settings** **Settings ID:** ${settings._id} **📍 Shipping Origin:** - **Business Name:** ${settings.shippingOrigin.name} - **Address:** ${settings.shippingOrigin.street1}${settings.shippingOrigin.street2 ? `, ${settings.shippingOrigin.street2}` : ''} - **City:** ${settings.shippingOrigin.city}, ${settings.shippingOrigin.state || ''} ${settings.shippingOrigin.zip} - **Country:** ${settings.shippingOrigin.country} ${settings.shippingOrigin.phone ? `- **Phone:** ${settings.shippingOrigin.phone}` : ''} ${settings.shippingOrigin.email ? `- **Email:** ${settings.shippingOrigin.email}` : ''} ${settings.storeOrderNotification ? `**📧 Order Notifications:** - **Status:** ${settings.storeOrderNotification.enabled ? '✅ Enabled' : '❌ Disabled'} - **Subject Line:** "${settings.storeOrderNotification.subject}" - **Email Template ID:** ${settings.storeOrderNotification.emailTemplateId} - **Default Template ID:** ${settings.storeOrderNotification.defaultEmailTemplateId}` : '**📧 Order Notifications:** Not configured'} ${settings.storeOrderFulfillmentNotification ? `**📦 Fulfillment Notifications:** - **Status:** ${settings.storeOrderFulfillmentNotification.enabled ? '✅ Enabled' : '❌ Disabled'} - **Subject Line:** "${settings.storeOrderFulfillmentNotification.subject}" - **Email Template ID:** ${settings.storeOrderFulfillmentNotification.emailTemplateId} - **Default Template ID:** ${settings.storeOrderFulfillmentNotification.defaultEmailTemplateId}` : '**📦 Fulfillment Notifications:** Not configured'} **Created:** ${new Date(settings.createdAt).toLocaleString()} **Last Updated:** ${new Date(settings.updatedAt).toLocaleString()} These settings control your store's shipping origin and email notification preferences.` }] }; } catch (error) { return { content: [{ type: 'text', text: `❌ **Error Getting Store Settings**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}` }] }; } } /** * Get all Store API tool definitions */ getTools(): Tool[] { return [ // Shipping Zones Tools { name: 'ghl_create_shipping_zone', description: 'Create a new shipping zone with specific countries and states', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, name: { type: 'string', description: 'Name of the shipping zone' }, countries: { type: 'array', description: 'Array of countries with optional state restrictions', items: { type: 'object', properties: { code: { type: 'string', description: 'Country code (e.g., US, CA)' }, states: { type: 'array', description: 'Optional array of state codes for this country', items: { type: 'object', properties: { code: { type: 'string', description: 'State code (e.g., CA, NY)' } }, required: ['code'] } } }, required: ['code'] } } }, required: ['name', 'countries'] } }, { name: 'ghl_list_shipping_zones', description: 'List all shipping zones for a location', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, limit: { type: 'number', description: 'Number of zones to return (optional)' }, offset: { type: 'number', description: 'Number of zones to skip (optional)' }, withShippingRate: { type: 'boolean', description: 'Include shipping rates in response (optional)' } } } }, { name: 'ghl_get_shipping_zone', description: 'Get details of a specific shipping zone', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone to retrieve' }, withShippingRate: { type: 'boolean', description: 'Include shipping rates in response (optional)' } }, required: ['shippingZoneId'] } }, { name: 'ghl_update_shipping_zone', description: 'Update a shipping zone\'s name or countries', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone to update' }, name: { type: 'string', description: 'New name for the shipping zone (optional)' }, countries: { type: 'array', description: 'Updated array of countries with optional state restrictions (optional)', items: { type: 'object', properties: { code: { type: 'string', description: 'Country code (e.g., US, CA)' }, states: { type: 'array', description: 'Optional array of state codes for this country', items: { type: 'object', properties: { code: { type: 'string', description: 'State code (e.g., CA, NY)' } }, required: ['code'] } } }, required: ['code'] } } }, required: ['shippingZoneId'] } }, { name: 'ghl_delete_shipping_zone', description: 'Delete a shipping zone and all its associated shipping rates', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone to delete' } }, required: ['shippingZoneId'] } }, // Shipping Rates Tools (key ones) { name: 'ghl_get_available_shipping_rates', description: 'Get available shipping rates for an order based on destination and order details', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, country: { type: 'string', description: 'Destination country code' }, address: { type: 'object', description: 'Shipping address details', properties: { street1: { type: 'string', description: 'Street address line 1' }, city: { type: 'string', description: 'City' }, country: { type: 'string', description: 'Country code' } }, required: ['street1', 'city', 'country'] }, totalOrderAmount: { type: 'number', description: 'Total order amount' }, totalOrderWeight: { type: 'number', description: 'Total order weight' }, products: { type: 'array', description: 'Array of products in the order', items: { type: 'object', properties: { id: { type: 'string', description: 'Product ID' }, quantity: { type: 'number', description: 'Product quantity' } }, required: ['id', 'quantity'] } } }, required: ['country', 'address', 'totalOrderAmount', 'totalOrderWeight', 'products'] } }, { name: 'ghl_create_shipping_rate', description: 'Create a new shipping rate for a shipping zone', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone' }, name: { type: 'string', description: 'Name of the shipping rate' }, currency: { type: 'string', description: 'Currency code (e.g., USD)' }, amount: { type: 'number', description: 'Shipping rate amount' }, conditionType: { type: 'string', description: 'Condition type for rate calculation' } }, required: ['shippingZoneId', 'name', 'currency', 'amount', 'conditionType'] } }, { name: 'ghl_list_shipping_rates', description: 'List all shipping rates for a specific shipping zone', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone' } }, required: ['shippingZoneId'] } }, { name: 'ghl_get_shipping_rate', description: 'Get details of a specific shipping rate', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone' }, shippingRateId: { type: 'string', description: 'ID of the shipping rate to retrieve' } }, required: ['shippingZoneId', 'shippingRateId'] } }, { name: 'ghl_update_shipping_rate', description: 'Update a shipping rate\'s properties', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone' }, shippingRateId: { type: 'string', description: 'ID of the shipping rate to update' } }, required: ['shippingZoneId', 'shippingRateId'] } }, { name: 'ghl_delete_shipping_rate', description: 'Delete a shipping rate', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingZoneId: { type: 'string', description: 'ID of the shipping zone' }, shippingRateId: { type: 'string', description: 'ID of the shipping rate to delete' } }, required: ['shippingZoneId', 'shippingRateId'] } }, // Shipping Carriers Tools { name: 'ghl_create_shipping_carrier', description: 'Create a new shipping carrier for dynamic rate calculation', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, name: { type: 'string', description: 'Name of the shipping carrier' }, callbackUrl: { type: 'string', description: 'Callback URL for carrier rate requests' }, services: { type: 'array', description: 'Array of available services', items: { type: 'object', properties: { name: { type: 'string', description: 'Service name' }, value: { type: 'string', description: 'Service value' } }, required: ['name', 'value'] } } }, required: ['name', 'callbackUrl', 'services'] } }, { name: 'ghl_list_shipping_carriers', description: 'List all shipping carriers for a location', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' } } } }, { name: 'ghl_get_shipping_carrier', description: 'Get details of a specific shipping carrier', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingCarrierId: { type: 'string', description: 'ID of the shipping carrier to retrieve' } }, required: ['shippingCarrierId'] } }, { name: 'ghl_update_shipping_carrier', description: 'Update a shipping carrier\'s properties', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingCarrierId: { type: 'string', description: 'ID of the shipping carrier to update' } }, required: ['shippingCarrierId'] } }, { name: 'ghl_delete_shipping_carrier', description: 'Delete a shipping carrier', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingCarrierId: { type: 'string', description: 'ID of the shipping carrier to delete' } }, required: ['shippingCarrierId'] } }, // Store Settings Tools { name: 'ghl_create_store_setting', description: 'Create or update store settings including shipping origin and notifications', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }, shippingOrigin: { type: 'object', description: 'Shipping origin address details', properties: { name: { type: 'string', description: 'Business name' }, street1: { type: 'string', description: 'Street address line 1' }, city: { type: 'string', description: 'City' }, zip: { type: 'string', description: 'Postal/ZIP code' }, country: { type: 'string', description: 'Country code' } }, required: ['name', 'street1', 'city', 'zip', 'country'] } }, required: ['shippingOrigin'] } }, { name: 'ghl_get_store_setting', description: 'Get current store settings', inputSchema: { type: 'object', properties: { locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' } } } } ]; } /** * Execute Store API tools */ async executeStoreTool(toolName: string, params: any): Promise<StoreToolResult> { switch (toolName) { // Shipping Zones case 'ghl_create_shipping_zone': return this.createShippingZone(params); case 'ghl_list_shipping_zones': return this.listShippingZones(params); case 'ghl_get_shipping_zone': return this.getShippingZone(params); case 'ghl_update_shipping_zone': return this.updateShippingZone(params); case 'ghl_delete_shipping_zone': return this.deleteShippingZone(params); // Shipping Rates case 'ghl_get_available_shipping_rates': return this.getAvailableShippingRates(params); case 'ghl_create_shipping_rate': return this.createShippingRate(params); case 'ghl_list_shipping_rates': return this.listShippingRates(params); case 'ghl_get_shipping_rate': return this.getShippingRate(params); case 'ghl_update_shipping_rate': return this.updateShippingRate(params); case 'ghl_delete_shipping_rate': return this.deleteShippingRate(params); // Shipping Carriers case 'ghl_create_shipping_carrier': return this.createShippingCarrier(params); case 'ghl_list_shipping_carriers': return this.listShippingCarriers(params); case 'ghl_get_shipping_carrier': return this.getShippingCarrier(params); case 'ghl_update_shipping_carrier': return this.updateShippingCarrier(params); case 'ghl_delete_shipping_carrier': return this.deleteShippingCarrier(params); // Store Settings case 'ghl_create_store_setting': return this.createStoreSetting(params); case 'ghl_get_store_setting': return this.getStoreSetting(params); default: throw new Error(`Unknown Store tool: ${toolName}`); } } }