ratio-mcp-server

MCP (Model Context Protocol) server for the Ratio e-commerce platform. Enables AI-powered app development through Claude in Cursor IDE or the Claude Desktop app.

Quick Start

Install via npx (no clone needed)

Add to your Cursor config (.cursor/mcp.json) or Claude Desktop config:

{
  "mcpServers": {
    "ratio": {
      "command": "npx",
      "args": ["-y", "ratio-mcp-server"],
      "env": {
        "RATIO_APP_ID": "your_app_id",
        "RATIO_APP_SECRET": "your_app_secret",
        "RATIO_TEST_STORE_URL": "https://dev-os-ecosystem.dev.gokwik.io",
        "RATIO_ACCESS_TOKEN": "your_access_token",
        "RATIO_REFRESH_TOKEN": "your_refresh_token",
        "RATIO_SCOPES": "READ_PRODUCTS,WRITE_PRODUCTS",
        "DEVELOPER_TOKEN": "",
        "DEVELOPER_ID": "",
        "DEBUG": "false"
      }
    }
  }
}

Restart Cursor or Claude Desktop, and you're ready to go.

Tip: You can leave DEVELOPER_TOKEN and DEVELOPER_ID empty — use the developer_login tool to authenticate dynamically.

Available Tools

Developer Authentication

| Tool | Description | |------|-------------| | developer_signup | Register a new developer account | | developer_verify_otp | Verify email OTP code after signup | | developer_login | Login and store token for the session |

App Management

| Tool | Description | |------|-------------| | create_app | Create a new app in the Developer Dashboard | | get_app | Get app details by ID | | update_app | Update an existing app | | delete_app | Delete an app | | list_apps | List all your apps |

Merchant Store APIs

| Tool | Description | |------|-------------| | get_products | Fetch products from test store | | create_product | Create a new product | | update_product | Update an existing product | | get_orders | Fetch orders with filtering | | get_customers | Fetch customers with filtering |

OAuth Flow

| Tool | Description | |------|-------------| | request_auth_code | Start OAuth flow for app installation | | get_access_token | Exchange auth code for tokens | | refresh_access_token | Refresh an expired access token | | check_token_status | Check if token is expired |

Build & Submission

| Tool | Description | |------|-------------| | build_frontend | Run production build for React frontend | | validate_build | Validate build meets submission requirements | | create_submission_zip | Zip the build for app submission |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | RATIO_APP_ID | Yes | Your Ratio application ID | | RATIO_APP_SECRET | Yes | Your Ratio application secret | | RATIO_TEST_STORE_URL | Yes | Base URL of the Ratio API | | RATIO_ACCESS_TOKEN | Yes | OAuth access token for merchant store | | RATIO_REFRESH_TOKEN | Yes | OAuth refresh token | | RATIO_SCOPES | Yes | Comma-separated list of scopes | | DEVELOPER_TOKEN | No | Developer Dashboard JWT (or use developer_login) | | DEVELOPER_ID | No | Developer UUID (auto-set by developer_login) | | DEBUG | No | Set to "true" for verbose logging |

Example Usage

Once configured, just chat naturally in Cursor or Claude Desktop:

"Login to Ratio developer dashboard with my email [email protected]"
"List all my apps"
"Create a new app called MyAnalyticsApp in the analytics category"
"Fetch all products from my test store"
"Build the frontend and create a submission zip"

Requirements

• Node.js >= 18.0.0
• A Ratio developer account (sign up here)

License

MIT