Cartix Engineering Documentation

Overview & Motivation #

Modern merchants maintain their mission-critical business data inside e-commerce platforms like WooCommerce. However, autonomous AI agents cannot directly query raw store databases without encountering massive security risks, rate-limit bans, credential exposures, and context-window token overflows.

Cartix serves as the secure, read-only Model Context Protocol (MCP) bridge between AI reasoning agents (Claude Desktop, Cursor, LangChain, custom agents) and WooCommerce REST endpoints.

Quick Start & Setup #

Follow these steps to clone and run Cartix on your development machine:

# 1. Clone repository & enter directory
git clone https://github.com/ilakkiyan-j/Cartix.git
cd Cartix

# 2. Install dependencies
npm install

# 3. Create environment configuration
cp .env.example .env

# 4. Build TypeScript bundle
npm run build

# 5. Start the server (runs streamable-http or stdio depending on MCP_TRANSPORT)
npm start

Environment Variables Reference #

All configuration is defined in src/config/env.ts and strictly validated with Zod at server startup:

Claude Desktop Integration #

Claude Desktop communicates with Cartix using the standard stdio transport. Add the server entry to your Claude Desktop configuration file:

Config Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cartix": {
      "command": "node",
      "args": ["/absolute/path/to/Cartix/dist/src/index.js"],
      "env": {
        "WOOCOMMERCE_URL": "https://store.example.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_...",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_...",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Architecture & Transport Protocols #

Cartix conforms strictly to the Model Context Protocol (MCP) specification. All tool requests and responses are encapsulated in standard JSON-RPC 2.0 frames across three supported transports:

Security & Privacy Guardrails #

Cartix enforces enterprise security at every layer of the proxy lifecycle:

1. Server-Side Credential Isolation

WooCommerce API keys are loaded once into server memory from environment variables. The MCP input schemas exposed to AI models require only business query parameters — keys are never passed through prompt contexts.

2. Automatic PII Redaction

Customer records are sanitized before returning JSON payloads:

• Email Masking: alexander@example.com becomes a***r@example.com.
• Physical Address Stripping: Street addresses and apartment details are stripped; only country and state are preserved for shipping zone reasoning.

3. Secret Redaction in Logs

All loggers automatically intercept and redact sensitive token patterns (\bck_[a-zA-Z0-9_-]+ and \bcs_[a-zA-Z0-9_-]+) to guarantee secrets are never written to disk, console, or observability sinks.

Rate Limiting & Reliability #

To safeguard store infrastructure from high-concurrency agent loops:

• In-Memory Token Bucket: Regulates outbound request bursts with configurable capacity and refill intervals.
• Exponential Backoff with Full Jitter: Transient network errors and 5xx responses are retried using randomized jitter delays (sleep = rand(0, min(max_delay, base * 2^attempt))).
• 429 Retry-After Header Parsing: Explicitly respects upstream WooCommerce throttling directives.

MCP Tools Specification #

Cartix registers 5 production-ready, read-only MCP tools implemented in TypeScript with Zod validation.

{
  "orders": [
    {
      "id": 1042,
      "status": "pending",
      "total": "49.99",
      "currency": "USD",
      "created_at": "2026-10-01T14:20:00Z",
      "customer": {
        "email": "a***e@example.com"
      },
      "item_count": 2
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

{
  "id": 1004,
  "status": "processing",
  "currency": "USD",
  "total": "129.50",
  "created_at": "2026-10-02T09:15:00Z",
  "line_items": [
    {
      "id": 88,
      "product_id": 45,
      "name": "Mechanical Keyboard RGB",
      "quantity": 1,
      "price": "129.50",
      "total": "129.50"
    }
  ],
  "customer": {
    "email": "j***n@company.org"
  }
}

{
  "products": [
    {
      "id": 87,
      "name": "Ergonomic Wireless Mechanical Keyboard",
      "sku": "KB-001",
      "price": "49.99",
      "stock_status": "instock",
      "stock_quantity": 45
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

{
  "id": 87,
  "name": "Ergonomic Wireless Mechanical Keyboard",
  "sku": "KB-001",
  "price": "49.99",
  "regular_price": "59.99",
  "sale_price": "49.99",
  "stock_status": "instock",
  "stock_quantity": 45,
  "manage_stock": true
}

{
  "inventory": [
    {
      "product_id": 92,
      "sku": "MC-011",
      "name": "Studio Condenser Microphone",
      "stock_quantity": 3,
      "stock_status": "instock",
      "is_low_stock": true
    },
    {
      "product_id": 97,
      "sku": "KC-016",
      "name": "Artisan Keycap Resin Galaxy",
      "stock_quantity": 0,
      "stock_status": "outofstock",
      "is_low_stock": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1
  }
}

Agent Studio & Client Integration #

Cartix conforms directly to the Model Context Protocol (MCP) standard, enabling plug-and-play connectivity with Razorpay Agent Studio, Claude Desktop, Cursor, LangChain, and custom autonomous agent workflows.

1. Razorpay Agent Studio Setup

In Agent Studio, register Cartix as an external MCP tool server using either the direct HTTP connector or standard process invocation:

{
  "name": "cartix-woocommerce-connector",
  "transport": "streamable-http",
  "endpoint": "http://localhost:3000/mcp",
  "capabilities": ["tools"],
  "healthCheck": "http://localhost:3000/health"
}

2. Programmatic Client Integration (TypeScript)

Connect any agent pipeline to Cartix via the official @modelcontextprotocol/sdk:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/src/index.js"],
  env: process.env,
});

const client = new Client({ name: "agent-studio-client", version: "1.0.0" }, { capabilities: {} });
await client.connect(transport);

// Query available WooCommerce MCP tools
const tools = await client.listTools();
console.log(`Discovered ${tools.tools.length} safe tools.`);

Testing & Quality Assurance #

The automated test suite runs on Vitest and contains 60 automated tests across 10 test files, guaranteeing comprehensive coverage:

• Schema & Input Validation: Strict Zod constraint checks for IDs, status enums, date strings, and pagination.
• Error Mapping: Deterministic HTTP 400, 401, 404, 429, and 500 error code translations into MCP error envelopes.
• PII Sanitization: Regular expression tests verifying zero email or address leakage.
• Token Bucket & Backoff: Simulating upstream 429 responses and verifying jittered exponential retry delays.
• End-to-End MCP Handshake: Verification over stdio and streamable-http JSON-RPC 2.0 endpoints.

# Execute complete test suite
npm test

# Run tests in watch mode during development
npm run test:watch

Docker Containerization #

Deploy Cartix inside a hardened, unprivileged Node 20 Alpine container for cloud or internal microservice environments:

# Build optimized container image
docker build -t cartix-mcp .

# Run container with environment configuration
docker run -d -p 3000:3000 \
  -e WOOCOMMERCE_URL=https://store.example.com \
  -e WOOCOMMERCE_CONSUMER_KEY=ck_... \
  -e WOOCOMMERCE_CONSUMER_SECRET=cs_... \
  -e MCP_TRANSPORT=streamable-http \
  --name cartix-mcp-server \
  cartix-mcp

Explicit Operational Boundaries #

Cartix is architected with a strict zero-mutation security contract. The server does not register any tools capable of modifying merchant data.

License & Attribution #

Cartix is open-source software licensed under the MIT License.

MIT License

Copyright (c) 2026 Cartix Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.