@unchainedshop/api 4.0.0-rc.4 → 4.0.0-rc.5

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

@@ -8,6 +8,7 @@ import {
   ProductWrongTypeError,
 } from '../../../errors.js';
 import { ProductConfiguration, ProductTypes } from '@unchainedshop/core-products';
+import { log } from '@unchainedshop/logger';
 
 const extractVariationMatrix = (variations = []) => {
   const cartesianProduct = (arrays) => {
@@ -36,33 +37,33 @@ const combinationExists = (matrix, combination) => {
   });
 };
 
-// Zod schema for ProductAssignmentVectorInput
 const ProductAssignmentVectorSchema = z.object({
   key: z.string().min(1).describe('Attribute key (e.g., "Color", "Size")'),
   value: z.string().min(1).describe('Attribute value (e.g., "Red", "M")'),
 });
 
 export const AssignProductVariationSchema = {
-  proxyId: z.string().min(1).describe('should be ID of the CONFIGURABLE_PRODUCT (parent) only'),
+  proxyId: z.string().min(1).describe('ID of the CONFIGURABLE_PRODUCT (parent) only'),
   productId: z
     .string()
     .min(1)
-    .describe('ID of the product being assigned. can not be a CONFIGURABLE_PRODUCT product'),
+    .describe('ID of the product being assigned. Cannot be a CONFIGURABLE_PRODUCT product'),
   vectors: z
     .array(ProductAssignmentVectorSchema)
     .min(1)
     .describe('Combination of attributes uniquely identifying the variant'),
 };
