@ratio-mcp-sandbox/docs-server 1.0.0

package/dist/server.js

@@ -0,0 +1,87 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { DOCS_SERVER_NAME, DOCS_SERVER_VERSION } from '@ratio-mcp-sandbox/shared';
+import { docsTools } from './tools/index.js';
+import { logger } from './utils/logger.js';
+const DOCS_SERVER_INSTRUCTIONS = `You are connected to the Ratio Docs MCP Server — the authoritative reference for the Ratio/OpenStore platform API.
+
+PLATFORM TERMINOLOGY (IMPORTANT):
+On the Ratio platform, developers build "apps" (also called "applications") that merchants install on their stores. Users may refer to these as:
+- "agent" / "agents" → same as app / apps
+- "bot" / "bots" → same as app / apps
+- "integration" / "integrations" → same as app / apps
+- "plugin" / "plugins" → same as app / apps
+- "extension" / "extensions" → same as app / apps
+
+When the developer says "I want to create an agent" or "build a bot", they mean "create an app on Ratio". Do NOT tell them "Ratio doesn't have agents" — translate their terminology to "app" and guide them through the dev-server tools (developer_login → create_app → gather_requirements → etc.).
+
+CRITICAL RULES:
+1. ALWAYS use these tools BEFORE answering any question about the Ratio platform API, scopes, webhooks, or endpoints. NEVER answer from memory.
+2. If lookup_docs returns found=false, tell the user the information is not available. NEVER guess or hallucinate.
+3. ALWAYS call validate_api_code after generating any code that calls Ratio APIs, before presenting it to the developer.
+4. ALWAYS call get_available_scopes before answering scope-related questions.
+5. ALWAYS call get_api_reference before answering API endpoint questions.
+6. ALWAYS call get_webhook_events before answering webhook questions.
+
+TOOL USAGE:
+- lookup_docs: Unified search across all documentation. Use as the MANDATORY fallback when unsure about ANY platform detail. Understands aliases like agent, bot, integration, plugin (all map to "app").
+- get_available_scopes: Returns all 78 resources with their scopes. Use before discussing scope selection.
+- get_api_reference: Returns endpoints for a specific resource. Use before generating or discussing API calls.
+- get_scope_endpoint_map: Maps scopes to their endpoints. Use before code generation.
+- validate_api_code: Validates generated NestJS code against real API schemas. Use AFTER code generation.
+- get_webhook_events: Returns webhook event topics and verification details. Use before discussing webhooks.
+
+These tools exist to PREVENT hallucination. The Ratio platform has specific APIs, scopes, and patterns — do not assume you know them. Always verify.
+
+CROSS-SERVER RULE:
+When the user asks about the Ratio platform in a general / info-seeking way — "what is Ratio", "how does Ratio work", "what can I build on Ratio", "how do I get started" — your FIRST action is to call ratio-mcp-dev's get_app_lifecycle. That returns the onboarding journey map. The docs-server answers specific API / scope / webhook questions; the dev-server's lifecycle answers "how do I get started". Use both servers together — don't answer general platform questions from memory.`;
+/**
+ * Create and configure the Ratio Docs MCP Server
+ */
+export function createDocsServer() {
+    const server = new McpServer({
+        name: DOCS_SERVER_NAME,
+        version: DOCS_SERVER_VERSION,
+    }, {
+        instructions: DOCS_SERVER_INSTRUCTIONS,
+    });
+    // Register all tools
+    for (const tool of docsTools) {
+        // Pass Zod shape directly — MCP SDK handles Zod-to-JSON conversion internally
+        const shape = tool.inputSchema.shape;
+        server.tool(tool.name, tool.description, shape, async (args) => {
+            logger.toolCall(tool.name, args);
+            const startTime = Date.now();
+            try {
+                const result = tool.handler(args);
+                const duration = Date.now() - startTime;
+                logger.toolResult(tool.name, duration, result);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                logger.toolError(tool.name, duration, error);
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: true, message }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+        logger.debug(`Registered tool: ${tool.name}`);
+    }
+    logger.info(`${DOCS_SERVER_NAME} initialized with ${docsTools.length} tools`);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;meA+Bkc,CAAC;AAEpe;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,mBAAmB;KAC7B,EACD;QACE,YAAY,EAAE,wBAAwB;KACvC,CACF,CAAC;IAEF,qBAAqB;IACrB,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,8EAA8E;QAC9E,MAAM,KAAK,GAAI,IAAI,CAAC,WAA0C,CAAC,KAAK,CAAC;QAErE,MAAM,CAAC,IAAI,CACT,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,WAAW,EAChB,KAAK,EACL,KAAK,EAAE,IAA6B,EAAE,EAAE;YACtC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACjC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAE7B,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;gBACxC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAE/C,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;yBACtC;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;gBACxC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAE7C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;yBACxD;qBACF;oBACD,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;QAEF,MAAM,CAAC,KAAK,CAAC,oBAAoB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,GAAG,gBAAgB,qBAAqB,SAAS,CAAC,MAAM,QAAQ,CAAC,CAAC;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/get-api-reference.d.ts

@@ -0,0 +1,60 @@
+/**
+ * get_api_reference — Returns complete API reference for a resource.
+ * Optionally filters by scope to show only endpoints accessible with that scope.
+ */
+export declare function getApiReference(input: {
+    resource: string;
+    scope_filter?: string;
+}): {
+    error: boolean;
+    message: string;
+    available_resources: string[];
+    available_scopes?: undefined;
+    resource?: undefined;
+    base_url?: undefined;
+    auth?: undefined;
+    endpoint_count?: undefined;
+    endpoints?: undefined;
+    schemas?: undefined;
+    statuses?: undefined;
+    scope_filter_applied?: undefined;
+} | {
+    error: boolean;
+    message: string;
+    available_scopes: string[];
+    available_resources?: undefined;
+    resource?: undefined;
+    base_url?: undefined;
+    auth?: undefined;
+    endpoint_count?: undefined;
+    endpoints?: undefined;
+    schemas?: undefined;
+    statuses?: undefined;
+    scope_filter_applied?: undefined;
+} | {
+    resource: string;
+    base_url: string;
+    auth: Record<string, string> | undefined;
+    endpoint_count: number;
+    endpoints: {
+        method: string;
+        path: string;
+        controller_order: number;
+        handler_name: string;
+        required_scope: string;
+        summary: string;
+        description: string | undefined;
+        query_params: import("@ratio-mcp-sandbox/shared").EndpointParam[];
+        path_params: import("@ratio-mcp-sandbox/shared").EndpointParam[];
+        request_body: Record<string, unknown> | null;
+        response_schema: string | null;
+    }[];
+    schemas: Record<string, unknown>;
+    statuses: string[];
+    scope_filter_applied: string | null;
+    error?: undefined;
+    message?: undefined;
+    available_resources?: undefined;
+    available_scopes?: undefined;
+};
+//# sourceMappingURL=get-api-reference.d.ts.map

package/dist/tools/get-api-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-api-reference.d.ts","sourceRoot":"","sources":["../../src/tools/get-api-reference.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoDjF"}

package/dist/tools/get-api-reference.js

@@ -0,0 +1,53 @@
+import { loadResourceSchema, getAvailableResourceFiles } from '../utils/schema-loader.js';
+/**
+ * get_api_reference — Returns complete API reference for a resource.
+ * Optionally filters by scope to show only endpoints accessible with that scope.
+ */
+export function getApiReference(input) {
+    const availableResources = getAvailableResourceFiles();
+    if (!availableResources.includes(input.resource)) {
+        return {
+            error: true,
+            message: `Unknown resource: "${input.resource}"`,
+            available_resources: availableResources,
+        };
+    }
+    const schema = loadResourceSchema(input.resource);
+    let endpoints = schema.endpoints;
+    // Filter by scope if provided
+    if (input.scope_filter) {
+        endpoints = endpoints.filter((ep) => ep.required_scope === input.scope_filter);
+        if (endpoints.length === 0) {
+            return {
+                error: true,
+                message: `No endpoints found for scope "${input.scope_filter}" in resource "${input.resource}"`,
+                available_scopes: [...new Set(schema.endpoints.map((ep) => ep.required_scope))],
+            };
+        }
+    }
+    // Sort by controller_order
+    endpoints = [...endpoints].sort((a, b) => a.controller_order - b.controller_order);
+    return {
+        resource: schema.resource,
+        base_url: schema.base_url,
+        auth: schema.auth,
+        endpoint_count: endpoints.length,
+        endpoints: endpoints.map((ep) => ({
+            method: ep.method,
+            path: ep.path,
+            controller_order: ep.controller_order,
+            handler_name: ep.handler_name,
+            required_scope: ep.required_scope,
+            summary: ep.summary,
+            description: ep.description,
+            query_params: ep.query_params || [],
+            path_params: ep.path_params || [],
+            request_body: ep.request_body || null,
+            response_schema: ep.response_schema || null,
+        })),
+        schemas: schema.schemas,
+        statuses: schema.statuses || [],
+        scope_filter_applied: input.scope_filter || null,
+    };
+}
+//# sourceMappingURL=get-api-reference.js.map

package/dist/tools/get-api-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-api-reference.js","sourceRoot":"","sources":["../../src/tools/get-api-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAE1F;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkD;IAChF,MAAM,kBAAkB,GAAG,yBAAyB,EAAE,CAAC;IAEvD,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjD,OAAO;YACL,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,sBAAsB,KAAK,CAAC,QAAQ,GAAG;YAChD,mBAAmB,EAAE,kBAAkB;SACxC,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAElD,IAAI,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IAEjC,8BAA8B;IAC9B,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACvB,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,cAAc,KAAK,KAAK,CAAC,YAAY,CAAC,CAAC;QAC/E,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO,EAAE,iCAAiC,KAAK,CAAC,YAAY,kBAAkB,KAAK,CAAC,QAAQ,GAAG;gBAC/F,gBAAgB,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;aAChF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,SAAS,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAEnF,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,cAAc,EAAE,SAAS,CAAC,MAAM;QAChC,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAChC,MAAM,EAAE,EAAE,CAAC,MAAM;YACjB,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,gBAAgB,EAAE,EAAE,CAAC,gBAAgB;YACrC,YAAY,EAAE,EAAE,CAAC,YAAY;YAC7B,cAAc,EAAE,EAAE,CAAC,cAAc;YACjC,OAAO,EAAE,EAAE,CAAC,OAAO;YACnB,WAAW,EAAE,EAAE,CAAC,WAAW;YAC3B,YAAY,EAAE,EAAE,CAAC,YAAY,IAAI,EAAE;YACnC,WAAW,EAAE,EAAE,CAAC,WAAW,IAAI,EAAE;YACjC,YAAY,EAAE,EAAE,CAAC,YAAY,IAAI,IAAI;YACrC,eAAe,EAAE,EAAE,CAAC,eAAe,IAAI,IAAI;SAC5C,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;QAC/B,oBAAoB,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;KACjD,CAAC;AACJ,CAAC"}

package/dist/tools/get-scope-map.d.ts

@@ -0,0 +1,17 @@
+import type { ScopeEndpointMapping } from '@ratio-mcp-sandbox/shared';
+/**
+ * get_scope_endpoint_map — Given a list of scopes, returns exactly which endpoints
+ * are unlocked, in controller_order. This is what the codegen reads before generating routes.
+ *
+ * Works by scanning resource schema files and matching endpoints by required_scope.
+ */
+export declare function getScopeEndpointMap(input: {
+    scopes: string[];
+}): {
+    requested_scopes: string[];
+    resolved_scopes: string[];
+    total_endpoints: number;
+    mappings: ScopeEndpointMapping[];
+    _instruction: string;
+};
+//# sourceMappingURL=get-scope-map.d.ts.map

package/dist/tools/get-scope-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-scope-map.d.ts","sourceRoot":"","sources":["../../src/tools/get-scope-map.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AA6BtE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE;;;;;;EAgF9D"}

package/dist/tools/get-scope-map.js

@@ -0,0 +1,102 @@
+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
+ *   (these are custom scopes that don't follow the write_X pattern)
+ */
+function resolveInheritedScopes(scopes) {
+    const resolved = new Set(scopes);
+    for (const scope of scopes) {
+        if (scope.startsWith('write_')) {
+            const resource = scope.replace('write_', '');
+            resolved.add(`read_${resource}`);
+        }
+        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)) {
+            // Custom order scopes inherit read_orders
+            resolved.add('read_orders');
+        }
+    }
+    return resolved;
+}
+/**
+ * get_scope_endpoint_map — Given a list of scopes, returns exactly which endpoints
+ * are unlocked, in controller_order. This is what the codegen reads before generating routes.
+ *
+ * Works by scanning resource schema files and matching endpoints by required_scope.
+ */
+export function getScopeEndpointMap(input) {
+    const result = [];
+    // Resolve scope inheritance
+    const resolvedScopes = resolveInheritedScopes(input.scopes);
+    // Determine which resources to scan based on scope names
+    // Scope format: read_orders → resource "orders", write_products → resource "products"
+    const resourceNames = new Set();
+    for (const scope of resolvedScopes) {
+        // Extract resource name by removing the prefix (read_, write_, delete_, or custom like order-create)
+        const match = scope.match(/^(?:read_|write_|delete_)(.+)$/);
+        if (match) {
+            resourceNames.add(match[1]);
+        }
+        else {
+            // For custom scopes like "order-create", try to extract resource from the scope code
+            const parts = scope.split(/[-_]/);
+            if (parts.length > 0) {
+                resourceNames.add(parts[0]);
+                // Also try plural form
+                resourceNames.add(parts[0] + 's');
+            }
+        }
+    }
+    // Group endpoints by resource
+    const endpointsByResource = new Map();
+    for (const resourceName of resourceNames) {
+        try {
+            const resourceSchema = loadResourceSchema(resourceName);
+            const matchingEndpoints = resourceSchema.endpoints
+                .filter((ep) => resolvedScopes.has(ep.required_scope))
+                .map((ep) => ({
+                method: ep.method,
+                path: ep.path,
+                controller_order: ep.controller_order,
+                handler_name: ep.handler_name,
+                summary: ep.summary,
+                required_scope: ep.required_scope,
+            }));
+            if (matchingEndpoints.length > 0) {
+                const existing = endpointsByResource.get(resourceName) || [];
+                existing.push(...matchingEndpoints);
+                endpointsByResource.set(resourceName, existing);
+            }
+        }
+        catch {
+            // Resource schema file not found — skip
+        }
+    }
+    // Build result sorted by controller_order within each resource
+    for (const [resourceName, endpoints] of endpointsByResource) {
+        const sorted = endpoints.sort((a, b) => a.controller_order - b.controller_order);
+        result.push({
+            scope: input.scopes.filter((s) => {
+                const match = s.match(/^(?:read_|write_|delete_)(.+)$/);
+                return match && match[1] === resourceName;
+            }).join(', '),
+            resource: resourceName,
+            endpoints: sorted,
+        });
+    }
+    return {
+        requested_scopes: input.scopes,
+        resolved_scopes: [...resolvedScopes],
+        total_endpoints: result.reduce((sum, r) => sum + r.endpoints.length, 0),
+        mappings: result,
+        _instruction: 'Use these endpoints in controller_order for deterministic code generation.',
+    };
+}
+//# sourceMappingURL=get-scope-map.js.map

package/dist/tools/get-scope-map.js.map

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

package/dist/tools/get-scopes.d.ts

@@ -0,0 +1,63 @@
+/**
+ * get_available_scopes — Returns all available scopes grouped by primary resource.
+ * Returns all scopes from the platform grouped by resource.
+ * Data sourced from GET /api/v1/scopes — all 147 scopes across 78 resources.
+ */
+export declare function getAvailableScopes(input: {
+    resource?: string;
+}): {
+    error: boolean;
+    message: string;
+    available_resources: string[];
+    resource?: undefined;
+    resource_info?: undefined;
+    scopes?: undefined;
+    total?: undefined;
+    total_resources?: undefined;
+    total_scopes?: undefined;
+    resources?: undefined;
+    _instruction?: undefined;
+} | {
+    resource: string;
+    resource_info: {
+        description: string;
+        codegen_ready: boolean;
+        commonly_needed_with: string[] | undefined;
+        example_app_types: string[] | undefined;
+    } | undefined;
+    scopes: {
+        code: string;
+        label: string;
+    }[];
+    total: number;
+    error?: undefined;
+    message?: undefined;
+    available_resources?: undefined;
+    total_resources?: undefined;
+    total_scopes?: undefined;
+    resources?: undefined;
+    _instruction?: undefined;
+} | {
+    total_resources: number;
+    total_scopes: number;
+    resources: {
+        resource: string;
+        description: string;
+        codegen_ready: boolean;
+        is_primary: boolean;
+        scopes: {
+            code: string;
+            label: string;
+        }[];
+        count: number;
+    }[];
+    _instruction: string;
+    error?: undefined;
+    message?: undefined;
+    available_resources?: undefined;
+    resource?: undefined;
+    resource_info?: undefined;
+    scopes?: undefined;
+    total?: undefined;
+};
+//# sourceMappingURL=get-scopes.d.ts.map

package/dist/tools/get-scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-scopes.d.ts","sourceRoot":"","sources":["../../src/tools/get-scopes.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqE9D"}

package/dist/tools/get-scopes.js

@@ -0,0 +1,72 @@
+import { SCOPES_BY_RESOURCE, PRIMARY_RESOURCES, RESOURCE_METADATA, getAllResources } from '@ratio-mcp-sandbox/shared';
+/**
+ * get_available_scopes — Returns all available scopes grouped by primary resource.
+ * Returns all scopes from the platform grouped by resource.
+ * Data sourced from GET /api/v1/scopes — all 147 scopes across 78 resources.
+ */
+export function getAvailableScopes(input) {
+    if (input.resource) {
+        const resourceScopes = SCOPES_BY_RESOURCE[input.resource];
+        const resourceMeta = RESOURCE_METADATA[input.resource];
+        if (!resourceScopes) {
+            return {
+                error: true,
+                message: `Unknown resource: "${input.resource}"`,
+                available_resources: getAllResources(),
+            };
+        }
+        return {
+            resource: input.resource,
+            resource_info: resourceMeta
+                ? {
+                    description: resourceMeta.description,
+                    codegen_ready: resourceMeta.codegen_ready,
+                    commonly_needed_with: resourceMeta.commonly_needed_with,
+                    example_app_types: resourceMeta.example_app_types,
+                }
+                : undefined,
+            scopes: resourceScopes.map((s) => ({
+                code: s.code,
+                label: s.label,
+            })),
+            total: resourceScopes.length,
+        };
+    }
+    // Return ALL resources with their scopes — primary resources first with metadata, then the rest
+    const allResourceNames = getAllResources();
+    const primarySet = new Set(PRIMARY_RESOURCES);
+    const resources = allResourceNames.map((resourceName) => {
+        const scopes = SCOPES_BY_RESOURCE[resourceName] || [];
+        const meta = RESOURCE_METADATA[resourceName];
+        return {
+            resource: resourceName,
+            description: meta?.description || '',
+            codegen_ready: meta?.codegen_ready || false,
+            is_primary: primarySet.has(resourceName),
+            scopes: scopes.map((s) => ({
+                code: s.code,
+                label: s.label,
+            })),
+            count: scopes.length,
+        };
+    })
+        // Sort: primary resources first, then alphabetical
+        .sort((a, b) => {
+        if (a.is_primary && !b.is_primary)
+            return -1;
+        if (!a.is_primary && b.is_primary)
+            return 1;
+        return a.resource.localeCompare(b.resource);
+    });
+    return {
+        total_resources: resources.length,
+        total_scopes: resources.reduce((sum, r) => sum + r.count, 0),
+        resources,
+        _instruction: 'These are ALL scopes available on the platform (sourced from the real API). ' +
+            'Primary resources are listed first — these are the most commonly needed. ' +
+            'codegen_ready=true means generate_api_routes can auto-generate backend code for that resource. ' +
+            'Present the scopes to the developer grouped by resource. Let them pick what they need. ' +
+            'After selecting scopes, call define_app_requirements with confirmed=false for preview, then confirmed=true.',
+    };
+}
+//# sourceMappingURL=get-scopes.js.map

package/dist/tools/get-scopes.js.map

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

package/dist/tools/get-webhooks.d.ts

@@ -0,0 +1,30 @@
+/**
+ * get_webhook_events — Returns available webhook events, optionally filtered by resource.
+ */
+export declare function getWebhookEvents(input: {
+    resource?: string;
+}): {
+    error: boolean;
+    message: string;
+    available_resources: string[];
+    total_events?: undefined;
+    verification?: undefined;
+    retry_policy?: undefined;
+    events?: undefined;
+    resource_filter?: undefined;
+} | {
+    total_events: number;
+    verification: Record<string, string> | undefined;
+    retry_policy: Record<string, unknown> | undefined;
+    events: {
+        topic: string;
+        description: string;
+        resource: string;
+        required_scope: string | null | undefined;
+    }[];
+    resource_filter: string | null;
+    error?: undefined;
+    message?: undefined;
+    available_resources?: undefined;
+};
+//# sourceMappingURL=get-webhooks.d.ts.map

package/dist/tools/get-webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-webhooks.d.ts","sourceRoot":"","sources":["../../src/tools/get-webhooks.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;EA6B5D"}

package/dist/tools/get-webhooks.js

@@ -0,0 +1,32 @@
+import { loadWebhooks } from '../utils/schema-loader.js';
+/**
+ * get_webhook_events — Returns available webhook events, optionally filtered by resource.
+ */
+export function getWebhookEvents(input) {
+    const webhooks = loadWebhooks();
+    let events = webhooks.events;
+    if (input.resource) {
+        events = events.filter((e) => e.resource === input.resource);
+        if (events.length === 0) {
+            const availableResources = [...new Set(webhooks.events.map((e) => e.resource))];
+            return {
+                error: true,
+                message: `No webhook events found for resource: "${input.resource}"`,
+                available_resources: availableResources,
+            };
+        }
+    }
+    return {
+        total_events: events.length,
+        verification: webhooks.verification,
+        retry_policy: webhooks.retry_policy,
+        events: events.map((e) => ({
+            topic: e.topic,
+            description: e.description,
+            resource: e.resource,
+            required_scope: e.required_scope,
+        })),
+        resource_filter: input.resource || null,
+    };
+}
+//# sourceMappingURL=get-webhooks.js.map

package/dist/tools/get-webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-webhooks.js","sourceRoot":"","sources":["../../src/tools/get-webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAEhC,IAAI,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAE7B,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAChF,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,OAAO,EAAE,0CAA0C,KAAK,CAAC,QAAQ,GAAG;gBACpE,mBAAmB,EAAE,kBAAkB;aACxC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,MAAM;QAC3B,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,cAAc,EAAE,CAAC,CAAC,cAAc;SACjC,CAAC,CAAC;QACH,eAAe,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;KACxC,CAAC;AACJ,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+/**
+ * Tool definition for MCP registration
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType;
+    handler: (input: Record<string, unknown>) => unknown;
+}
+/**
+ * All docs-server tools (6 tools)
+ */
+export declare const docsTools: ToolDefinition[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"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,EAyGrC,CAAC"}