Omnisend MCP Server

Instructions

Implementation Reference

• src/tools/products/index.ts:24-48 (handler)

  Handler function that executes the listProducts tool. It calls the imported listProducts helper from api-resources, applies product field filtering, formats the response as MCP content with JSON text, and handles errors.

  async (args) => {
    try {
      const response = await listProducts(args);
      
      // Filter products data to include only defined fields
      const filteredProducts = response.products.map(filterProductFields);
      
      return {
        content: [
          { 
            type: "text", 
            text: JSON.stringify({
              products: filteredProducts,
              paging: response.paging
            }, null, 2) 
          }
        ]
      };
    } catch (error) {
      if (error instanceof Error) {
        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
      }
      return { content: [{ type: "text", text: "An unknown error occurred" }] };
    }
  }

• src/tools/products/index.ts:10-23 (schema)

  JSON Schema defining the input parameters for the listProducts tool, including pagination, status, vendor, date filters, categories, and tags.

  {
    additionalProperties: false,
    properties: {
      limit: { description: "Maximum number of products to return", type: "number" },
      offset: { description: "Skip first N results", type: "number" },
      status: { description: "Filter products by status", enum: ["active", "draft", "archived"], type: "string" },
      vendor: { description: "Filter products by vendor/brand", type: "string" },
      createdAfter: { description: "Filter products created after specified date (ISO format)", type: "string" },
      updatedAfter: { description: "Filter products updated after specified date (ISO format)", type: "string" },
      categories: { description: "Filter products by categories", items: { type: "string" }, type: "array" },
      tags: { description: "Filter products by tags", items: { type: "string" }, type: "array" }
    },
    type: "object"
  },

• src/tools/products/index.ts:7-49 (registration)

  The server.tool call that registers the listProducts tool with the MCP server, specifying name, description, input schema, and handler.

  server.tool(
    "listProducts",
    "Retrieve a list of products from the Omnisend catalog with pagination support. The response includes pagination information (next/previous cursor, limit, offset).",
    {
      additionalProperties: false,
      properties: {
        limit: { description: "Maximum number of products to return", type: "number" },
        offset: { description: "Skip first N results", type: "number" },
        status: { description: "Filter products by status", enum: ["active", "draft", "archived"], type: "string" },
        vendor: { description: "Filter products by vendor/brand", type: "string" },
        createdAfter: { description: "Filter products created after specified date (ISO format)", type: "string" },
        updatedAfter: { description: "Filter products updated after specified date (ISO format)", type: "string" },
        categories: { description: "Filter products by categories", items: { type: "string" }, type: "array" },
        tags: { description: "Filter products by tags", items: { type: "string" }, type: "array" }
      },
      type: "object"
    },
    async (args) => {
      try {
        const response = await listProducts(args);
        
        // Filter products data to include only defined fields
        const filteredProducts = response.products.map(filterProductFields);
        
        return {
          content: [
            { 
              type: "text", 
              text: JSON.stringify({
                products: filteredProducts,
                paging: response.paging
              }, null, 2) 
            }
          ]
        };
      } catch (error) {
        if (error instanceof Error) {
          return { content: [{ type: "text", text: `Error: ${error.message}` }] };
        }
        return { content: [{ type: "text", text: "An unknown error occurred" }] };
      }
    }
  );

• src/api-resources/products/index.ts:5-16 (helper)

  Supporting helper function that performs the HTTP GET request to the Omnisend '/products' API endpoint with query params and returns the ProductsResponse.

  export const listProducts = async (params: ListProductsParams = {}): Promise<ProductsResponse> => {
    try {
      const response = await omnisendApi.get<ProductsResponse>('/products', { params });
      return response.data;
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Error getting products list: ${error.message}`);
      } else {
        throw new Error('Unknown error occurred when getting products list');
      }
    }
  };