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

package/src/mcp/tools/assortment/handlers/reorderAssortmentFilters.ts

@@ -0,0 +1,22 @@
+import { Context } from '../../../../context.js';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function reorderAssortmentFilters(
+  context: Context,
+  params: Params<'REORDER_FILTERS'>,
+) {
+  const { modules } = context;
+  const { sortKeys } = params;
+
+  const reorderedFilters = await modules.assortments.filters.updateManualOrder({
+    sortKeys: sortKeys as any,
+  });
+  const filters = await Promise.all(
+    reorderedFilters?.map(async ({ filterId, ...rest }) => ({
+      ...(await getNormalizedFilterDetails(filterId, context)),
+      ...rest,
+    })) || [],
+  );
+  return { filters };
+}

package/src/mcp/tools/assortment/handlers/reorderAssortmentLinks.ts

@@ -0,0 +1,17 @@
+import { Context } from '../../../../context.js';
+import { getNormalizedAssortmentDetails } from '../../../utils/getNormalizedAssortmentDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function reorderAssortmentLinks(context: Context, params: Params<'REORDER_LINKS'>) {
+  const { modules } = context;
+  const { sortKeys } = params;
+
+  const links = await modules.assortments.links.updateManualOrder({ sortKeys: sortKeys as any });
+  const normalizedAssortmentLinks = await Promise.all(
+    links?.map(async (link) => ({
+      ...(await getNormalizedAssortmentDetails({ assortmentId: link?.childAssortmentId }, context)),
+      ...link,
+    })) || [],
+  );
+  return { assortments: normalizedAssortmentLinks };
+}

package/src/mcp/tools/assortment/handlers/reorderAssortmentMedia.ts

@@ -0,0 +1,11 @@
+import { Context } from '../../../../context.js';
+import normalizeMediaUrl from '../../../utils/normalizeMediaUrl.js';
+import { Params } from '../schemas.js';
+
+export default async function reorderAssortmentMedia(context: Context, params: Params<'REORDER_LINKS'>) {
+  const { modules } = context;
+  const { sortKeys } = params;
+  const media = await modules.assortments.media.updateManualOrder({ sortKeys: sortKeys as any });
+
+  return { links: await normalizeMediaUrl(media, context) };
+}

package/src/mcp/tools/assortment/handlers/reorderAssortmentProducts.ts

@@ -0,0 +1,22 @@
+import { Context } from '../../../../context.js';
+import { getNormalizedProductDetails } from '../../../utils/getNormalizedProductDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function reorderAssortmentProducts(
+  context: Context,
+  params: Params<'REORDER_PRODUCTS'>,
+) {
+  const { modules } = context;
+  const { sortKeys } = params;
+
+  const reorderedProducts = await modules.assortments.products.updateManualOrder({
+    sortKeys: sortKeys as any,
+  });
+  const products = await Promise.all(
+    reorderedProducts?.map(async ({ productId, ...rest }) => ({
+      ...(await getNormalizedProductDetails(productId, context)),
+      ...rest,
+    })) || [],
+  );
+  return { products };
+}

package/src/mcp/tools/assortment/handlers/searchAssortmentProducts.ts

@@ -0,0 +1,48 @@
+import { Context } from '../../../../context.js';
+import { AssortmentNotFoundError } from '../../../../errors.js';
+import { getNormalizedAssortmentDetails } from '../../../utils/getNormalizedAssortmentDetails.js';
+import { getNormalizedProductDetails } from '../../../utils/getNormalizedProductDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function searchAssortmentProducts(
+  context: Context,
+  params: Params<'SEARCH_PRODUCTS'>,
+) {
+  const { modules, services } = context;
+  const { assortmentId, queryString, limit = 50, offset = 0, includeInactive = false } = params;
+
+  const assortment = await getNormalizedAssortmentDetails({ assortmentId }, context);
+  if (!assortment) throw new AssortmentNotFoundError({ assortmentId });
+
+  const productIds = await modules.assortments.findProductIds({
+    assortmentId,
+  });
+
+  const filterIds = await modules.assortments.filters.findFilterIds({
+    assortmentId,
+  });
+
+  const result = await services.filters.searchProducts(
+    {
+      queryString,
+      includeInactive,
+      productIds,
+      filterIds,
+    } as any,
+    {
+      locale: context.locale,
+    },
+  );
+
+  const products = await modules.products.search.findFilteredProducts({
+    limit,
+    offset,
+    productIds: result.aggregatedFilteredProductIds,
+    productSelector: result.searchConfiguration.productSelector,
+    sort: result.searchConfiguration.sortStage,
+  });
+  const products_normalized = await Promise.all(
+    products?.map(async ({ _id }) => getNormalizedProductDetails(_id, context)) || [],
+  );
+  return { assortment, products: products_normalized };
+}

