@ratio-mcp-qa/docs-server 1.0.1

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" | "fulfillments" | "draft_orders" | "returns" | "shipping" | "gift_cards" | "analytics" | "channels" | "content" | "files" | "locations" | "themes" | "markets" | "reports" | "locales" | "publications" | "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;AA0ID,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,181 @@
+import { getAvailableResourceFiles, loadResourceSchema, loadWebhooks, loadOAuth } from '../utils/schema-loader.js';
+import { SCOPES_BY_RESOURCE, PRIMARY_RESOURCES, RESOURCE_METADATA } from '@ratio-mcp-qa/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, scopes] of Object.entries(SCOPES_BY_RESOURCE)) {
+        const meta = RESOURCE_METADATA[resource];
+        for (const scope of scopes) {
+            const searchText = `${scope.code} ${scope.label} ${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,
+                        resource,
+                        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/dist/tools/validate-code.d.ts

@@ -0,0 +1,12 @@
+import type { ValidationResult } from '@ratio-mcp-qa/shared';
+/**
+ * validate_api_code — Anti-hallucination layer.
+ * Takes generated NestJS controller/service code as string input, validates against the schema.
+ * Checks: correct endpoints, correct HTTP methods, correct scope annotations, correct handler order.
+ */
+export declare function validateApiCode(input: {
+    code: string;
+    resource: string;
+    scopes: string[];
+}): ValidationResult;
+//# sourceMappingURL=validate-code.d.ts.map

package/dist/tools/validate-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-code.d.ts","sourceRoot":"","sources":["../../src/tools/validate-code.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,sBAAsB,CAAC;AAwB9E;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,gBAAgB,CAgLnB"}

package/dist/tools/validate-code.js

@@ -0,0 +1,185 @@
+import { loadResourceSchema } from '../utils/schema-loader.js';
+/**
+ * Resolve scope inheritance:
+ * - write_X includes read_X
+ * - delete_X includes write_X and read_X
+ * - order-create / order-update / order-cancel include read_orders
+ */
+function resolveInheritedScopes(scopes) {
+    const resolved = new Set(scopes);
+    for (const scope of scopes) {
+        if (scope.startsWith('write_')) {
+            resolved.add(`read_${scope.replace('write_', '')}`);
+        }
+        else if (scope.startsWith('delete_')) {
+            const resource = scope.replace('delete_', '');
+            resolved.add(`write_${resource}`);
+            resolved.add(`read_${resource}`);
+        }
+        else if (['order-create', 'order-update', 'order-cancel'].includes(scope)) {
+            resolved.add('read_orders');
+        }
+    }
+    return resolved;
+}
+/**
+ * validate_api_code — Anti-hallucination layer.
+ * Takes generated NestJS controller/service code as string input, validates against the schema.
+ * Checks: correct endpoints, correct HTTP methods, correct scope annotations, correct handler order.
+ */
+export function validateApiCode(input) {
+    const errors = [];
+    // Load the schema for the resource
+    let schema;
+    try {
+        schema = loadResourceSchema(input.resource);
+    }
+    catch {
+        return {
+            valid: false,
+            errors: [{
+                    type: 'UNKNOWN_ENDPOINT',
+                    message: `Unknown resource: "${input.resource}"`,
+                    suggestion: `Check that a schema file exists for "${input.resource}"`,
+                }],
+        };
+    }
+    // Resolve which scopes the developer has (including inherited by naming convention)
+    const resolvedScopes = resolveInheritedScopes(input.scopes);
+    // Get allowed endpoints based on scopes
+    const allowedEndpoints = schema.endpoints.filter((ep) => resolvedScopes.has(ep.required_scope));
+    const allowedEndpointKeys = new Set(allowedEndpoints.map((ep) => `${ep.method} ${ep.path}`));
+    // Parse code for endpoint patterns
+    // Look for: @Get(), @Post(), @Patch(), @Put(), @Delete() decorators
+    // and method names like getOrders(), createOrder(), etc.
+    const decoratorPattern = /@(Get|Post|Patch|Put|Delete)\s*\(\s*['"`]([^'"`]*)['"`]\s*\)/g;
+    const handlerPattern = /(?:async\s+)?(\w+)\s*\(/g;
+    // Extract decorators (HTTP method + path)
+    const foundEndpoints = [];
+    const lines = input.code.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const decoratorMatch = /@(Get|Post|Patch|Put|Delete)\s*\(\s*['"`]?([^'"`\)]*?)['"`]?\s*\)/.exec(line);
+        if (decoratorMatch) {
+            const method = decoratorMatch[1].toUpperCase();
+            let path = decoratorMatch[2] || '/';
+            // Look for the handler name on the next few lines
+            let handlerName;
+            for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+                const handlerMatch = /(?:async\s+)?(\w+)\s*\(/.exec(lines[j]);
+                if (handlerMatch && !['if', 'for', 'while', 'switch', 'catch'].includes(handlerMatch[1])) {
+                    handlerName = handlerMatch[1];
+                    break;
+                }
+            }
+            foundEndpoints.push({ method, path, line: i + 1, handlerName });
+        }
+    }
+    // Check for @Controller decorator to get base path
+    const controllerMatch = /@Controller\s*\(\s*['"`]([^'"`]*)['"`]\s*\)/.exec(input.code);
+    const basePath = controllerMatch ? controllerMatch[1] : '';
+    // Validate each found endpoint
+    for (const found of foundEndpoints) {
+        // Reconstruct full path
+        const fullPath = basePath
+            ? `/${basePath}/${found.path}`.replace(/\/+/g, '/').replace(/\/$/, '')
+            : found.path;
+        // Normalize path: convert NestJS :param to schema :param format
+        const normalizedPath = fullPath.replace(/:(\w+)/g, ':$1');
+        // Find matching endpoint in schema
+        const schemaEndpoint = schema.endpoints.find((ep) => ep.method === found.method && normalizePath(ep.path) === normalizePath(normalizedPath));
+        if (!schemaEndpoint) {
+            // Check if it's a valid endpoint but wrong method
+            const samePathEndpoint = schema.endpoints.find((ep) => normalizePath(ep.path) === normalizePath(normalizedPath));
+            if (samePathEndpoint) {
+                errors.push({
+                    type: 'WRONG_METHOD',
+                    message: `Line ${found.line}: ${found.method} ${normalizedPath} uses wrong HTTP method`,
+                    suggestion: `Correct method is ${samePathEndpoint.method} ${samePathEndpoint.path}`,
+                });
+            }
+            else {
+                const validEndpoints = schema.endpoints
+                    .filter((ep) => ep.method === found.method)
+                    .map((ep) => `${ep.method} ${ep.path}`);
+                errors.push({
+                    type: 'UNKNOWN_ENDPOINT',
+                    message: `Line ${found.line}: ${found.method} ${normalizedPath} does not exist in the ${input.resource} API`,
+                    suggestion: `Valid ${found.method} endpoints: ${validEndpoints.join(', ') || 'none'}`,
+                });
+            }
+            continue;
+        }
+        // Check scope access
+        if (!allowedEndpointKeys.has(`${schemaEndpoint.method} ${schemaEndpoint.path}`)) {
+            errors.push({
+                type: 'SCOPE_MISMATCH',
+                message: `${schemaEndpoint.handler_name} requires ${schemaEndpoint.required_scope} scope but app only has [${input.scopes.join(', ')}]`,
+                suggestion: `Remove ${schemaEndpoint.handler_name} endpoint or request ${schemaEndpoint.required_scope} scope`,
+            });
+        }
+        // Check handler name
+        if (found.handlerName && found.handlerName !== schemaEndpoint.handler_name) {
+            errors.push({
+                type: 'WRONG_HANDLER_NAME',
+                message: `Line ${found.line}: Handler "${found.handlerName}" should be "${schemaEndpoint.handler_name}"`,
+                suggestion: `Rename to "${schemaEndpoint.handler_name}" to match the API convention`,
+            });
+        }
+    }
+    // Check endpoint ordering
+    const orderedEndpoints = foundEndpoints
+        .map((found) => {
+        const fullPath = basePath
+            ? `/${basePath}/${found.path}`.replace(/\/+/g, '/').replace(/\/$/, '')
+            : found.path;
+        const normalizedPath = fullPath.replace(/:(\w+)/g, ':$1');
+        const schemaEp = schema.endpoints.find((ep) => ep.method === found.method && normalizePath(ep.path) === normalizePath(normalizedPath));
+        return schemaEp ? { ...found, controller_order: schemaEp.controller_order, schema_handler: schemaEp.handler_name } : null;
+    })
+        .filter(Boolean);
+    for (let i = 1; i < orderedEndpoints.length; i++) {
+        if (orderedEndpoints[i].controller_order < orderedEndpoints[i - 1].controller_order) {
+            errors.push({
+                type: 'WRONG_ORDER',
+                message: `${orderedEndpoints[i].schema_handler} (order: ${orderedEndpoints[i].controller_order}) appears before ${orderedEndpoints[i - 1].schema_handler} (order: ${orderedEndpoints[i - 1].controller_order})`,
+                suggestion: `Endpoints must follow controller_order: ${allowedEndpoints.sort((a, b) => a.controller_order - b.controller_order).map((e) => e.handler_name).join(' → ')}`,
+            });
+        }
+    }
+    // Check for missing endpoints (that the scopes would allow)
+    for (const allowed of allowedEndpoints) {
+        const found = foundEndpoints.some((f) => {
+            const fullPath = basePath
+                ? `/${basePath}/${f.path}`.replace(/\/+/g, '/').replace(/\/$/, '')
+                : f.path;
+            return f.method === allowed.method && normalizePath(fullPath) === normalizePath(allowed.path);
+        });
+        if (!found) {
+            errors.push({
+                type: 'MISSING_ENDPOINT',
+                message: `Missing endpoint: ${allowed.method} ${allowed.path} (${allowed.handler_name})`,
+                suggestion: `Add ${allowed.handler_name} handler with @${capitalize(allowed.method.toLowerCase())}() decorator`,
+            });
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        endpoints_validated: foundEndpoints.length,
+    };
+}
+/**
+ * Normalize a path for comparison (remove leading/trailing slashes, normalize params)
+ */
+function normalizePath(path) {
+    return path
+        .replace(/^\/+|\/+$/g, '')
+        .replace(/\{(\w+)\}/g, ':$1') // Convert {id} to :id
+        .replace(/:(\w+)/g, ':$1')
+        .toLowerCase();
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//# sourceMappingURL=validate-code.js.map

package/dist/tools/validate-code.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Logger that writes to BOTH stderr (for MCP protocol) AND a persistent log file.
+ * The log file is stored in the mcp-v2 root so you can review the full flow after testing.
+ */
+declare const LOG_FILE: string;
+export declare const logger: {
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
+    toolCall: (toolName: string, input: unknown) => void;
+    toolResult: (toolName: string, durationMs: number, result: unknown) => void;
+    toolError: (toolName: string, durationMs: number, error: unknown) => void;
+};
+export { LOG_FILE };
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,QAAA,MAAM,QAAQ,QAAoC,CAAC;AAiCnD,eAAO,MAAM,MAAM;oBACD,MAAM,WAAW,OAAO,EAAE;oBAK1B,MAAM,WAAW,OAAO,EAAE;qBAKzB,MAAM,WAAW,OAAO,EAAE;qBAK1B,MAAM,WAAW,OAAO,EAAE;yBAQtB,MAAM,SAAS,OAAO;2BAMpB,MAAM,cAAc,MAAM,UAAU,OAAO;0BAM5C,MAAM,cAAc,MAAM,SAAS,OAAO;CAOjE,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,85 @@
+/**
+ * Logger that writes to BOTH stderr (for MCP protocol) AND a persistent log file.
+ * The log file is stored in the mcp-v2 root so you can review the full flow after testing.
+ */
+import { appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Log file lives in ratio-mcp-v2/logs/docs-server.log
+const LOGS_DIR = resolve(__dirname, '..', '..', '..', '..', 'logs');
+const LOG_FILE = join(LOGS_DIR, 'docs-server.log');
+try {
+    if (!existsSync(LOGS_DIR)) {
+        mkdirSync(LOGS_DIR, { recursive: true });
+    }
+}
+catch { /* ignore */ }
+function timestamp() {
+    return new Date().toISOString();
+}
+function writeToFile(line) {
+    try {
+        if (!existsSync(LOGS_DIR)) {
+            mkdirSync(LOGS_DIR, { recursive: true });
+        }
+        appendFileSync(LOG_FILE, line + '\n', 'utf-8');
+    }
+    catch { /* swallow */ }
+}
+function safeStringify(obj, maxLen = 4000) {
+    try {
+        const str = JSON.stringify(obj);
+        if (str && str.length > maxLen) {
+            return str.substring(0, maxLen) + `...[truncated, total ${str.length} chars]`;
+        }
+        return str || '';
+    }
+    catch {
+        return String(obj);
+    }
+}
+export const logger = {
+    info: (message, ...args) => {
+        const line = `[ratio-docs] ${timestamp()} INFO: ${message}${args.length ? ' ' + args.map(a => safeStringify(a)).join(' ') : ''}`;
+        console.error(line);
+        writeToFile(line);
+    },
+    warn: (message, ...args) => {
+        const line = `[ratio-docs] ${timestamp()} WARN: ${message}${args.length ? ' ' + args.map(a => safeStringify(a)).join(' ') : ''}`;
+        console.error(line);
+        writeToFile(line);
+    },
+    error: (message, ...args) => {
+        const line = `[ratio-docs] ${timestamp()} ERROR: ${message}${args.length ? ' ' + args.map(a => safeStringify(a)).join(' ') : ''}`;
+        console.error(line);
+        writeToFile(line);
+    },
+    debug: (message, ...args) => {
+        const line = `[ratio-docs] ${timestamp()} DEBUG: ${message}${args.length ? ' ' + args.map(a => safeStringify(a)).join(' ') : ''}`;
+        if (process.env.DEBUG) {
+            console.error(line);
+        }
+        writeToFile(line);
+    },
+    toolCall: (toolName, input) => {
+        const line = `[ratio-docs] ${timestamp()} TOOL_CALL: ▶ ${toolName} | input: ${safeStringify(input)}`;
+        console.error(line);
+        writeToFile(line);
+    },
+    toolResult: (toolName, durationMs, result) => {
+        const line = `[ratio-docs] ${timestamp()} TOOL_RESULT: ✓ ${toolName} | ${durationMs}ms | output: ${safeStringify(result)}`;
+        console.error(line);
+        writeToFile(line);
+    },
+    toolError: (toolName, durationMs, error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        const stack = error instanceof Error ? error.stack : '';
+        const line = `[ratio-docs] ${timestamp()} TOOL_ERROR: ✗ ${toolName} | ${durationMs}ms | error: ${message}${stack ? `\n  STACK: ${stack}` : ''}`;
+        console.error(line);
+        writeToFile(line);
+    },
+};
+export { LOG_FILE };
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/dist/utils/schema-loader.d.ts

@@ -0,0 +1,13 @@
+import type { ResourceSchema, WebhooksSchema, OAuthSchema } from '@ratio-mcp-qa/shared';
+export declare function loadResourceSchema(resource: string): ResourceSchema;
+export declare function loadWebhooks(): WebhooksSchema;
+export declare function loadOAuth(): OAuthSchema;
+/**
+ * Get list of available resource schema files (excludes oauth.json and webhooks.json)
+ */
+export declare function getAvailableResourceFiles(): string[];
+/**
+ * Clear the cache (useful for testing)
+ */
+export declare function clearCache(): void;
+//# sourceMappingURL=schema-loader.d.ts.map

package/dist/utils/schema-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-loader.d.ts","sourceRoot":"","sources":["../../src/utils/schema-loader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAgCxF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAEnE;AAED,wBAAgB,YAAY,IAAI,cAAc,CAE7C;AAED,wBAAgB,SAAS,IAAI,WAAW,CAEvC;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CASpD;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}