@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.

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.