octocode-mcp 2.3.7 → 2.3.8

package/build/index.js

@@ -238,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);
@@ -303,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
@@ -545,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) {
@@ -677,284 +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 = 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 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',
@@ -995,7 +758,7 @@ async function fetchGitHubFileContent(params) {
                     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.`,
+                            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')) {
@@ -1146,46 +909,52 @@ async function suggestCodeSearchFallback(owner, filePath) {
 }
 
 const GITHUB_SEARCH_CODE_TOOL_NAME = 'githubSearchCode';
-const DESCRIPTION$6 = `Search code across GitHub repositories using GitHub's code search API.
+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
 
-Search Syntax (all terms must be present with AND logic):
-- Multiple words: react lifecycle → finds files with BOTH "react" AND "lifecycle" (separate words)
-- Exact phrases: "error handling" → finds exact phrase "error handling" (quoted phrase)
-- Mixed: "async function" timeout → finds exact phrase "async function" AND word "timeout"
-- Complex: useState useEffect "custom hook" → finds "useState" AND "useEffect" AND exact phrase "custom hook"
-- Advanced: authentication authorization "jwt token" → finds "authentication" AND "authorization" AND exact phrase "jwt token"
-- Framework: "React.Component" "componentDidMount" → finds both exact phrases in same file
+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.
 
-Key difference: Quotes create exact phrases, no quotes = individual words (all must be present).
-Start with 1-2 terms, add more to narrow results. Use filters 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 query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: react lifecycle (both words), "error handling" (exact phrase), async await "try catch" (words + phrase), "function definition" variable scope (phrase + words)'),
+                .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('Programming language filter (javascript, python, typescript, go, etc). Narrows search to specific language files. Use for language-specific searches.'),
+                .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 or organization name(s) to search within. Format: "microsoft" or ["facebook", "google"]. Drastically narrows search scope. Do NOT use owner/repo format.'),
+                .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). Format: "owner/repo" or ["microsoft/vscode", "facebook/react"]. Use for repository-specific searches.'),
+                .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('Target specific filename or pattern. Examples: "package.json", "*.test.js", "Dockerfile". Use for file-specific searches.'),
+                .describe('Target specific filename or pattern. Use for file-specific searches.'),
             extension: z
                 .string()
                 .optional()
-                .describe('File extension filter (js, py, ts, go, etc). Alternative to language parameter. Examples: "js", "py", "tsx".'),
+                .describe('File extension filter. Alternative to language parameter.'),
             match: z
                 .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
                 .optional()
@@ -1194,7 +963,7 @@ function registerGitHubSearchCodeTool(server) {
                 .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 filter in KB. Format: ">10" (larger than), ">=5" (at least), "<100" (smaller than), "<=50" (at most), "10..50" (range), "25" (exact). Examples from docs: ">10", "10..50", "<100"'),
+                .describe('File size filter in KB. Format: ">N" (larger than), "<N" (smaller than), "N..M" (range), "N" (exact).'),
             limit: z
                 .number()
                 .int()
@@ -1308,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,
@@ -1482,10 +1255,10 @@ function parseSearchQuery(query) {
 }
 
 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()
@@ -1495,11 +1268,11 @@ 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()
@@ -1749,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()
@@ -1762,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()
@@ -1820,7 +1593,7 @@ function registerSearchGitHubIssuesTool(server) {
             label: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Label names (bug, feature, etc.). Can be single string or array.'),
+                .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
@@ -2083,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()
@@ -2095,11 +1868,11 @@ 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'),
@@ -2118,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()
@@ -2409,26 +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 = `Search GitHub repositories using GitHub's repository search API with comprehensive filtering.
-
-Search Logic (AND operation for multiple terms):
-- Multiple words: "react typescript" → repositories containing BOTH "react" AND "typescript"
-- Exact phrases: "web framework" → repositories with exact phrase "web framework"
-- Mixed: "machine learning" python → exact phrase "machine learning" AND word "python"
-- Filter combinations: language:javascript stars:>1000 → JavaScript repos with 1000+ stars
+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.
 
-Supported Filters: language, stars (ranges), topics, owner/org, license, dates (created/updated), 
-size, forks, community metrics (good-first-issues, help-wanted), archived status, visibility.
-
-Examples:
-- Popular projects: stars:">1000" language:typescript
-- Beginner-friendly: good-first-issues:">5" stars:"100..5000"
-- Recent quality: created:">2023-01-01" stars:">500"
-- Organization repos: owner:microsoft language:python`;
+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
  */
@@ -2461,21 +2232,21 @@ 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 with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: react typescript (both words), "web framework" (exact phrase), "machine learning" python (phrase + word).'),
+                .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(s). Format: "microsoft" or ["facebook", "google"]. Do NOT use owner/repo format. Dramatically narrows search scope to specific organizations.'),
+                .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 (javascript, python, typescript, go, etc). Filters repositories by primary language. Essential for language-specific searches.'),
+                .describe('Programming language filter. Filters repositories by primary language. Essential for language-specific searches.'),
             stars: z
                 .union([
                 z.number().int().min(0),
@@ -2484,11 +2255,11 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "10..100", or exact number "50"'),
             ])
                 .optional()
-                .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). Examples from docs: ">1000", "100..5000", "<100"'),
+                .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('Repository topics filter. Examples: "machine-learning", ["react", "typescript"]. Topics use kebab-case format (machine-learning, web-development).'),
+                .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),
@@ -2497,7 +2268,7 @@ function registerSearchGitHubReposTool(server) {
                     .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). Examples from docs: ">100", "10..100", "<10"'),
+                .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([
@@ -2507,40 +2278,40 @@ function registerSearchGitHubReposTool(server) {
                     .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">5", ">=3", "<10", "<=2", "3..10", or exact number "5"'),
             ])
                 .optional()
-                .describe('Number of topics filter. Format: ">5" (many topics), ">=3" (at least 3), "<10" (few topics), "1..3" (range), "5" (exact). Well-documented projects typically have 3-10 topics.'),
+                .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. Examples: "mit", "apache-2.0", ["mit", "apache-2.0"]. Common licenses: mit, apache-2.0, gpl-3.0, bsd-3-clause.'),
+                .describe('License filter.'),
             archived: z
                 .boolean()
                 .optional()
-                .describe('Archive status filter. false (active repos only), true (archived repos only). Use false to find actively maintained projects.'),
+                .describe('Archive status filter. false (active repos only), true (archived repos only).'),
             'include-forks': z
                 .enum(['false', 'true', 'only'])
                 .optional()
-                .describe('Fork inclusion. "false" (exclude forks), "true" (include forks), "only" (forks only). Use "false" for original projects.'),
+                .describe('Fork inclusion. "false" (exclude forks), "true" (include forks), "only" (forks only).'),
             visibility: z
                 .enum(['public', 'private', 'internal'])
                 .optional()
-                .describe('Repository visibility. "public" (open source), "private" (private repos you have access to), "internal" (organization internal).'),
+                .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('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). Examples from docs: ">2020-01-01", "2023-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('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). Essential for finding actively maintained projects. Examples from docs: ">2024-01-01", "2022-01-01..2023-12-31"'),
+                .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" (large projects), ">=500" (medium-large), "<100" (small projects), "<=50" (tiny), "100..1000" (medium range), "500" (exact). Examples from docs: ">1000", "100..1000", "<100"'),
+                .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
             'good-first-issues': z
                 .union([
@@ -2550,7 +2321,7 @@ 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. Format: ">5" (many beginner issues), "1..10" (some beginner issues). Perfect for finding beginner-friendly open source projects.'),
+                .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),
@@ -2559,7 +2330,7 @@ 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. Format: ">10" (many help wanted), "1..5" (some help wanted). Great for finding projects actively seeking contributors.'),
+                .describe('Help wanted issues count. Format: ">10" (many help wanted), "1..5" (some help wanted).'),
             followers: z
                 .union([
                 z.number().int().min(0),
@@ -2568,12 +2339,15 @@ function registerSearchGitHubReposTool(server) {
                     .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). Indicates developer/org reputation.'),
-            // SEARCH SCOPE
+                .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" (repository names only), "description" (descriptions only), "readme" (README content). Default searches all fields.'),
+                .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([
@@ -2585,12 +2359,12 @@ function registerSearchGitHubReposTool(server) {
             ])
                 .optional()
                 .default('best-match')
-                .describe('Sort criteria. "stars" (popularity), "updated" (recent activity), "forks" (community engagement), "help-wanted-issues" (contribution opportunities), "best-match" (relevance).'),
+                .describe('Sort criteria.'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Sort order direction. "desc" (descending, highest first), "asc" (ascending, lowest first). Default is descending for most useful results.'),
+                .describe('Sort order direction.'),
             limit: z
                 .number()
                 .int()
@@ -2598,7 +2372,7 @@ function registerSearchGitHubReposTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Maximum number of repositories to return (1-100). Default: 30. Higher values may increase response time.'),
+                .describe('Maximum number of repositories to return (1-100).'),
         },
         annotations: {
             title: 'GitHub Repository Search',
@@ -2828,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) {
@@ -2838,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()
@@ -2937,7 +2961,7 @@ function parseNpmSearchOutput(output) {
 }
 
 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,
@@ -2945,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',
@@ -3095,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
-
-## 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
+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)
 
-## 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 = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-mcp",
-  "version": "2.3.7",
+  "version": "2.3.8",
   "description": "Model Context Protocol (MCP) server for advanced GitHub repository analysis, code discovery, and npm package exploration. Provides AI assistants with powerful tools to search, analyze, and understand codebases across GitHub and npm ecosystems.",
   "author": "Guy Bary <guybary@gmail.com>",
   "homepage": "https://github.com/bgauryy/octocode-mcp#readme",