@ratio-mcp/dev-server 1.5.0 → 1.6.0

package/README.md

@@ -0,0 +1,118 @@
+# @ratio-mcp/dev-server
+
+> MCP server exposing 33 individually-callable tools that cover the full Ratio app-creation lifecycle. Production environment.
+
+Not installed directly — included via [`@ratio-mcp/setup`](https://www.npmjs.com/package/@ratio-mcp/setup).
+
+---
+
+## What it does
+
+Lets developers describe an app in plain English and walks them through every phase:
+
+```
+auth → app creation → scope selection → webhook setup
+   → scaffold frontend → build → validate → submit → review
+   → publish → scaffold backend → generate API routes
+```
+
+Each tool is gated by a **prerequisite-graph guard**. Calling `upload_build` before `validate_build` returns a structured error showing exactly which tools are missing and the chain needed to unblock — the LLM self-corrects instead of guessing.
+
+---
+
+## Tool catalog (33 tools)
+
+| Category | Tools |
+|---|---|
+| **Auth** (3) | `developer_signup`, `developer_verify_otp`, `developer_login` |
+| **Reference data** (1) | `get_categories` |
+| **Hookdeck** (1) | `setup_hookdeck` |
+| **App management** (5) | `create_app`, `get_app`, `update_app`, `list_apps`, `delete_app` |
+| **Requirements** (3) | `gather_requirements`, `define_app_requirements`, `validate_scopes` |
+| **Scaffold** (2) | `scaffold_frontend`, `scaffold_backend` |
+| **Token mgmt** (2) | `refresh_access_token`, `check_token_status` |
+| **Codegen** (1) | `generate_api_routes` |
+| **Build** (3) | `build_frontend`, `validate_build`, `create_submission_zip` |
+| **Submission** (4) | `upload_build`, `submit_for_review`, `get_app_status`, `publish_app` |
+| **Webhooks** (5) | `get_webhook_topics`, `create_webhooks`, `list_webhooks`, `toggle_webhook`, `delete_webhook` |
+| **Lifecycle / status** (2) | `get_app_lifecycle`, `get_status` |
+
+Call `get_status` at any time to see which tools are completed, available, or blocked by missing prerequisites.
+
+---
+
+## Generated artifacts (written to developer's filesystem)
+
+When the developer runs `scaffold_frontend` + `scaffold_backend` + `generate_api_routes`:
+
+```
+~/Desktop/<project>/
+├── frontend/                       # React + Vite (auth, routing, layout pre-wired)
+│   └── ...
+└── backend/                        # NestJS
+    └── src/
+        ├── main.ts
+        ├── app.module.ts                            # auto-patched with new module imports
+        ├── oauth/                                   # OAuth callback handler (merchant install)
+        ├── orders/                                  # scope-filtered from schemas/orders.json
+        │   ├── orders.controller.ts
+        │   ├── orders.service.ts
+        │   └── orders.module.ts
+        ├── products/                                # same pattern for products
+        └── webhook/                                 # only if webhooks configured
+            ├── webhook.controller.ts                # HMAC-SHA256 signature verification
+            ├── webhook.service.ts                   # 8 orders + 3 products event handlers
+            └── webhook.module.ts
+```
+
+After `generate_api_routes`, the backend auto-starts on port 3000 with `npm run dev`. If Hookdeck was configured earlier, a public tunnel is also live.
+
+---
+
+## Webhook event coverage
+
+The generated `webhook.service.ts` routes these events out of the box:
+
+| Resource | Events handled |
+|---|---|
+| Orders (8) | `orders/create` (also alias `order-create`), `orders/updated`, `orders/cancelled`, `orders/fulfilled`, `orders/paid`, `orders/partially_fulfilled`, `orders/delete`, `orders/edited` |
+| Products (3) | `products/create`, `products/update`, `products/delete` |
+| App (1) | `app/uninstalled` |
+
+Other events the platform fires (`customers/*`, `inventory/*`, `collections/*`, etc.) hit the `default:` branch and log a warning — they need handler stubs added if the developer subscribes to them.
+
+---
+
+## Environment
+
+**Production** — `https://gkx.gokwik.co/aes`
+
+Override at runtime via `RATIO_API_BASE_URL` in the developer's `.env` file (loaded before the server starts).
+
+---
+
+## Persistent state
+
+The MCP keeps per-user state in `~/.ratio-v2/`, created lazily at first use. State survives Claude Desktop restarts — in-progress work isn't lost across sessions.
+
+**Active:**
+
+| Path | Purpose |
+|---|---|
+| `~/.ratio-v2/requirements.json` | Per-app scope + project-path state. Written by `define_app_requirements`, enriched by `scaffold_frontend`, read by `generate_api_routes` to scope-filter the generated controllers. **Load-bearing — the whole multi-session codegen flow depends on it.** |
+
+
+## Logging
+
+Dual output:
+
+- **stderr** (MCP protocol — visible in Claude Desktop logs)
+- **File** (`logs/dev-server.log`)
+
+Key prefixes: `[tool-guard]`, `[session-state]`, `API_REQ:`, `API_RES:`, `API_ERR:`.
+
+---
+
+## License
+
+UNLICENSED — internal to the Ratio platform / GoKwik.

package/dist/schemas/app-distribution.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "topic": "app_distribution",
+  "summary": "Every Ratio app has a distribution type chosen at creation: public or private. It controls who can install the app, whether it is listed in the marketplace, and whether it goes through human review.",
+  "types": {
+    "public": {
+      "definition": "Available to ALL merchants via the marketplace.",
+      "distribution": "Listed in the public marketplace; any merchant can discover and install it.",
+      "review": "Each submitted version must pass admin (human) review before it can be published.",
+      "publication": "Published manually after approval (or via the app's auto-publish setting).",
+      "use_case": "Third-party integrations sold to many merchants.",
+      "create": "Default. create_app with app_type omitted or app_type: \"public\"."
+    },
+    "private": {
+      "definition": "Available ONLY to an explicit whitelist of merchants.",
+      "distribution": "Not listed in the marketplace; installable only by whitelisted merchant IDs.",
+      "review": "Skips human review — versions are auto-reviewed (system actor) and auto-published on upload.",
+      "publication": "Immediate on version upload.",
+      "requirement": "At least one merchant ID must be provided at creation time.",
+      "whitelist_management": "Add/remove merchants any time via the manage_private_merchants tool (or GET/POST/DELETE /applications/:id/private-merchants).",
+      "use_case": "Custom builds for specific enterprise clients or partner integrations.",
+      "create": "create_app with app_type: \"private\" and merchant_ids: [\"merchant-id-1\", ...] (at least one)."
+    }
+  },
+  "comparison": [
+    { "aspect": "Distribution",  "public": "All merchants",         "private": "Whitelisted merchants only" },
+    { "aspect": "Marketplace",   "public": "Listed",                "private": "Hidden" },
+    { "aspect": "Review",        "public": "Human review required", "private": "Auto-reviewed (system)" },
+    { "aspect": "Publication",   "public": "After approval",        "private": "Immediate on upload" },
+    { "aspect": "Merchant ID whitelist", "public": "N/A",          "private": "Required (>= 1)" }
+  ],
+  "mcp_support": {
+    "create_app": "Accepts app_type ('public' | 'private', default public) and merchant_ids. Private requires merchant_ids (>= 1).",
+    "manage_private_merchants": "list | add | remove whitelisted merchants for a private app."
+  }
+}

