octocode-mcp 2.3.6 → 2.3.8

package/build/index.js

@@ -107,9 +107,9 @@ function escapeShellArg(arg, shellType, isGitHubQuery // Flag to indicate if thi
         const isWindows = platform() === 'win32';
         shellType = isWindows ? 'cmd' : 'unix';
     }
-    // Special handling for GitHub search queries
+    // Special handling for GitHub search queries to preserve AND logic
     if (isGitHubQuery) {
-        // If the argument already contains quotes, preserve them
+        // If the argument already contains quotes, preserve them for exact phrases
         if (arg.includes('"')) {
             // For Unix-like shells, wrap the entire argument in single quotes
             if (shellType === 'unix') {
@@ -122,6 +122,13 @@ function escapeShellArg(arg, shellType, isGitHubQuery // Flag to indicate if thi
             // For PowerShell
             return `'${arg.replace(/'/g, "''")}'`;
         }
+        // For space-separated terms (AND search), minimize escaping
+        if (arg.includes(' ') && shellType === 'unix') {
+            // Only escape if contains dangerous shell characters
+            if (!/[;&|<>$`\\]/.test(arg)) {
+                return `"${arg}"`;
+            }
+        }
     }
     switch (shellType) {
         case 'powershell':
@@ -158,16 +165,28 @@ function escapeWindowsCmdArg(arg) {
 }
 /**
  * Escape arguments for Unix shells with special handling for GitHub CLI queries
+ * Preserves AND search logic by not over-escaping space-separated terms
  */
 function escapeUnixShellArg(arg, isGitHubQuery) {
-    // If it's a GitHub search query with special characters or spaces
-    if (isGitHubQuery && (arg.includes(' ') || /[:"']/g.test(arg))) {
-        // Preserve existing quotes if present
+    // For GitHub search queries, we need to preserve AND logic
+    if (isGitHubQuery) {
+        // If the query contains quotes, preserve them for exact phrase matching
         if (arg.includes('"')) {
+            // Use single quotes to wrap the entire query while preserving internal quotes
+            return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+        }
+        // For space-separated terms (AND search), only escape if absolutely necessary
+        // GitHub CLI expects space-separated terms for AND logic
+        if (arg.includes(' ') && !/[;&|<>$`\\]/.test(arg)) {
+            // Only wrap in quotes if it contains shell metacharacters beyond spaces
+            return `"${arg}"`;
+        }
+        // For single terms or terms with special chars, escape normally
+        if (/[;&|<>$`\\]/.test(arg)) {
             return `'${arg.replace(/'/g, "'\"'\"'")}'`;
         }
-        // Add double quotes for terms that need them
-        return `"${arg}"`;
+        // Simple terms don't need escaping
+        return arg;
     }
     // Standard Unix shell escaping for other arguments
     if (/[^a-zA-Z0-9\-_./=@:]/.test(arg)) {
@@ -219,10 +238,15 @@ async function executeGitHubCommand(command, args = [], options = {}) {
             index > 1 &&
             (arg.includes(':') || arg.startsWith('(')) &&
             !arg.startsWith('--');
-        // Don't escape GitHub search qualifiers - they need to be passed as-is
-        // This includes qualifiers like "language:typescript", "user:microsoft", "org:microsoft"
-        // and complex expressions like "(user:microsoft OR org:microsoft)"
+        // GitHub search qualifiers need special handling
+        // Most qualifiers can be passed as-is, but those with shell metacharacters need escaping
         if (isGitHubQualifier) {
+            // Check if the qualifier contains shell metacharacters that need escaping
+            if (/[<>&|;`$\\]/.test(arg)) {
+                // Escape qualifiers that contain shell metacharacters like size:<1000, size:>500
+                return escapeShellArg(arg, shellConfig.type, false);
+            }
+            // Safe qualifiers like "language:typescript", "user:microsoft" can be passed as-is
             return arg;
         }
         return escapeShellArg(arg, shellConfig.type, isMainQueryArgument);
@@ -284,6 +308,14 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
                 stderr.trim() !== '';
         if (shouldTreatAsError) {
             const errorType = type === 'npm' ? 'NPM command error' : 'GitHub CLI command error';
+            // Enhanced error messaging for common GitHub issues
+            if (type === 'github' && stderr.includes('404')) {
+                const isRepoNotFound = stderr.includes('Not Found');
+                const enhancedMessage = isRepoNotFound
+                    ? `${stderr}\n\nThis is often due to incorrect repository name. Use github_search_code to find the correct repository.`
+                    : stderr;
+                return createErrorResult(errorType, new Error(enhancedMessage));
+            }
             return createErrorResult(errorType, new Error(stderr));
         }
         // Try to parse stdout as JSON, fallback to string if not possible
@@ -313,61 +345,6 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     }
 }
 
-var LogLevel;
-(function (LogLevel) {
-    LogLevel["ERROR"] = "ERROR";
-    LogLevel["WARN"] = "WARN";
-    LogLevel["INFO"] = "INFO";
-    LogLevel["DEBUG"] = "DEBUG";
-})(LogLevel || (LogLevel = {}));
-class Logger {
-    appName;
-    timestamp;
-    constructor(appName = 'octocode-mcp', timestamp = true) {
-        this.appName = appName;
-        this.timestamp = timestamp;
-    }
-    formatMessage(level, message, ...args) {
-        const timestamp = this.timestamp ? `[${new Date().toISOString()}] ` : '';
-        const prefix = `${timestamp}[${this.appName}] [${level}]`;
-        const formattedArgs = args.length > 0
-            ? ' ' +
-                args
-                    .map(arg => {
-                    if (arg instanceof Error) {
-                        return `${arg.message}\n${arg.stack}`;
-                    }
-                    return typeof arg === 'object'
-                        ? JSON.stringify(arg, null, 2)
-                        : String(arg);
-                })
-                    .join(' ')
-            : '';
-        return `${prefix} ${message}${formattedArgs}`;
-    }
-    error(message, ...args) {
-        // eslint-disable-next-line no-console
-        console.error(this.formatMessage(LogLevel.ERROR, message, ...args));
-    }
-    warn(message, ...args) {
-        // eslint-disable-next-line no-console
-        console.warn(this.formatMessage(LogLevel.WARN, message, ...args));
-    }
-    info(message, ...args) {
-        // eslint-disable-next-line no-console
-        console.log(this.formatMessage(LogLevel.INFO, message, ...args));
-    }
-    debug(message, ...args) {
-        if (process.env.DEBUG === 'true' ||
-            process.env.NODE_ENV === 'development') {
-            // eslint-disable-next-line no-console
-            console.log(this.formatMessage(LogLevel.DEBUG, message, ...args));
-        }
-    }
-}
-// Singleton instance
-const logger = new Logger();
-
 function createResult(options) {
     const { data, error } = options;
     if (error) {
@@ -387,7 +364,6 @@ function createResult(options) {
         };
     }
     catch (jsonError) {
-        logger.error('JSON serialization failed:', jsonError);
         return {
             content: [
                 {
@@ -582,7 +558,7 @@ function createSearchFailedError(type = 'code') {
 }
 
 const API_STATUS_CHECK_TOOL_NAME = 'apiStatusCheck';
-const DESCRIPTION$9 = `Check GitHub and NPM authentication status. Returns connected status and GitHub organizations for accessing private repositories. No parameters required.`;
+const DESCRIPTION$9 = `Check GitHub and NPM authentication status and available organizations. Verifies API connections and returns user organizations for accessing private repositories. Essential for troubleshooting access issues. No parameters required.`;
 // Helper function to parse execution results with proper typing
 function parseExecResult(result) {
     if (!result.isError && result.content?.[0]?.text) {
@@ -714,235 +690,34 @@ function registerApiStatusCheckTool(server) {
     });
 }
 
-const GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME = 'githubViewRepoStructure';
-const DESCRIPTION$8 = `Explore repository structure and navigate directories. Auto-detects branches and provides file/folder listings with size information. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), path (optional).`;
-function registerViewRepositoryStructureTool(server) {
-    server.registerTool(GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME, {
-        description: DESCRIPTION$8,
-        inputSchema: {
-            owner: z
-                .string()
-                .min(1)
-                .max(100)
-                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, 'Invalid GitHub username/org format')
-                .describe(`Repository owner/org name (e.g., 'microsoft', 'google', NOT 'microsoft/vscode')`),
-            repo: z
-                .string()
-                .min(1)
-                .max(100)
-                .regex(/^[a-zA-Z0-9._-]+$/, 'Invalid repository name format')
-                .describe('Repository name (case-sensitive)'),
-            branch: z
-                .string()
-                .min(1)
-                .max(255)
-                .regex(/^[^\s]+$/, 'Branch name cannot contain spaces')
-                .describe('Branch name. Falls back to default branch if not found'),
-            path: z
-                .string()
-                .optional()
-                .default('')
-                .refine(path => !path.includes('..'), 'Path traversal not allowed')
-                .refine(path => path.length <= 500, 'Path too long')
-                .describe('Directory path within repository. Leave empty for root.'),
-        },
-        annotations: {
-            title: 'GitHub Repository Explorer',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
-    }, async (args) => {
-        try {
-            const result = await viewRepositoryStructure(args);
-            return result;
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            return createResult({
-                error: `Failed to explore repository. ${errorMessage}. Verify repository exists and is accessible`,
-            });
-        }
-    });
-}
-/**
- * Views the structure of a GitHub repository at a specific path.
- * Optimized for code analysis workflows with smart defaults and clear errors.
- */
-async function viewRepositoryStructure(params) {
-    const cacheKey = generateCacheKey('gh-repo-structure', params);
-    return withCache(cacheKey, async () => {
-        const { owner, repo, branch, path = '' } = params;
-        try {
-            // Clean up path
-            const cleanPath = path.startsWith('/') ? path.substring(1) : path;
-            // Try the requested branch first, then fallback to main/master
-            const branchesToTry = await getSmartBranchFallback(owner, repo, branch);
-            let items = [];
-            let usedBranch = branch;
-            let lastError = null;
-            let attemptCount = 0;
-            const maxAttempts = 3; // Prevent infinite loops
-            for (const tryBranch of branchesToTry) {
-                if (attemptCount >= maxAttempts)
-                    break;
-                attemptCount++;
-                try {
-                    const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
-                    const result = await executeGitHubCommand('api', [apiPath], {
-                        cache: false,
-                    });
-                    if (!result.isError) {
-                        const execResult = JSON.parse(result.content[0].text);
-                        const apiItems = execResult.result;
-                        items = Array.isArray(apiItems) ? apiItems : [apiItems];
-                        usedBranch = tryBranch;
-                        break;
-                    }
-                    else {
-                        lastError = new Error(result.content[0].text);
-                    }
-                }
-                catch (error) {
-                    lastError = error instanceof Error ? error : new Error(String(error));
-                    // Try next branch
-                    continue;
-                }
-            }
-            if (items.length === 0) {
-                // Use the most descriptive error message
-                const errorMsg = lastError?.message || 'Unknown error';
-                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
-                    if (path) {
-                        return createResult({
-                            error: `Path "${path}" not found. Verify the path or use github_search_code to find files`,
-                        });
-                    }
-                    else {
-                        return createResult({
-                            error: `Repository not found: ${owner}/${repo}. Check spelling and case sensitivity`,
-                        });
-                    }
-                }
-                else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
-                    return createResult({
-                        error: `Access denied to ${owner}/${repo}. Repository may be private - use api_status_check`,
-                    });
-                }
-                else {
-                    return createResult({
-                        error: `Failed to access ${owner}/${repo}. Check network connection`,
-                    });
-                }
-            }
-            // Limit total items to 100 for efficiency
-            const limitedItems = items.slice(0, 100);
-            // Sort: directories first, then alphabetically
-            limitedItems.sort((a, b) => {
-                if (a.type !== b.type) {
-                    return a.type === 'dir' ? -1 : 1;
-                }
-                return a.name.localeCompare(b.name);
-            });
-            // Create simplified, token-efficient structure
-            const files = limitedItems
-                .filter(item => item.type === 'file')
-                .map(item => ({
-                name: item.name,
-                size: item.size,
-                url: item.path, // Use path for fetching
-            }));
-            const folders = limitedItems
-                .filter(item => item.type === 'dir')
-                .map(item => ({
-                name: item.name,
-                url: item.path, // Use path for browsing
-            }));
-            return createResult({
-                data: {
-                    repository: `${owner}/${repo}`,
-                    branch: usedBranch,
-                    path: cleanPath || '/',
-                    githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
-                    files: {
-                        count: files.length,
-                        files: files,
-                    },
-                    folders: {
-                        count: folders.length,
-                        folders: folders,
-                    },
-                },
-            });
-        }
-        catch (error) {
-            return createResult({
-                error: `Failed to access repository. ${error}. Verify repository name and authentication`,
-            });
-        }
-    });
-}
-/**
- * Smart branch detection with automatic fallback to common branch names.
- */
-async function getSmartBranchFallback(owner, repo, requestedBranch) {
-    const branches = [requestedBranch];
-    try {
-        // Try to get repository info to find default branch
-        const repoInfoResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
-            cache: false,
-        });
-        if (!repoInfoResult.isError) {
-            const execResult = JSON.parse(repoInfoResult.content[0].text);
-            const repoData = execResult.result;
-            const defaultBranch = repoData.default_branch;
-            if (defaultBranch && !branches.includes(defaultBranch)) {
-                branches.push(defaultBranch);
-            }
-        }
-    }
-    catch {
-        // If we can't get repo info, proceed with standard fallbacks
-    }
-    // Add common branch names if not already included
-    const commonBranches = ['main', 'master', 'develop', 'dev'];
-    commonBranches.forEach(branch => {
-        if (!branches.includes(branch)) {
-            branches.push(branch);
-        }
-    });
-    return branches;
-}
-
 const GITHUB_GET_FILE_CONTENT_TOOL_NAME = 'githubGetFileContent';
-const DESCRIPTION$7 = `Fetch file content from GitHub repositories. Use ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} first to explore repository structure and find exact file paths. Supports automatic branch fallback (main/master) and handles files up to 300KB. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), filePath (required).`;
+const DESCRIPTION$8 = `Fetch file content from GitHub repositories. Automatically handles branch fallback (main/master) and files up to 300KB. Returns decoded file content with metadata. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), filePath (required).`;
 function registerFetchGitHubFileContentTool(server) {
     server.registerTool(GITHUB_GET_FILE_CONTENT_TOOL_NAME, {
-        description: DESCRIPTION$7,
+        description: DESCRIPTION$8,
         inputSchema: {
             owner: z
                 .string()
                 .min(1)
                 .max(100)
                 .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
-                .describe(`Repository owner/org name (e.g., 'microsoft', 'google', NOT 'microsoft/vscode')`),
+                .describe(`Repository owner/organization name (e.g., 'facebook', 'microsoft'). Do NOT include repository name here.`),
             repo: z
                 .string()
                 .min(1)
                 .max(100)
                 .regex(/^[a-zA-Z0-9._-]+$/)
-                .describe(`Repository name only (e.g., 'vscode', 'react', NOT 'microsoft/vscode')`),
+                .describe(`Repository name only (e.g., 'react', 'vscode'). Do NOT include owner/org prefix.`),
             branch: z
                 .string()
                 .min(1)
                 .max(255)
                 .regex(/^[^\s]+$/)
-                .describe(`Branch name. Falls back to main/master if not found`),
+                .describe(`Branch name (e.g., 'main', 'master'). Tool will automatically try 'main' and 'master' if specified branch is not found.`),
             filePath: z
                 .string()
                 .min(1)
-                .describe(`Exact file path from repo root (e.g., src/index.js, README.md)`),
+                .describe(`File path from repository root (e.g., 'src/index.js', 'README.md', 'docs/api.md'). Do NOT start with slash.`),
         },
         annotations: {
             title: 'GitHub File Content - Direct Access',
@@ -969,18 +744,39 @@ async function fetchGitHubFileContent(params) {
         const { owner, repo, branch, filePath } = params;
         try {
             // Try to fetch file content directly
-            const apiPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}`;
+            const apiPath = `/repos/${owner}/${repo}/contents/${filePath}`;
             const result = await executeGitHubCommand('api', [apiPath], {
                 cache: false,
             });
             if (result.isError) {
                 const errorMsg = result.content[0].text;
+                // Check repository existence only after content fetch fails
+                const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+                    cache: false,
+                });
+                if (repoCheckResult.isError) {
+                    const repoErrorMsg = repoCheckResult.content[0].text;
+                    if (repoErrorMsg.includes('404')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" not found. This is often due to incorrect repository name. Steps to resolve:\n1. Use github_search_code with query="${filePath.split('/').pop()}" owner="${owner}" to find the correct repository\n2. Verify the exact repository name\n3. Check if the repository might have been renamed or moved`,
+                        });
+                    }
+                    else if (repoErrorMsg.includes('403')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" exists but access is denied. Repository might be private or archived. Use api_status_check to verify permissions.`,
+                        });
+                    }
+                }
                 // Try fallback branches if original branch fails
                 if (errorMsg.includes('404') &&
                     branch !== 'main' &&
                     branch !== 'master') {
                     const fallbackBranches = ['main', 'master'];
+                    const triedBranches = [branch];
                     for (const fallbackBranch of fallbackBranches) {
+                        if (triedBranches.includes(fallbackBranch))
+                            continue;
+                        triedBranches.push(fallbackBranch);
                         const fallbackPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${fallbackBranch}`;
                         const fallbackResult = await executeGitHubCommand('api', [fallbackPath], {
                             cache: false,
@@ -989,27 +785,32 @@ async function fetchGitHubFileContent(params) {
                             return await processFileContent(fallbackResult, owner, repo, fallbackBranch, filePath);
                         }
                     }
+                    return createResult({
+                        error: `File not found in any common branches (tried: ${triedBranches.join(', ')}). File might have been moved or deleted. Use github_search_code to find current location.`,
+                    });
                 }
-                // Handle common errors
+                // Handle common errors with more context
                 if (errorMsg.includes('404')) {
+                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: 'File not found. Use github_view_repo_structure to explore repository structure',
+                        error: `File "${filePath}" not found in branch "${branch}". Use github_view_repo_structure to verify path.${searchSuggestion}`,
                     });
                 }
                 else if (errorMsg.includes('403')) {
                     return createResult({
-                        error: 'Access denied. Repository may be private - use apiStatusCheck to verify',
+                        error: `Access denied to "${filePath}" in "${owner}/${repo}". Repository or file might be private/archived. Use api_status_check to verify permissions, or github_search_code with query="path:${filePath}" owner="${owner}" to find in accessible repositories.`,
                     });
                 }
                 else if (errorMsg.includes('maxBuffer') ||
                     errorMsg.includes('stdout maxBuffer length exceeded')) {
                     return createResult({
-                        error: 'File too large (>300KB). Use githubSearchCode to search for patterns within the file',
+                        error: `File "${filePath}" is too large (>300KB). Use github_search_code with query="path:${filePath}" to search within the file or download directly from GitHub.`,
                     });
                 }
                 else {
+                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: 'Failed to fetch file. Verify repository name and file path',
+                        error: `Failed to fetch "${filePath}". Error: ${errorMsg}. Verify repository name, branch, and file path.${searchSuggestion}`,
                     });
                 }
             }
@@ -1017,15 +818,14 @@ async function fetchGitHubFileContent(params) {
         }
         catch (error) {
             const errorMessage = error.message;
-            // Handle maxBuffer errors that escape the main try-catch
             if (errorMessage.includes('maxBuffer') ||
                 errorMessage.includes('stdout maxBuffer length exceeded')) {
                 return createResult({
-                    error: 'File too large (>300KB). Use github_search_code to search for patterns within the file',
+                    error: `File "${filePath}" is too large (>300KB). Use github_search_code to search within the file or download directly from GitHub.`,
                 });
             }
             return createResult({
-                error: 'Unexpected error. Check network connection and try again',
+                error: `Unexpected error fetching "${filePath}": ${errorMessage}. Check network connection and try again.`,
             });
         }
     });
@@ -1088,41 +888,82 @@ async function processFileContent(result, owner, repo, branch, filePath) {
         },
     });
 }
+// Helper function to suggest code search strategy
+async function suggestCodeSearchFallback(owner, filePath) {
+    try {
+        // Extract filename and try to find in same organization
+        const fileName = filePath.split('/').pop() || filePath;
+        const searchResult = await executeGitHubCommand('api', [`/search/code?q=${encodeURIComponent(fileName)}+in:path+org:${owner}`], { cache: false });
+        if (!searchResult.isError) {
+            const results = JSON.parse(searchResult.content[0].text);
+            if (results.total_count > 0) {
+                const firstMatch = results.items[0];
+                return ` File might be in ${firstMatch.repository.full_name}. Try these searches:\n1. github_search_code with query="${fileName}" owner="${owner}"\n2. github_search_code with query="path:${filePath}" owner="${owner}"`;
+            }
+        }
+    }
+    catch {
+        // Fallback to generic message if search fails
+    }
+    return ` Try these searches:\n1. github_search_code with query="${filePath.split('/').pop()}" owner="${owner}"\n2. github_search_code with query="path:${filePath}"`;
+}
 
 const GITHUB_SEARCH_CODE_TOOL_NAME = 'githubSearchCode';
-const DESCRIPTION$6 = `Search code across GitHub repositories. Start with simple 1-2 word queries, then refine with filters like language, owner, or filename. Supports exact phrase matching with quotes. Parameters: query (required), language (optional), owner (optional - GitHub username/org, NOT owner/repo), filename (optional), extension (optional), match (optional), size (optional), limit (optional).`;
+const DESCRIPTION$7 = `Search code across GitHub repositories using GitHub's code search API.
+
+Never use filters and flags on exploretory searches and on initial searches.
+Use filters and flags on subsequent searches when you know what to search for or if the user asks for it explicitly.
+Using too many flags might make miss relevant results. Use filters and flags to narrow down the results when getting too many.
+
+Search Syntax - ALL terms must be present (AND logic):
+The search finds files that contain ALL specified terms. Each space-separated term is required to be present in the same file.
+- Multiple terms: All individual words must exist in the file
+- Quoted phrases: Exact phrase matching for multi-word expressions  
+- Mixed terms: Combination of individual words AND exact phrases, all must be present
+- Additional filters: Language, owner, repository, filename, extension, size and other flags supported
+
+Key behavior: All search terms are combined with AND logic - every term must be found in the file.
+Quotes create exact phrase matching, unquoted terms are individual word requirements.
+Start with 1-2 terms, add more to narrow results. Use filters and flags for precision.
+
+`;
 function registerGitHubSearchCodeTool(server) {
     server.registerTool(GITHUB_SEARCH_CODE_TOOL_NAME, {
-        description: DESCRIPTION$6,
+        description: DESCRIPTION$7,
         inputSchema: {
             query: z
                 .string()
                 .min(1)
-                .describe('Search terms. START SIMPLE: Use 1-2 words first (e.g., "useState", "auth"). Add more terms only after seeing initial results.'),
+                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases.'),
             language: z
                 .string()
                 .optional()
-                .describe('Language filter (javascript, python, etc). Use only when needed.'),
+                .describe('Programming language filter. Narrows search to specific language files. Use for language-specific searches.'),
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner/org (for organization-specific searches). Format: username or org-name only, NOT owner/repo. Use this to search within a specific organization.'),
+                .describe('Repository owner/organization name(s) to search within (e.g., "facebook", ["google", "microsoft"]). Use this to search within specific organizations. Do NOT use owner/repo format - just the organization/username.'),
+            repo: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('Filter on specific repository(ies). Must use full "owner/repo" format (e.g., "facebook/react", ["vuejs/vue", "angular/angular"]). Use this for searching within specific repositories.'),
             filename: z
                 .string()
                 .optional()
-                .describe('Specific filename to search. Use for targeted searches.'),
+                .describe('Target specific filename or pattern. Use for file-specific searches.'),
             extension: z
                 .string()
                 .optional()
-                .describe('File extension (.js, .py, etc). Alternative to language filter.'),
+                .describe('File extension filter. Alternative to language parameter.'),
             match: z
                 .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
                 .optional()
-                .describe('Search scope: "file" for content, "path" for filenames. Default: file content.'),
+                .describe('Search scope: "file" for file content (default), "path" for filenames/paths, or ["file", "path"] for both. Controls where to search for terms.'),
             size: z
                 .string()
+                .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">10", ">=5", "<100", "<=50", "10..100", or exact number "50"')
                 .optional()
-                .describe('File size in KB. Format: >10, <100, or 10..50'),
+                .describe('File size filter in KB. Format: ">N" (larger than), "<N" (smaller than), "N..M" (range), "N" (exact).'),
             limit: z
                 .number()
                 .int()
@@ -1130,7 +971,7 @@ function registerGitHubSearchCodeTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Results limit (1-100). Default: 30'),
+                .describe('Maximum number of results to return (1-100). Default: 30. Higher values may increase response time.'),
         },
         annotations: {
             title: 'GitHub Code Search - Smart & Efficient',
@@ -1236,6 +1077,10 @@ function transformToOptimizedFormat$1(items) {
                 : [0, 0]) || [],
         })) || [],
         url: singleRepo ? item.path : simplifyGitHubUrl(item.url),
+        repository: {
+            nameWithOwner: item.repository.nameWithOwner,
+            url: item.repository.url,
+        },
     }));
     const result = {
         items: optimizedItems,
@@ -1262,32 +1107,18 @@ function extractSingleRepository$1(items) {
 }
 /**
  * Build command line arguments for GitHub CLI with improved parameter handling.
- * Ensures exact string search capability with proper quote and escape handling.
- *
- * This function is refactored to correctly distinguish between search qualifiers
- * (like `language` and `extension`), which will be passed as separate arguments
- * to `gh search`, and command-line flags (like `--size` and `--limit`).
+ * Preserves quoted phrases and supports both AND search and exact phrase matching.
  */
 function buildGitHubCliArgs(params) {
     const args = ['code'];
-    // Extract qualifiers from the query
-    const queryParts = params.query.trim().split(/\s+/);
-    const searchTerms = [];
-    const qualifiers = [];
-    queryParts.forEach(part => {
-        if (part.includes(':')) {
-            qualifiers.push(part);
-        }
-        else {
-            searchTerms.push(part);
-        }
-    });
-    // Add search terms if any
-    if (searchTerms.length > 0) {
-        args.push(searchTerms.join(' '));
-    }
-    // Add extracted qualifiers
-    qualifiers.forEach(qualifier => {
+    // Parse query to preserve quoted phrases and extract qualifiers
+    const { searchQuery, extractedQualifiers } = parseSearchQuery(params.query);
+    // Add the main search query if present
+    if (searchQuery) {
+        args.push(searchQuery);
+    }
+    // Add extracted qualifiers from the query
+    extractedQualifiers.forEach(qualifier => {
         args.push(qualifier);
     });
     // Add explicit parameters as qualifiers
@@ -1300,6 +1131,10 @@ function buildGitHubCliArgs(params) {
         const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
         owners.forEach(owner => args.push(`org:${owner}`));
     }
+    if (params.repo && !params.query.includes('repo:')) {
+        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
+        repos.forEach(repo => args.push(`repo:${repo}`));
+    }
     if (params.filename && !params.query.includes('filename:')) {
         args.push(`filename:${params.filename}`);
     }
@@ -1382,12 +1217,48 @@ function validateSearchParameters(params) {
     // }
     return null; // No validation errors
 }
+/**
+ * Parse search query to preserve quoted phrases and extract qualifiers.
+ * Handles:
+ * - Quoted phrases: "error handling" -> kept as single unit
+ * - Multiple terms: react lifecycle -> both terms for AND search
+ * - Mixed: "error handling" debug -> phrase + term
+ * - Qualifiers: language:javascript -> extracted separately
+ */
+function parseSearchQuery(query) {
+    const qualifiers = [];
+    const searchTerms = [];
+    // Regular expression to match quoted strings or individual words/qualifiers
+    const tokenRegex = /"([^"]+)"|([^\s]+)/g;
+    let match;
+    while ((match = tokenRegex.exec(query)) !== null) {
+        const token = match[1] || match[2]; // match[1] is quoted content, match[2] is unquoted
+        // Check if it's a qualifier (contains : but not inside quotes)
+        if (!match[1] && token.includes(':') && /^[a-zA-Z]+:/.test(token)) {
+            qualifiers.push(token);
+        }
+        else {
+            // It's a search term (either quoted or unquoted)
+            if (match[1]) {
+                // Preserve quotes for exact phrase search
+                searchTerms.push(`"${token}"`);
+            }
+            else {
+                searchTerms.push(token);
+            }
+        }
+    }
+    return {
+        searchQuery: searchTerms.join(' '),
+        extractedQualifiers: qualifiers,
+    };
+}
 
 const GITHUB_SEARCH_COMMITS_TOOL_NAME = 'githubSearchCommits';
-const DESCRIPTION$5 = `Search commit history across GitHub repositories. Supports filtering by repository, author, date ranges, and commit attributes. Parameters: query (optional), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), author (optional), authorName (optional), authorEmail (optional), committer (optional), committerName (optional), committerEmail (optional), authorDate (optional), committerDate (optional), hash (optional), parent (optional), tree (optional), merge (optional), visibility (optional), limit (optional), sort (optional), order (optional).`;
+const DESCRIPTION$6 = `Search commit history across GitHub repositories. Find commits by message, author, date, or repository. Supports advanced filtering for comprehensive commit analysis. Returns commit SHA, message, author, and date information.`;
 function registerGitHubSearchCommitsTool(server) {
     server.registerTool(GITHUB_SEARCH_COMMITS_TOOL_NAME, {
-        description: DESCRIPTION$5,
+        description: DESCRIPTION$6,
         inputSchema: {
             query: z
                 .string()
@@ -1397,34 +1268,40 @@ function registerGitHubSearchCommitsTool(server) {
             owner: z
                 .string()
                 .optional()
-                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
+                .describe('Repository owner/organization name only (e.g., "facebook", "microsoft"). Do NOT include repository name. Must be used with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
             // Author filters
             author: z
                 .string()
                 .optional()
                 .describe('GitHub username of commit author'),
-            authorName: z
+            'author-name': z
                 .string()
                 .optional()
                 .describe('Full name of commit author'),
-            authorEmail: z.string().optional().describe('Email of commit author'),
+            'author-email': z
+                .string()
+                .optional()
+                .describe('Email of commit author'),
             // Committer filters
             committer: z
                 .string()
                 .optional()
                 .describe('GitHub username of committer'),
-            committerName: z.string().optional().describe('Full name of committer'),
-            committerEmail: z.string().optional().describe('Email of committer'),
+            'committer-name': z
+                .string()
+                .optional()
+                .describe('Full name of committer'),
+            'committer-email': z.string().optional().describe('Email of committer'),
             // Date filters
-            authorDate: z
+            'author-date': z
                 .string()
                 .optional()
                 .describe('When authored. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
-            committerDate: z
+            'committer-date': z
                 .string()
                 .optional()
                 .describe('When committed. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
@@ -1603,22 +1480,22 @@ function buildGitHubCommitCliArgs(params) {
     // Author filters
     if (params.author)
         args.push(`--author=${params.author}`);
-    if (params.authorName)
-        args.push(`--author-name=${params.authorName}`);
-    if (params.authorEmail)
-        args.push(`--author-email=${params.authorEmail}`);
+    if (params['author-name'])
+        args.push(`--author-name=${params['author-name']}`);
+    if (params['author-email'])
+        args.push(`--author-email=${params['author-email']}`);
     // Committer filters
     if (params.committer)
         args.push(`--committer=${params.committer}`);
-    if (params.committerName)
-        args.push(`--committer-name=${params.committerName}`);
-    if (params.committerEmail)
-        args.push(`--committer-email=${params.committerEmail}`);
+    if (params['committer-name'])
+        args.push(`--committer-name=${params['committer-name']}`);
+    if (params['committer-email'])
+        args.push(`--committer-email=${params['committer-email']}`);
     // Date filters
-    if (params.authorDate)
-        args.push(`--author-date=${params.authorDate}`);
-    if (params.committerDate)
-        args.push(`--committer-date=${params.committerDate}`);
+    if (params['author-date'])
+        args.push(`--author-date=${params['author-date']}`);
+    if (params['committer-date'])
+        args.push(`--committer-date=${params['committer-date']}`);
     // Hash filters
     if (params.hash)
         args.push(`--hash=${params.hash}`);
@@ -1628,7 +1505,7 @@ function buildGitHubCommitCliArgs(params) {
         args.push(`--tree=${params.tree}`);
     // State filters
     if (params.merge !== undefined)
-        args.push(`--merge=${params.merge}`);
+        args.push(`--merge`);
     // Visibility
     if (params.visibility)
         args.push(`--visibility=${params.visibility}`);
@@ -1645,10 +1522,10 @@ function buildGitHubCommitCliArgs(params) {
 }
 
 const GITHUB_SEARCH_ISSUES_TOOL_NAME = 'githubSearchIssues';
-const DESCRIPTION$4 = `Search GitHub issues for bug discovery and feature analysis. Supports filtering by state, labels, assignee, dates, and more. Parameters: query (required), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), app (optional), archived (optional), assignee (optional), author (optional), closed (optional), commenter (optional), comments (optional), created (optional), includePrs (optional), interactions (optional), involves (optional), labels (optional), language (optional), locked (optional), match (optional), mentions (optional), milestone (optional), noAssignee (optional), noLabel (optional), noMilestone (optional), noProject (optional), project (optional), reactions (optional), state (optional), teamMentions (optional), updated (optional), visibility (optional), sort (optional), order (optional), limit (optional).`;
+const DESCRIPTION$5 = `Search GitHub issues for bug reports, feature requests, and discussions. Find issues by keywords, state, labels, author, or repository. Returns issue number, title, state, labels, and metadata for effective issue tracking and analysis.`;
 function registerSearchGitHubIssuesTool(server) {
     server.registerTool(GITHUB_SEARCH_ISSUES_TOOL_NAME, {
-        description: DESCRIPTION$4,
+        description: DESCRIPTION$5,
         inputSchema: {
             query: z
                 .string()
@@ -1658,11 +1535,11 @@ function registerSearchGitHubIssuesTool(server) {
                 .string()
                 .min(1)
                 .optional()
-                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
+                .describe('Repository owner/organization name only (e.g., "facebook", "microsoft"). Do NOT include repository name. Must be used with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
             app: z
                 .string()
                 .optional()
@@ -1678,33 +1555,45 @@ function registerSearchGitHubIssuesTool(server) {
                 .describe('GitHub username of issue creator'),
             closed: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('When closed. Format: >2020-01-01'),
+                .describe('When closed. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "2020-01-01..2023-12-31" (range)'),
             commenter: z
                 .string()
                 .optional()
                 .describe('User who commented on issue'),
             comments: z
-                .number()
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">10", ">=5", "<20", "<=15", "5..20", or exact number "10"'),
+            ])
                 .optional()
-                .describe('Comment count. Format: >10, <5, 5..10'),
+                .describe('Comment count filter. Format: ">10" (many comments), ">=5" (at least 5), "<5" (few comments), "5..10" (range), "10" (exact)'),
             created: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('When created. Format: >2020-01-01'),
-            includePrs: z
+                .describe('When created. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "2020-01-01..2023-12-31" (range)'),
+            'include-prs': z
                 .boolean()
                 .optional()
                 .describe('Include pull requests. Default: false'),
             interactions: z
-                .number()
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">100", ">=50", "<200", "<=150", "50..200", or exact number "100"'),
+            ])
                 .optional()
-                .describe('Total interactions (reactions + comments)'),
+                .describe('Total interactions (reactions + comments) filter. Format: ">100" (highly engaged), ">=50" (moderately engaged), "<20" (low engagement), "50..200" (range)'),
             involves: z.string().optional().describe('User involved in any way'),
-            labels: z
-                .string()
+            label: z
+                .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Label names (bug, feature, etc.)'),
+                .describe('Label names. Can be single string or array.'),
             language: z.string().optional().describe('Repository language'),
             locked: z.boolean().optional().describe('Conversation locked status'),
             match: z
@@ -1713,27 +1602,39 @@ function registerSearchGitHubIssuesTool(server) {
                 .describe('Search scope. Default: title and body'),
             mentions: z.string().optional().describe('Issues mentioning this user'),
             milestone: z.string().optional().describe('Milestone name'),
-            noAssignee: z.boolean().optional().describe('Issues without assignee'),
-            noLabel: z.boolean().optional().describe('Issues without labels'),
-            noMilestone: z
+            'no-assignee': z
+                .boolean()
+                .optional()
+                .describe('Issues without assignee'),
+            'no-label': z.boolean().optional().describe('Issues without labels'),
+            'no-milestone': z
                 .boolean()
                 .optional()
                 .describe('Issues without milestone'),
-            noProject: z.boolean().optional().describe('Issues not in projects'),
+            'no-project': z.boolean().optional().describe('Issues not in projects'),
             project: z.string().optional().describe('Project board number'),
             reactions: z
-                .number()
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">10", ">=5", "<50", "<=25", "5..50", or exact number "10"'),
+            ])
                 .optional()
-                .describe('Reaction count. Format: >10'),
+                .describe('Reaction count filter. Format: ">10" (popular), ">=5" (some reactions), "<50" (moderate), "5..50" (range), "10" (exact)'),
             state: z
                 .enum(['open', 'closed'])
                 .optional()
                 .describe('Issue state. Default: all'),
-            teamMentions: z.string().optional().describe('Team mentioned in issue'),
+            'team-mentions': z
+                .string()
+                .optional()
+                .describe('Team mentioned in issue (@org/team-name)'),
             updated: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('When updated. Format: >2020-01-01'),
+                .describe('When updated. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "2020-01-01..2023-12-31" (range)'),
             visibility: z
                 .enum(['public', 'private', 'internal'])
                 .optional()
@@ -1889,23 +1790,40 @@ function buildGitHubIssuesAPICommand(params) {
             queryParts.push(`${key}:${value}`);
     });
     // Special qualifiers - handle labels carefully
-    if (params.labels) {
-        queryParts.push(`label:"${params.labels}"`);
+    if (params.label) {
+        const labels = Array.isArray(params.label) ? params.label : [params.label];
+        labels.forEach(label => queryParts.push(`label:"${label}"`));
     }
     if (params.milestone)
         queryParts.push(`milestone:"${params.milestone}"`);
-    if (params.noAssignee)
+    if (params['no-assignee'])
         queryParts.push('no:assignee');
-    if (params.noLabel)
+    if (params['no-label'])
         queryParts.push('no:label');
-    if (params.noMilestone)
+    if (params['no-milestone'])
         queryParts.push('no:milestone');
+    if (params['no-project'])
+        queryParts.push('no:project');
     if (params.archived !== undefined)
         queryParts.push(`archived:${params.archived}`);
     if (params.locked)
         queryParts.push('is:locked');
     if (params.visibility)
         queryParts.push(`is:${params.visibility}`);
+    if (params['include-prs'])
+        queryParts.push('is:pr');
+    if (params['team-mentions'])
+        queryParts.push(`team:${params['team-mentions']}`);
+    if (params.project)
+        queryParts.push(`project:${params.project}`);
+    if (params.app)
+        queryParts.push(`app:${params.app}`);
+    if (params.comments)
+        queryParts.push(`comments:${params.comments}`);
+    if (params.interactions)
+        queryParts.push(`interactions:${params.interactions}`);
+    if (params.reactions)
+        queryParts.push(`reactions:${params.reactions}`);
     // Extract qualifiers from original query and add them if not already set by params
     if (baseQuery.includes('is:') && !params.state) {
         const isMatch = baseQuery.match(/\bis:(open|closed)\b/i);
@@ -1913,7 +1831,7 @@ function buildGitHubIssuesAPICommand(params) {
             queryParts.push(`state:${isMatch[1].toLowerCase()}`);
         }
     }
-    if (baseQuery.includes('label:') && !params.labels) {
+    if (baseQuery.includes('label:') && !params.label) {
         const labelMatch = baseQuery.match(/\blabel:("[^"]*"|[^\s]+)/i);
         if (labelMatch) {
             const labelValue = labelMatch[1].replace(/"/g, '');
@@ -1938,10 +1856,10 @@ function buildGitHubIssuesAPICommand(params) {
 
 // TODO: add PR commeents. e.g, gh pr view <PR_NUMBER_OR_URL_OR_BRANCH> --comments
 const GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME = 'githubSearchPullRequests';
-const DESCRIPTION$3 = `Search pull requests for implementation discovery and code review analysis. Supports filtering by state, review status, branches, and more. Parameters: query (required), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), author (optional), assignee (optional), mentions (optional), commenter (optional), involves (optional), reviewedBy (optional), reviewRequested (optional), state (optional), head (optional), base (optional), language (optional), created (optional), updated (optional), mergedAt (optional), closed (optional), draft (optional), checks (optional), merged (optional), review (optional), limit (optional), sort (optional), order (optional).`;
+const DESCRIPTION$4 = `Search GitHub pull requests for code changes, feature implementations, and bug fixes. Find PRs by keywords, state, author, review status, or repository. Returns PR number, title, state, branches, and review information for code review analysis.`;
 function registerSearchGitHubPullRequestsTool(server) {
     server.registerTool(GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME, {
-        description: DESCRIPTION$3,
+        description: DESCRIPTION$4,
         inputSchema: {
             query: z
                 .string()
@@ -1950,18 +1868,21 @@ function registerSearchGitHubPullRequestsTool(server) {
             owner: z
                 .string()
                 .optional()
-                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
+                .describe('Repository owner/organization name only (e.g., "facebook", "microsoft"). Do NOT include repository name. Must be used with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
             author: z.string().optional().describe('GitHub username of PR author'),
             assignee: z.string().optional().describe('GitHub username of assignee'),
             mentions: z.string().optional().describe('PRs mentioning this user'),
             commenter: z.string().optional().describe('User who commented on PR'),
             involves: z.string().optional().describe('User involved in any way'),
-            reviewedBy: z.string().optional().describe('User who reviewed the PR'),
-            reviewRequested: z
+            'reviewed-by': z
+                .string()
+                .optional()
+                .describe('User who reviewed the PR'),
+            'review-requested': z
                 .string()
                 .optional()
                 .describe('User/team requested for review'),
@@ -1970,10 +1891,7 @@ function registerSearchGitHubPullRequestsTool(server) {
                 .optional()
                 .describe('PR state. Default: all'),
             head: z.string().optional().describe('Source branch name'),
-            base: z
-                .string()
-                .optional()
-                .describe('Target branch name (main, develop, etc.)'),
+            base: z.string().optional().describe('Target branch name'),
             language: z.string().optional().describe('Repository language'),
             created: z
                 .string()
@@ -1983,7 +1901,7 @@ function registerSearchGitHubPullRequestsTool(server) {
                 .string()
                 .optional()
                 .describe('When updated. Format: >2020-01-01'),
-            mergedAt: z
+            'merged-at': z
                 .string()
                 .optional()
                 .describe('When merged. Format: >2020-01-01'),
@@ -2004,6 +1922,49 @@ function registerSearchGitHubPullRequestsTool(server) {
                 .enum(['none', 'required', 'approved', 'changes_requested'])
                 .optional()
                 .describe('Review status filter'),
+            app: z.string().optional().describe('GitHub App that created the PR'),
+            archived: z
+                .boolean()
+                .optional()
+                .describe('Include archived repositories'),
+            comments: z
+                .number()
+                .optional()
+                .describe('Comment count filter. Format: >10, <5, 5..10'),
+            interactions: z
+                .number()
+                .optional()
+                .describe('Total interactions (reactions + comments)'),
+            'team-mentions': z
+                .string()
+                .optional()
+                .describe('Team mentioned in PR (@org/team-name)'),
+            reactions: z
+                .number()
+                .optional()
+                .describe('Reaction count filter. Format: >10'),
+            locked: z.boolean().optional().describe('Conversation locked status'),
+            'no-assignee': z.boolean().optional().describe('PRs without assignee'),
+            'no-label': z.boolean().optional().describe('PRs without labels'),
+            'no-milestone': z
+                .boolean()
+                .optional()
+                .describe('PRs without milestone'),
+            'no-project': z.boolean().optional().describe('PRs not in projects'),
+            label: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('Label names. Can be single string or array.'),
+            milestone: z.string().optional().describe('Milestone title'),
+            project: z.string().optional().describe('Project board owner/number'),
+            visibility: z
+                .enum(['public', 'private', 'internal'])
+                .optional()
+                .describe('Repository visibility'),
+            match: z
+                .enum(['title', 'body', 'comments'])
+                .optional()
+                .describe('Search scope. Default: title and body'),
             limit: z
                 .number()
                 .int()
@@ -2138,16 +2099,16 @@ function buildGitHubPullRequestsAPICommand(params) {
             queryParts.push(`${key}:${value}`);
     });
     // Special qualifiers
-    if (params.reviewedBy)
-        queryParts.push(`reviewed-by:${params.reviewedBy}`);
-    if (params.reviewRequested)
-        queryParts.push(`review-requested:${params.reviewRequested}`);
+    if (params['reviewed-by'])
+        queryParts.push(`reviewed-by:${params['reviewed-by']}`);
+    if (params['review-requested'])
+        queryParts.push(`review-requested:${params['review-requested']}`);
     if (params.head)
         queryParts.push(`head:${params.head}`);
     if (params.base)
         queryParts.push(`base:${params.base}`);
-    if (params.mergedAt)
-        queryParts.push(`merged:${params.mergedAt}`);
+    if (params['merged-at'])
+        queryParts.push(`merged:${params['merged-at']}`);
     if (params.draft !== undefined)
         queryParts.push(`draft:${params.draft}`);
     if (params.checks)
@@ -2156,6 +2117,39 @@ function buildGitHubPullRequestsAPICommand(params) {
         queryParts.push(`is:${params.merged ? 'merged' : 'unmerged'}`);
     if (params.review)
         queryParts.push(`review:${params.review}`);
+    // Additional parameters
+    if (params.app)
+        queryParts.push(`app:${params.app}`);
+    if (params.archived !== undefined)
+        queryParts.push(`archived:${params.archived}`);
+    if (params.comments)
+        queryParts.push(`comments:${params.comments}`);
+    if (params.interactions)
+        queryParts.push(`interactions:${params.interactions}`);
+    if (params.reactions)
+        queryParts.push(`reactions:${params.reactions}`);
+    if (params.locked)
+        queryParts.push('is:locked');
+    if (params.visibility)
+        queryParts.push(`is:${params.visibility}`);
+    if (params['team-mentions'])
+        queryParts.push(`team:${params['team-mentions']}`);
+    if (params['no-assignee'])
+        queryParts.push('no:assignee');
+    if (params['no-label'])
+        queryParts.push('no:label');
+    if (params['no-milestone'])
+        queryParts.push('no:milestone');
+    if (params['no-project'])
+        queryParts.push('no:project');
+    if (params.label) {
+        const labels = Array.isArray(params.label) ? params.label : [params.label];
+        labels.forEach(label => queryParts.push(`label:"${label}"`));
+    }
+    if (params.milestone)
+        queryParts.push(`milestone:"${params.milestone}"`);
+    if (params.project)
+        queryParts.push(`project:${params.project}`);
     // Add type qualifier to search only pull requests
     queryParts.push('type:pr');
     const query = queryParts.filter(Boolean).join(' ');
@@ -2185,11 +2179,27 @@ function buildGitHubPullRequestsAPICommand(params) {
  * 4. Recent Quality:
  * { stars: ">1000", created: ">2023-01-01", limit: 10 }
  *
+ * RESEARCH & EXPLORATION PATTERNS:
+ *
+ * 1. Topic-based Discovery (HIGHLY RECOMMENDED for unknown projects):
+ * { topic: ["machine-learning", "nlp", "pytorch"], limit: 20 }
+ * { topic: ["kubernetes", "monitoring"], stars: ">100", limit: 15 }
+ *
+ * 2. Exploratory Research Flow:
+ * - Start with topics to discover repositories
+ * - Then use githubViewRepoStructure to understand project layout
+ * - Read README.md, docs/, and configuration files
+ * - Finally use githubSearchCode for specific implementations
+ *
  * AVOID: OR queries + language filter, 5+ filters, multi-word OR
  * TIP: Use limit parameter instead of adding more filters
  */
 const GITHUB_SEARCH_REPOSITORIES_TOOL_NAME = 'githubSearchRepositories';
-const DESCRIPTION$2 = `Discover GitHub repositories with smart filtering. Supports language, stars, topics, ownership, dates, and community metrics. Parameters: query (optional), owner (optional - GitHub username/org, NOT owner/repo), language (optional), stars (optional), topic (optional), forks (optional), numberOfTopics (optional), license (optional), archived (optional), includeForks (optional), visibility (optional), created (optional), updated (optional), size (optional), goodFirstIssues (optional), helpWantedIssues (optional), followers (optional), match (optional), sort (optional), order (optional), limit (optional).`;
+const DESCRIPTION$3 = `Search GitHub repositories by name, description, topics, language, or organization. Find projects based on stars, forks, activity, and community metrics. Returns repository details including name, description, stars, language, and owner information for project discovery.
+
+Search Syntax - ALL terms must be present (AND logic):
+Multiple search terms require ALL to be found in the repository (name, description, or README).
+Use quotes for exact phrase matching. Additional filters supported via parameters.`;
 /**
  * Extract owner/repo information from various query formats
  */
@@ -2222,70 +2232,88 @@ function extractOwnerRepoFromQuery(query) {
 }
 function registerSearchGitHubReposTool(server) {
     server.registerTool(GITHUB_SEARCH_REPOSITORIES_TOOL_NAME, {
-        description: DESCRIPTION$2,
+        description: DESCRIPTION$3,
         inputSchema: {
             query: z
                 .string()
                 .optional()
-                .describe('Search query. START SIMPLE: Use 1-2 words with NO filters first (e.g., "react", "auth"). Add qualifiers only after initial search.'),
+                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases.'),
             // CORE FILTERS (GitHub CLI flags)
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner or organization name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). For private repos, use organizations from api_status_check (user_organizations). Can be a single value or array.'),
+                .describe('Repository owner/organization name(s) (e.g., "facebook", ["google", "microsoft"]). Search within specific organizations. Do NOT use owner/repo format - just the organization/username.'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter. Use when results need refinement.'),
+                .describe('Programming language filter. Filters repositories by primary language. Essential for language-specific searches.'),
             stars: z
                 .union([
                 z.number().int().min(0),
-                z.string().regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "10..100", or exact number "50"'),
             ])
                 .optional()
-                .describe('Stars filter. Supports ranges and thresholds.'),
+                .describe('Star count filter. Format: ">1000" (more than), ">=500" (more than or equal), "<100" (less than), "<=50" (less than or equal), "100..1000" (range), "500" (exact).'),
             topic: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Topics filter. Can be a single value or array.'),
-            forks: z.number().optional().describe('Number of forks filter.'),
-            // UPDATED: Match CLI parameter name exactly
-            numberOfTopics: z
-                .number()
+                .describe('Repository topics filter. Excellent for discovering projects and understanding repository ecosystems. Topics use kebab-case format.'),
+            forks: z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">100", ">=50", "<10", "<=5", "10..100", or exact number "5"'),
+            ])
+                .optional()
+                .describe('Fork count filter. Format: ">100" (more than), ">=50" (more than or equal), "<10" (less than), "<=5" (less than or equal), "10..100" (range), "5" (exact).'),
+            // Match CLI parameter name exactly
+            'number-topics': z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">5", ">=3", "<10", "<=2", "3..10", or exact number "5"'),
+            ])
                 .optional()
-                .describe('Filter by number of topics (indicates documentation quality).'),
+                .describe('Number of topics filter. Format: ">5" (many topics), ">=3" (at least 3), "<10" (few topics), "1..3" (range), "5" (exact).'),
             // QUALITY & STATE FILTERS
             license: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('License filter. Works well as array ["mit", "apache-2.0"].'),
+                .describe('License filter.'),
             archived: z
                 .boolean()
                 .optional()
-                .describe('Filter archived repositories (true/false).'),
-            includeForks: z
+                .describe('Archive status filter. false (active repos only), true (archived repos only).'),
+            'include-forks': z
                 .enum(['false', 'true', 'only'])
                 .optional()
-                .describe('Include forks: false (exclude), true (include), only (forks only).'),
+                .describe('Fork inclusion. "false" (exclude forks), "true" (include forks), "only" (forks only).'),
             visibility: z
                 .enum(['public', 'private', 'internal'])
                 .optional()
-                .describe('Repository visibility filter.'),
+                .describe('Repository visibility.'),
             // DATE & SIZE FILTERS
             created: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('Created date filter. Format: ">2020-01-01", "<2023-12-31".'),
+                .describe('Repository creation date filter. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "<=2023-12-31" (on or before), "2020-01-01..2023-12-31" (range), "2023-01-01" (exact).'),
             updated: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2024-01-01", ">=2024-01-01", "<2022-01-01", "<=2022-01-01", "2023-01-01..2024-12-31", or exact date "2024-01-01"')
                 .optional()
-                .describe('Updated date filter. Good for finding active projects.'),
+                .describe('Last updated date filter. Format: ">2024-01-01" (recently updated), ">=2024-01-01" (on or after), "<2022-01-01" (not recently updated), "2023-01-01..2024-12-31" (range).'),
             size: z
                 .string()
+                .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">1000", ">=500", "<100", "<=50", "100..1000", or exact number "500"')
                 .optional()
-                .describe('Repository size filter in KB. Format: ">1000", "<500".'),
+                .describe('Repository size filter in KB. Format: ">1000" (large projects), ">=500" (medium-large), "<100" (small projects), "<=50" (tiny), "100..1000" (medium range), "500" (exact).'),
             // COMMUNITY FILTERS - Match CLI parameter names exactly
-            goodFirstIssues: z
+            'good-first-issues': z
                 .union([
                 z.number().int().min(0),
                 z
@@ -2293,8 +2321,8 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
             ])
                 .optional()
-                .describe('Good first issues count. WORKING: Filter for beginner-friendly projects. EXCELLENT when combined with stars "100..5000" for quality beginner projects.'),
-            helpWantedIssues: z
+                .describe('Good first issues count. Format: ">5" (many beginner issues), "1..10" (some beginner issues).'),
+            'help-wanted-issues': z
                 .union([
                 z.number().int().min(0),
                 z
@@ -2302,13 +2330,24 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
             ])
                 .optional()
-                .describe('Help wanted issues count. Good for finding projects needing contributors.'),
-            followers: z.number().optional().describe('Followers count filter.'),
-            // SEARCH SCOPE
+                .describe('Help wanted issues count. Format: ">10" (many help wanted), "1..5" (some help wanted).'),
+            followers: z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "100..1000", or exact number "500"'),
+            ])
+                .optional()
+                .describe('Repository owner followers count. Format: ">1000" (popular developers), ">=500" (established developers), "<100" (smaller developers), "100..1000" (range).'),
+            // SEARCH SCOPE - Match CLI exactly
             match: z
-                .enum(['name', 'description', 'readme'])
+                .union([
+                z.enum(['name', 'description', 'readme']),
+                z.array(z.enum(['name', 'description', 'readme'])),
+            ])
                 .optional()
-                .describe('Search scope: name, description, or readme content.'),
+                .describe('Search scope. "name" (repository names only), "description" (descriptions only), "readme" (README content). Can be single value or array.'),
             // SORTING & LIMITS - Match CLI defaults exactly
             sort: z
                 .enum([
@@ -2320,7 +2359,7 @@ function registerSearchGitHubReposTool(server) {
             ])
                 .optional()
                 .default('best-match')
-                .describe('Sort criteria for results.'),
+                .describe('Sort criteria.'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
@@ -2333,7 +2372,7 @@ function registerSearchGitHubReposTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Maximum results to return (1-100). Default: 30'),
+                .describe('Maximum number of repositories to return (1-100).'),
         },
         annotations: {
             title: 'GitHub Repository Search',
@@ -2534,13 +2573,13 @@ function buildGitHubReposSearchCommand(params) {
     // CORE FILTERS
     addArg('owner', 'owner', !hasEmbeddedQualifiers);
     addArg('language', 'language', !hasEmbeddedQualifiers);
-    addArg('forks', 'forks', !hasEmbeddedQualifiers);
+    addArg('forks', 'forks', !hasEmbeddedQualifiers, value => typeof value === 'number' ? value.toString() : value.trim());
     addArg('topic', 'topic', !hasEmbeddedQualifiers);
-    addArg('numberOfTopics', 'number-topics');
+    addArg('number-topics', 'number-topics', true, value => typeof value === 'number' ? value.toString() : value.trim());
     addArg('stars', 'stars', !hasEmbeddedQualifiers, value => typeof value === 'number' ? value.toString() : value.trim());
     // QUALITY & STATE FILTERS
     addArg('archived', 'archived');
-    addArg('includeForks', 'include-forks');
+    addArg('include-forks', 'include-forks');
     addArg('visibility', 'visibility');
     addArg('license', 'license');
     // DATE & SIZE FILTERS
@@ -2548,9 +2587,9 @@ function buildGitHubReposSearchCommand(params) {
     addArg('updated', 'updated');
     addArg('size', 'size');
     // COMMUNITY FILTERS
-    addArg('goodFirstIssues', 'good-first-issues', true, value => typeof value === 'number' ? value.toString() : value);
-    addArg('helpWantedIssues', 'help-wanted-issues', true, value => typeof value === 'number' ? value.toString() : value);
-    addArg('followers', 'followers');
+    addArg('good-first-issues', 'good-first-issues', true, value => typeof value === 'number' ? value.toString() : value);
+    addArg('help-wanted-issues', 'help-wanted-issues', true, value => typeof value === 'number' ? value.toString() : value);
+    addArg('followers', 'followers', true, value => typeof value === 'number' ? value.toString() : value.trim());
     // SEARCH SCOPE
     addArg('match', 'match');
     // SORTING AND LIMITS
@@ -2563,8 +2602,258 @@ function buildGitHubReposSearchCommand(params) {
     return { command: 'search', args };
 }
 
+const GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME = 'githubViewRepoStructure';
+const DESCRIPTION$2 = `Browse GitHub repository file structure and navigate directories. Essential for exploring project layout, finding documentation, configuration files, and source code. Returns file/folder listings with size information. Automatically handles branch detection. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), path (optional - directory path).`;
+function registerViewRepositoryStructureTool(server) {
+    server.registerTool(GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME, {
+        description: DESCRIPTION$2,
+        inputSchema: {
+            owner: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, 'Invalid GitHub username/org format')
+                .describe('Repository owner/organization name (e.g., "facebook", "microsoft"). Do NOT include repository name.'),
+            repo: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-zA-Z0-9._-]+$/, 'Invalid repository name format')
+                .describe(`Repository name under a organization. `),
+            branch: z
+                .string()
+                .min(1)
+                .max(255)
+                .regex(/^[^\s]+$/, 'Branch name cannot contain spaces')
+                .describe('Branch name (e.g., "main", "master", "develop"). Tool will automatically try default branch if specified branch is not found.'),
+            path: z
+                .string()
+                .optional()
+                .default('')
+                .refine(path => !path.includes('..'), 'Path traversal not allowed')
+                .refine(path => path.length <= 500, 'Path too long')
+                .describe('Directory path within repository (e.g., "src", "docs", "src/components"). Leave empty for root directory. Do NOT start with slash.'),
+        },
+        annotations: {
+            title: 'GitHub Repository Explorer',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            const result = await viewRepositoryStructure(args);
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            return createResult({
+                error: `Failed to explore repository. ${errorMessage}. Verify repository exists and is accessible`,
+            });
+        }
+    });
+}
+/**
+ * Views the structure of a GitHub repository at a specific path.
+ * Optimized for code analysis workflows with smart defaults and clear errors.
+ */
+async function viewRepositoryStructure(params) {
+    const cacheKey = generateCacheKey('gh-repo-structure', params);
+    return withCache(cacheKey, async () => {
+        const { owner, repo, branch, path = '' } = params;
+        try {
+            // Clean up path
+            const cleanPath = path.startsWith('/') ? path.substring(1) : path;
+            // Try the requested branch first, then fallback to main/master
+            const branchesToTry = await getSmartBranchFallback(owner, repo, branch);
+            let items = [];
+            let usedBranch = branch;
+            let lastError = null;
+            let attemptCount = 0;
+            const maxAttempts = branchesToTry.length;
+            const triedBranches = [];
+            for (const tryBranch of branchesToTry) {
+                if (attemptCount >= maxAttempts)
+                    break;
+                attemptCount++;
+                triedBranches.push(tryBranch);
+                try {
+                    const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
+                    const result = await executeGitHubCommand('api', [apiPath], {
+                        cache: false,
+                    });
+                    if (!result.isError) {
+                        const execResult = JSON.parse(result.content[0].text);
+                        const apiItems = execResult.result;
+                        items = Array.isArray(apiItems) ? apiItems : [apiItems];
+                        usedBranch = tryBranch;
+                        break;
+                    }
+                    else {
+                        lastError = new Error(result.content[0].text);
+                    }
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    continue;
+                }
+            }
+            if (items.length === 0) {
+                // Check repository existence only after content fetch fails
+                const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+                    cache: false,
+                });
+                if (repoCheckResult.isError) {
+                    const repoErrorMsg = repoCheckResult.content[0].text;
+                    if (repoErrorMsg.includes('404')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" not found. It might have been deleted, renamed, or made private. Use github_search_code to find current location.`,
+                        });
+                    }
+                    else if (repoErrorMsg.includes('403')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" exists but access is denied. Repository might be private or archived. Use api_status_check to verify permissions.`,
+                        });
+                    }
+                }
+                const errorMsg = lastError?.message || 'Unknown error';
+                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
+                    if (path) {
+                        const searchSuggestion = await suggestPathSearchFallback(owner, path);
+                        return createResult({
+                            error: `Path "${path}" not found in any branch (tried: ${triedBranches.join(', ')}).${searchSuggestion}`,
+                        });
+                    }
+                    else {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" structure not accessible. Repository might be empty, private, or you might not have sufficient permissions. Use github_search_code with owner="${owner}" to find accessible repositories.`,
+                        });
+                    }
+                }
+                else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                    return createResult({
+                        error: `Access denied to "${owner}/${repo}". Repository exists but might be private/archived. Use api_status_check to verify permissions, or github_search_code with owner="${owner}" to find accessible repositories.`,
+                    });
+                }
+                else {
+                    const searchSuggestion = path
+                        ? await suggestPathSearchFallback(owner, path)
+                        : '';
+                    return createResult({
+                        error: `Failed to access "${owner}/${repo}": ${errorMsg}. Check network connection and repository permissions.${searchSuggestion}`,
+                    });
+                }
+            }
+            // Limit total items to 100 for efficiency
+            const limitedItems = items.slice(0, 100);
+            // Sort: directories first, then alphabetically
+            limitedItems.sort((a, b) => {
+                if (a.type !== b.type) {
+                    return a.type === 'dir' ? -1 : 1;
+                }
+                return a.name.localeCompare(b.name);
+            });
+            // Create simplified, token-efficient structure
+            const files = limitedItems
+                .filter(item => item.type === 'file')
+                .map(item => ({
+                name: item.name,
+                size: item.size,
+                url: item.path, // Use path for fetching
+            }));
+            const folders = limitedItems
+                .filter(item => item.type === 'dir')
+                .map(item => ({
+                name: item.name,
+                url: item.path, // Use path for browsing
+            }));
+            return createResult({
+                data: {
+                    repository: `${owner}/${repo}`,
+                    branch: usedBranch,
+                    path: cleanPath || '/',
+                    githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
+                    files: {
+                        count: files.length,
+                        files: files,
+                    },
+                    folders: {
+                        count: folders.length,
+                        folders: folders,
+                    },
+                },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return createResult({
+                error: `Failed to access repository "${owner}/${repo}": ${errorMessage}. Verify repository name, permissions, and network connection.`,
+            });
+        }
+    });
+}
+/**
+ * Smart branch detection with automatic fallback to common branch names.
+ * Now includes more comprehensive branch detection and better error handling.
+ */
+async function getSmartBranchFallback(owner, repo, requestedBranch) {
+    const branches = new Set([requestedBranch]);
+    try {
+        // Try to get repository info to find default branch
+        const repoInfoResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+            cache: false,
+        });
+        if (!repoInfoResult.isError) {
+            const execResult = JSON.parse(repoInfoResult.content[0].text);
+            const repoData = execResult.result;
+            const defaultBranch = repoData.default_branch;
+            if (defaultBranch) {
+                branches.add(defaultBranch);
+            }
+        }
+    }
+    catch {
+        // If we can't get repo info, proceed with standard fallbacks
+    }
+    // Add only main/master as fallback branches
+    const commonBranches = ['main', 'master'];
+    commonBranches.forEach(branch => branches.add(branch));
+    // Convert Set back to array, with requested branch first
+    const branchesArray = Array.from(branches);
+    branchesArray.sort((a, b) => {
+        if (a === requestedBranch)
+            return -1;
+        if (b === requestedBranch)
+            return 1;
+        return 0;
+    });
+    return branchesArray;
+}
+// Helper function to suggest path search strategy
+async function suggestPathSearchFallback(owner, path) {
+    try {
+        // Extract last path segment and try to find in same organization
+        const pathSegment = path.split('/').pop() || path;
+        const searchResult = await executeGitHubCommand('api', [
+            `/search/code?q=${encodeURIComponent(pathSegment)}+in:path+org:${owner}`,
+        ], { cache: false });
+        if (!searchResult.isError) {
+            const results = JSON.parse(searchResult.content[0].text);
+            if (results.total_count > 0) {
+                const firstMatch = results.items[0];
+                return ` Directory might be in ${firstMatch.repository.full_name}. Try these searches:\n1. github_search_code with query="${pathSegment}" owner="${owner}"\n2. github_search_code with query="path:${path}" owner="${owner}"`;
+            }
+        }
+    }
+    catch {
+        // Fallback to generic message if search fails
+    }
+    return ` Try these searches:\n1. github_search_code with query="${path.split('/').pop()}" owner="${owner}"\n2. github_search_code with query="path:${path}"`;
+}
+
 const NPM_PACKAGE_SEARCH_TOOL_NAME = 'npmPackageSearch';
