Skip to main content
Glama
kavingas

Catalog Services MCP Server

by kavingas
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Catalog Services MCP Server

An MCP (Model Context Protocol) server for Adobe Commerce Catalog Services, providing tools to interact with product, category, and environment services via gRPC and REST APIs.

Proto Schemas from https://git.corp.adobe.com/magento/proto-schemas

Features

This MCP server provides the following tools:

  • Product Variants: Get product variant information (configurable product options)

  • Product Overrides: Query product price overrides by customer group and website

  • Category Permissions: Retrieve category permission information

  • Environment Details: Get environment, website, and store view information

Related MCP server: Shopify Universal MCP Server

Prerequisites

  • Python 3.11 or higher

  • uv - Fast Python package installer and resolver

  • Cursor IDE (or any MCP-compatible client)

Installation

1. Install uv

If you don't have uv installed, install it first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

2. Clone and Setup the Project

# Clone the repository
git clone <repository-url>
cd catalog-services-mcp

# Install dependencies using uv
uv sync

3. Configure Environment Variables

Set the required environment variables for authentication:

# Adobe Commerce Catalog Service credentials
export CATALOG_SERVICE_API_KEY="your_api_key"
export CATALOG_SERVICE_PRIVATE_KEY="your_private_key"

# New Relic credentials (if using New Relic tools)
export NEW_RELIC_API_KEY="your_new_relic_api_key"

4. Configure MCP in Cursor

Add the following configuration to your Cursor MCP settings file (~/.cursor/mcp.json):