-// Full schema for the mutation
+
 export const AddProductAssignmentZodSchema = z.object(AssignProductVariationSchema);
 
 export type AddProductAssignmentParams = z.infer<typeof AddProductAssignmentZodSchema>;
 
 export async function addProductAssignmentHandler(context: Context, params: AddProductAssignmentParams) {
   const { proxyId, productId, vectors } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler addProductAssignmentHandler', { userId, params });
     const proxyProduct = await modules.products.findProduct({
       productId: proxyId,
     });

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

@@ -7,9 +7,9 @@ export const AddProductMediaUploadSchema = {
   mediaName: z
     .string()
     .min(1)
-    .describe('Name of the media file (e.g. "image.png") use random name if not provided'),
+    .describe('Name of the media file (e.g. "image.png"); use random name if not provided'),
   productId: z.string().min(1).describe('ID of the product to link media to'),
-  url: z.string().describe('Anonymously fetchable URL of the source media, can be a data URL too'),
+  url: z.string().describe('Anonymously fetchable URL of the source media'),
 };
 
 export const AddProductMediaUploadZodSchema = z.object(AddProductMediaUploadSchema);
@@ -24,7 +24,7 @@ export async function addProductMediaUploadHandler(
   const { modules, services, userId } = context;
 
   try {
-    log('addProductMediaUploadHandler', { mediaName, productId, userId, url });
+    log('handler addProductAssignmentHandler', { userId, params });
     const {
       _id: fileId,
       putURL,

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
 import { Product, ProductText, ProductTypes } from '@unchainedshop/core-products';
+import { log } from '@unchainedshop/logger';
 const productTypeKeys = Object.keys(ProductTypes) as [
   keyof typeof ProductTypes,
   ...(keyof typeof ProductTypes)[],
@@ -39,11 +40,14 @@ export type CreateProductParams = z.infer<typeof CreateProductZodSchema>;
 
 export async function createProductHandler(context: Context, params: CreateProductParams) {
   const { product, texts } = params;
+  const { modules, userId } = context;
+
   try {
-    const newProduct = await context.modules.products.create(product as Product);
+    log('handler createProductHandler', { userId, params });
+    const newProduct = await modules.products.create(product as Product);
     let productTexts: any[] = texts;
     if (texts) {
-      productTexts = await context.modules.products.texts.updateTexts(
+      productTexts = await modules.products.texts.updateTexts(
         newProduct._id,
         texts as unknown as ProductText[],
       );

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

@@ -3,6 +3,7 @@ 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,
@@ -47,9 +48,10 @@ export async function createProductVariationHandler(
   params: CreateProductVariationParams,
 ) {
   const { productId, variation, texts } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler createProductVariationHandler', { userId, params });
     const product = await modules.products.findProduct({ productId });
     if (!product) throw new ProductNotFoundError({ productId });
 

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

@@ -2,6 +2,7 @@ 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
@@ -30,8 +31,10 @@ export async function createProductVariationOptionHandler(
   params: CreateProductVariationOptionParams,
 ) {
   const { productVariationId, option, texts } = params;
-  const { modules } = context;
+  const { modules, userId } = context;
+
   try {
+    log('handler createProductVariationOptionHandler', { userId, params });
     const variation = await modules.products.variations.findProductVariation({
       productVariationId,
     });

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

@@ -1,19 +1,14 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
 import { getNormalizedProductDetails } from '../../utils/getNormalizedProductDetails.js';
+import { log } from '@unchainedshop/logger';
 
-/**
- * Zod schema for the get_product tool (as raw object for MCP)
- */
 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'),
 };
 
-/**
- * Zod object schema for type inference and validation
- */
 export const GetProductZodSchema = z
   .object(GetProductSchema)
   .refine(
@@ -21,20 +16,15 @@ export const GetProductZodSchema = z
     'At least one of productId, slug, or sku must be provided',
   );
 
-/**
- * Interface for the get_product tool parameters
- */
 export type GetProductParams = z.infer<typeof GetProductZodSchema>;
 
-/**
- * Implementation of the get_product tool
- */
 export async function getProductHandler(context: Context, params: GetProductParams) {
   const { productId, slug, sku } = params;
+  const { modules, userId } = context;
 
   try {
-    // Find the product
-    const product = await context.modules.products.findProduct({
+    log('handler getProductHandler', { userId, params });
+    const product = await modules.products.findProduct({
       productId,
       slug,
       sku,

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

@@ -0,0 +1,272 @@
+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';
+
+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 plan details for a PLAN_PRODUCT type 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 attribute vectors.',
+    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_media_reorder',
+    '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),
+  );
+};

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

@@ -1,131 +1,36 @@
 import { z } from 'zod';
-import { SortDirection } from '@unchainedshop/utils';
 import { Context } from '../../../context.js';
-import { ProductText } from '@unchainedshop/core-products';
-import normalizeMediaUrl from '../../utils/normalizeMediaUrl.js';
-
-/**
- * Zod schema for the list_products tool (as raw object for MCP)
- */
-export const ListProductsSchema = {
-  // Search & Filter
-  queryString: z.string().optional().describe('Text search across product fields'),
-  tags: z.array(z.string()).optional().describe('Filter by product tags'),
-  productIds: z.array(z.string()).optional().describe('Filter by specific product IDs'),
-  filterQuery: z
-    .array(
-      z.object({
-        key: z.string().describe('Filter key'),
-        value: z.string().optional().describe('Filter value'),
-      }),
-    )
-    .optional()
-    .describe('Key-value filter pairs'),
-  assortmentId: z.string().optional().describe('Filter by assortment'),
-  includeInactive: z.boolean().default(false).describe('Include inactive products'),
-
-  // Pagination
-  limit: z.number().min(1).max(100).default(20).describe('Results per page'),
-  offset: z.number().min(0).default(0).describe('Skip results for pagination'),
-
-  // Sorting
-  sort: z
-    .array(
-      z.object({
-        key: z.string().describe('Sort field'),
-        value: z.enum(['ASC', 'DESC']).describe('Sort direction'),
-      }),
-    )
-    .optional()
-    .describe('Sort options'),
+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'),
 };
 
-/**
- * Zod object schema for type inference
- */
-export const ListProductsZodSchema = z.object(ListProductsSchema);
+export const ProductsListZodSchema = z.object(ProductsListSchema);
 
-/**
- * Interface for the list_products tool parameters
- */
-export type ListProductsParams = z.infer<typeof ListProductsZodSchema>;
+export type ProductsListParams = z.infer<typeof ProductsListZodSchema>;
 
-/**
- * Implementation of the list_products tool
- */
-export async function listProductsHandler(context: Context, params: ListProductsParams) {
-  const {
-    queryString,
-    tags,
-    productIds,
-    filterQuery,
-    assortmentId,
-    includeInactive = false,
-    limit = 20,
-    offset = 0,
-    sort,
-  } = params;
+export async function productsListHandler(context: Context, params: ProductsListParams) {
+  const { modules, userId } = context;
 
   try {
-    let filteredProductIds = productIds;
-
-    // If assortmentId is provided, get product IDs from assortment
-    if (assortmentId) {
-      const assortmentProductIds = await context.modules.assortments.products.findProductIds({
-        assortmentId,
-      });
-
-      if (filteredProductIds) {
-        // Intersection of both sets
-        filteredProductIds = filteredProductIds.filter((id) => assortmentProductIds.includes(id));
-      } else {
-        filteredProductIds = assortmentProductIds;
-      }
-    }
+    log('handler productsListHandler', { userId, params });
 
-    let searchResult: any = {};
-    if (queryString)
-      searchResult = await context.services.filters.searchProducts(
-        {
-          queryString,
-          productIds: filteredProductIds,
-          includeInactive,
-          filterQuery: filterQuery?.filter((f) => f.key) as { key: string; value?: string }[],
-        },
-        {
-          locale: context.locale,
-        },
-      );
-    const products = await context.modules.products.findProducts({
-      productIds: searchResult?.aggregatedFilteredProductIds,
-      tags,
-      limit,
-      offset,
-      includeDrafts: includeInactive,
-      sort: sort?.filter((s) => s.key) as { key: string; value: SortDirection }[],
-    });
-
-    const productTexts = await context.loaders.productTextLoader.loadMany(
-      products.map(({ _id }) => ({
-        productId: _id,
-        locale: context.locale,
-      })),
-    );
-
-    // iterate all products and add texts
+    const products = await modules.products.findProducts(params as any);
     const normalizedProducts = await Promise.all(
-      products.map(async (product) => {
-        const texts = productTexts.filter((text) => (text as ProductText)?.productId === product._id);
-        const productMedias = await context.modules.products.media.findProductMedias({
-          productId: product._id,
-        });
-        const media = await normalizeMediaUrl(productMedias, context);
-        return {
-          ...product,
-          texts,
-          media,
-        };
-      }),
+      products.map(async ({ _id }) => getNormalizedProductDetails(_id, context)),
     );
 
     return {
@@ -134,15 +39,18 @@ export async function listProductsHandler(context: Context, params: ListProducts
           type: 'text' as const,
           text: JSON.stringify({
             products: normalizedProducts,
-            total: searchResult?.aggregatedTotalProductIds?.length,
-            filtered: searchResult?.aggregatedFilteredProductIds?.length || products?.length,
           }),
         },
       ],
     };
   } catch (error) {
     return {
-      content: [{ type: 'text' as const, text: `Error listing products: ${(error as Error).message}` }],
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error fetching products: ${(error as Error).message}`,
+        },
+      ],
     };
   }
 }

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
 
 export const ProductReviewsCountSchema = {
   queryString: z.string().optional().describe('Optional query string to filter reviews'),
@@ -10,9 +11,10 @@ export const ProductReviewsCountZodSchema = z.object(ProductReviewsCountSchema);
 export type ProductReviewsCountParams = z.infer<typeof ProductReviewsCountZodSchema>;
 
 export async function productReviewsCountHandler(context: Context, params: ProductReviewsCountParams) {
-  const { modules } = context;
+  const { modules, userId } = context;
 
   try {
+    log('handler productReviewsCountHandler', { userId, params });
     const count = await modules.products.reviews.count(params);
 
     return {

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

@@ -30,6 +30,7 @@ export async function productReviewsHandler(context: Context, params: ProductRev
   try {
     log(`query productReviews: ${limit} ${offset} ${queryString || ''}`, {
       userId,
+      params,
     });
 
     const reviews = await modules.products.reviews.findProductReviews(params as any);