-const DESCRIPTION$1 = `Search NPM packages with fuzzy matching. Supports multiple search terms and aggregates results. Use functional keywords like "react hooks", "auth", or "testing". Parameters: queries (required, string or array), searchLimit (optional).`;
+const DESCRIPTION$1 = `Search NPM packages by name or functionality keywords. Supports multiple search terms for comprehensive package discovery. Returns package name, version, description, keywords, and repository information. Best for finding JavaScript/TypeScript libraries and tools.`;
 const MAX_DESCRIPTION_LENGTH = 100;
 const MAX_KEYWORDS = 10;
 function registerNpmSearchTool(server) {
@@ -2573,7 +2862,7 @@ function registerNpmSearchTool(server) {
         inputSchema: {
             queries: z
                 .union([z.string(), z.array(z.string())])
-                .describe('Search terms for packages. Use functionality keywords: "react hooks", "cli tool", "testing"'),
+                .describe('Search terms for NPM packages (e.g., "react hooks", ["typescript", "eslint"], "data visualization"). Use functionality keywords rather than exact package names for best results.'),
             searchLimit: z
                 .number()
                 .int()
@@ -2667,13 +2956,12 @@ function parseNpmSearchOutput(output) {
         return packages.map(normalizePackage);
     }
     catch (error) {
-        logger.warn('Failed to parse NPM search results:', error);
         return [];
     }
 }
 
 const NPM_VIEW_PACKAGE_TOOL_NAME = 'npmViewPackage';
-const DESCRIPTION = `View detailed NPM package information including repository URL, exports, version history, dependencies, and download stats. Returns optimized metadata for code navigation. Parameters: packageName (required).`;
+const DESCRIPTION = `Get detailed NPM package information including version, description, repository URL, size, and download statistics. Essential for understanding package details before installation. Returns optimized metadata for package evaluation and code navigation.`;
 function registerNpmViewPackageTool(server) {
     server.registerTool(NPM_VIEW_PACKAGE_TOOL_NAME, {
         description: DESCRIPTION,
@@ -2681,7 +2969,7 @@ function registerNpmViewPackageTool(server) {
             packageName: z
                 .string()
                 .min(1)
-                .describe('NPM package name (e.g., "react", "express", "@types/node")'),
+                .describe('NPM package name (e.g., "react", "express", "@types/node"). Include @ prefix for scoped packages.'),
         },
         annotations: {
             title: 'NPM Package Analyzer',
@@ -2831,133 +3119,125 @@ using gh cli for github and npm cli for packages.
 
 CRITICAL SEARCH PRINCIPLES:
 
-## 1. PROGRESSIVE SEARCH STRATEGY (MOST IMPORTANT):
-   a) START BROAD: Begin with simple, general terms (1-2 words max)
-   b) ANALYZE RESULTS: Learn from what you find (repo names, owners, common patterns)
-   c) REFINE GRADUALLY: Add filters only after understanding the landscape
+PROGRESSIVE SEARCH STRATEGY (MOST IMPORTANT):
+   a) START BROAD: Begin with simple, general queries and terms (1-2 words max)
+   b) ANALYZE RESULTS: Learn from what you find
+   c) REFINE GRADUALLY: Add filters only after understanding the landscape and if needed (only if the user asks for it explicitly)
    d) MULTIPLE ANGLES: Try different search terms if first approach yields no results
 