package/dist/schemas/customers.json

@@ -0,0 +1,26 @@
+{
+  "resource": "customers",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "_generated": "by scripts/sync-schemas.mjs from backend OpenAPI (x-required-scope). Do not hand-edit.",
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/api/v1/customers/:id",
+      "controller_order": 1,
+      "handler_name": "getCustomerById",
+      "required_scope": "read_customers",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    }
+  ]
+}

package/dist/schemas/discounts.json

@@ -0,0 +1,81 @@
+{
+  "resource": "discounts",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "common_headers": {
+    "idempotency-key": "header"
+  },
+  "_generated": "by scripts/sync-schemas.mjs from backend OpenAPI (x-required-scope). Do not hand-edit.",
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/api/v1/discounts",
+      "controller_order": 1,
+      "handler_name": "create",
+      "required_scope": "write_discounts",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": []
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/discounts",
+      "controller_order": 2,
+      "handler_name": "findAll",
+      "required_scope": "read_discounts",
+      "request_body": null
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/discounts/:id",
+      "controller_order": 3,
+      "handler_name": "findOne",
+      "required_scope": "read_discounts",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/discounts/:id",
+      "controller_order": 4,
+      "handler_name": "update",
+      "required_scope": "write_discounts",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": {
+        "content_type": "application/json",
+        "fields": []
+      }
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/discounts/:id",
+      "controller_order": 5,
+      "handler_name": "remove",
+      "required_scope": "write_discounts",
+      "path_params": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    }
+  ]
+}