package/src/mcp/tools/assortment/handlers/setAssortmentBase.ts

@@ -0,0 +1,15 @@
+import { Context } from '../../../../context.js';
+import { AssortmentNotFoundError } from '../../../../errors.js';
+import { getNormalizedAssortmentDetails } from '../../../utils/getNormalizedAssortmentDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function setAssortmentBase(context: Context, params: Params<'SET_BASE'>) {
+  const { modules } = context;
+  const { assortmentId } = params;
+
+  const existingAssortment = await modules.assortments.findAssortment({ assortmentId });
+  if (!existingAssortment) throw new AssortmentNotFoundError({ assortmentId });
+
+  await modules.assortments.setBase(assortmentId);
+  return { assortment: await getNormalizedAssortmentDetails({ assortmentId }, context) };
+}

package/src/mcp/tools/assortment/handlers/updateAssortment.ts

@@ -0,0 +1,26 @@
+import { Context } from '../../../../context.js';
+import { AssortmentNotFoundError } from '../../../../errors.js';
+import { getNormalizedAssortmentDetails } from '../../../utils/getNormalizedAssortmentDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function updateAssortment(context: Context, params: Params<'UPDATE'>) {
+  const { modules } = context;
+  const { assortmentId, assortment } = params;
+
+  const existingAssortment = await modules.assortments.findAssortment({ assortmentId });
+  if (!existingAssortment) throw new AssortmentNotFoundError({ assortmentId });
+
+  const updateData: any = {};
+
+  if (assortment.isRoot !== undefined) updateData.isRoot = assortment.isRoot;
+  if (assortment.isActive !== undefined) updateData.isActive = assortment.isActive;
+  if (assortment.tags !== undefined) updateData.tags = assortment.tags;
+  if (assortment.sequence !== undefined) updateData.sequence = assortment.sequence;
+  if (assortment.meta !== undefined) updateData.meta = assortment.meta;
+
+  if (Object.keys(updateData).length > 0) {
+    await modules.assortments.update(assortmentId, updateData);
+  }
+
+  return { assortment: await getNormalizedAssortmentDetails({ assortmentId }, context) };
+}

package/src/mcp/tools/assortment/handlers/updateAssortmentMediaTexts.ts

@@ -0,0 +1,21 @@
+import { AssortmentMediaText } from '@unchainedshop/core-assortments';
+import { Context } from '../../../../context.js';
+import { AssortmentMediaNotFoundError } from '../../../../errors.js';
+import { Params } from '../schemas.js';
+
+export default async function updateAssortmentMediaTexts(
+  context: Context,
+  params: Params<'UPDATE_MEDIA_TEXTS'>,
+) {
+  const { modules } = context;
+  const { assortmentMediaId, mediaTexts } = params;
+
+  const media = await modules.assortments.media.findAssortmentMedia({ assortmentMediaId });
+  if (!media) throw new AssortmentMediaNotFoundError({ assortmentMediaId });
+
+  const texts_updated = await modules.assortments.media.texts.updateMediaTexts(
+    assortmentMediaId,
+    mediaTexts as AssortmentMediaText[],
+  );
+  return { texts: texts_updated };
+}

package/src/mcp/tools/assortment/handlers/updateAssortmentStatus.ts