-## 2. SEARCH PROGRESSION EXAMPLES:
-   - User asks about "React state management"
-     1st search: "state" or "redux" (BROAD)
-     2nd search: "react state" with language:javascript (REFINED)
-     3rd search: owner:facebook with specific terms (TARGETED)
-   
-   - User asks about "authentication libraries"
-     1st search: "auth" or "authentication" (BROAD)
-     2nd search: Add language filter based on results
-     3rd search: Focus on specific owners/topics found
+HANDLING NO RESULTS:
+   - NEVER give up after one failed search. 
+   - Act on fallbacks messages and try to understand the user's intent.
+   - Try progressively BROADER terms (simplify queries and remove filters)
 
-## 3. HANDLING NO RESULTS:
-   - NEVER give up after one failed search
-   - Try progressively BROADER terms
-   - Remove ALL filters and try core keywords
-   - Search for related concepts (e.g., "auth" → "login" → "session")
-   - Check different owners/organizations
-   - For code search: try searching in popular repos first
-
-## 4. SMART FILTER USAGE:
+SMART FILTER USAGE:
    - NO FILTERS on first search (unless user specifies)
    - Add ONE filter at a time based on results
-   - Common progression: query → +language → +stars → +owner
+   - Common progression: query → +language → +stars → +owner (only if user asks for it explicitly)
    - Reserve complex filters for final refinement
 
