@supermodeltools/mcp-server 0.4.4 → 0.4.6

package/dist/server.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -10,6 +43,29 @@ const sdk_1 = require("@supermodeltools/sdk");
 const create_supermodel_graph_1 = __importDefault(require("./tools/create-supermodel-graph"));
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const zip_repository_1 = require("./utils/zip-repository");
+const undici_1 = require("undici");
+const constants_1 = require("./constants");
+const logger = __importStar(require("./utils/logger"));
+// Configure HTTP timeout for API requests (default from constants)
+// Some complex repos can take 10+ minutes to process
+const parsedTimeout = parseInt(process.env.SUPERMODEL_TIMEOUT_MS || '', 10);
+const TIMEOUT_MS = Number.isFinite(parsedTimeout) && parsedTimeout > 0
+    ? parsedTimeout
+    : constants_1.DEFAULT_API_TIMEOUT_MS;
+const agent = new undici_1.Agent({
+    headersTimeout: TIMEOUT_MS,
+    bodyTimeout: TIMEOUT_MS,
+    connectTimeout: constants_1.CONNECTION_TIMEOUT_MS,
+});
+const fetchWithTimeout = (url, init) => {
+    return fetch(url, {
+        ...init,
+        // @ts-ignore - 'dispatcher' is a valid undici option that TypeScript's
+        // built-in fetch types don't recognize. This routes requests through our
+        // custom Agent with extended timeouts.
+        dispatcher: agent,
+    });
+};
 class Server {
     server;
     client;
@@ -57,10 +113,11 @@ Example:
         const config = new sdk_1.Configuration({
             basePath: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com',
             apiKey: process.env.SUPERMODEL_API_KEY,
+            fetchApi: fetchWithTimeout,
         });
-        console.error('[DEBUG] Server configuration:');
-        console.error('[DEBUG] Base URL:', config.basePath);
-        console.error('[DEBUG] API Key set:', !!process.env.SUPERMODEL_API_KEY);
+        logger.debug('Server configuration:');
+        logger.debug('Base URL:', config.basePath);
+        logger.debug('API Key set:', !!process.env.SUPERMODEL_API_KEY);
         this.client = {
             graphs: new sdk_1.DefaultApi(config),
         };
@@ -82,11 +139,10 @@ Example:
     }
     async start() {
         // Clean up any stale ZIP files from previous sessions
-        // (older than 24 hours)
-        await (0, zip_repository_1.cleanupOldZips)(24 * 60 * 60 * 1000);
+        await (0, zip_repository_1.cleanupOldZips)(constants_1.ZIP_CLEANUP_AGE_MS);
         const transport = new stdio_js_1.StdioServerTransport();
         await this.server.connect(transport);
-        console.error('Supermodel MCP Server running on stdio');
+        logger.info('Supermodel MCP Server running on stdio');
     }
 }
 exports.Server = Server;

package/dist/tools/create-supermodel-graph.js

@@ -1,15 +1,48 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handler = exports.tool = exports.metadata = void 0;
 const promises_1 = require("fs/promises");
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
-const crypto_2 = require("crypto");
 const path_1 = require("path");
 const types_1 = require("../types");
 const filtering_1 = require("../filtering");
 const queries_1 = require("../queries");
 const zip_repository_1 = require("../utils/zip-repository");
+const logger = __importStar(require("../utils/logger"));
 exports.metadata = {
     resource: 'graphs',
     operation: 'write',
@@ -108,10 +141,6 @@ Query types available: graph_status, summary, get_node, search, list_nodes, func
                 type: 'string',
                 description: 'Path to the repository directory to analyze. Can be a subdirectory for faster analysis and smaller graph size (e.g., "/repo/src/core" instead of "/repo").',
             },
