@unchainedshop/api 3.1.13 → 4.0.0-rc.10

package/src/mcp/tools/product/createProductVariationHandler.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { ProductTypes, ProductVariationType } from '@unchainedshop/core-products';
+import { ProductNotFoundError, ProductWrongTypeError } from '../../../errors.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+const productVariationTypeKeys = Object.keys(ProductVariationType) as [
+  keyof typeof ProductVariationType,
+  ...(keyof typeof ProductVariationType)[],
+];
+
+export const CreateProductVariationSchema = {
+  productId: z
+    .string()
+    .min(1)
+    .describe(
+      'Product ID for which to create the variation. it should only be CONFIGURABLE_PRODUCT type product id',
+    ),
+  variation: z.object({
+    key: z
+      .string()
+      .min(1)
+      .describe('unique value that is not already used as key for the products variations vector'),
+    type: z.enum(productVariationTypeKeys).describe('Product variation types'),
+  }),
+  texts: z
+    .array(
+      z.object({
+        locale: z
+          .string()
+          .min(2)
+          .describe(
+            'locale iso code like "en-US", "de-CH" use default defaultLanguageIsoCode in shop info if not explicitly provided. if language is explicitly provided check if it exists',
+          ),
+        title: z.string().describe('variation title'),
+        subtitle: z.string().optional().describe('variation additional description'),
+      }),
+    )
+    .optional(),
+};
+
+export const CreateProductVariationZodSchema = z.object(CreateProductVariationSchema);
+export type CreateProductVariationParams = z.infer<typeof CreateProductVariationZodSchema>;
+
+export async function createProductVariationHandler(
+  context: Context,
+  params: CreateProductVariationParams,
+) {
+  const { productId, variation, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler createProductVariationHandler', { userId, params });
+    const product = await modules.products.findProduct({ productId });
+    if (!product) throw new ProductNotFoundError({ productId });
+
+    if (product.type !== ProductTypes.ConfigurableProduct)
+      throw new ProductWrongTypeError({
+        productId,
+        received: product.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+
+    const newVariation = await modules.products.variations.create({
+      options: [],
+      productId,
+      ...variation,
+    });
+
+    if (texts) {
+      await modules.products.variations.texts.updateVariationTexts(newVariation._id, texts as any);
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating product variation: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/createProductVariationOptionHandler.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { ProductVariationNotFoundError } from '../../../errors.js';
+import { log } from '@unchainedshop/logger';
+
+const ProductVariationTextInputSchema = z.object({
+  locale: z
+    .string()
+    .min(2)
+    .describe(
+      'locale iso code like "en-US", "de-CH" use default defaultLanguageIsoCode in shop info if not explicitly provided. if language is explicitly provided check if it exists',
+    ),
+  title: z.string().describe('variation option title in the specified locale'),
+  subtitle: z.string().optional().describe('variation option subtitle in the specified locale'),
+});
+
+export const CreateProductVariationOptionSchema = {
+  productVariationId: z
+    .string()
+    .min(1)
+    .describe('ID of the product variation, it should only be a CONFIGURABLE_PRODUCT type ID'),
+  option: z.string().min(1).describe('Name of the new option (e.g., "Red")'),
+  texts: z.array(ProductVariationTextInputSchema),
+};
+export const CreateProductVariationOptionZodSchema = z.object(CreateProductVariationOptionSchema);
+export type CreateProductVariationOptionParams = z.infer<typeof CreateProductVariationOptionZodSchema>;
+
+export async function createProductVariationOptionHandler(
+  context: Context,
+  params: CreateProductVariationOptionParams,
+) {
+  const { productVariationId, option, texts } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler createProductVariationOptionHandler', { userId, params });
+    const variation = await modules.products.variations.findProductVariation({
+      productVariationId,
+    });
+    if (!variation) throw new ProductVariationNotFoundError({ productVariationId });
+
+    const newOption = await modules.products.variations.addVariationOption(productVariationId, {
+      value: option,
+    });
+
+    if (texts) {
+      await modules.products.variations.texts.updateVariationTexts(
+        productVariationId,
+        texts as any,
+        option,
+      );
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            variation: newOption,
+            product: await getNormalizedProductDetails(newOption?.productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating variation option: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/getProduct.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
+
+export const GetProductSchema = {
+  productId: z.string().optional().describe('Product ID for lookup'),
+  slug: z.string().optional().describe('Product slug for lookup'),
+  sku: z.string().optional().describe('Product SKU for lookup'),
+};
+
+export const GetProductZodSchema = z
+  .object(GetProductSchema)
+  .refine(
+    (data) => data.productId || data.slug || data.sku,
+    'At least one of productId, slug, or sku must be provided',
+  );
+
+export type GetProductParams = z.infer<typeof GetProductZodSchema>;
+
+export async function getProductHandler(context: Context, params: GetProductParams) {
+  const { productId, slug, sku } = params;
+  const { modules, userId } = context;
+
+  try {
+    log('handler getProductHandler', { userId, params });
+    const product = await modules.products.findProduct({
+      productId,
+      slug,
+      sku,
+    });
+
+    if (!product) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Product not found with ${productId ? `ID: ${productId}` : slug ? `slug: ${slug}` : `SKU: ${sku}`}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(productId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error getting product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/product/index.ts

@@ -0,0 +1,373 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import { productsListHandler, ProductsListSchema } from './listProducts.js';
+import { productsCountHandler, ProductsCountSchema } from './productsCountHandler.js';
+import { getProductHandler, GetProductSchema } from './getProduct.js';
+import { createProductHandler, CreateProductSchema } from './createProductHandler.js';
+import { removeProductHandler, RemoveProductSchema } from './removeProductHandler.js';
+import { publishProductHandler, PublishProductSchema } from './publishProduct.js';
+import { unpublishProductHandler, UnpublishProductSchema } from './unpublishProductHandler.js';
+import { updateProductHandler, UpdateProductSchema } from './updateProductHandler.js';
+import { updateProductTextsHandler, UpdateProductTextsSchema } from './updateProductTextsHandler.js';
+import {
+  updateProductCommerceHandler,
+  UpdateProductCommerceSchema,
+} from './updateProductCommerceHandler.js';
+import {
+  updateProductWarehousingHandler,
+  UpdateProductWarehousingSchema,
+} from './updateProductWarehousingHandler.js';
+import { updateProductSupplyHandler, UpdateProductSupplySchema } from './updateProductSupplyHandler.js';
+import {
+  updateProductTokenizationHandler,
+  UpdateProductTokenizationSchema,
+} from './updateProductTokenizationHandler.js';
+import { updateProductPlanHandler, UpdateProductPlanSchema } from './updateProductPlanHandler.js';
+import {
+  removeProductVariationHandler,
+  RemoveProductVariationSchema,
+} from './removeProductVariationHandler.js';
+import {
+  createProductVariationHandler,
+  CreateProductVariationSchema,
+} from './createProductVariationHandler.js';
+import {
+  addProductAssignmentHandler,
+  AssignProductVariationSchema,
+} from './addProductAssignmentHandler.js';
+import {
+  createProductVariationOptionHandler,
+  CreateProductVariationOptionSchema,
+} from './createProductVariationOptionHandler.js';
+import {
+  removeProductVariationOptionHandler,
+  RemoveProductVariationOptionSchema,
+} from './removeProductVariationOptionHandler.js';
+import {
+  removeProductAssignmentHandler,
+  RemoveProductAssignmentSchema,
+} from './removeProductAssignmentHandler.js';
+import {
+  addProductMediaUploadHandler,
+  AddProductMediaUploadSchema,
+} from './addProductMediaUploadHandler.js';
+import { removeProductMediaHandler, RemoveProductMediaSchema } from './removeProductMediaHandler.js';
+import {
+  updateProductMediaTextsHandler,
+  UpdateProductMediaTextsSchema,
+} from './updateProductMediaTextsHandler.js';
+import { reorderProductMediaHandler, ReorderProductMediaSchema } from './reorderProductMediaHandler.js';
+import { productReviewsCountHandler, ProductReviewsCountSchema } from './productReviewsCountHandler.js';
+import { productReviewsHandler, ProductReviewsSchema } from './productReviewsHandler.js';
+import {
+  translatedProductTextsHandler,
+  TranslatedProductTextsSchema,
+} from './translatedProductTextsHandler.js';
+import {
+  translatedProductMediaTextsHandler,
+  TranslatedProductMediaTextsSchema,
+} from './translatedProductMediaTextsHandler.js';
+import {
+  translatedProductVariationTextsHandler,
+  TranslatedProductVariationTextsSchema,
+} from './translatedProductVariationTextsHandler.js';
+import {
+  updateProductVariationTextsHandler,
+  UpdateProductVariationTextsSchema,
+} from './updateProductVariationTextsHandler.js';
+import { productSiblingsHandler, ProductSiblingsSchema } from './productSiblingsHandler.js';
+import { productMediaHandler, ProductMediaSchema } from './productMediaHandler.js';
+import { variationProductsHandler, VariationProductsSchema } from './variationProductsHandler.js';
+import { productVariationsHandler, ProductVariationsSchema } from './productVariationsHandler.js';
+import {
+  addProductBundleItemHandler,
+  AddProductBundleItemSchema,
+} from './addProductBundleItemHandler.js';
+import {
+  removeProductBundleItemHandler,
+  RemoveProductBundleItemSchema,
+} from './removeProductBundleItemHandler.js';
+import { productAssignmentsHandler, ProductAssignmentsSchema } from './productAssignmentsHandler.js';
+import { productBundleItemsHandler, ProductBundleItemsSchema } from './productBundleItemsHandler.js';
+import { simulatedPriceRangeHandler, SimulatedPriceRangeSchema } from './simulatedPriceRangeHandler.js';
+import { simulatedPriceHandler, SimulatedPriceSchema } from './simulatedPriceHandler.js';
+import { catalogPriceHandler, CatalogPriceSchema } from './catalogPriceHandler.js';
+
+export const registerProductTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'product_list',
+    'List products filtered by tags, slugs, or query string; supports pagination and sorting.',
+    ProductsListSchema,
+    async (params) => productsListHandler(context, params),
+  );
+
+  server.tool(
+    'product_count',
+    'Count products filtered by tags, slugs, draft status, or query string.',
+    ProductsCountSchema,
+    async (params) => productsCountHandler(context, params),
+  );
+  server.tool(
+    'product_get',
+    'Retrieve product details by productId, slug, or SKU.',
+    GetProductSchema,
+    async (params) => getProductHandler(context, params),
+  );
+
+  server.tool(
+    'product_create',
+    'Create a new product with localized text information. it will be in DRAFT/unpublish status',
+    CreateProductSchema,
+    async (params) => createProductHandler(context, params),
+  );
+  server.tool(
+    'product_remove',
+    'Remove a product by its ID. Changing its status to DELETED and removing it from sale',
+    RemoveProductSchema,
+    async (params) => removeProductHandler(context, params),
+  );
+
+  server.tool(
+    'product_publish',
+    'Publish a product by its id changing it to active and available for sale',
+    PublishProductSchema,
+    async (params) => publishProductHandler(context, params),
+  );
+
+  server.tool(
+    'product_unpublish',
+    'Deactivates or Unpublishes product by its id changing it to DRAFT and not available for sale',
+    UnpublishProductSchema,
+    async (params) => unpublishProductHandler(context, params),
+  );
+  server.tool(
+    'product_update',
+    'Update specified fields (such as tags, sequence, and metadata) of an existing product identified by its productId.',
+    UpdateProductSchema,
+    async (params) => updateProductHandler(context, params),
+  );
+
+  server.tool(
+    'product_updateTexts',
+    'Update localized texts (title, subtitle, description, slug, vendor, brand, labels) of a product',
+    UpdateProductTextsSchema,
+    async (params) => updateProductTextsHandler(context, params),
+  );
+
+  server.tool(
+    'product_updateCommerce',
+    'Update commerce information (pricing) for a product (all types except CONFIGURABLE_PRODUCT)',
+    UpdateProductCommerceSchema,
+    async (params) => updateProductCommerceHandler(context, params),
+  );
+
+  server.tool(
+    'product_updateWarehousing',
+    'Update warehousing details (SKU, base unit) for a SIMPLE_PRODUCT type product',
+    UpdateProductWarehousingSchema,
+    async (params) => updateProductWarehousingHandler(context, params),
+  );
+
+  server.tool(
+    'product_updateSupply',
+    'Update the supply (delivery) details for a SIMPLE_PRODUCT type product',
+    UpdateProductSupplySchema,
+    async (params) => updateProductSupplyHandler(context, params),
+  );
+  server.tool(
+    'product_updateTokenization',
+    'Update tokenization details for a TOKENIZED_PRODUCT type product',
+    UpdateProductTokenizationSchema,
+    async (params) => updateProductTokenizationHandler(context, params),
+  );
+  server.tool(
+    'product_updatePlan',
+    'Update the subscription plan configuration for a product of type PLAN. This includes usage calculation type (LICENSED or METERED), billing interval settings, and optional trial period configuration. This operation is only valid for products with type PLAN_PRODUCT.',
+    UpdateProductPlanSchema,
+    async (params) => updateProductPlanHandler(context, params),
+  );
+
+  server.tool(
+    'product_createVariation',
+    'Create a variation for a CONFIGURABLE_PRODUCT product including localized texts.',
+    CreateProductVariationSchema,
+    async (params) => createProductVariationHandler(context, params),
+  );
+
+  server.tool(
+    'productVariation_remove',
+    'Remove a product variation by its ID.',
+    RemoveProductVariationSchema,
+    async (params) => removeProductVariationHandler(context, params),
+  );
+
+  server.tool(
+    'product_assignVariation',
+    'Assign a product variant to a configurable product with a unique combination of option vectors. assigning with incomplete vector will fail. make sure all variation options are selected before calling this tool.',
+    AssignProductVariationSchema,
+    async (params) => addProductAssignmentHandler(context, params),
+  );
+
+  server.tool(
+    'product_createVariationOption',
+    'Create a new option for a product variation with localized titles and subtitles.',
+    CreateProductVariationOptionSchema,
+    async (params) => createProductVariationOptionHandler(context, params),
+  );
+
+  server.tool(
+    'productVariationOption_remove',
+    'Remove an option from a product variation by its value.',
+    RemoveProductVariationOptionSchema,
+    async (params) => removeProductVariationOptionHandler(context, params),
+  );
+
+  server.tool(
+    'product_removeAssignment',
+    'Remove a product variant assignment from a configurable product using attribute vectors.',
+    RemoveProductAssignmentSchema,
+    async (params) => removeProductAssignmentHandler(context, params),
+  );
+
+  server.tool(
+    'product_addMedia',
+    'Add a media asset to a product from a publicly accessible URL',
+    AddProductMediaUploadSchema,
+    async (params) => addProductMediaUploadHandler(context, params),
+  );
+
+  server.tool(
+    'productMedia_remove',
+    'Remove a product media asset by its ID.',
+    RemoveProductMediaSchema,
+    async (params) => removeProductMediaHandler(context, params),
+  );
+
+  server.tool(
+    'productMedia_updateTexts',
+    'Update localized texts (title, subtitle) of a product media asset.',
+    UpdateProductMediaTextsSchema,
+    async (params) => updateProductMediaTextsHandler(context, params),
+  );
+
+  server.tool(
+    'product_reorderMedias',
+    'Reorder media assets of a product by providing new sort keys.',
+    ReorderProductMediaSchema,
+    async (params) => reorderProductMediaHandler(context, params),
+  );
+
+  server.tool(
+    'productReviews_count',
+    'Count product reviews optionally filtered by query string.',
+    ProductReviewsCountSchema,
+    async (params) => productReviewsCountHandler(context, params),
+  );
+
+  server.tool(
+    'productReviews_list',
+    'Retrieve a paginated list of product reviews with optional filtering and sorting.',
+    ProductReviewsSchema,
+    async (params) => productReviewsHandler(context, params),
+  );
+  server.tool(
+    'product_getTexts',
+    'Retrieve translated texts associated with a specific product_',
+    TranslatedProductTextsSchema,
+    async (params) => translatedProductTextsHandler(context, params),
+  );
+
+  server.tool(
+    'productMedia_getTexts',
+    'Retrieve translated texts associated with a specific product media asset.',
+    TranslatedProductMediaTextsSchema,
+    async (params) => translatedProductMediaTextsHandler(context, params),
+  );
+
+  server.tool(
+    'productVariation_getTexts',
+    'Retrieve translated texts for a product variation or optionally a specific variation option.',
+    TranslatedProductVariationTextsSchema,
+    async (params) => translatedProductVariationTextsHandler(context, params),
+  );
+  server.tool(
+    'productVariation_updateTexts',
+    'Update product variation texts with the specified locales for product variations that match the provided variation ID and production option value.',
+    UpdateProductVariationTextsSchema,
+    async (params) => updateProductVariationTextsHandler(context, params),
+  );
+  server.tool(
+    'product_siblings',
+    'Retrieve sibling products of a given product, optionally filtered by assortment ID, with support for pagination and inclusion of inactive products.',
+    ProductSiblingsSchema,
+    async (params) => productSiblingsHandler(context, params),
+  );
+
+  server.tool(
+    'product_getMedias',
+    'Retrieve media assets associated with a product, optionally filtered by tags and paginated.',
+    ProductMediaSchema,
+    async (params) => productMediaHandler(context, params),
+  );
+  server.tool(
+    'product_variationProducts',
+    'Retrieve all variant products of a configurable product that exactly match the provided combination of variation key-value pairs (e.g., Color: Red, Size: M). You must provide at least one vector. Optionally include inactive variants in the result.',
+    VariationProductsSchema,
+    async (params) => variationProductsHandler(context, params),
+  );
+
+  server.tool(
+    'product_variations',
+    'Retrieve all defined variation attributes (e.g., Color, Size) and their possible values for a configurable product.',
+    ProductVariationsSchema,
+    async (params) => productVariationsHandler(context, params),
+  );
+
+  server.tool(
+    'product_addBundleItem',
+    'Adds a product as a bundled item to another product. Only works if the target product is of type BUNDLE_PRODUCT. You must provide the ID of the bundle and the ID and quantity of the item to include.',
+    AddProductBundleItemSchema,
+    async (params) => addProductBundleItemHandler(context, params),
+  );
+
+  server.tool(
+    'product_removeBundleItem',
+    'Removes a bundled product from a BUNDLE_PRODUCT using its 0-based index in the bundle list. The product must be of type BUNDLE_PRODUCT.',
+    RemoveProductBundleItemSchema,
+    async (params) => removeProductBundleItemHandler(context, params),
+  );
+
+  server.tool(
+    'product_assignments',
+    'Retrieve the full assignment matrix of a configurable product, including all assigned variants by their variation vectors. Optionally include inactive variants.',
+    ProductAssignmentsSchema,
+    async (params) => productAssignmentsHandler(context, params),
+  );
+
+  server.tool(
+    'product_bundleItems',
+    'Retrieve all bundle items from a product of type BUNDLE. Each item includes the configuration and quantity.',
+    ProductBundleItemsSchema,
+    async (params) => productBundleItemsHandler(context, params),
+  );
+
+  server.tool(
+    'product_simulatedPriceRange',
+    'Simulate the price range for a CONFIGURABLE_PRODUCT and its variant combinations based on quantity, variation selections, and pricing rules. Only applicable to configurable products.',
+    SimulatedPriceRangeSchema,
+    async (params) => simulatedPriceRangeHandler(context, params),
+  );
+  server.tool(
+    'product_simulatedPrice',
+    'Simulate the price for a product given a complete configuration vector and quantity. Useful for previewing dynamic pricing rules.',
+    SimulatedPriceSchema,
+    async (params) => simulatedPriceHandler(context, params),
+  );
+
+  server.tool(
+    'product_catalogPrice',
+    'Retrieve the catalog price for any product type, optionally for a specific quantity and currency. when ask for product price without specifying what, always use this tool',
+    CatalogPriceSchema,
+    async (params) => catalogPriceHandler(context, params),
+  );
+};

package/src/mcp/tools/product/listProducts.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+
+const SortOptionInputSchema = z.object({
+  key: z.string().min(1).describe('Field to sort by'),
+  value: z.enum(['ASC', 'DESC']).describe('Sort direction'),
+});
+
+export const ProductsListSchema = {
+  queryString: z.string().optional().describe('Free-text filter for products'),
+  tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Filter by lowercase tags'),
+  slugs: z.array(z.string().min(1)).optional().describe('Filter by product slugs'),
+  limit: z.number().int().min(1).max(100).default(10).describe('Maximum number of products to return'),
+  offset: z.number().int().min(0).default(0).describe('Number of products to skip'),
+  includeDrafts: z.boolean().default(false).describe('Whether to include draft (unpublished) products'),
+  sort: z.array(SortOptionInputSchema).optional().describe('Sorting options'),
+};
+
+export const ProductsListZodSchema = z.object(ProductsListSchema);
+
+export type ProductsListParams = z.infer<typeof ProductsListZodSchema>;
+
+export async function productsListHandler(context: Context, params: ProductsListParams) {
+  const { modules, userId } = context;
+
+  try {
+    log('handler productsListHandler', { userId, params });
+
+    const products = await modules.products.findProducts(params as any);
+    const normalizedProducts = await Promise.all(
+      products.map(async ({ _id }) => getNormalizedProductDetails(_id, context)),
+    );
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            products: normalizedProducts,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching products: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}