-## 5. TOOL SYNERGY:
-   - Use repository search to find relevant repos FIRST
-   - Then use code search within those repos
-   - Check npm packages for JavaScript/TypeScript queries
-   - Verify access with api_status_check for private repos
-
-## 6. RESEARCH BEST PRACTICES:
+RESEARCH BEST PRACTICES:
    - Conduct COMPREHENSIVE research with multiple searches
    - Learn from each search to improve the next
    - Provide context about your search strategy
    - Always verify technical details with actual code
 
-## 7. COMPLEX ANALYSIS PATTERNS:
+COMPLEX ANALYSIS PATTERNS:
 
-### Multi-Framework Comparison (e.g., React vs Vue):
-   1. Search repos separately: "react", then "vue"
-   2. Find core implementation files: "scheduler" in React, "reactivity" in Vue
-   3. Search specific features: "concurrent", "fiber", "proxy"
+Multi-terms Comparison
+   1. Search repos separately: "repoA", then "repoB"
+   2. Review repositories structure and files
+   3. Review code and documentation
    4. Compare similar functionalities across repos
+   5. Use filters and flags to narrow down the results
 
-### Architecture Analysis (e.g., State Management):
-   1. Start broad: "state" or "store"
-   2. Identify major libraries: Redux, Zustand, Jotai
-   3. Search implementation patterns: "reducer", "atom", "selector"
-   4. Analyze each approach separately, then compare
-
-### Evolution Tracking (e.g., Feature History):
+Evolution Tracking (e.g., Feature History):
    1. Use commit search with broad terms first
    2. Narrow by date ranges progressively
    3. Track changes in specific files over time
    4. Identify key contributors and their patterns
 
