Hybris MCP Server

Instructions

Implementation Reference

• src/hybris-client.ts:405-416 (handler)

  Core handler function that performs the product search by making a request to the Hybris OCC REST API endpoint.

  async searchProducts(query: string, pageSize = 20, currentPage = 0): Promise<ProductSearchResult> {
    const params = new URLSearchParams({
      query,
      pageSize: pageSize.toString(),
      currentPage: currentPage.toString(),
      fields: 'products(code,name,description,price,stock,categories,images),pagination',
    });
  
    return this.request<ProductSearchResult>(
      `/rest/v2/${encodeURIComponent(this.config.baseSiteId!)}/products/search?${params}`
    );
  }

• src/index.ts:104-125 (registration)

  Registration of the search_products tool in the tools list, including metadata and input schema for MCP discovery.

  {
    name: 'search_products',
    description: 'Search for products in the Hybris catalog using a query string',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query for products',
        },
        pageSize: {
          type: 'number',
          description: 'Number of results per page (default: 20)',
        },
        currentPage: {
          type: 'number',
          description: 'Page number to retrieve (0-indexed, default: 0)',
        },
      },
      required: ['query'],
    },
  },

• src/index.ts:371-377 (handler)

  MCP tool dispatch handler that validates input arguments and invokes the HybrisClient searchProducts method.

  case 'search_products':
    result = await hybrisClient.searchProducts(
      validateString(args, 'query', true),
      validateNumber(args, 'pageSize', { min: 1, max: 100 }),
      validateNumber(args, 'currentPage', { min: 0 })
    );
    break;

• src/hybris-client.ts:15-22 (schema)

  TypeScript interface defining the structure of the search result output.

  export interface ProductSearchResult {
    products: Product[];
    pagination: {
      currentPage: number;
      pageSize: number;
      totalPages: number;
      totalResults: number;
    };