package/dist/schemas/draft_orders.json

@@ -0,0 +1,112 @@
+{
+  "resource": "draft_orders",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "common_headers": {
+    "gk-merchant-id": "Required. Tenant/merchant context for the request."
+  },
+  "notes": "Paths carry a doubled /v1 segment (global /api/v1 prefix + controller 'v1/draft-orders'). Line-item / customer / address shapes mirror the orders resource.",
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/api/v1/v1/draft-orders",
+      "controller_order": 1,
+      "handler_name": "createDraftOrder",
+      "required_scope": "write_draft_orders",
+      "summary": "Create a draft order",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          { "name": "email", "type": "string", "required": false, "description": "Customer email" },
+          { "name": "currency", "type": "string", "required": false, "description": "Currency code (e.g. INR)" },
+          { "name": "line_items", "type": "array", "required": false, "description": "Line items (same shape as orders: variant_id, product_id, title, quantity, sku, price)" },
+          { "name": "customer", "type": "object", "required": false, "description": "Customer details (same shape as orders)" },
+          { "name": "billing_address", "type": "object", "required": false, "description": "Billing address (same shape as orders)" },
+          { "name": "shipping_address", "type": "object", "required": false, "description": "Shipping address (same shape as orders)" },
+          { "name": "note", "type": "string", "required": false }
+        ]
+      },
+      "response_schema": "DraftOrder"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/v1/draft-orders",
+      "controller_order": 2,
+      "handler_name": "updateDraftOrder",
+      "required_scope": "write_draft_orders",
+      "summary": "Update a draft order",
+      "description": "Update a draft order. The draft order id is supplied in the request body (not the path).",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          { "name": "id", "type": "string", "required": true, "description": "The draft order ID to update (in body)" },
+          { "name": "email", "type": "string", "required": false },
+          { "name": "line_items", "type": "array", "required": false },
+          { "name": "customer", "type": "object", "required": false },
+          { "name": "shipping_address", "type": "object", "required": false },
+          { "name": "billing_address", "type": "object", "required": false }
+        ]
+      },
+      "response_schema": "DraftOrder"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/v1/draft-orders",
+      "controller_order": 3,
+      "handler_name": "getDraftOrders",
+      "required_scope": "read_draft_orders",
+      "summary": "List draft orders",
+      "query_params": [
+        { "name": "limit", "type": "number", "required": false },
+        { "name": "offset", "type": "number", "required": false },
+        { "name": "status", "type": "string", "required": false }
+      ],
+      "request_body": null,
+      "response_schema": "DraftOrderListResponse"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/v1/draft-orders/:id",
+      "controller_order": 4,
+      "handler_name": "getDraftOrderById",
+      "required_scope": "read_draft_orders",
+      "summary": "Get a draft order by ID",
+      "path_params": [
+        { "name": "id", "type": "string", "required": true, "description": "The draft order ID" }
+      ],
+      "request_body": null,
+      "response_schema": "DraftOrder"
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/v1/v1/draft-orders/:id",
+      "controller_order": 5,
+      "handler_name": "deleteDraftOrder",
+      "required_scope": "write_draft_orders",
+      "summary": "Delete a draft order",
+      "path_params": [
+        { "name": "id", "type": "string", "required": true, "description": "The draft order ID to delete" }
+      ],
+      "request_body": null,
+      "response_schema": "DraftOrder"
+    }
+  ],
+  "schemas": {
+    "DraftOrder": {
+      "id": "string — draft order identifier",
+      "email": "string | null",
+      "currency": "string",
+      "line_items": "LineItem[] — same shape as orders",
+      "customer": "Customer object",
+      "shipping_address": "Address | null",
+      "billing_address": "Address | null",
+      "note": "string | null",
+      "status": "string — draft status",
+      "created_at": "string — ISO 8601",
+      "updated_at": "string — ISO 8601"
+    }
+  }
+}