@@ -0,0 +1,18 @@
+import { Context } from '../../../../context.js';
+import { AssortmentNotFoundError } from '../../../../errors.js';
+import { getNormalizedAssortmentDetails } from '../../../utils/getNormalizedAssortmentDetails.js';
+import { Params } from '../schemas.js';
+
+export default async function updateAssortmentStatus(context: Context, params: Params<'UPDATE_STATUS'>) {
+  const { modules } = context;
+  const { assortmentId, statusAction } = params;
+  const assortment = await modules.assortments.findAssortment({ assortmentId });
+  if (!assortment) throw new AssortmentNotFoundError({ assortmentId });
+
+  const updateData = {
+    isActive: statusAction === 'ACTIVATE',
+  };
+
+  await modules.assortments.update(assortmentId, updateData as any);
+  return { assortment: await getNormalizedAssortmentDetails({ assortmentId }, context) };
+}

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

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Context } from '../../../context.js';
+import { assortmentManagement, AssortmentManagementSchema } from './assortmentManagement.js';
+
+export const registerAssortmentTools = (server: McpServer, context: Context) => {
+  server.tool(
+    'assortment_management',
+    'Unified assortment management system with comprehensive action-based operations: CREATE/UPDATE/REMOVE/GET/LIST/COUNT assortments, UPDATE_STATUS (activate/deactivate), ADD_MEDIA/REMOVE_MEDIA/REORDER_MEDIA/GET_MEDIA/UPDATE_MEDIA_TEXTS, ADD_PRODUCT/REMOVE_PRODUCT/GET_PRODUCTS/REORDER_PRODUCTS, ADD_FILTER/REMOVE_FILTER/GET_FILTERS/REORDER_FILTERS, ADD_LINK/REMOVE_LINK/GET_LINKS/REORDER_LINKS, GET_CHILDREN/SET_BASE, SEARCH_PRODUCTS, GET_TEXTS/GET_MEDIA_TEXTS. Supports comprehensive assortment management with type-specific validations and error handling.',
+    AssortmentManagementSchema,
+    async (params) => assortmentManagement(context, params),
+  );
+};

package/src/mcp/tools/assortment/schemas.ts

