/**
* GoHighLevel Products API Tools for MCP Server
* Provides comprehensive tools for managing products, prices, inventory, collections, and reviews
*/
import {
// MCP Product Types
MCPCreateProductParams,
MCPUpdateProductParams,
MCPListProductsParams,
MCPGetProductParams,
MCPDeleteProductParams,
MCPCreatePriceParams,
MCPUpdatePriceParams,
MCPListPricesParams,
MCPGetPriceParams,
MCPDeletePriceParams,
MCPBulkUpdateProductsParams,
MCPListInventoryParams,
MCPUpdateInventoryParams,
MCPGetProductStoreStatsParams,
MCPUpdateProductStoreParams,
MCPCreateProductCollectionParams,
MCPUpdateProductCollectionParams,
MCPListProductCollectionsParams,
MCPGetProductCollectionParams,
MCPDeleteProductCollectionParams,
MCPListProductReviewsParams,
MCPGetReviewsCountParams,
MCPUpdateProductReviewParams,
MCPDeleteProductReviewParams,
MCPBulkUpdateProductReviewsParams,
// API Client Types
GHLCreateProductRequest,
GHLUpdateProductRequest,
GHLListProductsRequest,
GHLGetProductRequest,
GHLDeleteProductRequest,
GHLCreatePriceRequest,
GHLUpdatePriceRequest,
GHLListPricesRequest,
GHLGetPriceRequest,
GHLDeletePriceRequest,
GHLBulkUpdateRequest,
GHLListInventoryRequest,
GHLUpdateInventoryRequest,
GHLGetProductStoreStatsRequest,
GHLUpdateProductStoreRequest,
GHLCreateProductCollectionRequest,
GHLUpdateProductCollectionRequest,
GHLListProductCollectionsRequest,
GHLGetProductCollectionRequest,
GHLDeleteProductCollectionRequest,
GHLListProductReviewsRequest,
GHLGetReviewsCountRequest,
GHLUpdateProductReviewRequest,
GHLDeleteProductReviewRequest,
GHLBulkUpdateProductReviewsRequest
} from '../types/ghl-types.js';
import { GHLApiClient } from '../clients/ghl-api-client.js';
import { Tool } from '@modelcontextprotocol/sdk/types.js';
export interface ProductsToolResult {
content: {
type: 'text';
text: string;
}[];
}
export class ProductsTools {
constructor(private apiClient: GHLApiClient) {}
// Product Operations
async createProduct(params: MCPCreateProductParams): Promise<ProductsToolResult> {
try {
const request: GHLCreateProductRequest = {
...params,
locationId: params.locationId || this.apiClient.getConfig().locationId
};
const response = await this.apiClient.createProduct(request);
if (!response.data) {
throw new Error('No data returned from API');
}
return {
content: [{
type: 'text',
text: `🛍️ **Product Created Successfully!**
📦 **Product Details:**
• **ID:** ${response.data._id}
• **Name:** ${response.data.name}
• **Type:** ${response.data.productType}
• **Location:** ${response.data.locationId}
• **Available in Store:** ${response.data.availableInStore ? '✅ Yes' : '❌ No'}
• **Created:** ${new Date(response.data.createdAt).toLocaleString()}
${response.data.description ? `📝 **Description:** ${response.data.description}` : ''}
${response.data.image ? `🖼️ **Image:** ${response.data.image}` : ''}
${response.data.collectionIds?.length ? `📂 **Collections:** ${response.data.collectionIds.length} assigned` : ''}
${response.data.variants?.length ? `🔧 **Variants:** ${response.data.variants.length} configured` : ''}
${response.data.medias?.length ? `📸 **Media Files:** ${response.data.medias.length} attached` : ''}
✨ **Status:** Product successfully created and ready for configuration!`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Creating Product**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async listProducts(params: MCPListProductsParams): Promise<ProductsToolResult> {
try {
const request: GHLListProductsRequest = {
...params,
locationId: params.locationId || this.apiClient.getConfig().locationId
};
const response = await this.apiClient.listProducts(request);
if (!response.data) {
throw new Error('No data returned from API');
}
const products = response.data.products;
const total = response.data.total[0]?.total || 0;
return {
content: [{
type: 'text',
text: `🛍️ **Products List** (${products.length} of ${total} total)
${products.length === 0 ? '📭 **No products found**' : products.map((product, index) => `
**${index + 1}. ${product.name}** (${product.productType})
• **ID:** ${product._id}
• **Store Status:** ${product.availableInStore ? '✅ Available' : '❌ Not Available'}
• **Created:** ${new Date(product.createdAt).toLocaleString()}
${product.description ? `• **Description:** ${product.description.substring(0, 100)}${product.description.length > 100 ? '...' : ''}` : ''}
${product.collectionIds?.length ? `• **Collections:** ${product.collectionIds.length}` : ''}
`).join('\n')}
📊 **Summary:**
• **Total Products:** ${total}
• **Displayed:** ${products.length}
${params.search ? `• **Search:** "${params.search}"` : ''}
${params.storeId ? `• **Store Filter:** ${params.storeId}` : ''}
${params.includedInStore !== undefined ? `• **Store Status:** ${params.includedInStore ? 'Included only' : 'Excluded only'}` : ''}`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Listing Products**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
getTools(): Tool[] {
return [
// Product Management Tools
{
name: 'ghl_create_product',
description: 'Create a new product in GoHighLevel',
inputSchema: {
type: 'object',
properties: {
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
name: { type: 'string', description: 'Product name' },
productType: {
type: 'string',
enum: ['DIGITAL', 'PHYSICAL', 'SERVICE', 'PHYSICAL/DIGITAL'],
description: 'Type of product'
},
description: { type: 'string', description: 'Product description' },
image: { type: 'string', description: 'Product image URL' },
availableInStore: { type: 'boolean', description: 'Whether product is available in store' },
slug: { type: 'string', description: 'Product URL slug' }
},
required: ['name', 'productType']
}
},
{
name: 'ghl_list_products',
description: 'List products with optional filtering',
inputSchema: {
type: 'object',
properties: {
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
limit: { type: 'number', description: 'Maximum number of products to return' },
offset: { type: 'number', description: 'Number of products to skip' },
search: { type: 'string', description: 'Search term for product names' },
storeId: { type: 'string', description: 'Filter by store ID' },
includedInStore: { type: 'boolean', description: 'Filter by store inclusion status' },
availableInStore: { type: 'boolean', description: 'Filter by store availability' }
},
required: []
}
},
{
name: 'ghl_get_product',
description: 'Get a specific product by ID',
inputSchema: {
type: 'object',
properties: {
productId: { type: 'string', description: 'Product ID to retrieve' },
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }
},
required: ['productId']
}
},
{
name: 'ghl_update_product',
description: 'Update an existing product',
inputSchema: {
type: 'object',
properties: {
productId: { type: 'string', description: 'Product ID to update' },
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
name: { type: 'string', description: 'Product name' },
productType: {
type: 'string',
enum: ['DIGITAL', 'PHYSICAL', 'SERVICE', 'PHYSICAL/DIGITAL'],
description: 'Type of product'
},
description: { type: 'string', description: 'Product description' },
image: { type: 'string', description: 'Product image URL' },
availableInStore: { type: 'boolean', description: 'Whether product is available in store' }
},
required: ['productId']
}
},
{
name: 'ghl_delete_product',
description: 'Delete a product by ID',
inputSchema: {
type: 'object',
properties: {
productId: { type: 'string', description: 'Product ID to delete' },
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' }
},
required: ['productId']
}
},
// Price Management Tools
{
name: 'ghl_create_price',
description: 'Create a price for a product',
inputSchema: {
type: 'object',
properties: {
productId: { type: 'string', description: 'Product ID to create price for' },
name: { type: 'string', description: 'Price name/variant name' },
type: {
type: 'string',
enum: ['one_time', 'recurring'],
description: 'Price type'
},
currency: { type: 'string', description: 'Currency code (e.g., USD)' },
amount: { type: 'number', description: 'Price amount in cents' },
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
compareAtPrice: { type: 'number', description: 'Compare at price (for discounts)' }
},
required: ['productId', 'name', 'type', 'currency', 'amount']
}
},
{
name: 'ghl_list_prices',
description: 'List prices for a product',
inputSchema: {
type: 'object',
properties: {
productId: { type: 'string', description: 'Product ID to list prices for' },
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
limit: { type: 'number', description: 'Maximum number of prices to return' },
offset: { type: 'number', description: 'Number of prices to skip' }
},
required: ['productId']
}
},
// Inventory Tools
{
name: 'ghl_list_inventory',
description: 'List inventory items with stock levels',
inputSchema: {
type: 'object',
properties: {
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
limit: { type: 'number', description: 'Maximum number of items to return' },
offset: { type: 'number', description: 'Number of items to skip' },
search: { type: 'string', description: 'Search term for inventory items' }
},
required: []
}
},
// Collection Tools
{
name: 'ghl_create_product_collection',
description: 'Create a new product collection',
inputSchema: {
type: 'object',
properties: {
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
name: { type: 'string', description: 'Collection name' },
slug: { type: 'string', description: 'Collection URL slug' },
image: { type: 'string', description: 'Collection image URL' },
seo: {
type: 'object',
properties: {
title: { type: 'string', description: 'SEO title' },
description: { type: 'string', description: 'SEO description' }
}
}
},
required: ['name', 'slug']
}
},
{
name: 'ghl_list_product_collections',
description: 'List product collections',
inputSchema: {
type: 'object',
properties: {
locationId: { type: 'string', description: 'GHL Location ID (optional, uses default if not provided)' },
limit: { type: 'number', description: 'Maximum number of collections to return' },
offset: { type: 'number', description: 'Number of collections to skip' },
name: { type: 'string', description: 'Search by collection name' }
},
required: []
}
}
];
}
async executeProductsTool(toolName: string, params: any): Promise<ProductsToolResult> {
switch (toolName) {
case 'ghl_create_product':
return this.createProduct(params as MCPCreateProductParams);
case 'ghl_list_products':
return this.listProducts(params as MCPListProductsParams);
case 'ghl_get_product':
return this.getProduct(params as MCPGetProductParams);
case 'ghl_update_product':
return this.updateProduct(params as MCPUpdateProductParams);
case 'ghl_delete_product':
return this.deleteProduct(params as MCPDeleteProductParams);
case 'ghl_create_price':
return this.createPrice(params as MCPCreatePriceParams);
case 'ghl_list_prices':
return this.listPrices(params as MCPListPricesParams);
case 'ghl_list_inventory':
return this.listInventory(params as MCPListInventoryParams);
case 'ghl_create_product_collection':
return this.createProductCollection(params as MCPCreateProductCollectionParams);
case 'ghl_list_product_collections':
return this.listProductCollections(params as MCPListProductCollectionsParams);
default:
return {
content: [{
type: 'text',
text: `❌ **Unknown Products Tool**: ${toolName}`
}]
};
}
}
// Additional Product Operations
async getProduct(params: MCPGetProductParams): Promise<ProductsToolResult> {
try {
const response = await this.apiClient.getProduct(
params.productId,
params.locationId || this.apiClient.getConfig().locationId
);
if (!response.data) {
throw new Error('No data returned from API');
}
return {
content: [{
type: 'text',
text: `🛍️ **Product Details**
📦 **${response.data.name}** (${response.data.productType})
• **ID:** ${response.data._id}
• **Location:** ${response.data.locationId}
• **Available in Store:** ${response.data.availableInStore ? '✅ Yes' : '❌ No'}
• **Created:** ${new Date(response.data.createdAt).toLocaleString()}
• **Updated:** ${new Date(response.data.updatedAt).toLocaleString()}
${response.data.description ? `📝 **Description:** ${response.data.description}` : ''}
${response.data.image ? `🖼️ **Image:** ${response.data.image}` : ''}
${response.data.slug ? `🔗 **Slug:** ${response.data.slug}` : ''}
${response.data.collectionIds?.length ? `📂 **Collections:** ${response.data.collectionIds.length} assigned` : ''}
${response.data.variants?.length ? `🔧 **Variants:** ${response.data.variants.length} configured` : ''}
${response.data.medias?.length ? `📸 **Media Files:** ${response.data.medias.length} attached` : ''}
${response.data.isTaxesEnabled ? `💰 **Taxes:** Enabled` : ''}
${response.data.isLabelEnabled ? `🏷️ **Labels:** Enabled` : ''}`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Getting Product**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async updateProduct(params: MCPUpdateProductParams): Promise<ProductsToolResult> {
try {
const request: GHLUpdateProductRequest = {
...params,
locationId: params.locationId || this.apiClient.getConfig().locationId
};
const response = await this.apiClient.updateProduct(params.productId, request);
if (!response.data) {
throw new Error('No data returned from API');
}
return {
content: [{
type: 'text',
text: `✅ **Product Updated Successfully!**
📦 **Updated Product:**
• **ID:** ${response.data._id}
• **Name:** ${response.data.name}
• **Type:** ${response.data.productType}
• **Available in Store:** ${response.data.availableInStore ? '✅ Yes' : '❌ No'}
• **Last Updated:** ${new Date(response.data.updatedAt).toLocaleString()}
🔄 **Product has been successfully updated with the new information!**`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Updating Product**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async deleteProduct(params: MCPDeleteProductParams): Promise<ProductsToolResult> {
try {
const response = await this.apiClient.deleteProduct(
params.productId,
params.locationId || this.apiClient.getConfig().locationId
);
if (!response.data) {
throw new Error('No data returned from API');
}
return {
content: [{
type: 'text',
text: `🗑️ **Product Deleted Successfully!**
✅ **Status:** ${response.data.status ? 'Product successfully deleted' : 'Deletion failed'}
🗂️ **Product ID:** ${params.productId}
⚠️ **Note:** This action cannot be undone. The product and all associated data have been permanently removed.`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Deleting Product**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async createPrice(params: MCPCreatePriceParams): Promise<ProductsToolResult> {
try {
const request: GHLCreatePriceRequest = {
...params,
locationId: params.locationId || this.apiClient.getConfig().locationId
};
const response = await this.apiClient.createPrice(params.productId, request);
if (!response.data) {
throw new Error('No data returned from API');
}
return {
content: [{
type: 'text',
text: `💰 **Price Created Successfully!**
🏷️ **Price Details:**
• **ID:** ${response.data._id}
• **Name:** ${response.data.name}
• **Type:** ${response.data.type}
• **Amount:** ${response.data.amount / 100} ${response.data.currency}
• **Product ID:** ${response.data.product}
• **Created:** ${new Date(response.data.createdAt).toLocaleString()}
${response.data.compareAtPrice ? `💸 **Compare At:** ${response.data.compareAtPrice / 100} ${response.data.currency}` : ''}
${response.data.recurring ? `🔄 **Recurring:** ${response.data.recurring.intervalCount} ${response.data.recurring.interval}(s)` : ''}
${response.data.sku ? `📦 **SKU:** ${response.data.sku}` : ''}
✨ **Price is ready for use in your product catalog!**`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Creating Price**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async listPrices(params: MCPListPricesParams): Promise<ProductsToolResult> {
try {
const request: GHLListPricesRequest = {
...params,
locationId: params.locationId || this.apiClient.getConfig().locationId
};
const response = await this.apiClient.listPrices(params.productId, request);
if (!response.data) {
throw new Error('No data returned from API');
}
const prices = response.data.prices;
return {
content: [{
type: 'text',
text: `💰 **Product Prices** (${prices.length} of ${response.data.total} total)
${prices.length === 0 ? '📭 **No prices found**' : prices.map((price, index) => `
**${index + 1}. ${price.name}** (${price.type})
• **ID:** ${price._id}
• **Amount:** ${price.amount / 100} ${price.currency}
${price.compareAtPrice ? `• **Compare At:** ${price.compareAtPrice / 100} ${price.currency}` : ''}
${price.recurring ? `• **Recurring:** ${price.recurring.intervalCount} ${price.recurring.interval}(s)` : ''}
${price.sku ? `• **SKU:** ${price.sku}` : ''}
• **Created:** ${new Date(price.createdAt).toLocaleString()}
`).join('\n')}
📊 **Summary:**
• **Total Prices:** ${response.data.total}
• **Product ID:** ${params.productId}`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Listing Prices**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async listInventory(params: MCPListInventoryParams): Promise<ProductsToolResult> {
try {
const request: GHLListInventoryRequest = {
altId: params.locationId || this.apiClient.getConfig().locationId,
altType: 'location',
...params
};
const response = await this.apiClient.listInventory(request);
if (!response.data) {
throw new Error('No data returned from API');
}
const inventory = response.data.inventory;
const total = response.data.total.total;
return {
content: [{
type: 'text',
text: `📦 **Inventory Items** (${inventory.length} of ${total} total)
${inventory.length === 0 ? '📭 **No inventory items found**' : inventory.map((item, index) => `
**${index + 1}. ${item.name}** ${item.productName ? `(${item.productName})` : ''}
• **ID:** ${item._id}
• **Available Quantity:** ${item.availableQuantity}
• **SKU:** ${item.sku || 'N/A'}
• **Out of Stock Purchases:** ${item.allowOutOfStockPurchases ? '✅ Allowed' : '❌ Not Allowed'}
• **Product ID:** ${item.product}
• **Last Updated:** ${new Date(item.updatedAt).toLocaleString()}
${item.image ? `• **Image:** ${item.image}` : ''}
`).join('\n')}
📊 **Summary:**
• **Total Items:** ${total}
• **Displayed:** ${inventory.length}
${params.search ? `• **Search:** "${params.search}"` : ''}`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Listing Inventory**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async createProductCollection(params: MCPCreateProductCollectionParams): Promise<ProductsToolResult> {
try {
const request: GHLCreateProductCollectionRequest = {
...params,
altId: params.locationId || this.apiClient.getConfig().locationId,
altType: 'location'
};
const response = await this.apiClient.createProductCollection(request);
if (!response.data?.data) {
throw new Error('No data returned from API');
}
return {
content: [{
type: 'text',
text: `📂 **Product Collection Created Successfully!**
🏷️ **Collection Details:**
• **ID:** ${response.data.data._id}
• **Name:** ${response.data.data.name}
• **Slug:** ${response.data.data.slug}
• **Location:** ${response.data.data.altId}
• **Created:** ${new Date(response.data.data.createdAt).toLocaleString()}
${response.data.data.image ? `🖼️ **Image:** ${response.data.data.image}` : ''}
${response.data.data.seo?.title ? `🔍 **SEO Title:** ${response.data.data.seo.title}` : ''}
${response.data.data.seo?.description ? `📝 **SEO Description:** ${response.data.data.seo.description}` : ''}
✨ **Collection is ready to organize your products!**`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Creating Collection**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
async listProductCollections(params: MCPListProductCollectionsParams): Promise<ProductsToolResult> {
try {
const request: GHLListProductCollectionsRequest = {
...params,
altId: params.locationId || this.apiClient.getConfig().locationId,
altType: 'location'
};
const response = await this.apiClient.listProductCollections(request);
if (!response.data?.data) {
throw new Error('No data returned from API');
}
const collections = response.data.data;
return {
content: [{
type: 'text',
text: `📂 **Product Collections** (${collections.length} of ${response.data.total} total)
${collections.length === 0 ? '📭 **No collections found**' : collections.map((collection: any, index: number) => `
**${index + 1}. ${collection.name}**
• **ID:** ${collection._id}
• **Slug:** ${collection.slug}
${collection.image ? `• **Image:** ${collection.image}` : ''}
${collection.seo?.title ? `• **SEO Title:** ${collection.seo.title}` : ''}
• **Created:** ${new Date(collection.createdAt).toLocaleString()}
`).join('\n')}
📊 **Summary:**
• **Total Collections:** ${response.data.total}
• **Displayed:** ${collections.length}
${params.name ? `• **Search:** "${params.name}"` : ''}`
}]
};
} catch (error) {
return {
content: [{
type: 'text',
text: `❌ **Error Listing Collections**\n\n${error instanceof Error ? error.message : 'Unknown error occurred'}`
}]
};
}
}
}