@unchainedshop/api 4.0.0-rc.2 → 4.0.0-rc.3

package/src/mcp/README.md

@@ -0,0 +1,25 @@
+# MCP Server
+
+This directory contains the Model Context Protocol (MCP) server implementation for Unchained Commerce.
+
+## Structure
+
+```
+mcp/
+├── index.ts              # Main MCP server setup
+├── types.ts              # Shared type definitions
+├── tools/                # Individual tool implementations
+│   ├── index.ts          # Re-exports for all tools
+│   └── listProducts.ts   # List products tool
+└── utils/                # Shared utilities
+    └── html.ts           # HTML generation utilities
+```
+
+## Adding New Tools
+
+To add a new tool:
+
+1. Create a new file in the `tools/` directory
+2. Export the schema and handler from the file
+3. Add the exports to `tools/index.ts`
+4. Register the tool in the main `index.ts` file

package/src/mcp/index.ts

@@ -0,0 +1,313 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../context.js';
+import {
+  listProductsHandler,
+  ListProductsSchema,
+  getProductHandler,
+  GetProductSchema,
+  createProductHandler,
+  CreateProductSchema,
+  RemoveProductSchema,
+  removeProductHandler,
+  PublishProductSchema,
+  publishProductHandler,
+  UnpublishProductSchema,
+  unpublishProductHandler,
+  UpdateProductSchema,
+  updateProductHandler,
+  UpdateProductTextsSchema,
+  updateProductTextsHandler,
+  UpdateProductCommerceSchema,
+  updateProductCommerceHandler,
+  ListCurrenciesSchema,
+  currenciesHandler,
+  CurrencySchema,
+  currencyHandler,
+  ListCountriesSchema,
+  countriesHandler,
+  CountrySchema,
+  countryHandler,
+  ListLanguagesSchema,
+  languagesHandler,
+  LanguageSchema,
+  languageHandler,
+  UpdateProductSupplySchema,
+  updateProductSupplyHandler,
+  UpdateProductPlanSchema,
+  updateProductPlanHandler,
+  UpdateProductTokenizationSchema,
+  updateProductTokenizationHandler,
+  ProductsCountSchema,
+  productsCountHandler,
+  CreateProductVariationSchema,
+  createProductVariationHandler,
+  RemoveProductVariationSchema,
+  removeProductVariationHandler,
+  AssignProductVariationSchema,
+  addProductAssignmentHandler,
+  CreateProductVariationOptionSchema,
+  createProductVariationOptionHandler,
+  removeProductAssignmentHandler,
+  RemoveProductVariationOptionSchema,
+  removeProductVariationOptionHandler,
+  RemoveProductAssignmentSchema,
+  CreateLanguageSchema,
+  createLanguageHandler,
+  UpdateLanguageSchema,
+  updateLanguageHandler,
+  RemoveLanguageSchema,
+  removeLanguageHandler,
+  AddProductMediaUploadSchema,
+  addProductMediaUploadHandler,
+  RemoveProductMediaSchema,
+  removeProductMediaHandler,
+  UpdateProductMediaTextsSchema,
+  updateProductMediaTextsHandler,
+  ReorderProductMediaSchema,
+  reorderProductMediaHandler,
+  ProductReviewsCountSchema,
+  productReviewsCountHandler,
+  ProductReviewsSchema,
+  productReviewsHandler,
+} from './tools/index.js';
+
+export default function createMcpServer(context: Context, roles) {
+  const server = new McpServer({
+    name: 'Unchained MCP Server',
+    version: '1.0.0',
+  });
+
+  if (!roles?.includes('admin')) {
+    return server;
+  }
+
+  server.tool(
+    'list_products',
+    'Search and list products with comprehensive filtering and pagination support',
+    ListProductsSchema,
+    async (params) => listProductsHandler(context, params),
+  );
+
+  server.tool(
+    'products_count',
+    'Search and returns total number of products registered in the system with comprehensive filtering if provided',
+    ProductsCountSchema,
+    async (params) => productsCountHandler(context, params),
+  );
+  server.tool('get_product', 'Get detailed product information', GetProductSchema, async (params) =>
+    getProductHandler(context, params),
+  );
+
+  server.tool(
+    'create_product',
+    'Adds or create new product the product will be in DRAFT/unpublish status',
+    CreateProductSchema,
+    async (params) => createProductHandler(context, params),
+  );
+  server.tool(
+    'remove_product',
+    'Removed or deletes a product by its id changing its status to DELETED and removing it from sale',
+    RemoveProductSchema,
+    async (params) => removeProductHandler(context, params),
+  );
+
+  server.tool(
+    'publish_product',
+    'Publish a product by its id changing it to active and available for sale',
+    PublishProductSchema,
+    async (params) => publishProductHandler(context, params),
+  );
+
+  server.tool(
+    'unpublish_product',
+    'Deactivates or Unpublishes product by its id changing it to DRAFT and not available for sale',
+    UnpublishProductSchema,
+    async (params) => unpublishProductHandler(context, params),
+  );
+  server.tool(
+    'update_product',
+    'Modify/Update generic infos of a product (tags for ex.)',
+    UpdateProductSchema,
+    async (params) => updateProductHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_texts',
+    'Modify/update localized texts of a product',
+    UpdateProductTextsSchema,
+    async (params) => updateProductTextsHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_commerce',
+    'Modify/update products commerce info like prices, taxes, etc. for all product types except CONFIGURABLE_PRODUCT. for currency value always use registered currency in the system and not a custom one, it should not be called for CONFIGURABLE_PRODUCT type products',
+    UpdateProductCommerceSchema,
+    async (params) => updateProductCommerceHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_warehousing',
+    'Modify/update products commerce info like prices, taxes, etc. for SIMPLE_PRODUCT product type only.  it is only available for SIMPLE_PRODUCT type products',
+    UpdateProductCommerceSchema,
+    async (params) => updateProductCommerceHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_supply',
+    'Modify/update products supply of SIMPLE_PRODUCT type info like prices, taxes, etc. it is only available for SIMPLE_PRODUCT type products',
+    UpdateProductSupplySchema,
+    async (params) => updateProductSupplyHandler(context, params),
+  );
+  server.tool(
+    'update_tokenized_product',
+    'Modify/update products supply of TOKENIZED_PRODUCT type info like contractAddress, contractStandard, tokenId, supply, ercMetadataProperties etc. it is only available for TOKENIZED_PRODUCT type products',
+    UpdateProductTokenizationSchema,
+    async (params) => updateProductTokenizationHandler(context, params),
+  );
+  server.tool(
+    'update_product_plan',
+    'Modify/update products subscription/plan information of PLAN_PRODUCT type info like billing period, trial period and usage calculation, etc. it is only available for PLAN_PRODUCT type products',
+    UpdateProductPlanSchema,
+    async (params) => updateProductPlanHandler(context, params),
+  );
+
+  server.tool(
+    'list_currencies',
+    'List all available currencies in the system, when currency is required and not implicitly provided use this tool to get the list of available currencies also if non existing currency is provided to you by a user inform them it does not exist and to create it first before they can use it',
+    ListCurrenciesSchema,
+    async (params) => currenciesHandler(context, params),
+  );
+
+  server.tool(
+    'get_currency',
+    'Gets a single currency registered in the system',
+    CurrencySchema,
+    async (params) => currencyHandler(context, params),
+  );
+
+  server.tool(
+    'list_countries',
+    'List all available countries in the system, when country is required and not implicitly provided use this tool to get the list of available countries also if non existing country is provided to you by a user inform them it does not exist and to create it first before they can use it',
+    ListCountriesSchema,
+    async (params) => countriesHandler(context, params),
+  );
+
+  server.tool(
+    'get_country',
+    'Gets a single country registered in the system',
+    CountrySchema,
+    async (params) => countryHandler(context, params),
+  );
+
+  server.tool(
+    'list_languages',
+    'List all available languages in the system, when language is required and not implicitly provided use this tool to get the list of available languages also if non existing language is provided to you by a user inform them it does not exist and to create it first before they can use it',
+    ListLanguagesSchema,
+    async (params) => languagesHandler(context, params),
+  );
+
+  server.tool(
+    'get_language',
+    'Gets a single language registered in the system',
+    LanguageSchema,
+    async (params) => languageHandler(context, params),
+  );
+
+  server.tool(
+    'create_product_variation',
+    'Adds/create a variation of a product, it is only available for CONFIGURABLE_PRODUCT type products',
+    CreateProductVariationSchema,
+    async (params) => createProductVariationHandler(context, params),
+  );
+
+  server.tool(
+    'remove_product_variation',
+    'removes a variation of a product',
+    RemoveProductVariationSchema,
+    async (params) => removeProductVariationHandler(context, params),
+  );
+
+  server.tool(
+    'assign_product_variation',
+    'Link a product to a ConfigurableProduct variation option by providing a vector combination that uniquely identifies the variation option',
+    AssignProductVariationSchema,
+    async (params) => addProductAssignmentHandler(context, params),
+  );
+
+  server.tool(
+    'add_variation_options',
+    'Adds variation option to an existing product variations',
+    CreateProductVariationOptionSchema,
+    async (params) => createProductVariationOptionHandler(context, params),
+  );
+
+  server.tool(
+    'remove_variation_options',
+    'Removes product option value for product variation with the provided variation option value',
+    RemoveProductVariationOptionSchema,
+    async (params) => removeProductVariationOptionHandler(context, params),
+  );
+
+  server.tool(
+    'remove_product_variation_assignment',
+    'Unlinks a product from a ConfigurableProduct by providing a configuration combination that uniquely identifies a row in the assignment matrix',
+    RemoveProductAssignmentSchema,
+    async (params) => removeProductAssignmentHandler(context, params),
+  );
+
+  server.tool('add_language', 'Adds new language', CreateLanguageSchema, async (params) =>
+    createLanguageHandler(context, params),
+  );
+
+  server.tool('update_language', 'Updates language', UpdateLanguageSchema, async (params) =>
+    updateLanguageHandler(context, params),
+  );
+
+  server.tool('remove_language', 'Deletes a language', RemoveLanguageSchema, async (params) =>
+    removeLanguageHandler(context, params),
+  );
+
+  server.tool(
+    'add_product_media',
+    'Adds media to a product',
+    AddProductMediaUploadSchema,
+    async (params) => addProductMediaUploadHandler(context, params),
+  );
+
+  server.tool(
+    'remove_product_media',
+    "Remove a media asset from a product's visualization",
+    RemoveProductMediaSchema,
+    async (params) => removeProductMediaHandler(context, params),
+  );
+
+  server.tool(
+    'update_product_media_texts',
+    "Modify localized texts part of a product's media asset",
+    UpdateProductMediaTextsSchema,
+    async (params) => updateProductMediaTextsHandler(context, params),
+  );
+
+  server.tool(
+    'reorder_product_media',
+    'Reorder a media asset (first is primary)',
+    ReorderProductMediaSchema,
+    async (params) => reorderProductMediaHandler(context, params),
+  );
+
+  server.tool(
+    'product_review_count',
+    'Returns total number of product reviews',
+    ProductReviewsCountSchema,
+    async (params) => productReviewsCountHandler(context, params),
+  );
+
+  server.tool(
+    'product_reviews',
+    ' Get all product reviews, by default sorted by creation date (descending)',
+    ProductReviewsSchema,
+    async (params) => productReviewsHandler(context, params),
+  );
+
+  return server;
+}

