@ratio-mcp-sandbox/docs-server

Anti-hallucination reference MCP for the Ratio platform. Ground-truth lookups for scopes, REST endpoints, webhook events, and OAuth flow. Sandbox environment.

Not installed directly — included via @ratio-mcp-sandbox/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/
├── scopes.json          # 147 scopes across 78 resources
├── 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

Currently orders and products have full type schemas. Other resources will be added as the platform exposes them via Swagger.

Environment

Sandbox — points at https://api-gw-v4.dev.gokwik.in/sandbox/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.