-### Performance Analysis:
-   1. Search for benchmarks: "benchmark", "perf", "performance"
-   2. Look for optimization commits: "optimize", "faster", "improve"
-   3. Find profiling code: "profile", "measure", "timing"
-   4. Compare implementation strategies
-
-## 8. CROSS-REPOSITORY INTELLIGENCE:
+CROSS-REPOSITORY INTELLIGENCE:
    - When comparing frameworks, search EACH separately first
    - Build mental model of each codebase structure
-   - Use discovered patterns to refine searches
-   - Connect findings across repositories for insights
+   - Use discovered patterns to refine searches and connect findings across repositories for insights
+
+RESEARCH WORKFLOW BEST PRACTICES:
+
+Discovery Phase (Unknown Projects/Topics):
+   - START with ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME} using TOPICS
+   - Topics are underutilized but extremely powerful for discovery
+   - Example: { topic: ["react", "typescript", "testing"], stars: ">500" }
+
+Understanding Phase
+   - ALWAYS use ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} first to verify repository exists
+   - CRITICAL: Many failures are due to incorrect repository names - verify before proceeding
+   - Check README.md, docs/, configuration files
+   - Understand project structure before searching code
+   - Never make assumptions about repository names or file locations - always verify
+
+Implementation Search (Specific Code):
+   - Fetch importnat files using ${GITHUB_GET_FILE_CONTENT_TOOL_NAME}
+   - Use ${GITHUB_SEARCH_CODE_TOOL_NAME} with NARROW queries
+   - Start precise, broaden only if needed
+   - Use exact phrases when you know patterns
+   - Verify dependences and imports
+
+File Access Validation Workflow:
+   1. VERIFY repository name first with ${GITHUB_SEARCH_CODE_TOOL_NAME} if unsure
+   2. Use ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} to confirm repository structure
+   3. Navigate to parent directory first to understand layout
+   4. Only then use ${GITHUB_GET_FILE_CONTENT_TOOL_NAME} with confirmed paths
+   5. Most "file not found" errors are due to incorrect repository names
 
