@ratio-mcp/dev-server 1.0.0 → 1.1.0

package/dist/tools/agent-chat.js

@@ -0,0 +1,379 @@
+import { z } from 'zod';
+import { allDevTools } from './index.js';
+import { getNextStep, getCurrentPhase, canSkipPhase, } from '../services/orchestrator.js';
+import { getSession, recordToolSuccess, resetSession, } from '../services/session-state.js';
+import { formatSuccess, formatInputNeeded, formatError, formatComplete, } from '../services/response-formatter.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Input schema for the agent-chat tool.
+ * This is the single unified tool that replaces all 24+ individual tools.
+ */
+const agentChatSchema = z.object({
+    message: z.string().describe('The user message or intent. Can be natural language like "I want to build an order management app" ' +
+        'OR structured input like providing app details. For the very first message, just say what you want to build.'),
+    input_data: z
+        .record(z.unknown())
+        .optional()
+        .describe('Structured input data when the orchestrator requests specific fields. ' +
+        'For example: { "email": "dev@example.com", "password": "pass123" } for login, ' +
+        'or { "name": "My App", "description": "..." } for app creation. ' +
+        'The previous response will tell you exactly which fields are needed.'),
+    action: z
+        .enum(['next', 'skip', 'status', 'reset'])
+        .default('next')
+        .describe('Action to take: "next" = proceed with flow (default), ' +
+        '"skip" = skip current optional phase (only webhooks), ' +
+        '"status" = show current progress without advancing, ' +
+        '"reset" = start over from scratch'),
+});
+/**
+ * Normalize input field names so each tool always receives its canonical fields.
+ *
+ * The LLM can send reasonable variants like "categories" or "categoryIds"
+ * instead of the exact "category_ids" the Zod schema expects.  Instead of
+ * scattering fallback logic in every tool handler, we fix it once here — the
+ * same way the backend DTO enforces a single canonical field via class-validator.
+ *
+ * Rules per tool are explicit and easy to audit.
+ */
+function normalizeToolInput(toolName, args) {
+    const normalized = { ...args };
+    if (toolName === 'create_app' || toolName === 'update_app') {
+        // Canonical field: category_ids (array of slugs)
+        // LLM may send: categories, categoryIds, category_slugs
+        if (!normalized.category_ids) {
+            const value = normalized.categories ??
+                normalized.categoryIds ??
+                normalized.category_slugs;
+            if (value) {
+                normalized.category_ids = value;
+                delete normalized.categories;
+                delete normalized.categoryIds;
+                delete normalized.category_slugs;
+                logger.info(`[normalizeToolInput] Mapped variant field to category_ids for ${toolName}`);
+            }
+        }
+    }
+    if (toolName === 'build_frontend') {
+        // If project_path doesn't contain a package.json but has a /frontend
+        // sub-directory, the scaffold tool returned the parent path — adjust
+        // to point at the actual frontend dir.  This mirrors the backend's
+        // approach of resolving paths at the controller layer.
+        // (Handled at runtime in the tool itself — see build.ts fix.)
+    }
+    return normalized;
+}
+/**
+ * Handler for the unified agent-chat tool.
+ * Orchestrates the entire Ratio app development lifecycle through a single interface.
+ */
+async function handleAgentChat(input) {
+    try {
+        const { message, input_data, action } = input;
+        const inputData = input_data;
+        const actionType = action || 'next';
+        logger.info(`agent-chat: action=${actionType}, hasInputData=${!!inputData}, messageLen=${String(message).length}`);
+        // ─────────────────────────────────────────────────────────────────────
+        // Capture app description from early messages for later use
+        // (e.g., "I want to build an order management app")
+        // ─────────────────────────────────────────────────────────────────────
+        const session = getSession();
+        const msgStr = String(message || '').trim();
+        if (msgStr.length > 10 && !session.context.appDescription) {
+            // Store the developer's initial description — used by gather_requirements
+            session.context.appDescription = msgStr;
+            logger.info(`Captured app description: "${msgStr.substring(0, 80)}..."`);
+        }
+        // Also capture from input_data.description if provided during app creation
+        if (inputData?.description && !session.context.appDescription) {
+            session.context.appDescription = String(inputData.description);
+        }
+        // ─────────────────────────────────────────────────────────────────────
+        // Action: reset
+        // ─────────────────────────────────────────────────────────────────────
+        if (actionType === 'reset') {
+            resetSession();
+            logger.info('Session reset by user');
+            return {
+                message: 'Session reset. Starting fresh! Tell me about the app you want to build.',
+                phase: 'auth',
+                progress: { current: 0, total: 15, percentage: 0 },
+                needsInput: true,
+                inputPrompt: 'What kind of app would you like to build? (e.g., "order management app", "inventory tracking system")',
+                inputFields: ['message'],
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────
+        // Action: status
+        // ─────────────────────────────────────────────────────────────────────
+        if (actionType === 'status') {
+            const currentPhase = getCurrentPhase();
+            const orchestratorResult = getNextStep(inputData);
+            return {
+                message: `Current phase: ${orchestratorResult.phase_description}. ${orchestratorResult.message}`,
+                phase: currentPhase,
+                progress: orchestratorResult.progress,
+                needsInput: orchestratorResult.needsInput,
+                inputPrompt: orchestratorResult.inputPrompt,
+                inputFields: orchestratorResult.inputFields,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────
+        // Action: skip
+        // ─────────────────────────────────────────────────────────────────────
+        if (actionType === 'skip') {
+            const currentPhase = getCurrentPhase();
+            // Check if this phase can be skipped
+            if (!canSkipPhase(currentPhase)) {
+                return {
+                    message: `Cannot skip "${currentPhase}" phase. This phase is required.`,
+                    phase: currentPhase,
+                    progress: { current: 0, total: 15, percentage: 0 },
+                    needsInput: false,
+                    error: `Phase "${currentPhase}" is mandatory and cannot be skipped.`,
+                };
+            }
+            // Mark phase as complete and advance
+            const session = getSession();
+            if (currentPhase === 'webhooks') {
+                session.context.webhooksConfigured = true;
+                recordToolSuccess('skip_webhooks', { skipped: true });
+                logger.info('Webhooks phase skipped');
+            }
+            // Get the next step after skipping
+            const nextOrchestrationResult = getNextStep();
+            if (nextOrchestrationResult.phase === 'complete') {
+                return formatComplete();
+            }
+            return formatInputNeeded(nextOrchestrationResult);
+        }
+        // ─────────────────────────────────────────────────────────────────────
+        // Action: next (main flow)
+        // ─────────────────────────────────────────────────────────────────────
+        if (actionType === 'next') {
+            // Step 1: Get orchestrator guidance
+            const orchestratorResult = getNextStep(inputData);
+            logger.info(`Orchestrator returned phase=${orchestratorResult.phase}, tool=${orchestratorResult.toolToCall}, needsInput=${orchestratorResult.needsInput}`);
+            // Step 2: Check if we're done
+            if (orchestratorResult.phase === 'complete') {
+                logger.info('Application development complete');
+                return formatComplete();
+            }
+            // Step 3: Check if user input is required
+            if (orchestratorResult.needsInput && !inputData) {
+                logger.info(`Input needed for ${orchestratorResult.toolToCall}: fields=${orchestratorResult.inputFields}`);
+                return formatInputNeeded(orchestratorResult);
+            }
+            // Step 4: Execute the tool
+            const toolName = orchestratorResult.toolToCall;
+            let toolArgs = { ...orchestratorResult.toolArgs };
+            logger.info(`[agent-chat] ── TOOL EXECUTION ──`);
+            logger.info(`[agent-chat] Tool: ${toolName}`);
+            logger.info(`[agent-chat] Orchestrator args: ${JSON.stringify(orchestratorResult.toolArgs)}`);
+            // If user provided input, merge it with orchestrator-provided args
+            if (inputData) {
+                logger.info(`[agent-chat] User inputData: ${JSON.stringify(inputData)}`);
+                toolArgs = { ...toolArgs, ...inputData };
+                logger.info(`[agent-chat] Merged args: ${JSON.stringify(toolArgs)}`);
+            }
+            // ── Normalize input field names ──────────────────────────────────
+            toolArgs = normalizeToolInput(toolName, toolArgs);
+            logger.info(`[agent-chat] Normalized args: ${JSON.stringify(toolArgs)}`);
+            // Find the tool from the registry
+            const tool = allDevTools.find((t) => t.name === toolName);
+            if (!tool) {
+                logger.error(`Tool not found: ${toolName}`);
+                return formatError(orchestratorResult, new Error(`Tool "${toolName}" not found in registry`), toolName);
+            }
+            // Validate & apply Zod defaults before executing.
+            // Direct MCP tool calls go through Zod automatically, but agent_chat
+            // bypasses that — so we parse here to ensure .default() values,
+            // type coercions, and validations all apply consistently.
+            let validatedArgs = toolArgs;
+            try {
+                validatedArgs = tool.inputSchema.parse(toolArgs);
+                logger.info(`[agent-chat] Zod validation passed for ${toolName}`);
+            }
+            catch (zodError) {
+                // If Zod rejects the input, log it but still try with raw args
+                // (some tools handle loose input gracefully)
+                logger.warn(`[agent-chat] Zod validation failed for ${toolName}, using raw args: ${zodError instanceof Error ? zodError.message : String(zodError)}`);
+            }
+            // Execute the tool
+            let toolResult;
+            const startTime = Date.now();
+            try {
+                toolResult = await tool.handler(validatedArgs);
+                const duration = Date.now() - startTime;
+                logger.info(`[agent-chat] Tool ${toolName} succeeded in ${duration}ms`);
+                logger.info(`[agent-chat] Tool ${toolName} result keys: ${toolResult ? JSON.stringify(Object.keys(toolResult)) : 'null'}`);
+                logger.debug(`[agent-chat] Tool ${toolName} full result: ${JSON.stringify(toolResult)?.slice(0, 3000)}`);
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                logger.error(`[agent-chat] Tool ${toolName} FAILED in ${duration}ms: ${error instanceof Error ? error.message : String(error)}`);
+                if (error instanceof Error && error.stack) {
+                    logger.error(`[agent-chat] Stack: ${error.stack}`);
+                }
+                return formatError(orchestratorResult, error instanceof Error ? error : new Error(String(error)), toolName);
+            }
+            // Step 5: Check if the tool returned a soft error (error: true in result)
+            const resultObj = toolResult;
+            if (resultObj && resultObj.error === true) {
+                logger.error(`[agent-chat] Tool ${toolName} returned soft error: ${resultObj.message || 'Unknown error'}`);
+                return formatError(orchestratorResult, new Error(String(resultObj.message || `Tool "${toolName}" returned an error`)), toolName);
+            }
+            // Step 6: Record success and get next step
+            logger.info(`[agent-chat] Recording success for ${toolName} and getting next step...`);
+            recordToolSuccess(toolName, toolResult);
+            const nextOrchestrationResult = getNextStep();
+            logger.info(`[agent-chat] Next step after ${toolName}: phase=${nextOrchestrationResult.phase}, tool=${nextOrchestrationResult.toolToCall}`);
+            // Step 6: Check if we're now complete
+            if (nextOrchestrationResult.phase === 'complete') {
+                logger.info('Application development complete after tool execution');
+                return formatComplete();
+            }
+            // Step 7: Return success with what's next
+            const successResponse = formatSuccess(nextOrchestrationResult, toolResult, toolName);
+            logger.info(`Returning success response. Next phase: ${nextOrchestrationResult.phase}`);
+            return successResponse;
+        }
+        // Default fallback (should not reach here with valid action enum)
+        return {
+            message: 'Invalid action. Please use "next", "skip", "status", or "reset".',
+            phase: getCurrentPhase(),
+            progress: { current: 0, total: 15, percentage: 0 },
+            needsInput: false,
+            error: `Unknown action: ${actionType}`,
+        };
+    }
+    catch (error) {
+        logger.error(`Unexpected error in agent-chat: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            message: 'An unexpected error occurred. Please try again or reset the session.',
+            phase: getCurrentPhase(),
+            progress: { current: 0, total: 15, percentage: 0 },
+            needsInput: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * The unified agent-chat tool definition.
+ * This single tool replaces all 24+ individual dev tools by orchestrating them intelligently.
+ */
+export const agentChatTool = {
+    name: 'agent_chat',
+    description: `Unified interface for the entire Ratio app development lifecycle.
+
+This is the SINGLE tool for building Ratio apps from start to finish. Instead of juggling 24+ individual tools, use this one conversational interface.
+
+## The Workflow (9 Phases)
+1. **Authentication** - Log in with your Ratio developer account
+2. **App Setup** - Create your application and select categories
+3. **Requirements** - Define your app's OAuth scopes and API access
+4. **Webhooks** (optional) - Configure webhook subscriptions for real-time events
+5. **Frontend Build** - Scaffold, build, and submit your React frontend
+6. **Review Wait** - Your app goes under admin review
+7. **Publish & OAuth** - Publish your approved app and complete the OAuth flow
+8. **Backend Codegen** - Auto-generate NestJS backend from your scopes
+9. **Complete** - You're done! Your app is live
+
+## How to Use This Tool
+
+### First Message
+Just tell me what you want to build:
+\`\`\`
+{
+  "message": "I want to build an order management app",
+  "action": "next"
+}
+\`\`\`
+
+### When Input is Requested
+I'll ask for specific information. Provide it like this:
+\`\`\`
+{
+  "message": "Your email and password",
+  "input_data": {
+    "email": "dev@example.com",
+    "password": "yourpassword"
+  },
+  "action": "next"
+}
+\`\`\`
+
+### Special Actions
+- **"next"** (default): Proceed with the current step and advance to the next one
+- **"skip"**: Skip the current phase (only webhooks can be skipped; it's optional)
+- **"status"**: Check where you are without advancing
+- **"reset"**: Start completely over from scratch
+
+## Examples
+
+### Start a new app
+\`\`\`
+{
+  "message": "Build a product inventory system",
+  "action": "next"
+}
+\`\`\`
+
+### Provide credentials when asked
+\`\`\`
+{
+  "message": "Logging in",
+  "input_data": {
+    "email": "john@company.com",
+    "password": "mypassword"
+  },
+  "action": "next"
+}
+\`\`\`
+
+### Skip optional webhooks phase
+\`\`\`
+{
+  "message": "Skip webhooks for now",
+  "action": "skip"
+}
+\`\`\`
+
+### Check current progress
+\`\`\`
+{
+  "message": "Where are we?",
+  "action": "status"
+}
+\`\`\`
+
+### Start over
+\`\`\`
+{
+  "message": "Start fresh",
+  "action": "reset"
+}
+\`\`\`
+
+## Response Format
+You'll get back a response with:
+- \`message\` - Status/result description
+- \`phase\` - Your current phase
+- \`progress\` - Percentage of overall completion
+- \`needsInput\` - Whether you need to provide data
+- \`inputPrompt\` - What information is needed (if asking)
+- \`inputFields\` - Which fields to fill
+- \`data\` - Extracted results from the last tool (masked for security)
+
+## Tips
+- Follow the orchestrator's guidance on what's needed next
+- Input fields are always listed in the response
+- Sensitive data (tokens, secrets) is automatically masked in responses
+- If you make a mistake, just provide the correct data on the next call
+- Webhooks are optional; you can configure them later in the dashboard`,
+    inputSchema: agentChatSchema,
+    handler: handleAgentChat,
+};
+// Re-export allDevTools for any code that needs access to the underlying tools
+export { allDevTools };
+//# sourceMappingURL=agent-chat.js.map

package/dist/tools/agent-chat.js.map

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

package/dist/tools/app-management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-management.d.ts","sourceRoot":"","sources":["../../src/tools/app-management.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,kBAAkB,EAAE,cAAc,EA2H9C,CAAC"}
+{"version":3,"file":"app-management.d.ts","sourceRoot":"","sources":["../../src/tools/app-management.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,kBAAkB,EAAE,cAAc,EAsJ9C,CAAC"}

package/dist/tools/app-management.js

@@ -1,15 +1,20 @@
 import { z } from 'zod';
 import { developerApiRequest } from '../api/developer.js';
+import { resolveCategoryIdsToUUIDs } from './reference-data.js';
 import { logger } from '../utils/logger.js';
 export const appManagementTools = [
     {
         name: 'create_app',
-        description: 'Create a new application in the Ratio Developer Dashboard. Returns app_id, client_id, and client_secret.',
+        description: 'Create a new application in the Ratio Developer Dashboard. Returns app_id, client_id, and client_secret. ' +
+            'PREREQUISITES before calling this tool:\n' +
+            '1. Call get_categories and let the developer pick categories\n' +
+            '2. Ask the developer: "Do you have a callback URL for OAuth, or should I use localhost?"\n' +
+            'Only call create_app after both are answered.',
         inputSchema: z.object({
             name: z.string().min(1).max(100).describe('Application name (required)'),
             description: z.string().max(2000).optional().describe('Application description'),
-            category_ids: z.array(z.string()).min(1).describe('Category strings (e.g. ["analytics", "marketing"])'),
-            redirect_uri: z.string().optional().describe('OAuth callback URL'),
+            category_ids: z.array(z.string()).min(1).describe('Category slugs from get_categories (e.g. ["analytics", "marketing"]). MUST call get_categories first to get valid slugs.'),
+            redirect_uri: z.string().default('http://localhost:3000/callback').describe('OAuth callback URL. MUST ask the developer before defaulting. Use http://localhost:3000/callback only if the developer has no preference.'),
             contact_email: z.string().optional().describe('Contact email'),
             tags: z.array(z.string()).optional().describe('Application tags'),
             icon: z.string().optional().describe('Icon URL'),
@@ -17,7 +22,21 @@ export const appManagementTools = [
         handler: async (input) => {
             const inp = input;
             logger.info(`Creating application: ${inp.name}`);
-            const appData = { name: inp.name, categoryIds: inp.category_ids };
+            // Accept category_ids OR common variants (LLM may send different field names).
+            // Primary normalization happens in agent_chat's normalizeToolInput(), but this
+            // fallback covers direct tool calls outside the agent_chat flow.
+            const rawCategories = (inp.category_ids ?? inp.categories ?? inp.category_slugs ?? inp.categoryIds);
+            if (!rawCategories || !Array.isArray(rawCategories) || rawCategories.length === 0) {
+                throw new Error('category_ids is required and must be a non-empty array of category slugs. ' +
+                    'Call get_categories first to see valid slugs, then provide them as category_ids: ["slug1", "slug2"].');
+            }
+            // Resolve category slugs/names to UUIDs (same as update_app)
+            const resolvedCategories = await resolveCategoryIdsToUUIDs(rawCategories);
+            if (resolvedCategories.length === 0) {
+                throw new Error(`None of the provided categories could be resolved: [${rawCategories.join(', ')}]. ` +
+                    'Call get_categories first to see valid category slugs.');
+            }
+            const appData = { name: inp.name, categoryIds: resolvedCategories };
             if (inp.description)
                 appData['description'] = inp.description;
             if (inp.redirect_uri)
@@ -65,12 +84,12 @@ export const appManagementTools = [
     },
     {
         name: 'update_app',
-        description: 'Update an existing application. Only provided fields will be updated.',
+        description: 'Update an existing application. Only provided fields will be updated. Category slugs are auto-resolved to UUIDs.',
         inputSchema: z.object({
             app_id: z.string().min(1).describe('Application ID to update'),
             name: z.string().optional().describe('New name'),
             description: z.string().optional().describe('New description'),
-            category_ids: z.array(z.string()).optional().describe('New categories'),
+            category_ids: z.array(z.string()).optional().describe('Category slugs or UUIDs. Slugs are auto-resolved.'),
             redirect_uri: z.string().optional().describe('New redirect URI'),
             contact_email: z.string().optional().describe('New contact email'),
             tags: z.array(z.string()).optional().describe('New tags'),
@@ -83,8 +102,10 @@ export const appManagementTools = [
                 updateData['name'] = inp.name;
             if (inp.description !== undefined)
                 updateData['description'] = inp.description;
-            if (inp.category_ids !== undefined)
-                updateData['categoryIds'] = inp.category_ids;
+            if (inp.category_ids !== undefined) {
+                const resolved = await resolveCategoryIdsToUUIDs(inp.category_ids);
+                updateData['categoryIds'] = resolved;
+            }
             if (inp.redirect_uri !== undefined)
                 updateData['redirectUri'] = inp.redirect_uri;
             if (inp.contact_email !== undefined)

package/dist/tools/app-management.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/tools/auth.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,SAAS,EAAE,cAAc,EAgLrC,CAAC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/tools/auth.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOjD,eAAO,MAAM,SAAS,EAAE,cAAc,EAiNrC,CAAC"}

package/dist/tools/auth.js

@@ -1,18 +1,28 @@
 import { z } from 'zod';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
 import { requestAuthorization, exchangeCodeForToken, refreshToken } from '../api/oauth.js';
 import { saveToken, getToken, isTokenExpired, writeTokenToScaffoldEnv } from '../store/token-store.js';
 import { getRequirements, getRequirementsByClientId } from '../store/requirements-store.js';
 import { logger } from '../utils/logger.js';
+const DEBUG_LOG = path.join(os.homedir(), 'Desktop', 'ratio-debug.log');
+function debugLog(msg) {
+    fs.appendFileSync(DEBUG_LOG, `[${new Date().toISOString()}] ${msg}\n`);
+}
 export const authTools = [
     {
         name: 'request_auth_code',
         description: 'Request an authorization code for app installation (OAuth Step 1). App must be PUBLISHED first. ' +
-            'Auto-fills scopes from saved requirements if app_id is provided.',
+            'Auto-fills scopes from saved requirements if app_id is provided. ' +
+            'IMPORTANT: Ask the developer if they have a callback URL for OAuth. If they do, use it. ' +
+            'If not, default to http://localhost:3000/callback. The redirect_uri here MUST match ' +
+            'the one used in get_access_token, and should match the redirect_uri set during create_app.',
         inputSchema: z.object({
             app_id: z.string().optional().describe('App ID to auto-fill scopes from requirements'),
             client_id: z.string().min(1).describe('Application Client ID'),
             merchant_id: z.string().min(1).describe('Merchant ID of the store installing the app'),
-            redirect_uri: z.string().describe('Registered redirect URI'),
+            redirect_uri: z.string().default('http://localhost:3000/callback').describe('OAuth callback URL. Ask the developer if they have one, otherwise defaults to http://localhost:3000/callback'),
             scopes: z.array(z.string()).optional().describe('Scopes to request. Auto-filled from requirements if omitted.'),
         }),
         handler: async (input) => {
@@ -33,30 +43,49 @@ export const authTools = [
                 }
             }
             const response = await requestAuthorization({ clientId: client_id, merchantId: merchant_id, redirectUri: redirect_uri, scopes });
-            const { code, redirectUri, expiresAt } = response.data;
+            debugLog(`FULL RESPONSE: ${JSON.stringify(response, null, 2)}`);
+            debugLog(`Raw response keys: ${JSON.stringify(Object.keys(response))}`);
+            debugLog(`response.data type: ${typeof response.data}, value: ${JSON.stringify(response.data)?.slice(0, 500)}`);
+            // The API might return data nested differently — try multiple paths
+            const responseData = response.data || response;
+            const code = responseData.code ?? responseData.authorizationCode ?? responseData.authorization_code ?? response.code;
+            const resolvedRedirectUri = responseData.redirectUri ?? responseData.redirect_uri ?? redirect_uri;
+            const expiresAt = responseData.expiresAt ?? responseData.expires_at;
+            debugLog(`Extracted code: ${code ? String(code).substring(0, 12) + '...' : 'UNDEFINED'}`);
+            debugLog(`Extracted redirectUri: ${resolvedRedirectUri}`);
             return {
                 success: true,
-                message: response.message,
+                message: response.message || 'Authorization code obtained',
                 auth_code: code,
-                redirect_uri: redirectUri,
+                redirect_uri: resolvedRedirectUri,
                 expires_at: expiresAt,
                 warning: 'Auth code expires quickly! Call get_access_token immediately.',
+                _debug: {
+                    responseKeys: Object.keys(response),
+                    hasData: response.data !== undefined,
+                    dataKeys: response.data ? Object.keys(response.data) : [],
+                    rawResponse: JSON.stringify(response).slice(0, 500),
+                },
             };
         },
     },
     {
         name: 'get_access_token',
         description: 'Exchange authorization code for access and refresh tokens (OAuth Step 2). ' +
-            'Saves tokens persistently and auto-injects into backend .env if project is scaffolded.',
+            'Saves tokens persistently and auto-injects into backend .env if project is scaffolded. ' +
+            'IMPORTANT: redirect_uri MUST exactly match the one used in request_auth_code.',
         inputSchema: z.object({
             auth_code: z.string().min(1).describe('Authorization code from request_auth_code'),
             client_id: z.string().min(1).describe('Application Client ID'),
             client_secret: z.string().min(1).describe('Application Client Secret'),
-            redirect_uri: z.string().describe('Redirect URI (must match request_auth_code)'),
+            redirect_uri: z.string().default('http://localhost:3000/callback').describe('Must match the redirect_uri used in request_auth_code'),
         }),
         handler: async (input) => {
             const { auth_code, client_id, client_secret, redirect_uri } = input;
+            logger.info(`[get_access_token] ══ START ══`);
+            logger.info(`[get_access_token] input: client_id=${client_id}, has_client_secret=${!!client_secret}, redirect_uri=${redirect_uri}, auth_code=${auth_code?.substring(0, 12)}...`);
             const tokenData = await exchangeCodeForToken({ code: auth_code, clientId: client_id, clientSecret: client_secret, redirectUri: redirect_uri });
+            logger.info(`[get_access_token] exchangeCodeForToken returned: token_type=${tokenData.token_type}, expires_in=${tokenData.expires_in}, merchant_id=${tokenData.merchant_id}, scope=${tokenData.scope}, has_access_token=${!!tokenData.access_token}, has_refresh_token=${!!tokenData.refresh_token}`);
             const expiresAt = new Date(Date.now() + tokenData.expires_in * 1000);
             const storedToken = {
                 access_token: tokenData.access_token,
@@ -67,15 +96,23 @@ export const authTools = [
                 created_at: new Date().toISOString(),
                 client_id, client_secret, redirect_uri,
             };
+            logger.info(`[get_access_token] Saving token to store with key=${client_id}, scopes=${storedToken.scopes.join(',')}, merchant_id=${storedToken.merchant_id}`);
             saveToken(client_id, storedToken);
+            logger.info(`[get_access_token] Token saved successfully`);
             // Auto-inject into backend .env
             let tokenInjected = false;
+            logger.info(`[get_access_token] Looking up requirements by client_id=${client_id}`);
             const requirements = getRequirementsByClientId(client_id);
+            logger.info(`[get_access_token] requirements found=${!!requirements}, project_path=${requirements?.project_path}`);
             if (requirements?.project_path) {
                 const backendEnvPath = `${requirements.project_path}/backend/.env`;
+                logger.info(`[get_access_token] Auto-injecting token into ${backendEnvPath}`);
                 writeTokenToScaffoldEnv(backendEnvPath, storedToken);
                 tokenInjected = true;
-                logger.info(`Token injected into: ${backendEnvPath}`);
+                logger.info(`[get_access_token] Token injected into: ${backendEnvPath}`);
+            }
+            else {
+                logger.info(`[get_access_token] No project_path in requirements — token NOT auto-injected into backend .env (will be injected when scaffold_backend runs)`);
             }
             return {
                 success: true,