package/src/mcp/tools/addProductAssignmentHandler.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { getNormalizedProductDetails } from '../utils/getNormalizedProductDetails.js';
+import {
+  ProductNotFoundError,
+  ProductVariationVectorAlreadySet,
+  ProductVariationVectorInvalid,
+  ProductWrongTypeError,
+} from '../../errors.js';
+import { ProductConfiguration, ProductTypes } from '@unchainedshop/core-products';
+
+const extractVariationMatrix = (variations = []) => {
+  const cartesianProduct = (arrays) => {
+    return arrays.reduce(
+      (acc, array) => acc.flatMap((item) => array.map((value) => [...item, value])),
+      [[]],
+    );
+  };
+  const keys = variations.map((item) => item.key);
+  const options = variations.map((item) => item.options);
+  const combinations = cartesianProduct(options);
+  return combinations.map((combination) =>
+    combination.reduce((acc, value, index) => {
+      acc[keys[index]] = value;
+      return acc;
+    }, {}),
+  );
+};
+
+const combinationExists = (matrix, combination) => {
+  return matrix.some((variation) => {
+    return (
+      Object.keys(variation).length === Object.keys(combination).length && // Ensure both have the same number of keys
+      Object.entries(combination).every(([key, value]) => variation[key] === value)
+    );
+  });
+};
+
+// 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'),
+  productId: z
+    .string()
+    .min(1)
+    .describe('ID of the product being assigned. can not 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;
+
+  try {
+    const proxyProduct = await modules.products.findProduct({
+      productId: proxyId,
+    });
+    if (!proxyProduct) throw new ProductNotFoundError({ proxyId });
+
+    if (proxyProduct.type !== ProductTypes.ConfigurableProduct)
+      throw new ProductWrongTypeError({
+        proxyId,
+        received: proxyProduct.type,
+        required: ProductTypes.ConfigurableProduct,
+      });
+    const variations = await modules.products.variations.findProductVariations({
+      productId: proxyId,
+    });
+    const variationMatrix = extractVariationMatrix(variations);
+    const normalizedVectors = vectors?.reduce((prev, { key, value }) => {
+      return {
+        ...prev,
+        [key]: value,
+      };
+    }, {});
+    if (!combinationExists(variationMatrix, normalizedVectors))
+      throw new ProductVariationVectorInvalid({ proxyId, vectors });
+
+    const added = await modules.products.assignments.addProxyAssignment({
+      productId,
+      proxyId,
+      vectors: vectors as ProductConfiguration[],
+    });
+
+    if (!added) throw new ProductVariationVectorAlreadySet({ proxyId, vectors });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            product: await getNormalizedProductDetails(proxyId, context),
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error assigning product: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/addProductMediaUploadHandler.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { log } from '@unchainedshop/logger';
+import { FileNotFoundError, FileUploadExpiredError } from '../../errors.js';
+
+export const AddProductMediaUploadSchema = {
+  mediaName: z
+    .string()
+    .min(1)
+    .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'),
+};
+
+export const AddProductMediaUploadZodSchema = z.object(AddProductMediaUploadSchema);
+
+export type AddProductMediaUploadParams = z.infer<typeof AddProductMediaUploadZodSchema>;
+
+export async function addProductMediaUploadHandler(
+  context: Context,
+  params: AddProductMediaUploadParams,
+) {
+  const { mediaName, productId, url } = params;
+  const { modules, services, userId } = context;
+
+  try {
+    log('addProductMediaUploadHandler', { mediaName, productId, userId, url });
+    const {
+      _id: fileId,
+      putURL,
+      type,
+      size,
+    } = await services.files.createSignedURL({
+      directoryName: 'product-media',
+      fileName: mediaName,
+      meta: { productId },
+    });
+
+    const sourceResponse = await fetch(url);
+    const uploadUrl = new URL(putURL, process.env.ROOT_URL || 'http://localhost:4010');
+    const uploadResponse = await fetch(uploadUrl, {
+      method: 'PUT',
+      body: sourceResponse.body,
+      duplex: 'half',
+    } as RequestInit);
+
+    if (!uploadResponse.ok) {
+      throw new Error(`Upload failed: ${uploadResponse.status} ${uploadResponse.statusText}`);
+    }
+
+    const file = await modules.files.findFile({ fileId });
+    if (!file) throw new FileNotFoundError({ fileId });
+
+    if (file.expires && new Date(file.expires).getTime() < Date.now()) {
+      throw new FileUploadExpiredError({ fileId });
+    }
+    const linked = await services.files.linkFile({ fileId, size, type });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({
+            file: linked,
+          }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error uploading product media: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/countriesHandler.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { SortDirection } from '@unchainedshop/utils';
+
+const sortDirectionKeys = Object.keys(SortDirection) as [
+  keyof typeof SortDirection,
+  ...(keyof typeof SortDirection)[],
+];
+
+export const ListCountriesSchema = {
+  limit: z.number().int().min(1).max(100).default(50),
+  offset: z.number().int().min(0).default(0),
+  includeInactive: z.boolean().default(false),
+  queryString: z.string().min(1).optional(),
+  sort: z
+    .array(
+      z.object({
+        key: z.string().min(1),
+        value: z.enum(sortDirectionKeys).describe("Sort direction, e.g., 'ASC' or 'DESC'"),
+      }),
+    )
+    .optional(),
+};
+
+export const ListCountriesZodSchema = z.object(ListCountriesSchema);
+
+export type ListCountriesParams = z.infer<typeof ListCountriesZodSchema>;
+
+export async function countriesHandler(context: Context, params: ListCountriesParams) {
+  const { limit, offset, includeInactive, queryString, sort } = params;
+  const { modules } = context;
+
+  try {
+    const countries = await modules.countries.findCountries({
+      limit,
+      offset,
+      includeInactive,
+      queryString,
+      sort: sort as any[],
+    });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ countries }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving countries: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/countryHandler.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+import { CountryNotFoundError } from '../../errors.js';
+
+export const CountrySchema = {
+  countryId: z.string().min(1).describe('The ID of the country to fetch'),
+};
+
+export const CountryZodSchema = z.object(CountrySchema);
+
+export type CountryParams = z.infer<typeof CountryZodSchema>;
+
+export async function countryHandler(context: Context, params: CountryParams) {
+  const { countryId } = params;
+  const { modules } = context;
+
+  try {
+    const country = await modules.countries.findCountry({ countryId });
+
+    if (!country) throw new CountryNotFoundError({ countryId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ country }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error retrieving country: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}

package/src/mcp/tools/createLanguageHandler.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { Context } from '../../context.js';
+
+const CreateLanguageInputSchema = z.object({
+  isoCode: z
+    .string()
+    .min(2)
+    .max(10)
+    .describe('Language ISO code, e.g. "en" or "de-CH, accept only valid ISO code"'),
+});
+
+export const CreateLanguageSchema = {
+  language: CreateLanguageInputSchema,
+};
+
+export const CreateLanguageZodSchema = z.object(CreateLanguageSchema);
+export type CreateLanguageParams = z.infer<typeof CreateLanguageZodSchema>;
+
+export async function createLanguageHandler(context: Context, params: CreateLanguageParams) {
+  const { language } = params;
+  const { modules } = context;
+
+  try {
+    const languageId = await modules.languages.create(language as any);
+
+    const newLanguage = await modules.languages.findLanguage({ languageId });
+
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ language: newLanguage }),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: `Error creating language: ${(error as Error).message}`,
+        },
+      ],
+    };
+  }
+}