@@ -0,0 +1,343 @@
+import { z } from 'zod';
+import { SortDirection } from '@unchainedshop/utils';
+import {
+  PaginationSchema,
+  SortingSchema,
+  SearchSchema,
+  LocalizationTextSchema,
+} from '../../utils/sharedSchemas.js';
+
+export const sortDirectionKeys = Object.keys(SortDirection) as [string, ...string[]];
+
+export const AssortmentTextInputSchema = LocalizationTextSchema.extend({
+  slug: z.string().optional().describe('URL slug'),
+  description: z.string().optional().describe('Markdown description'),
+}).describe('Assortment localized text data');
+
+export const AssortmentMediaTextInputSchema = LocalizationTextSchema.describe(
+  'Assortment media localized text data',
+);
+
+export const AssortmentSchema = z.object({
+  isRoot: z.boolean().optional().describe('Whether this is a root-level assortment'),
+  isActive: z.boolean().optional().describe('Whether this assortment is active'),
+  tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Tags (lowercased strings)'),
+  sequence: z.number().int().optional().describe('Sorting sequence'),
+  meta: z.record(z.unknown()).optional().describe('Custom metadata as key-value pairs'),
+});
+
+export const actionValidators = {
+  CREATE: z.object({
+    assortment: AssortmentSchema.describe('Assortment data'),
+    texts: z.array(AssortmentTextInputSchema).optional().describe('Localized assortment text entries'),
+  }),
+
+  UPDATE: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+    assortment: AssortmentSchema.describe('Assortment data to update'),
+  }),
+
+  REMOVE: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+  }),
+
+  GET: z
+    .object({
+      assortmentId: z.string().min(1).optional().describe('Assortment ID'),
+      slug: z.string().optional().describe('Assortment slug'),
+    })
+    .refine((data) => data.assortmentId || data.slug, {
+      message: 'Either assortmentId or slug is required',
+    }),
+
+  LIST: z.object({
+    ...PaginationSchema,
+    ...SortingSchema,
+    ...SearchSchema,
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Filter by tags'),
+    slugs: z.array(z.string().min(1)).optional().describe('Filter by assortment slugs'),
+    includeLeaves: z.boolean().default(true).optional().describe('Include leaf-level assortments'),
+  }),
+
+  COUNT: z.object({
+    ...SearchSchema,
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Filter by tags'),
+    slugs: z.array(z.string().min(1)).optional().describe('Filter by assortment slugs'),
+    includeLeaves: z.boolean().optional().describe('Include leaf-level assortments'),
+  }),
+
+  UPDATE_STATUS: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+    statusAction: z.enum(['ACTIVATE', 'DEACTIVATE']).describe('Status action'),
+  }),
+
+  ADD_MEDIA: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+    mediaId: z.string().min(1).describe('Media ID'),
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Tags for media association'),
+  }),
+
+  REMOVE_MEDIA: z.object({
+    mediaId: z.string().min(1).describe('Media ID'),
+  }),
+
+  REORDER_MEDIA: z.object({
+    sortKeys: z
+      .array(
+        z.object({
+          assortmentMediaId: z.string().min(1).describe('Assortment Media asset ID'),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+      )
+      .nonempty()
+      .describe('Sort keys'),
+  }),
+
+  GET_MEDIA: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Filter by tags'),
+    ...PaginationSchema,
+  }),
+
+  UPDATE_MEDIA_TEXTS: z.object({
+    assortmentMediaId: z.string().min(1).describe('Assortment media ID'),
+    mediaTexts: z.array(AssortmentMediaTextInputSchema).describe('Media texts'),
+  }),
+
+  ADD_PRODUCT: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+    productId: z.string().min(1).describe('Product ID'),
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Tags for product association'),
+  }),
+
+  REMOVE_PRODUCT: z.object({
+    assortmentProductId: z
+      .string()
+      .min(1)
+      .describe(
+        'Assortment Product ID (from assortment product relationship, _id of assortment product)',
+      ),
+  }),
+
+  GET_PRODUCTS: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+  }),
+
+  REORDER_PRODUCTS: z.object({
+    sortKeys: z
+      .array(
+        z.object({
+          assortmentProductId: z
+            .string()
+            .min(1)
+            .describe(
+              'Assortment product ID,(from assortment product relationship, _id of assortment product)',
+            ),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+      )
+      .nonempty()
+      .describe('Sort keys'),
+  }),
+
+  ADD_FILTER: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+    filterId: z.string().min(1).describe('Filter ID'),
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Tags for filter association'),
+  }),
+
+  REMOVE_FILTER: z.object({
+    assortmentFilterId: z
+      .string()
+      .min(1)
+      .describe('Assortment Filter ID (from assortment filter relationship)'),
+  }),
+
+  GET_FILTERS: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+  }),
+
+  REORDER_FILTERS: z.object({
+    sortKeys: z
+      .array(
+        z.object({
+          assortmentFilterId: z
+            .string()
+            .min(1)
+            .describe('Assortment filter ID (from assortment filter relationship)'),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+      )
+      .nonempty()
+      .describe('Sort keys'),
+  }),
+
+  ADD_LINK: z.object({
+    parentAssortmentId: z.string().min(1).describe('Parent assortment ID'),
+    childAssortmentId: z.string().min(1).describe('Child assortment ID'),
+    tags: z.array(z.string().min(1).toLowerCase()).optional().describe('Tags for link association'),
+  }),
+
+  REMOVE_LINK: z.object({
+    assortmentLinkId: z.string().min(1).describe('Assortment link ID'),
+  }),
+
+  GET_LINKS: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+  }),
+
+  REORDER_LINKS: z.object({
+    sortKeys: z
+      .array(
+        z.object({
+          assortmentLinkId: z.string().min(1).describe('Assortment link ID'),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+      )
+      .nonempty()
+      .describe('Sort keys'),
+  }),
+
+  GET_CHILDREN: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID (optional for root-level)'),
+    includeInactive: z.boolean().optional().describe('Include inactive children'),
+  }),
+
+  SET_BASE: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID to set as base'),
+  }),
+
+  SEARCH_PRODUCTS: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+    ...PaginationSchema,
+    ...SearchSchema,
+  }),
+
+  GET_TEXTS: z.object({
+    assortmentId: z.string().min(1).describe('Assortment ID'),
+  }),
+
+  GET_MEDIA_TEXTS: z.object({
+    assortmentMediaId: z.string().min(1).describe('Assortment media ID'),
+  }),
+} as const;
+
+export const AssortmentManagementSchema = {
+  action: z
+    .enum([
+      'CREATE',
+      'UPDATE',
+      'REMOVE',
+      'GET',
+      'LIST',
+      'COUNT',
+      'UPDATE_STATUS',
+      'ADD_MEDIA',
+      'REMOVE_MEDIA',
+      'REORDER_MEDIA',
+      'GET_MEDIA',
+      'UPDATE_MEDIA_TEXTS',
+      'ADD_PRODUCT',
+      'REMOVE_PRODUCT',
+      'GET_PRODUCTS',
+      'REORDER_PRODUCTS',
+      'ADD_FILTER',
+      'REMOVE_FILTER',
+      'GET_FILTERS',
+      'REORDER_FILTERS',
+      'ADD_LINK',
+      'REMOVE_LINK',
+      'GET_LINKS',
+      'REORDER_LINKS',
+      'GET_CHILDREN',
+      'SET_BASE',
+      'SEARCH_PRODUCTS',
+      'GET_TEXTS',
+      'GET_MEDIA_TEXTS',
+    ])
+    .describe('Assortment management action to perform'),
+
+  assortmentId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Assortment ID (required for most actions except CREATE, LIST, COUNT)'),
+  slug: z.string().optional().describe('Assortment slug (alternative to assortmentId for GET action)'),
+  assortmentMediaId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Assortment media ID (required for media-specific actions)'),
+
+  assortment: AssortmentSchema.optional().describe('Assortment data object for CREATE/UPDATE actions'),
+  texts: z
+    .array(AssortmentTextInputSchema)
+    .optional()
+    .describe('Localized assortment text entries for CREATE action'),
+
+  statusAction: z
+    .enum(['ACTIVATE', 'DEACTIVATE'])
+    .optional()
+    .describe('Status action for UPDATE_STATUS action'),
+
+  mediaId: z.string().min(1).optional().describe('Media ID for ADD_MEDIA action'),
+  sortKeys: z
+    .array(
+      z.union([
+        z.object({
+          assortmentMediaId: z.string().min(1).describe('Media asset ID'),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+        z.object({
+          assortmentProductId: z.string().min(1).describe('_id of assortment product relationship ID'),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+        z.object({
+          assortmentFilterId: z.string().min(1).describe('Filter relationship ID'),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+        z.object({
+          assortmentLinkId: z.string().min(1).describe('Link relationship ID'),
+          sortKey: z.number().int().describe('New sort position'),
+        }),
+      ]),
+    )
+    .optional()
+    .describe('Sort keys for REORDER actions'),
+  mediaTexts: z
+    .array(AssortmentMediaTextInputSchema)
+    .optional()
+    .describe('Media text updates for UPDATE_MEDIA_TEXTS action'),
+  tags: z.array(z.string()).optional().describe('Tags filter or association tags'),
+  assortmentProductId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Product ID for REORDER_PRODUCTS/REMOVE_PRODUCT actions'),
+  productId: z.string().min(1).optional().describe('Product ID for ADD_PRODUCT/REMOVE_PRODUCT actions'),
+  filterId: z.string().min(1).optional().describe('Filter ID for ADD_FILTER/REMOVE_FILTER actions'),
+  assortmentFilterId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Filter ID for REORDER_FILTERS/REMOVE_FILTER actions'),
+  parentAssortmentId: z.string().min(1).optional().describe('Parent assortment ID for ADD_LINK action'),
+  childAssortmentId: z.string().min(1).optional().describe('Child assortment ID for ADD_LINK action'),
+  assortmentLinkId: z.string().min(1).optional().describe('Link ID for REMOVE_LINK action'),
+
+  ...PaginationSchema,
+  ...SortingSchema,
+  ...SearchSchema,
+  includeLeaves: z.boolean().optional().describe('Include leaf-level assortments in results'),
+  slugs: z.array(z.string()).optional().describe('Filter by specific slugs'),
+};
+
+export const AssortmentManagementZodSchema = z.object(AssortmentManagementSchema);
+export type AssortmentManagementParams = z.infer<typeof AssortmentManagementZodSchema>;
+
+export type ActionName = keyof typeof actionValidators;
+export type Params<T extends ActionName> = z.infer<(typeof actionValidators)[T]>;
+export type Handler<T extends ActionName> = (
+  assortmentModule: any,
+  params: Params<T>,
+) => Promise<unknown>;

package/src/mcp/tools/filter/filterManagement.ts

@@ -0,0 +1,34 @@
+import { Context } from '../../../context.js';
+import { log } from '@unchainedshop/logger';
+import {
+  actionValidators,
+  FilterManagementSchema,
+  FilterManagementZodSchema,
+  FilterManagementParams,
+  ActionName,
+} from './schemas.js';
+import actionHandlers from './handlers/index.js';
+import { createMcpResponse, createMcpErrorResponse } from '../../utils/sharedSchemas.js';
+
+export { FilterManagementSchema, FilterManagementZodSchema, FilterManagementParams };
+
+export async function filterManagement(context: Context, params: FilterManagementParams) {
+  const { action, ...actionParams } = params;
+  log('MCP handler filterManagement ', { userId: context.userId, params });
+
+  try {
+    if (!(action in actionHandlers)) {
+      throw new Error(`Unknown action: ${action}`);
+    }
+
+    const parsedParams = actionValidators[action as ActionName].parse(actionParams);
+    const data = await actionHandlers[action as ActionName](context, parsedParams as never);
+
+    return createMcpResponse({
+      action,
+      data,
+    });
+  } catch (error) {
+    return createMcpErrorResponse(action, error);
+  }
+}

package/src/mcp/tools/filter/handlers/countFilters.ts

@@ -0,0 +1,14 @@
+import { Context } from '../../../../context.js';
+import { Params } from '../schemas.js';
+
+export default async function countFilters(context: Context, params: Params<'COUNT'>) {
+  const { modules } = context;
+  const { includeInactive = false, queryString } = params;
+
+  const count = await modules.filters.count({
+    includeInactive,
+    queryString,
+  });
+
+  return { count };
+}

package/src/mcp/tools/filter/handlers/createFilter.ts

@@ -0,0 +1,27 @@
+import { Context } from '../../../../context.js';
+import { FilterDirector } from '@unchainedshop/core';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+import { FilterText } from '@unchainedshop/core-filters';
+
+export default async function createFilter(context: Context, params: Params<'CREATE'>) {
+  const { modules } = context;
+  const { filter, texts } = params;
+  const { key, type, options = [] } = filter as any;
+
+  const newFilter = await modules.filters.create({
+    key,
+    type,
+    options,
+    isActive: true,
+  });
+
+  await FilterDirector.invalidateProductIdCache(newFilter, context);
+
+  if (texts && texts.length > 0) {
+    await modules.filters.texts.updateTexts({ filterId: newFilter._id }, texts as FilterText[]);
+  }
+
+  const normalizedFilter = await getNormalizedFilterDetails(newFilter._id, context);
+  return { filter: normalizedFilter };
+}

package/src/mcp/tools/filter/handlers/createFilterOption.ts

@@ -0,0 +1,30 @@
+import { Context } from '../../../../context.js';
+import { FilterDirector } from '@unchainedshop/core';
+import { FilterNotFoundError } from '../../../../errors.js';
+import { getNormalizedFilterDetails } from '../../../utils/getNormalizedFilterDetails.js';
+import { Params } from '../schemas.js';
+import { FilterText } from '@unchainedshop/core-filters';
+
+export default async function createFilterOption(context: Context, params: Params<'CREATE_OPTION'>) {
+  const { modules } = context;
+  const { filterId, option, optionTexts } = params;
+
+  if (!(await modules.filters.filterExists({ filterId }))) {
+    throw new FilterNotFoundError({ filterId });
+  }
+
+  const newOption = await modules.filters.createFilterOption(filterId, { value: option });
+  if (!newOption) return { filter: null };
+
+  await FilterDirector.invalidateProductIdCache(newOption, context);
+
+  if (optionTexts && optionTexts.length > 0) {
+    await modules.filters.texts.updateTexts(
+      { filterId, filterOptionValue: option },
+      optionTexts as FilterText[],
+    );
+  }
+
+  const normalizedFilter = await getNormalizedFilterDetails(filterId, context);
+  return { filter: normalizedFilter };
+}