-## 9. TOOL-SPECIFIC BEST PRACTICES:
+TOOL-SPECIFIC BEST PRACTICES:
 
-### ${API_STATUS_CHECK_TOOL_NAME}:
+${API_STATUS_CHECK_TOOL_NAME}:
    - Run FIRST when dealing with private repositories
    - Use organizations list to scope searches
    - Verify authentication before extensive searches
 
-### ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}:
+${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}:
    - Start with topic/language, add stars/forks filters later
    - Use date ranges for trending analysis
    - Combine multiple searches for comprehensive discovery
 
-### ${GITHUB_SEARCH_CODE_TOOL_NAME}:
+${GITHUB_SEARCH_CODE_TOOL_NAME}:
    - Begin with function/class names, not full signatures
    - Use extension filters for targeted searches
    - Try partial matches before exact phrases
 
-### ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME}:
+${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME}:
    - Navigate from root, then drill down
    - Use for understanding project organization
    - Check common paths: src/, lib/, packages/
 
-### ${GITHUB_GET_FILE_CONTENT_TOOL_NAME}:
+${GITHUB_GET_FILE_CONTENT_TOOL_NAME}:
    - Verify file paths with repo structure first
    - Use for implementation details and documentation
-   - Remember 300KB limit for large files
 
-### ${GITHUB_SEARCH_COMMITS_TOOL_NAME}:
-   - Search by feature keywords, not commit hashes
-   - Use author filter for contributor analysis
+${GITHUB_SEARCH_COMMITS_TOOL_NAME}:
+   - Search by feature keywords
    - Date ranges help track feature evolution
 