package/dist/schemas/loyalty.json

@@ -0,0 +1,147 @@
+{
+  "resource": "loyalty",
+  "auth": {
+    "type": "bearer",
+    "header": "Authorization",
+    "format": "Bearer <access_token>"
+  },
+  "_generated": "by scripts/sync-schemas.mjs from backend OpenAPI (x-required-scope). Do not hand-edit.",
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/api/v1/loyalty/points/credit",
+      "controller_order": 1,
+      "handler_name": "credit",
+      "required_scope": "write_loyalty",
+      "summary": "Credit loyalty points to a customer (idempotent).",
+      "description": "Adds points to the customer’s balance. Same `idempotency_key` on retry returns the existing transaction without double-crediting.",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          {
+            "name": "phone",
+            "type": "string",
+            "required": true,
+            "description": "Customer phone number (loyalty key)"
+          },
+          {
+            "name": "points",
+            "type": "number",
+            "required": true,
+            "description": "Points to apply (positive integer, max 100000 per transaction)"
+          },
+          {
+            "name": "idempotency_key",
+            "type": "string",
+            "required": true,
+            "description": "Caller-supplied idempotency key. Same key on retry returns the existing transaction without double-applying."
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "required": false,
+            "description": "Free-text description of the reason"
+          },
+          {
+            "name": "metadata",
+            "type": "object",
+            "required": false,
+            "description": "Arbitrary structured data attached to the ledger row"
+          }
+        ]
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/loyalty/points/debit",
+      "controller_order": 2,
+      "handler_name": "debit",
+      "required_scope": "write_loyalty",
+      "summary": "Debit loyalty points from a customer (idempotent).",
+      "description": "Deducts points from the customer’s balance. Returns 400 if the customer’s balance is insufficient.",
+      "request_body": {
+        "content_type": "application/json",
+        "fields": [
+          {
+            "name": "phone",
+            "type": "string",
+            "required": true,
+            "description": "Customer phone number (loyalty key)"
+          },
+          {
+            "name": "points",
+            "type": "number",
+            "required": true,
+            "description": "Points to apply (positive integer, max 100000 per transaction)"
+          },
+          {
+            "name": "idempotency_key",
+            "type": "string",
+            "required": true,
+            "description": "Caller-supplied idempotency key. Same key on retry returns the existing transaction without double-applying."
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "required": false,
+            "description": "Free-text description of the reason"
+          },
+          {
+            "name": "metadata",
+            "type": "object",
+            "required": false,
+            "description": "Arbitrary structured data attached to the ledger row"
+          }
+        ]
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/loyalty/points/:phone/balance",
+      "controller_order": 3,
+      "handler_name": "getBalance",
+      "required_scope": "read_loyalty",
+      "summary": "Get a customer's current loyalty balance + lifetime stats.",
+      "description": "Returns the redeemable balance and lifetime earned/redeemed/expired/adjusted totals. A customer with no loyalty record yet returns a zero-balance response.",
+      "path_params": [
+        {
+          "name": "phone",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/loyalty/points/:phone/history",
+      "controller_order": 4,
+      "handler_name": "getHistory",
+      "required_scope": "read_loyalty",
+      "summary": "Get a customer's loyalty transaction history (paginated).",
+      "description": "Returns the full points ledger (earn, redeem, adjust, reversal, expire) for the customer, most recent first, with pagination metadata.",
+      "query_params": [
+        {
+          "name": "page",
+          "type": "number",
+          "required": false,
+          "description": "Page number (1-based); os-loyalty defaults to 1"
+        },
+        {
+          "name": "limit",
+          "type": "number",
+          "required": false,
+          "description": "Rows per page"
+        }
+      ],
+      "path_params": [
+        {
+          "name": "phone",
+          "type": "string",
+          "required": true
+        }
+      ],
+      "request_body": null
+    }
+  ]
+}