{
  "mcpServers": {
    "Catalog Services": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/path/to/catalog-services-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Important: Replace /Users/YOUR_USERNAME/path/to/catalog-services-mcp with the actual path to your cloned repository.

5. Restart Cursor

After adding the configuration, restart Cursor IDE to load the MCP server.

Usage

Once configured, you can use the Catalog Services tools in Cursor by invoking them through the MCP protocol. Available tools include:

  • get_product_variants - Retrieve product variant information

  • get_product_overrides_by_website - Get product price overrides for all customer groups

  • get_category_permissions - Query category permissions

  • get_environment_details - Get environment information

  • get_environment_store_views - List all store views for an environment

  • find_store_view_codes - Find store views by website/store code

Development

Project Structure

catalog-services-mcp/
├── catalog_service/          # Main service module
│   ├── generated/           # Generated protobuf files
│   ├── proto-schemas/       # Proto schema definitions
│   ├── product_service_tool.py
│   ├── product_override_service_tool.py
│   ├── variant_service_tool.py
│   ├── category_permission_service_tool.py
│   └── environment_service_tool.py
├── main.py                  # MCP server entry point
├── pyproject.toml          # Project dependencies
└── README.md

Regenerating Protobuf Files

If you need to regenerate the protobuf files from the proto schemas:

cd catalog_service
./generate_protos.sh

Troubleshooting

MCP Server Not Starting

  1. Check that uv is installed and in your PATH:

    which uv

  2. Verify the path in mcp.json is correct and absolute

  3. Check Cursor logs for error messages

Authentication Errors

Ensure your environment variables are set correctly:

echo $CATALOG_SERVICE_API_KEY
echo $CATALOG_SERVICE_PRIVATE_KEY

Connection Issues

  • Verify network connectivity to Adobe Commerce services

  • Check that you're connected to the corporate VPN if required

  • Ensure firewall rules allow outbound connections

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Submit a pull request

License

Internal Adobe Commerce project

Available Tools

7 tools
find_store_view_codesA
Find and filter store views by website and/or store code.

Useful for discovering available store view codes when you know the
website and store codes but need to find valid store view codes.

Args:
    environment_id: Adobe Commerce Cloud environment ID
    website_code: Optional website code to filter by
    store_code: Optional store code to filter by
    timeout: Request timeout in seconds (default: 15.0)
    
Returns:
    Dict containing:
    - status: Success or error status
    - environment_id: The queried environment ID
    - matching_store_views: List of matching store views
    - count: Number of matching store views
    
Example:
    >>> result = find_store_view_codes(
    ...     environment_id='7059bb71-341a-4ccb-b543-d7b2948b73e4',
    ...     website_code='base',
    ...     store_code='main_website_store'
    ... )
    >>> print([sv['storeViewCode'] for sv in result['matching_store_views']])
ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
store_codeNo
website_codeNo
environment_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes return structure and includes an example, which is helpful. But with no annotations, it does not explicitly state read-only nature or potential side effects, leaving some ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections and an example, but the first two sentences are slightly redundant. Overall, it is appropriately concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Provides purpose, parameters, return structure, and an example. For a query tool, this is adequate. Lacks error handling details but not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since schema coverage is 0%, the description fully compensates by clearly explaining each parameter's meaning, including defaults and role (filter by, timeout).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool finds and filters store views by website and/or store code, with a specific use case. However, it does not explicitly differentiate from sibling tool get_environment_store_views, which may also list store views.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a specific use case for discovering store view codes when website and store codes are known. However, it does not discuss when not to use this tool or mention alternatives explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_category_permissionsA
Get category permissions from Catalog Service via gRPC.

This tool calls the GetCategoryPermissions RPC method to retrieve category permission
information from the Adobe Commerce Catalog Service. Category permissions control
which customer groups can view specific categories on different websites.

Args:
    environment_id: Adobe Commerce Cloud environment ID (e.g., '3f73a49a-3137-472c-bb0d-39d0e7925d86')
    category_ids: Optional list of category IDs to retrieve permissions for. 
                 If not provided, returns permissions for all categories.
    use_tls: Whether to use TLS connection (default: True)
    timeout: Request timeout in seconds (default: 15.0)
    
Returns:
    Dict containing category permission information with keys:
    - permissions: List of permission dictionaries, each containing:
        - environment_id: Environment ID
        - category_id: Category ID
        - displayable_permission_by_website_code: Map of website codes to customer group permissions
        - created: Creation timestamp
        - updated: Last update timestamp
        - deleted: Whether the permission is deleted
    - count: Number of permissions retrieved
    - status: Success or error status
    
Example:
    >>> result = get_category_permissions(
    ...     environment_id='3f73a49a-3137-472c-bb0d-39d0e7925d86',
    ...     category_ids=['1', '2', '4']
    ... )
    >>> print(result['count'])
    3
    >>> for perm in result['permissions']:
    ...     print(f"Category {perm['category_id']}: {perm['displayable_permission_by_website_code']}")
ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
use_tlsNo
category_idsNo
environment_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, but the description fully discloses the operation (read via gRPC), the parameters, and the return format. It implies a read-only action without explicit statement, but the 'Get' verb and the example output suggest no side effects. One could argue a 5, but the lack of explicit statement on mutability or error behavior keeps it at 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Args, Returns, Example) and is appropriately sized. Every sentence adds value, with no fluff. The most important information (what, how, params) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description includes parameter details, return format, and an example, making it complete for a retrieval tool. However, it does not mention error handling or edge cases (e.g., what happens if environment_id is invalid), and with no annotations, a bit more context on expected status codes could be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the tool description provides thorough explanations for all four parameters, including defaults, optionality, and examples (e.g., environment_id format, category_ids as optional list, use_tls default, timeout default). This adds significant semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get category permissions'), the service ('Catalog Service via gRPC'), and the resource ('category permission information'), distinguishing it from siblings which deal with store views, environments, products, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives or when not to use it. The purpose is clear enough to infer usage, but no comparative context is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_environment_detailsA
Get environment details from Catalog Service via HTTP REST API.

This tool calls the /catalog/v1/environments endpoint to retrieve environment 
information including websites, store views, and export details.

Args:
    environment_ids: List of Adobe Commerce Cloud environment IDs 
                    (e.g., ['7059bb71-341a-4ccb-b543-d7b2948b73e4'])
    timeout: Request timeout in seconds (default: 15.0)
    
Returns:
    Dict containing environment information with keys:
    - status: Success or error status
    - environments: List of environment details
    - count: Number of environments retrieved
    
Example:
    >>> result = get_environment_details(
    ...     environment_ids=['7059bb71-341a-4ccb-b543-d7b2948b73e4']
    ... )
    >>> print(result['count'])
    1
    >>> print(result['environments'][0]['websites'])
ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
environment_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description discloses the HTTP endpoint, return structure (status, environments, count), and example output. However, no annotations exist, and the description lacks details on authentication, rate limits, side effects, or error handling. The read-only nature is implied by 'Get' but not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured with Args, Returns, and an Example section. It is relatively concise for the information provided, though the example could be shortened. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the siblings cover narrower use cases, the description fully covers input, output, endpoint, and usage example. No gaps remain for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description adds crucial meaning: environment_ids gets a realistic example and explanation; timeout gets default and units. Both parameters are well described beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves environment details from Catalog Service, naming the endpoint and specifying content (websites, store views, export details). It distinguishes from more specific siblings like get_environment_store_views, though not explicitly limiting scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: call when environment details are needed. However, no explicit guidance on when to use this tool vs. siblings (e.g., get_environment_store_views for store views only) or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_environment_store_viewsA
Get all store views for a specific environment.

This is a convenience tool that retrieves environment details and extracts
all store view information in a flattened structure for easier use.

Args:
    environment_id: Adobe Commerce Cloud environment ID
    timeout: Request timeout in seconds (default: 15.0)
    
Returns:
    Dict containing:
    - status: Success or error status
    - environment_id: The queried environment ID
    - store_views: List of all store views with their codes
    - websites: List of all websites with their codes
    - count: Number of store views found
    
Example:
    >>> result = get_environment_store_views('7059bb71-341a-4ccb-b543-d7b2948b73e4')
    >>> for sv in result['store_views']:
    ...     print(f"{sv['websiteCode']}/{sv['storeCode']}/{sv['storeViewCode']}")
ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
environment_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It describes the tool as retrieving environment details and extracting store views, and mentions the return structure. However, it does not disclose any behavioral traits like idempotency, side effects, or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args, Returns, and Example sections. It is somewhat lengthy but each part is relevant. The example is helpful. Slight over-explanation could be trimmed, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has two parameters and no output schema in the data, but the description defines the return structure in detail. It provides enough context for an agent to understand inputs and outputs. However, it does not mention any prerequisites or typical usage patterns relative to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It provides clear semantics for both parameters: environment_id is an Adobe Commerce Cloud environment ID, and timeout is in seconds with a default of 15.0. This adds meaning beyond the minimal schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets all store views for a specific environment, using a specific verb and resource. It distinguishes itself from sibling tools like find_store_view_codes by focusing on a flattened structure of store views, websites, and codes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains it is a 'convenience tool' that retrieves environment details and extracts store views, implying it is an alternative to get_environment_details. However, it does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_product_overrides_by_websiteA
Get product overrides for all customer groups in a website.

This retrieves price overrides for all customer groups, not just one.
Useful when you need to see pricing across all customer segments.

Args:
    environment_id: Adobe Commerce Cloud environment ID
    website_code: Website code (e.g., 'base')
    skus: List of product SKUs to retrieve overrides for
    filter_virtual_cgs: Filter out virtual customer groups (default: False)
    use_tls: Whether to use TLS connection (default: True)
    timeout: Request timeout in seconds (default: 15.0)
    
Returns:
    Dict containing product overrides with keys:
    - overrides: List of product override dictionaries (all customer groups), each containing:
        - customer_group_code: SHA1 hash of customer group ID
          Use get_customer_group_id_from_code() to decode to numeric ID
          Common hashes:
            'b6589fc6ab0dc82cf12099d1c2d40ab994e8410c' = ID 0 (NOT LOGGED IN)
            '356a192b7913b04c54574d18c28d46e6395428ab' = ID 1 (General/Logged In)
            'da4b9237bacccdf19c0760cab7aec4a8359010b0' = ID 2 (Wholesale)
        - sku, website_code, currency, prices, tier_prices, etc.
    - count: Number of overrides retrieved
    - status: Success or error status
    
Example:
    >>> result = get_product_overrides_by_website.invoke({
    ...     'environment_id': 'abc123',
    ...     'website_code': 'base',
    ...     'skus': ['SKU123']
    ... })
    >>> # Returns overrides for all customer groups
    >>> for override in result['overrides']:
    ...     group_id = get_customer_group_id_from_code(override['customer_group_code'])
    ...     print(f"Group ID {group_id}: {override['customer_group_code']}, Price: {override['prices']}")
ParametersJSON Schema
NameRequiredDescriptionDefault
skusYes
timeoutNo
use_tlsNo
website_codeYes
environment_idYes
filter_virtual_cgsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden. It explains that this is a retrieval operation (non-destructive), describes the return format in detail, provides an example with decoding of customer_group_code, and lists all parameters with defaults.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description includes an Args section, Returns section, and an Example, which is well-structured. It is somewhat verbose but every sentence adds value, especially the example and hash codes. Slightly longer than necessary but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters (3 required) and an output schema, the description fully covers the input parameters, output structure, and usage. The example and hash code mapping provide additional context that compensates for the lack of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description fully explains each parameter: environment_id, website_code, skus, filter_virtual_cgs, use_tls, timeout, with defaults and types. This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets product overrides for all customer groups in a website, using the verb 'get' and specifying the resource. It distinguishes itself from sibling tools by emphasizing 'all customer groups', which is unique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Useful when you need to see pricing across all customer segments', which provides usage context. However, it does not explicitly mention when not to use it or suggest alternative tools for single-group queries, but the sibling tools list does not have an obvious single-group counterpart.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_productsA
Get product details from Catalog Service via gRPC.

This tool calls the GetProducts RPC method to retrieve product information
from the Adobe Commerce Catalog Service.

Args:
    environment_id: Adobe Commerce Cloud environment ID (e.g., 'abc123xyz')
    store_view_code: Store view code (e.g., 'default')
    store_code: Store code (e.g., 'main_website_store')
    website_code: Website code (e.g., 'base')
    skus: List of product SKUs to retrieve
    use_tls: Whether to use TLS connection (default: True)
    timeout: Request timeout in seconds (default: 15.0)
    
Returns:
    Dict containing product information with keys:
    - products: List of product dictionaries
    - count: Number of products retrieved
    - status: Success or error status
    
Example:
    >>> result = get_products(
    ...     environment_id='abc123xyz',
    ...     store_view_code='default',
    ...     store_code='main_website_store', 
    ...     website_code='base',
    ...     skus=['SKU123', 'SKU456']
    ... )
    >>> print(result['count'])
    2
ParametersJSON Schema
NameRequiredDescriptionDefault
skusYes
timeoutNo
use_tlsNo
store_codeYes
website_codeYes
environment_idYes
store_view_codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It states it retrieves product information, implying no destructive actions, but lacks details on authentication, rate limits, error handling, or data freshness. Adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a heading, Args/Returns/Example sections. Front-loaded with purpose. Slightly long but each part earns its place; could be condensed slightly but remains clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers parameters, return structure, and an example. The output schema exists (though not shown) so return values need not be fully explained. Missing details like error codes or pagination, but sufficient for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, but the description provides meaningful parameter descriptions for all 7 parameters (e.g., 'environment_id: Adobe Commerce Cloud environment ID') and specifies defaults for timeout and use_tls, adding value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets product details from Catalog Service via gRPC, citing the GetProducts RPC method. It distinguishes from siblings like get_category_permissions by focusing on products.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the sibling tools. It does not mention alternatives or contexts where this tool is preferred, merely documenting the function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_product_variantsA
Get product variants from Catalog Service via gRPC.

This tool calls the GetVariants RPC method to retrieve product variant information
(configurable product options and their values) from the Adobe Commerce Catalog Service.

Product variants represent the different configurations of a configurable product,
showing all available option combinations (like colors, sizes) and their corresponding
child product SKUs.

Args:
    environment_id: Adobe Commerce Cloud environment ID (e.g., '3f73a49a-3137-472c-bb0d-39d0e7925d86')
    store_view_code: Store view code (e.g., 'test')
    store_code: Store code (e.g., 'test')
    website_code: Website code (e.g., 'test')
    skus: List of parent product SKUs to retrieve variants for
    use_tls: Whether to use TLS connection (default: True)
    timeout: Request timeout in seconds (default: 15.0)
    
Returns:
    Dict containing variant information with keys:
    - variants: List of variant dictionaries, each containing:
        - id: Variant identifier
        - parent_sku: Parent product SKU
        - product_sku: Child product SKU for this variant
        - option_values: List of option values (attribute_code, uid, value_index)
    - count: Number of variants retrieved
    - status: Success or error status
    
Example:
    >>> result = get_product_variants(
    ...     environment_id='3f73a49a-3137-472c-bb0d-39d0e7925d86',
    ...     store_view_code='test',
    ...     store_code='test',
    ...     website_code='test',
    ...     skus=['CAT-249']
    ... )
    >>> print(result['count'])
    4
    >>> for variant in result['variants']:
    ...     print(f"{variant['product_sku']}: {[opt['attribute_code'] for opt in variant['option_values']]}")
ParametersJSON Schema
NameRequiredDescriptionDefault
skusYes
timeoutNo
use_tlsNo
store_codeYes
website_codeYes
environment_idYes
store_view_codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the RPC method used (GetVariants), the return structure with keys and example values, and includes an example. However, it does not mention side effects, authentication needs, error handling, or rate limits. Overall, it provides good behavioral context for a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (Args, Returns, Example) and is appropriately detailed. However, it is slightly longer than necessary; for example, the full example could be shortened. Still, the organization aids readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters (5 required), no output schema, and no annotations, the description is very complete. It documents all parameters, provides a return value schema, and includes a usage example. It leaves no significant gaps for an agent to understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description's Args section adds detailed explanations for all 7 parameters, including environment_id, store_view_code, skus, etc., with examples. This fully compensates for the missing schema descriptions and adds meaning beyond parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool retrieves product variants from Catalog Service via gRPC, explains what product variants are (configurable product options), and provides specific verbs and resource names. It distinguishes from siblings like get_products by focusing specifically on variants of configurable products.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives like get_products. It implies usage through the context of retrieving variants, but lacks guidance on prerequisites or scenarios where this tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv0.1.0
    • First observedfind_store_view_codes
    • First observedget_category_permissions
    • First observedget_environment_details
    • First observedget_environment_store_views
    • First observedget_product_overrides_by_website
    • First observedget_product_variants
    • First observedget_products
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Scored across 7 tools

Disambiguation4/5

Most tools target distinct resources (products, variants, overrides, categories, environments, store views). One pair, get_environment_details and get_environment_store_views, has overlapping functionality but is differentiated by output structure.

Naming Consistency4/5

All tools use snake_case with a verb-noun pattern. The slight inconsistency of 'find_' versus 'get_' for one tool is minor.

Tool Count5/5

With 7 tools covering environment info, store views, products, variants, overrides, and permissions, the count is well-scoped for a read-only catalog service.

Completeness4/5

The tool set covers key read operations for a catalog service. Missing search or mutation capabilities, but those may be out of scope for this server.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers