npm package: @hugolc/vtex-mcp-server
Description: A MCP server to interact with VTEX APIs
Author: Hugo Lindoso Correia
Latest version: 2.1.2

# VTEX MCP Server

This server implements the Model Context Protocol (MCP) to interact with VTEX APIs, enabling efficient integrations with AI tools and programming assistants.

## Prerequisites

- Node.js installed (recommended version: 18 or higher)

## Description

The `@hugolc/vtex-mcp-server` is a package that facilitates communication with VTEX APIs through the Model Context Protocol. It provides tools for:

- Fetching product details by ID
- Retrieving complete category trees
- Performing intelligent search operations for products
- Retrieving order information by ID
- Getting facets, suggestions, banners and more search-related data
- User authentication and session management
- Shopping cart management and checkout operations

## What is Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a protocol developed to enable bidirectional communication between AI models and external tools. It allows AI assistants and development tools to access external resources and APIs in a standardized way, enabling:

- Execution of domain-specific tools
- Real-time data retrieval
- Integration with external systems like the VTEX platform

## How to use

Add the following configurations to your MCP client configuration file.

### Configuration in specific MCP clients

To configure MCP in different clients, check the links below:

- **Claude Desktop**: [MCP Configuration in Claude](https://modelcontextprotocol.io/quickstart/user)
- **GitHub Copilot**: [Extending GitHub Copilot with MCP](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp)
- **Cursor**: [Model Context Protocol in Cursor](https://docs.cursor.com/context/model-context-protocol)

### Configuration example using VTEX API Key and Token

```json
{
  "servers": {
    "vtex-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@hugolc/vtex-mcp-server@latest"
      ],
      "env": {
        "VTEX_ACCOUNT": "account",
        "VTEX_APP_KEY": "appkey",
        "VTEX_APP_TOKEN": "token"
      }
    }
  }
}
```

### Example using administrative user session token

```json
{
  "servers": {
    "vtex-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@hugolc/vtex-mcp-server@latest"
      ],
      "env": {
        "VTEX_ACCOUNT": "account",
        "VTEX_TOKEN": "token"
      }
    }
  }
}
```

## Available Features

The server currently offers the following tools:

### Catalog Tools
- `getProductById`: Retrieves details of a specific product by ID
- `getCategoryTree`: Gets the complete category tree of the store

### Order Tools
- `getOrderById`: Retrieves order information by its ID from the VTEX OMS API

### Intelligent Search Tools
- `searchProducts`: Lists active products for a given search query with support for facets, pagination, and sorting
- `getFacets`: Lists the possible facets for a given search query
- `getAutocompleteSuggestions`: Lists suggested terms and attributes similar to the search term
- `getSearchSuggestions`: Lists suggested terms similar to the search term
- `getTopSearches`: Lists the 10 most searched terms in the past 14 days
- `getSearchCorrections`: Attempts to correct a misspelled term from the search
- `getBanners`: Lists the banners registered for a given query

### Authentication Tools
- `sendAccessKeyToken`: Initiates the authentication process and sends an access token to the provided email
- `validateAccessToken`: Validates the access token sent to the user's email

### Checkout Tools
- `getOrCreateCart`: Gets the current cart or creates a new shopping cart in VTEX
- `addClientProfile`: Adds customer profile information to the shopping cart in VTEX
- `addCartItems`: Adds items to the shopping cart in VTEX
- `getCheckoutUrl`: Gets the checkout URL for the shopping cart in VTEX, typically used to complete the purchase

## Next Steps

- Continue integrating more VTEX APIs with MCP
- Expand order management functionalities
- Add support for address and shipping management
- Expand resources for promotions and pricing management

## License

MIT