@ratio-mcp/docs-server 1.5.0 → 1.6.0

package/README.md

@@ -0,0 +1,75 @@
+# @ratio-mcp/docs-server
+
+> Anti-hallucination reference MCP for the Ratio platform. Ground-truth lookups for scopes, REST endpoints, webhook events, and OAuth flow. Production environment.
+
+Not installed directly — included via [`@ratio-mcp/setup`](https://www.npmjs.com/package/@ratio-mcp/setup).
+
+---
+
+## Why it exists
+
+Without grounded references, LLMs hallucinate platform details — wrong scope codes, invented endpoints, made-up webhook topics. This server exposes 6 tools that the LLM is **required** to call before answering platform-specific questions.
+
+When `lookup_docs` returns `found: false`, the LLM must tell the user the info isn't available — not guess.
+
+---
+
+## Tools (6)
+
+| Tool | When the LLM must call it |
+|---|---|
+| `lookup_docs` | **Mandatory fallback.** Any platform question where the LLM isn't 100% sure — unified fuzzy search across all docs. |
+| `get_available_scopes` | Before showing scope options to the developer. Returns all 78 resources × 147 scopes. |
+| `get_api_reference` | Before generating or discussing API calls for a resource. Returns endpoint definitions. |
+| `get_scope_endpoint_map` | Before code generation. Maps scopes → the endpoints they unlock. |
+| `get_webhook_events` | Before answering webhook questions. Returns the full event catalog. |
+| `validate_api_code` | **After generating code, before writing to disk.** Catches hallucinated fields, wrong endpoints, missing required fields. |
+
+---
+
+## Data sources
+
+The server bundles local JSON schemas — zero network calls at runtime:
+
+```
+packages/docs-server/src/schemas/
+├── orders.json          # REST endpoints with full request/response shapes
+├── products.json        # Same for products
+├── webhooks.json        # Event catalog + HMAC-SHA256 verification + retry policy
+└── oauth.json           # OAuth flow reference
+```
+
+> Scope data is NOT here — it lives in `@ratio-mcp/shared` (`scopes-data.ts`), sourced from `GET /api/v1/scopes`. Every other `*.json` in this dir is treated as an API resource by `getAvailableResourceFiles()`.
+
+Currently `orders` and `products` have full type schemas. Other resources will be added as the platform exposes them via Swagger.
+
+---
+
+## Environment
+
+**Production** — points at `https://gkx.gokwik.co/aes` for any tools that fall back to live API calls (most don't — schemas are local).
+
+---
+
+## Anti-hallucination contract
+
+Both MCP servers (this one and `dev-server`) embed mandatory tool-usage rules in their server instructions, surfaced to the LLM via the MCP handshake:
+
+> 1. ALWAYS call `lookup_docs` BEFORE answering questions about scopes, webhooks, APIs, or OAuth.
+> 2. If `lookup_docs` returns `found: false`, tell the user the info is not available — do NOT guess.
+> 3. ALWAYS call `validate_scopes` (dev-server) BEFORE presenting any scope to the developer.
+> 4. ALWAYS call `validate_api_code` AFTER generating Ratio API code, BEFORE writing to disk.
+
+These guardrails are the difference between "the LLM mostly works" and "the LLM never invents a platform field name."
+
+---
+
+## Logging
+
+stderr + file (`logs/docs-server.log`). Key log prefixes: `[lookup_docs]`, `[validate_api_code]`.
+
+---
+
+## 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
+    }
+  ]
+}