-            'Idempotency-Key': {
-                type: 'string',
-                description: 'Optional cache key in format {repo}:{type}:{hash}. If not provided, will be auto-generated using git commit hash or random UUID. Provide a previously used idempotency key to fetch a cached response, for example with a different filter.',
-            },
             query: {
                 type: 'string',
                 enum: [
@@ -169,70 +198,60 @@ Query types available: graph_status, summary, get_node, search, list_nodes, func
     },
 };
 /**
- * Generate an idempotency key in format {repo}:supermodel:{hash}
- * Tries to use git commit hash, falls back to UUID-based hash
+ * Generate an idempotency key in format {repo}-{pathHash}:supermodel:{hash}
+ * Includes path hash to prevent collisions between same-named repos
  */
 function generateIdempotencyKey(directory) {
     const repoName = (0, path_1.basename)(directory);
+    const absolutePath = (0, path_1.resolve)(directory);
+    // Always include path hash to prevent collisions
+    const pathHash = (0, crypto_1.createHash)('sha1').update(absolutePath).digest('hex').substring(0, 7);
     let hash;
     let statusHash = '';
     try {
-        // Try to get git commit hash
+        // Get git commit hash
         hash = (0, child_process_1.execSync)('git rev-parse --short HEAD', {
             cwd: directory,
             encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe']
         }).trim();
-        try {
-            // Get git status to detect uncommitted changes
-            const statusOutput = (0, child_process_1.execSync)('git status --porcelain', {
-                cwd: directory,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'pipe']
-            }).trim();
-            statusHash = (0, crypto_2.createHash)('sha1').update(statusOutput || 'clean').digest('hex').substring(0, 7);
-            console.error('[DEBUG] Generated idempotency key using git hash:', hash, 'and status hash:', statusHash);
-        }
-        catch (statusError) {
-            // If git status fails, just use commit hash
-            console.error('[DEBUG] Generated idempotency key using git hash:', hash, '(git status unavailable)');
+        // Include working tree status in hash to detect uncommitted changes
+        const statusOutput = (0, child_process_1.execSync)('git status --porcelain', {
+            cwd: directory,
+            encoding: 'utf-8',
+        }).toString();
+        if (statusOutput) {
+            // Create hash of status output
+            statusHash = '-' + (0, crypto_1.createHash)('sha1')
+                .update(statusOutput)
+                .digest('hex')
+                .substring(0, 7);
         }
     }
-    catch (error) {
-        // Git not available or not a git repo, use UUID-based hash
-        const uuid = (0, crypto_1.randomUUID)();
-        // Hash like git does (SHA-1) and take first 7 characters
-        hash = (0, crypto_2.createHash)('sha1').update(uuid).digest('hex').substring(0, 7);
-        console.error('[DEBUG] Generated idempotency key using random UUID hash:', hash);
+    catch {
+        // Fallback for non-git directories: use path hash as main identifier
+        hash = pathHash;
     }
-    return statusHash ? `${repoName}:supermodel:${hash}-${statusHash}` : `${repoName}:supermodel:${hash}`;
+    return `${repoName}-${pathHash}:supermodel:${hash}${statusHash}`;
 }
 const handler = async (client, args) => {
     if (!args) {
-        return (0, types_1.asErrorResult)('No arguments provided');
+        logger.error('No arguments provided to handler');
+        return (0, types_1.asErrorResult)('Missing required arguments. Provide a "directory" parameter.');
     }
-    const { jq_filter, directory, 'Idempotency-Key': providedIdempotencyKey, query, targetId, searchText, namePattern, filePathPrefix, labels, depth, relationshipTypes, limit, includeRaw, } = args;
+    const { jq_filter, directory, query, targetId, searchText, namePattern, filePathPrefix, labels, depth, relationshipTypes, limit, includeRaw, } = args;
     // Validate directory
     if (!directory || typeof directory !== 'string') {
-        return (0, types_1.asErrorResult)('Directory argument is required and must be a string path');
-    }
-    // Generate or validate idempotency key
-    let idempotencyKey;
-    let keyGenerated = false;
-    if (!providedIdempotencyKey || typeof providedIdempotencyKey !== 'string') {
-        idempotencyKey = generateIdempotencyKey(directory);
-        keyGenerated = true;
-        console.error('[DEBUG] Auto-generated idempotency key:', idempotencyKey);
-    }
-    else {
-        idempotencyKey = providedIdempotencyKey;
-        console.error('[DEBUG] Using provided idempotency key:', idempotencyKey);
+        logger.error('Invalid directory parameter:', directory);
+        return (0, types_1.asErrorResult)('Invalid "directory" parameter. Provide a valid directory path as a string.');
     }
+    // Generate idempotency key for API request
+    const idempotencyKey = generateIdempotencyKey(directory);
+    logger.debug('Auto-generated idempotency key:', idempotencyKey);
     // Check if we can skip zipping (graph already cached)
     // Use get() atomically to avoid TOCTOU race condition
     const cachedGraph = queries_1.graphCache.get(idempotencyKey);
     if (cachedGraph && query) {
-        console.error('[DEBUG] Graph cached, skipping ZIP creation');
+        logger.debug('Graph cached, skipping ZIP creation');
         // Execute query directly from cache using the cached graph
         // We pass the cached graph to executeQuery so it doesn't need to look it up again
         const result = await handleQueryModeWithCache(client, {
@@ -250,28 +269,9 @@ const handler = async (client, args) => {
             includeRaw,
             jq_filter,
         });
-        // Add metadata about cache hit
-        if (keyGenerated && result.content?.[0]?.type === 'text') {
-            const originalText = result.content[0].text;
-            let responseData;
-            try {
-                responseData = JSON.parse(originalText);
-                // Add metadata about auto-generated key
-                responseData._metadata = {
-                    ...responseData._metadata,
-                    idempotencyKey,
-                    idempotencyKeyGenerated: true
-                };
-                result.content[0].text = JSON.stringify(responseData, null, 2);
-            }
-            catch {
-                // Not JSON, prepend key info as text
-                result.content[0].text = `[Auto-generated Idempotency-Key: ${idempotencyKey}]\n\n${originalText}`;
-            }
-        }
         return result;
     }
-    console.error('[DEBUG] Auto-zipping directory:', directory);
+    logger.debug('Auto-zipping directory:', directory);
     // Handle auto-zipping
     let zipPath;
     let cleanup = null;
@@ -279,24 +279,30 @@ const handler = async (client, args) => {
         const zipResult = await (0, zip_repository_1.zipRepository)(directory);
         zipPath = zipResult.path;
         cleanup = zipResult.cleanup;
-        console.error('[DEBUG] Auto-zip complete:', zipResult.fileCount, 'files,', formatBytes(zipResult.sizeBytes));
+        logger.debug('Auto-zip complete:', zipResult.fileCount, 'files,', formatBytes(zipResult.sizeBytes));
     }
     catch (error) {
-        console.error('[ERROR] Auto-zip failed:', error.message);
-        // Provide helpful error messages
+        // Log full error details for debugging
+        logger.error('Auto-zip failed');
+        logger.error('Error type:', error.name || 'Error');
+        logger.error('Error message:', error.message);
+        if (error.stack) {
+            logger.error('Stack trace:', error.stack);
+        }
+        // Return user-friendly, actionable error messages
         if (error.message.includes('does not exist')) {
-            return (0, types_1.asErrorResult)(`Directory does not exist: ${directory}`);
+            return (0, types_1.asErrorResult)(`Directory not found. Please verify the path exists: ${directory}`);
         }
         if (error.message.includes('Permission denied')) {
-            return (0, types_1.asErrorResult)(`Permission denied accessing directory: ${directory}`);
+            return (0, types_1.asErrorResult)(`Permission denied. Check that you have read access to: ${directory}`);
         }
         if (error.message.includes('exceeds limit')) {
-            return (0, types_1.asErrorResult)(error.message);
+            return (0, types_1.asErrorResult)(error.message + '\n\nTry analyzing a subdirectory or excluding more files.');
         }
         if (error.message.includes('ENOSPC')) {
-            return (0, types_1.asErrorResult)('Insufficient disk space to create ZIP archive');
+            return (0, types_1.asErrorResult)('Insufficient disk space. Free up space and try again.');
         }
-        return (0, types_1.asErrorResult)(`Failed to create ZIP archive: ${error.message}`);
+        return (0, types_1.asErrorResult)(`Failed to create ZIP archive. Check the MCP server logs for details.`);
     }
     // Execute query with cleanup handling
     try {
@@ -323,25 +329,6 @@ const handler = async (client, args) => {
             // Legacy mode: use jq_filter directly on API response
             result = await handleLegacyMode(client, zipPath, idempotencyKey, jq_filter);
         }
-        // If key was auto-generated, add it to the response
-        if (keyGenerated && result.content && result.content[0]?.type === 'text') {
-            const originalText = result.content[0].text;
-            let responseData;
-            try {
-                responseData = JSON.parse(originalText);
-                // Add metadata about auto-generated key
-                responseData._metadata = {
-                    ...responseData._metadata,
-                    idempotencyKey,
-                    idempotencyKeyGenerated: true
-                };
-                result.content[0].text = JSON.stringify(responseData, null, 2);
-            }
-            catch {
-                // Not JSON, prepend key info as text
-                result.content[0].text = `[Auto-generated Idempotency-Key: ${idempotencyKey}]\n\n${originalText}`;
-            }
-        }
         return result;
     }
     finally {
@@ -423,13 +410,47 @@ async function handleQueryMode(client, params) {
     let result = await (0, queries_1.executeQuery)(queryParams);
     // If cache miss, fetch from API and retry
     if ((0, queries_1.isQueryError)(result) && result.error.code === 'CACHE_MISS') {
-        console.error('[DEBUG] Cache miss, fetching from API...');
+        logger.debug('Cache miss, fetching from API...');
         try {
             const apiResponse = await fetchFromApi(client, params.file, params.idempotencyKey);
             result = await (0, queries_1.executeQuery)(queryParams, apiResponse);
         }
         catch (error) {
-            return (0, types_1.asErrorResult)(`API call failed: ${error.message || String(error)}`);
+            // Error details are already logged by fetchFromApi and logErrorResponse
+            // Return a user-friendly, actionable error message
+            let errorMessage = '';
+            if (error.response) {
+                const status = error.response.status;
+                switch (status) {
+                    case 401:
+                        errorMessage = 'Authentication failed. Set your SUPERMODEL_API_KEY environment variable and restart the MCP server.';
+                        break;
+                    case 403:
+                        errorMessage = 'Access forbidden. Your API key does not have permission for this operation. Contact support if this is unexpected.';
+                        break;
+                    case 404:
+                        errorMessage = 'API endpoint not found. The service URL may be incorrect. Check your SUPERMODEL_BASE_URL configuration.';
+                        break;
+                    case 429:
+                        errorMessage = 'Rate limit exceeded. Wait a few minutes and try again.';
+                        break;
+                    case 500:
+                    case 502:
+                    case 503:
+                    case 504:
+                        errorMessage = 'Server error. The Supermodel API is temporarily unavailable. Try again in a few minutes.';
+                        break;
+                    default:
+                        errorMessage = `API error (HTTP ${status}). Check the MCP server logs for details.`;
+                }
+            }
+            else if (error.request) {
+                errorMessage = 'No response from server. Check your network connection and verify the API is reachable.';
+            }
+            else {
+                errorMessage = 'Request failed. Check the MCP server logs for details.';
+            }
+            return (0, types_1.asErrorResult)(errorMessage);
         }
     }
     // Handle query errors
@@ -513,21 +534,129 @@ function getErrorHints(errorCode, queryType) {
     }
 }
 /**
- * Fetch graph from API
+ * Get current timestamp in ISO format
+ */
+function getTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Log HTTP request details
+ */
+function logRequest(url, method, bodySize, idempotencyKey) {
+    logger.debug(`[${getTimestamp()}] [API REQUEST]`);
+    logger.debug(`  Method: ${method}`);
+    logger.debug(`  URL: ${url}`);
+    logger.debug(`  Idempotency-Key: ${idempotencyKey}`);
+    logger.debug(`  Body size: ${formatBytes(bodySize)}`);
+    logger.debug(`  Content-Type: multipart/form-data`);
+}
+/**
+ * Log HTTP response details
+ */
+function logResponse(status, statusText, responseSize, duration) {
+    logger.debug(`[${getTimestamp()}] [API RESPONSE]`);
+    logger.debug(`  Status: ${status} ${statusText}`);
+    logger.debug(`  Response size: ${formatBytes(responseSize)}`);
+    logger.debug(`  Duration: ${duration}ms`);
+}
+/**
+ * Log HTTP error with full details
+ */
+async function logErrorResponse(error) {
+    logger.error(`[${getTimestamp()}] [API ERROR]`);
+    logger.error(`  Error type: ${error.name || 'Unknown'}`);
+    logger.error(`  Error message: ${error.message || 'No message'}`);
+    if (error.response) {
+        const status = error.response.status;
+        const statusText = error.response.statusText || '';
+        logger.error(`  HTTP Status: ${status} ${statusText}`);
+        // Log specific error messages for common status codes
+        switch (status) {
+            case 401:
+                logger.error(`  Unauthorized: Invalid or missing API key`);
+                logger.error(`  Check SUPERMODEL_API_KEY environment variable`);
+                break;
+            case 403:
+                logger.error(`  Forbidden: API key valid but lacks permission`);
+                break;
+            case 404:
+                logger.error(`  Not Found: API endpoint does not exist`);
+                break;
+            case 429:
+                logger.error(`  Rate Limited: Too many requests`);
+                break;
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                logger.error(`  Server Error: Supermodel API is experiencing issues`);
+                break;
+        }
+        // Try to read and log the full error response body
+        try {
+            const responseText = await error.response.text();
+            logger.error(`  Response body: ${responseText}`);
+        }
+        catch (e) {
+            logger.warn(`  Could not read response body: ${e}`);
+        }
+    }
+    else if (error.request) {
+        logger.error(`  No response received from server`);
+        logger.error(`  Possible network issue or timeout`);
+    }
+    else {
+        logger.error(`  Request setup failed`);
+    }
+    if (error.stack) {
+        logger.error(`  Stack trace: ${error.stack}`);
+    }
+}
+/**
+ * Fetch graph from API with comprehensive logging
  */
 async function fetchFromApi(client, file, idempotencyKey) {
-    console.error('[DEBUG] Reading file:', file);
+    const startTime = Date.now();
+    logger.debug('Reading file:', file);
     const fileBuffer = await (0, promises_1.readFile)(file);
     const fileBlob = new Blob([fileBuffer], { type: 'application/zip' });
-    console.error('[DEBUG] File size:', fileBuffer.length, 'bytes');
-    console.error('[DEBUG] Making API request with idempotency key:', idempotencyKey);
+    const fileSize = fileBuffer.length;
+    logger.debug('File size:', formatBytes(fileSize));
+    // Get the base URL from environment or use default
+    const baseUrl = process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com';
+    const apiUrl = `${baseUrl}/v1/graphs/supermodel`;
+    // Log the request details
+    logRequest(apiUrl, 'POST', fileSize, idempotencyKey);
     const requestParams = {
         file: fileBlob,
         idempotencyKey: idempotencyKey,
     };
-    const response = await client.graphs.generateSupermodelGraph(requestParams);
-    console.error('[DEBUG] API request successful');
-    return response;
+    try {
+        const response = await client.graphs.generateSupermodelGraph(requestParams);
+        const duration = Date.now() - startTime;
+        // Calculate approximate response size
+        const responseSize = JSON.stringify(response).length;
+        logResponse(200, 'OK', responseSize, duration);
+        logger.debug(`[${getTimestamp()}] [API SUCCESS] Request completed successfully`);
+        return response;
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        logger.error(`[${getTimestamp()}] [API FAILURE] Request failed after ${duration}ms`);
+        // Log detailed error information
+        await logErrorResponse(error);
+        // Re-throw with enhanced error message
+        if (error.response?.status === 401) {
+            throw new Error(`API authentication failed (401 Unauthorized). Please check your SUPERMODEL_API_KEY environment variable.`);
+        }
+        else if (error.response?.status === 403) {
+            throw new Error(`API access forbidden (403 Forbidden). Your API key may not have permission to access this resource.`);
+        }
+        else if (error.response?.status >= 500) {
+            throw new Error(`Supermodel API server error (${error.response.status}). The service may be temporarily unavailable.`);
+        }
+        throw error;
+    }
 }
 /**
  * Legacy mode: direct jq filtering on API response
@@ -539,29 +668,44 @@ async function handleLegacyMode(client, file, idempotencyKey, jq_filter) {
     }
     catch (error) {
         if ((0, filtering_1.isJqError)(error)) {
-            return (0, types_1.asErrorResult)(error.message);
+            logger.error('jq filter error:', error.message);
+            return (0, types_1.asErrorResult)(`Invalid jq filter syntax. Check your filter and try again.`);
         }
-        // Enhanced error logging
-        console.error('[ERROR] API call failed:', error);
-        console.error('[ERROR] Error name:', error.name);
-        console.error('[ERROR] Error message:', error.message);
-        console.error('[ERROR] Error stack:', error.stack);
+        // Error details are already logged by fetchFromApi and logErrorResponse
+        // Return a user-friendly, actionable error message
+        let errorMessage = '';
         if (error.response) {
-            console.error('[ERROR] Response status:', error.response.status);
-            console.error('[ERROR] Response statusText:', error.response.statusText);
-            console.error('[ERROR] Response headers:', error.response.headers);
-            try {
-                const responseText = await error.response.text();
-                console.error('[ERROR] Response body:', responseText);
-            }
-            catch (e) {
-                console.error('[ERROR] Could not read response body');
+            const status = error.response.status;
+            switch (status) {
+                case 401:
+                    errorMessage = 'Authentication failed. Set your SUPERMODEL_API_KEY environment variable and restart the MCP server.';
+                    break;
+                case 403:
+                    errorMessage = 'Access forbidden. Your API key does not have permission for this operation. Contact support if this is unexpected.';
+                    break;
+                case 404:
+                    errorMessage = 'API endpoint not found. The service URL may be incorrect. Check your SUPERMODEL_BASE_URL configuration.';
+                    break;
+                case 429:
+                    errorMessage = 'Rate limit exceeded. Wait a few minutes and try again.';
+                    break;
+                case 500:
+                case 502:
+                case 503:
+                case 504:
+                    errorMessage = 'Server error. The Supermodel API is temporarily unavailable. Try again in a few minutes.';
+                    break;
+                default:
+                    errorMessage = `API error (HTTP ${status}). Check the MCP server logs for details.`;
             }
         }
-        if (error.request) {
-            console.error('[ERROR] Request was made but no response received');
+        else if (error.request) {
+            errorMessage = 'No response from server. Check your network connection and verify the API is reachable.';
+        }
+        else {
+            errorMessage = 'Request failed. Check the MCP server logs for details.';
         }
-        return (0, types_1.asErrorResult)(`API call failed: ${error.message || String(error)}. Check server logs for details.`);
+        return (0, types_1.asErrorResult)(errorMessage);
     }
 }
 exports.default = { metadata: exports.metadata, tool: exports.tool, handler: exports.handler };

package/dist/utils/logger.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Simple logging utility with environment variable control
+ *
+ * Usage:
+ *   DEBUG=true node dist/index.js  # Enable debug logging
+ *   node dist/index.js             # Disable debug logging
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debug = debug;
+exports.info = info;
+exports.warn = warn;
+exports.error = error;
+const DEBUG = process.env.DEBUG === 'true';
+/**
+ * Debug log - only shown when DEBUG=true
+ * Uses stderr to keep separate from application output
+ */
+function debug(msg, ...args) {
+    if (DEBUG) {
+        console.error('[DEBUG]', msg, ...args);
+    }
+}
+/**
+ * Info log - informational messages to stdout
+ */
+function info(msg, ...args) {
+    console.log('[INFO]', msg, ...args);
+}
+/**
+ * Warning log - warnings to stderr
+ */
+function warn(msg, ...args) {
+    console.error('[WARN]', msg, ...args);
+}
+/**
+ * Error log - errors to stderr
+ */
+function error(msg, ...args) {
+    console.error('[ERROR]', msg, ...args);
+}