Add initial implementation for VTEX MCP app

package.json

@@ -35,7 +35,8 @@
     "template-minimal",
     "template-with-view",
     "veo",
-    "whisper"
+    "whisper",
+    "vtex"
   ],
   "dependencies": {
     "@types/node": "^24.10.0"

vtex/README.md

@@ -0,0 +1,121 @@
+# VTEX Commerce MCP
+
+MCP server for VTEX e-commerce platform - providing product search, catalog management, and shopping cart operations.
+
+## Features
+
+### Product Tools
+
+- **VTEX_SEARCH_PRODUCTS** - Search products using VTEX Intelligent Search API
+  - Query-based search
+  - Filter by collection/cluster
+  - Pagination and sorting
+  - Faceted navigation
+
+- **VTEX_GET_PRODUCT** - Get a single product by URL slug
+  - Full product details
+  - Variant information
+  - Pricing and availability
+
+- **VTEX_GET_SUGGESTIONS** - Get search autocomplete suggestions
+  - Type-ahead functionality
+  - Popular searches
+
+### Cart Tools
+
+- **VTEX_GET_CART** - Get or create a shopping cart
+  - Retrieve existing cart by ID
+  - Create new empty cart
+
+- **VTEX_ADD_TO_CART** - Add items to cart
+  - Multiple items at once
+  - Seller specification
+
+- **VTEX_UPDATE_CART** - Update cart items
+  - Change quantities
+  - Remove items (set quantity to 0)
+
+## Configuration
+
+When installing this MCP, you need to provide:
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `account` | VTEX account name (e.g., "mystore") | Required |
+| `environment` | VTEX environment | `vtexcommercestable` |
+| `salesChannel` | Sales channel ID | `1` |
+| `locale` | Default locale | `pt-BR` |
+| `currency` | Currency code | `BRL` |
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Start development server
+bun run dev
+
+# Type checking
+bun run check
+
+# Build for production
+bun run build
+
+# Deploy
+bun run deploy
+```
+
+## API Reference
+
+### Product Search Response
+
+Products are returned in a standardized schema.org-compatible format:
+
+```typescript
+interface Product {
+  "@type": "Product";
+  productID: string;
+  name: string;
+  description?: string;
+  url: string;
+  brand?: { "@type": "Brand"; name: string };
+  image: Array<{ "@type": "ImageObject"; url: string; name?: string }>;
+  sku: string;
+  offers: {
+    "@type": "AggregateOffer";
+    lowPrice: number;
+    highPrice: number;
+    priceCurrency: string;
+    offers: Array<Offer>;
+  };
+  isVariantOf?: ProductGroup;
+  additionalProperty?: Array<PropertyValue>;
+}
+```
+
+### Cart Response
+
+```typescript
+interface Cart {
+  id: string;
+  items: Array<{
+    productId: string;
+    sku: string;
+    name: string;
+    quantity: number;
+    price: number;
+    listPrice: number;
+    image: string;
+    seller: string;
+  }>;
+  total: number;
+  subtotal: number;
+  coupons: string[];
+}
+```
+
+## License
+
+MIT
+

vtex/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@deco/mcp-vtex",
+  "version": "1.0.0",
+  "description": "MCP server for VTEX e-commerce platform - product search, catalog management, and shopping cart operations",
+  "private": true,
+  "type": "module",
+  "main": "./server/main.ts",
+  "exports": {
+    ".": "./server/main.ts",
+    "./lib": "./server/lib/index.ts",
+    "./tools": "./server/tools/index.ts"
+  },
+  "scripts": {
+    "dev": "deco dev",
+    "configure": "deco configure",
+    "gen": "deco gen --output=shared/deco.gen.ts",
+    "deploy": "npm run build && deco deploy ./dist/server",
+    "check": "tsc --noEmit",
+    "build": "bun --bun vite build",
+    "test": "bun test server/lib"
+  },
+  "dependencies": {
+    "@decocms/runtime": "0.24.0",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "^1.13.4",
+    "@cloudflare/workers-types": "^4.20251014.0",
+    "@mastra/core": "^0.24.0",
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "@types/mime-db": "^1.43.6",
+    "deco-cli": "^0.26.0",
+    "typescript": "^5.7.2",
+    "vite": "7.2.0",
+    "wrangler": "^4.28.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

vtex/server/lib/client.test.ts

@@ -0,0 +1,199 @@
+/**
+ * VTEX Client Tests
+ */
+
+import { describe, test, expect, beforeAll } from "bun:test";
+import { createClient, type VTEXProduct, type ProductSearchResult } from "./vtex-client.ts";
+import { toProduct, pickSku, type Product } from "./transform.ts";
+
+const TEST_ACCOUNT = "brmotorolanew";
+const TEST_ENVIRONMENT = "vtexcommercestable";
+const CURRENCY = "BRL";
+
+describe("VTEX Client", () => {
+  const client = createClient({
+    account: TEST_ACCOUNT,
+    environment: TEST_ENVIRONMENT,
+    salesChannel: "1",
+    locale: "pt-BR",
+  });
+
+  const baseUrl = `https://${TEST_ACCOUNT}.${TEST_ENVIRONMENT}.com.br`;
+
+  test("searchProducts returns products", async () => {
+    const result = await client.searchProducts({
+      query: "",
+      count: 5,
+    });
+
+    expect(result).toBeDefined();
+    expect(result.products).toBeArray();
+    expect(result.products.length).toBeGreaterThan(0);
+    expect(result.recordsFiltered).toBeGreaterThan(0);
+
+    // Check product structure
+    const product = result.products[0];
+    expect(product.productId).toBeDefined();
+    expect(product.productName).toBeDefined();
+    expect(product.linkText).toBeDefined();
+    expect(product.items).toBeArray();
+  });
+
+  test("searchProducts with query returns results", async () => {
+    const result = await client.searchProducts({
+      query: "motorola",
+      count: 5,
+    });
+
+    // Query might return 0 results depending on API state, just check structure
+    expect(result.products).toBeArray();
+    expect(typeof result.recordsFiltered).toBe("number");
+  });
+
+  test("getProductBySlug returns a product", async () => {
+    // First get a product from search to get a valid slug
+    const searchResult = await client.searchProducts({ count: 1 });
+    const slug = searchResult.products[0].linkText;
+
+    const product = await client.getProductBySlug(slug);
+
+    expect(product).toBeDefined();
+    expect(product?.productId).toBeDefined();
+    expect(product?.productName).toBeDefined();
+    expect(product?.items).toBeArray();
+  });
+
+  test("getProductBySlug returns null for invalid slug", async () => {
+    const product = await client.getProductBySlug("this-product-does-not-exist-12345");
+    expect(product).toBeNull();
+  });
+
+  test("getSuggestions returns suggestions", async () => {
+    const result = await client.getSuggestions("smart");
+
+    expect(result).toBeDefined();
+    expect(result.searches).toBeArray();
+  });
+});
+
+describe("VTEX Transform", () => {
+  const baseUrl = `https://${TEST_ACCOUNT}.${TEST_ENVIRONMENT}.com.br`;
+
+  test("pickSku returns available SKU", () => {
+    const items = [
+      {
+        itemId: "123",
+        name: "SKU 1",
+        nameComplete: "SKU 1 Complete",
+        images: [],
+        sellers: [
+          {
+            sellerId: "1",
+            sellerName: "Main Seller",
+            commertialOffer: {
+              Price: 10000,
+              ListPrice: 12000,
+              AvailableQuantity: 0,
+              PriceWithoutDiscount: 12000,
+              Installments: [],
+            },
+          },
+        ],
+        variations: [],
+      },
+      {
+        itemId: "456",
+        name: "SKU 2",
+        nameComplete: "SKU 2 Complete",
+        images: [],
+        sellers: [
+          {
+            sellerId: "1",
+            sellerName: "Main Seller",
+            commertialOffer: {
+              Price: 10000,
+              ListPrice: 12000,
+              AvailableQuantity: 5,
+              PriceWithoutDiscount: 12000,
+              Installments: [],
+            },
+          },
+        ],
+        variations: [],
+      },
+    ];
+
+    const sku = pickSku(items);
+    expect(sku.itemId).toBe("456"); // Should pick the available one
+  });
+
+  test("toProduct transforms VTEX product to schema.org format", () => {
+    const vtexProduct: VTEXProduct = {
+      productId: "123",
+      productName: "Test Product",
+      brand: "Test Brand",
+      brandId: 1,
+      description: "Test description",
+      linkText: "test-product",
+      link: "/test-product/p",
+      categories: ["/Category/"],
+      categoryId: "1",
+      items: [
+        {
+          itemId: "456",
+          name: "Test SKU",
+          nameComplete: "Test SKU Complete",
+          images: [
+            {
+              imageUrl: "https://example.com/image.jpg",
+              imageText: "Image",
+              imageLabel: "main",
+            },
+          ],
+          sellers: [
+            {
+              sellerId: "1",
+              sellerName: "Main Seller",
+              commertialOffer: {
+                Price: 10000,
+                ListPrice: 12000,
+                AvailableQuantity: 5,
+                PriceWithoutDiscount: 12000,
+                Installments: [
+                  {
+                    Value: 10000,
+                    NumberOfInstallments: 1,
+                    PaymentSystemName: "Visa",
+                  },
+                ],
+              },
+            },
+          ],
+          variations: [
+            { name: "Color", values: ["Red"] },
+          ],
+        },
+      ],
+      origin: "intelligent-search",
+    };
+
+    const sku = pickSku(vtexProduct.items);
+    const product = toProduct(vtexProduct, sku, baseUrl, CURRENCY);
+
+    expect(product["@type"]).toBe("Product");
+    expect(product.productID).toBe("123");
+    expect(product.name).toBe("Test Product");
+    expect(product.description).toBe("Test description");
+    expect(product.url).toContain("/test-product/p");
+    expect(product.brand?.name).toBe("Test Brand");
+    expect(product.sku).toBe("456");
+    expect(product.offers.lowPrice).toBe(100); // 10000/100
+    expect(product.offers.highPrice).toBe(120); // 12000/100
+    expect(product.offers.priceCurrency).toBe(CURRENCY);
+    expect(product.offers.offers[0].availability).toBe("https://schema.org/InStock");
+    expect(product.image.length).toBeGreaterThan(0);
+    expect(product.additionalProperty?.length).toBeGreaterThan(0);
+    expect(product.isVariantOf?.hasVariant.length).toBeGreaterThan(0);
+  });
+});
+