@ratio-mcp-qa/dev-server

MCP server exposing 33 individually-callable tools that cover the full Ratio app-creation lifecycle. QA environment.

Not installed directly — included via @ratio-mcp-qa/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

QA — https://api-gw-v4.dev.gokwik.in/qa/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.