package/dist/schemas/oauth.json

@@ -0,0 +1,71 @@
+{
+  "version": 1,
+  "flows": {
+    "authorization_code": {
+      "description": "Standard OAuth 2.0 Authorization Code flow for installing apps on merchant stores",
+      "steps": [
+        {
+          "step": 1,
+          "name": "Request Authorization Code",
+          "method": "POST",
+          "endpoint": "/api/v1/oauth/authorize",
+          "description": "Request an authorization code by providing client_id, merchant_id, redirect_uri, and scopes. The app must be published before this step.",
+          "request_body": {
+            "clientId": "string — Your app's client ID",
+            "redirectUri": "string — Registered redirect URI",
+            "merchantId": "string — Merchant ID of the store installing the app",
+            "scopes": "string[] — Array of scopes to request (e.g. ['read_orders'])"
+          },
+          "response": {
+            "code": "string — Authorization code (expires quickly)",
+            "redirectUri": "string — The redirect URI",
+            "expiresAt": "string — ISO 8601 expiry timestamp"
+          }
+        },
+        {
+          "step": 2,
+          "name": "Exchange Code for Tokens",
+          "method": "POST",
+          "endpoint": "/api/v1/oauth/token",
+          "description": "Exchange the authorization code for access and refresh tokens. Must be called immediately — the code expires quickly.",
+          "request_body": {
+            "grant_type": "authorization_code",
+            "code": "string — The authorization code from step 1",
+            "clientId": "string — Your app's client ID",
+            "clientSecret": "string — Your app's client secret",
+            "redirectUri": "string — Must match step 1"
+          },
+          "response": {
+            "access_token": "string — Bearer token for API calls",
+            "token_type": "Bearer",
+            "expires_in": "number — Seconds until token expires",
+            "refresh_token": "string — Token for refreshing access",
+            "scope": "string — Granted scopes (comma-separated)",
+            "merchant_id": "string — Merchant ID"
+          }
+        },
+        {
+          "step": 3,
+          "name": "Refresh Token",
+          "method": "POST",
+          "endpoint": "/api/v1/oauth/token",
+          "description": "Use the refresh token to get a new access token when the current one expires.",
+          "request_body": {
+            "grant_type": "refresh_token",
+            "refresh_token": "string — The refresh token",
+            "clientId": "string — Your app's client ID",
+            "clientSecret": "string — Your app's client secret"
+          },
+          "response": {
+            "access_token": "string — New bearer token",
+            "token_type": "Bearer",
+            "expires_in": "number — Seconds until new token expires",
+            "refresh_token": "string — New refresh token",
+            "scope": "string — Granted scopes",
+            "merchant_id": "string — Merchant ID"
+          }
+        }
+      ]
+    }
+  }
+}