@ratio-mcp/docs-server 1.1.1 → 1.3.0

package/dist/tools/index.d.ts

@@ -9,7 +9,7 @@ export interface ToolDefinition {
     handler: (input: Record<string, unknown>) => unknown;
 }
 /**
- * All docs-server tools (5 tools)
+ * All docs-server tools (6 tools)
  */
 export declare const docsTools: ToolDefinition[];
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC;IACvB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;CACtD;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,cAAc,EAgFrC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC;IACvB,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;CACtD;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,cAAc,EA0GrC,CAAC"}

package/dist/tools/index.js

@@ -4,14 +4,33 @@ import { getApiReference } from './get-api-reference.js';
 import { getScopeEndpointMap } from './get-scope-map.js';
 import { validateApiCode } from './validate-code.js';
 import { getWebhookEvents } from './get-webhooks.js';
+import { lookupDocs } from './lookup-docs.js';
 /**
- * All docs-server tools (5 tools)
+ * All docs-server tools (6 tools)
  */
 export const docsTools = [
+    {
+        name: 'lookup_docs',
+        description: 'MANDATORY FALLBACK: When you are unsure about ANY platform detail (API endpoints, scopes, webhooks, OAuth flow, ' +
+            'request/response formats, error codes), call this tool BEFORE answering. ' +
+            'If this tool returns found=false, tell the user the information is not available in the documentation. ' +
+            'Do NOT guess or hallucinate information — use only what this tool returns. ' +
+            'Searches across all documentation: API references, scopes, webhook events, and OAuth flow.',
+        inputSchema: z.object({
+            query: z.string().min(1).describe('Natural language search query (e.g., "how to cancel an order", "webhook verification")'),
+            category: z
+                .enum(['api', 'scopes', 'webhooks', 'oauth'])
+                .optional()
+                .describe('Optional category to narrow the search'),
+        }),
+        handler: (input) => lookupDocs(input),
+    },
     {
         name: 'get_available_scopes',
-        description: 'Returns all available OAuth scopes grouped by resource. ' +
-            'Use when a developer says what kind of app they want to build — show them available scopes to pick from. ' +
+        description: 'MANDATORY: Call this tool before answering ANY question about what OAuth scopes exist, what they grant access to, ' +
+            'or what resources are available on the platform. Do NOT rely on your training data for scope specifics. ' +
+            'If a scope is not returned by this tool, it does not exist — tell the user. ' +
+            'Returns all available OAuth scopes grouped by resource. ' +
             'Optionally filter by resource name (e.g. "orders", "products", "customers"). ' +
             'Returns 24 primary resources with their read/write/delete scopes. ' +
             'Each scope includes a rich description, use_cases, and commonly_paired_with hints ' +
@@ -27,7 +46,9 @@ export const docsTools = [
     },
     {
         name: 'get_api_reference',
-        description: 'Returns complete API reference for a resource including all endpoints, parameters, request/response schemas. ' +
+        description: 'MANDATORY: Call this tool before answering ANY question about API endpoints, request/response formats, ' +
+            'HTTP methods, query parameters, or request bodies. Do NOT guess endpoint details from your training data. ' +
+            'Returns complete API reference for a resource including all endpoints, parameters, request/response schemas. ' +
             'Endpoints are returned in controller_order for deterministic code generation. ' +
             'Optionally filter by scope to show only endpoints accessible with that scope.',
         inputSchema: z.object({
@@ -43,7 +64,8 @@ export const docsTools = [
         name: 'get_scope_endpoint_map',
         description: 'Given a list of scopes, returns exactly which API endpoints are unlocked, in controller_order. ' +
             'This is the primary tool for code generation — it tells you exactly what endpoints to generate. ' +
-            'Handles scope inheritance automatically (e.g. write_orders includes read_orders endpoints).',
+            'Handles scope inheritance automatically (e.g. write_orders includes read_orders endpoints). ' +
+            'MANDATORY before generating any backend code — do not guess which endpoints a scope grants.',
         inputSchema: z.object({
             scopes: z
                 .array(z.string())
@@ -54,10 +76,12 @@ export const docsTools = [
     },
     {
         name: 'validate_api_code',
-        description: 'Anti-hallucination validation layer. Takes generated NestJS controller/service code as a string and validates it against the API schema. ' +
-            'Checks: correct endpoints exist, correct HTTP methods, correct handler names, correct endpoint ordering (controller_order), ' +
-            'and scope access (developer has permission for each endpoint). Returns structured errors with suggestions for fixing. ' +
-            'Call this AFTER generating backend code to verify correctness before writing to disk.',
+        description: 'MANDATORY: Call this tool AFTER generating any NestJS controller/service code and BEFORE writing it to disk. ' +
+            'Anti-hallucination validation layer that checks generated code against the actual API schema. ' +
+            'Checks: correct endpoints exist, correct HTTP methods, correct handler names, correct endpoint ordering, ' +
+            'and scope access (developer has permission for each endpoint). ' +
+            'Returns structured errors with suggestions for fixing. ' +
+            'If validation fails, fix the code based on the errors — do NOT write invalid code to disk.',
         inputSchema: z.object({
             code: z.string().describe('The generated NestJS controller or service code as a string'),
             resource: z.string().describe('Resource name the code is for (e.g. "orders")'),
@@ -70,7 +94,9 @@ export const docsTools = [
     },
     {
         name: 'get_webhook_events',
-        description: 'Returns available webhook events for the Ratio platform. ' +
+        description: 'MANDATORY: Call this tool before answering ANY question about available webhook events, ' +
+            'webhook verification methods, or retry policies. Do NOT guess webhook event names or verification details. ' +
+            'Returns available webhook events for the Ratio platform. ' +
             'Optionally filter by resource (e.g. "orders", "products"). ' +
             'Includes verification method (HMAC-SHA256) and retry policy information.',
         inputSchema: z.object({

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/lookup-docs.d.ts

@@ -0,0 +1,58 @@
+/**
+ * lookup_docs — Unified documentation search tool.
+ *
+ * When the LLM is unsure about any API detail, scope, webhook event, or OAuth flow,
+ * it should call this tool to get grounded, verified information from the actual
+ * documentation schemas. If the information is not found here, the LLM should tell
+ * the user it doesn't have that information rather than guessing.
+ *
+ * Searches across: API references, scopes, webhook events, and OAuth docs.
+ */
+interface SearchResult {
+    source: string;
+    type: 'api_endpoint' | 'scope' | 'webhook_event' | 'oauth' | 'resource';
+    relevance: 'high' | 'medium' | 'low';
+    data: Record<string, unknown>;
+}
+export declare function lookupDocs(input: {
+    query: string;
+    category?: string;
+}): {
+    found: boolean;
+    message: string;
+    suggestion: string;
+    query?: undefined;
+    tokens?: undefined;
+    available_categories?: undefined;
+    available_resources?: undefined;
+    available_scope_resources?: undefined;
+    result_count?: undefined;
+    results?: undefined;
+    _instruction?: undefined;
+} | {
+    found: boolean;
+    query: string;
+    tokens: string[];
+    message: string;
+    suggestion: string;
+    available_categories: string[];
+    available_resources: string[];
+    available_scope_resources: ("orders" | "products" | "customers" | "inventory" | "discounts" | "payments" | "shipping" | "fulfillments" | "draft_orders" | "returns" | "gift_cards" | "analytics" | "channels" | "content" | "files" | "locations" | "themes" | "markets" | "reports" | "locales" | "publications" | "settings" | "webhooks" | "apps")[];
+    result_count?: undefined;
+    results?: undefined;
+    _instruction?: undefined;
+} | {
+    found: boolean;
+    query: string;
+    result_count: number;
+    results: SearchResult[];
+    _instruction: string;
+    message?: undefined;
+    suggestion?: undefined;
+    tokens?: undefined;
+    available_categories?: undefined;
+    available_resources?: undefined;
+    available_scope_resources?: undefined;
+};
+export {};
+//# sourceMappingURL=lookup-docs.d.ts.map

package/dist/tools/lookup-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-docs.d.ts","sourceRoot":"","sources":["../../src/tools/lookup-docs.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,cAAc,GAAG,OAAO,GAAG,eAAe,GAAG,OAAO,GAAG,UAAU,CAAC;IACxE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AA8ID,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2DrE"}

package/dist/tools/lookup-docs.js

@@ -0,0 +1,185 @@
+import { getAvailableResourceFiles, loadResourceSchema, loadWebhooks, loadOAuth } from '../utils/schema-loader.js';
+import { SCOPES_BY_RESOURCE, PRIMARY_RESOURCES, RESOURCE_METADATA } from '@ratio-mcp/shared';
+import { logger } from '../utils/logger.js';
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .replace(/[^a-z0-9_/\s]/g, '')
+        .split(/\s+/)
+        .filter((t) => t.length > 1);
+}
+function matchScore(tokens, text) {
+    const lower = text.toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+        if (lower.includes(token))
+            score++;
+    }
+    return score;
+}
+function searchApiEndpoints(tokens) {
+    const results = [];
+    const resources = getAvailableResourceFiles();
+    for (const resource of resources) {
+        try {
+            const schema = loadResourceSchema(resource);
+            for (const ep of schema.endpoints) {
+                const searchText = `${ep.method} ${ep.path} ${ep.summary || ''} ${ep.description || ''} ${ep.handler_name || ''} ${ep.required_scope || ''}`;
+                const score = matchScore(tokens, searchText);
+                if (score > 0) {
+                    results.push({
+                        source: `api/${resource}`,
+                        type: 'api_endpoint',
+                        relevance: score >= 2 ? 'high' : 'medium',
+                        data: {
+                            method: ep.method,
+                            path: ep.path,
+                            summary: ep.summary,
+                            description: ep.description,
+                            required_scope: ep.required_scope,
+                            handler_name: ep.handler_name,
+                            resource,
+                            query_params: ep.query_params || [],
+                            request_body: ep.request_body || null,
+                            response_schema: ep.response_schema || null,
+                        },
+                    });
+                }
+            }
+        }
+        catch {
+            // Skip resources that fail to load
+        }
+    }
+    return results;
+}
+function searchScopes(tokens) {
+    const results = [];
+    for (const resource of PRIMARY_RESOURCES) {
+        const scopes = SCOPES_BY_RESOURCE[resource] || [];
+        const meta = RESOURCE_METADATA[resource];
+        for (const scope of scopes) {
+            const searchText = `${scope.code} ${scope.label} ${scope.description} ${(scope.use_cases || []).join(' ')} ${resource}`;
+            const score = matchScore(tokens, searchText);
+            if (score > 0) {
+                results.push({
+                    source: `scopes/${resource}`,
+                    type: 'scope',
+                    relevance: score >= 2 ? 'high' : 'medium',
+                    data: {
+                        code: scope.code,
+                        label: scope.label,
+                        description: scope.description,
+                        resource,
+                        use_cases: scope.use_cases,
+                        commonly_paired_with: scope.commonly_paired_with,
+                        codegen_ready: meta?.codegen_ready || false,
+                    },
+                });
+            }
+        }
+    }
+    return results;
+}
+function searchWebhooks(tokens) {
+    const results = [];
+    try {
+        const webhooks = loadWebhooks();
+        for (const event of webhooks.events) {
+            const searchText = `${event.topic} ${event.description} ${event.resource} webhook`;
+            const score = matchScore(tokens, searchText);
+            if (score > 0) {
+                results.push({
+                    source: 'webhooks',
+                    type: 'webhook_event',
+                    relevance: score >= 2 ? 'high' : 'medium',
+                    data: {
+                        topic: event.topic,
+                        description: event.description,
+                        resource: event.resource,
+                        required_scope: event.required_scope,
+                        verification: webhooks.verification,
+                        retry_policy: webhooks.retry_policy,
+                    },
+                });
+            }
+        }
+    }
+    catch {
+        // Skip if webhooks schema fails
+    }
+    return results;
+}
+function searchOAuth(tokens) {
+    const results = [];
+    try {
+        const oauth = loadOAuth();
+        const oauthText = JSON.stringify(oauth).toLowerCase();
+        const score = matchScore(tokens, oauthText);
+        if (score > 0) {
+            results.push({
+                source: 'oauth',
+                type: 'oauth',
+                relevance: score >= 2 ? 'high' : 'medium',
+                data: oauth,
+            });
+        }
+    }
+    catch {
+        // Skip if oauth schema fails
+    }
+    return results;
+}
+export function lookupDocs(input) {
+    const { query, category } = input;
+    logger.info(`[lookup_docs] query="${query}", category="${category || 'all'}"`);
+    const tokens = tokenize(query);
+    if (tokens.length === 0) {
+        return {
+            found: false,
+            message: 'Query is too short or contains no searchable terms.',
+            suggestion: 'Try searching for specific terms like "orders", "OAuth", "webhook", "scope", etc.',
+        };
+    }
+    let results = [];
+    // Search specific category or all
+    if (!category || category === 'api') {
+        results.push(...searchApiEndpoints(tokens));
+    }
+    if (!category || category === 'scopes') {
+        results.push(...searchScopes(tokens));
+    }
+    if (!category || category === 'webhooks') {
+        results.push(...searchWebhooks(tokens));
+    }
+    if (!category || category === 'oauth') {
+        results.push(...searchOAuth(tokens));
+    }
+    // Sort by relevance (high first) then deduplicate
+    results.sort((a, b) => {
+        const order = { high: 0, medium: 1, low: 2 };
+        return order[a.relevance] - order[b.relevance];
+    });
+    // Limit to top 15 results
+    results = results.slice(0, 15);
+    if (results.length === 0) {
+        return {
+            found: false,
+            query,
+            tokens,
+            message: `No documentation found matching "${query}". This information is not available in the platform documentation.`,
+            suggestion: 'Tell the user that this information is not covered in the documentation. Do NOT guess or make up an answer.',
+            available_categories: ['api', 'scopes', 'webhooks', 'oauth'],
+            available_resources: getAvailableResourceFiles(),
+            available_scope_resources: [...PRIMARY_RESOURCES],
+        };
+    }
+    return {
+        found: true,
+        query,
+        result_count: results.length,
+        results,
+        _instruction: 'Use ONLY the data from these results to answer the user. Do NOT add information that is not present here.',
+    };
+}
+//# sourceMappingURL=lookup-docs.js.map

package/dist/tools/lookup-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-docs.js","sourceRoot":"","sources":["../../src/tools/lookup-docs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@ratio-mcp/docs-server",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "type": "module",
   "main": "dist/index.js",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "bin": {
     "ratio-docs-server": "dist/index.js"
   },
-  "scripts": {
-    "build": "tsc && cp -r src/schemas dist/schemas",
-    "dev": "node --loader ts-node/esm src/index.ts",
-    "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@ratio-mcp/shared": "^1.1.0",
-    "zod": "^3.23.0"
+    "zod": "^3.23.0",
+    "@ratio-mcp/shared": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsc && cp -r src/schemas dist/schemas",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
   }
-}
+}