-### ${GITHUB_SEARCH_ISSUES_TOOL_NAME} & ${GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME}:
-   - Search for problem descriptions, not solutions
+${GITHUB_SEARCH_ISSUES_TOOL_NAME} & ${GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME}:
+   - Search for problem descriptions
    - Use state filters progressively
-   - Labels reveal project categorization
 
-### ${NPM_PACKAGE_SEARCH_TOOL_NAME}:
-   - Use functional terms: "router", "validator", "parser"
-   - Search multiple related terms in parallel
-   - Aggregate results for comprehensive view
+${NPM_PACKAGE_SEARCH_TOOL_NAME}:
+   - Search npm package in registry - use one term at a time (partial or exact)
 
-### ${NPM_VIEW_PACKAGE_TOOL_NAME}:
-   - Check repository field for source code access
-   - Review exports for API understanding
-   - Use version history to gauge stability
+${NPM_VIEW_PACKAGE_TOOL_NAME}:
+   - Returns essential data like github path and package metadata like dependencies, exports...
 
-## 10. CHAIN OF THOUGHT OPTIMIZATION:
+CHAIN OF THOUGHT OPTIMIZATION:
    - Plan search sequence before executing
    - Document reasoning for each search refinement
    - Build knowledge progressively, don't jump to specifics
    - Validate findings with multiple sources
+   - Ask user for clarification if needed
+   - Learn from results and refine search strategy
+   - Output high level summary of the search and results based on data and not assumptions
 `;
 
 const SERVER_CONFIG = {
@@ -2996,39 +3276,31 @@ function registerAllTools(server) {
         },
         { name: NPM_VIEW_PACKAGE_TOOL_NAME, fn: registerNpmViewPackageTool },
     ];
-    logger.info(`Registering ${toolRegistrations.length} tools...`);
     let successCount = 0;
     for (const tool of toolRegistrations) {
         try {
-            logger.debug(`Registering tool: ${tool.name}`);
             tool.fn(server);
             successCount++;
-            logger.info(`✓ Successfully registered: ${tool.name}`);
         }
         catch (error) {
-            logger.error(`✗ Failed to register ${tool.name}:`, error);
             // Continue with other tools instead of failing completely
         }
     }
     if (successCount === 0) {
         throw new Error('No tools were successfully registered');
     }
-    logger.info(`All tools registration completed - ${successCount}/${toolRegistrations.length} successful`);
 }
 async function startServer() {
     try {
-        logger.info('Creating MCP server...');
         const server = new McpServer(SERVER_CONFIG);
         registerAllTools(server);
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        logger.info('=== Server Connected Successfully ===');
         // Ensure all buffered output is sent
         process.stdout.uncork();
         process.stderr.uncork();
-        const gracefulShutdown = async (signal) => {
+        const gracefulShutdown = async () => {
             try {
-                logger.info(`Received ${signal}, shutting down gracefully...`);
                 clearAllCache();
                 // Give server time to close properly
                 await Promise.race([
@@ -3038,35 +3310,30 @@ async function startServer() {
                 process.exit(0);
             }
             catch (error) {
-                logger.error('Error during shutdown:', error);
                 process.exit(1);
             }
         };
         // Handle process signals
-        process.on('SIGINT', () => gracefulShutdown('SIGINT'));
-        process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+        process.on('SIGINT', gracefulShutdown);
+        process.on('SIGTERM', gracefulShutdown);
         // Handle stdin close (important for MCP)
         process.stdin.on('close', async () => {
-            await gracefulShutdown('STDIN_CLOSE');
+            await gracefulShutdown();
         });
         // Handle uncaught errors
-        process.on('uncaughtException', error => {
-            logger.error('Uncaught exception:', error);
-            gracefulShutdown('UNCAUGHT_EXCEPTION');
+        process.on('uncaughtException', () => {
+            gracefulShutdown();
         });
-        process.on('unhandledRejection', (reason, promise) => {
-            logger.error('Unhandled rejection at:', promise, 'reason:', reason);
-            gracefulShutdown('UNHANDLED_REJECTION');
+        process.on('unhandledRejection', () => {
+            gracefulShutdown();
         });
         // Keep process alive
         process.stdin.resume();
     }
     catch (error) {
-        logger.error('Error details:', error);
         process.exit(1);
     }
 }
-startServer().catch(error => {
-    logger.error('Error:', error);
+startServer().catch(() => {
     process.exit(1);
 });