octocode-mcp 2.3.13 → 2.3.16

package/{build → dist}/index.js

@@ -85,7 +85,14 @@ const ALLOWED_NPM_COMMANDS = [
     'whoami',
 ];
 // Allowed command prefixes - this prevents shell injection by restricting to safe commands
-const ALLOWED_GH_COMMANDS = ['search', 'api', 'auth', 'org', 'pr'];
+const ALLOWED_GH_COMMANDS = [
+    'search',
+    'api',
+    'auth',
+    'org',
+    'pr',
+    'repo',
+];
 function createSuccessResult(data) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
@@ -247,10 +254,10 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     // Get shell configuration
     const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    // For GitHub search commands, we need minimal escaping to avoid interfering with GitHub CLI
     const escapedArgs = args.map((arg, index) => {
         const isMainQueryArgument = command === 'search' && index === 1;
         const isCliFlag = arg.startsWith('--');
+        const isApiPath = command === 'api' && arg.startsWith('/');
         // CLI flags like --language=javascript, --repo=owner/repo need minimal escaping
         if (isCliFlag) {
             // Only escape CLI flags if they contain dangerous shell characters
@@ -259,6 +266,22 @@ async function executeGitHubCommand(command, args = [], options = {}) {
             }
             return arg;
         }
+        // API paths with query parameters need proper escaping
+        if (isApiPath) {
+            // Always quote API paths that contain query parameters or special characters
+            if (arg.includes('?') || arg.includes('&') || /[\s*?[\]{}]/.test(arg)) {
+                if (shellConfig.type === 'unix') {
+                    return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+                }
+                else if (shellConfig.type === 'cmd') {
+                    return `"${arg.replace(/"/g, '""')}"`;
+                }
+                else {
+                    return `'${arg.replace(/'/g, "''")}'`;
+                }
+            }
+            return arg;
+        }
         // For search queries, only escape if absolutely necessary for shell safety
         if (isMainQueryArgument) {
             // Only escape if the argument contains shell metacharacters that could be dangerous
@@ -294,6 +317,29 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     }
     return executeGhCommand();
 }
+/**
+ * Helper function to detect shell configuration errors vs real GitHub errors
+ */
+function isShellConfigurationError(errorText) {
+    if (!errorText)
+        return false;
+    // Preserve GitHub API errors
+    if (errorText.includes('HTTP 404') ||
+        errorText.includes('HTTP 403') ||
+        errorText.includes('Not Found') ||
+        errorText.includes('API rate limit')) {
+        return false;
+    }
+    // Shell configuration conflicts to ignore
+    return (errorText.includes('head: illegal option') ||
+        errorText.includes('head: |: No such file or directory') ||
+        errorText.includes('head: cat: No such file or directory') ||
+        /^head:\s+/.test(errorText) ||
+        /^\s*head:\s+/.test(errorText) ||
+        (errorText.includes('No such file or directory') &&
+            !errorText.includes('HTTP') &&
+            !errorText.includes('gh:')));
+}
 /**
  * Execute shell commands with improved environment handling and error detection
  */
@@ -329,13 +375,8 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
             : stderr &&
                 !stderr.includes('Warning:') &&
                 !stderr.includes('notice:') &&
-                // Ignore shell configuration conflicts - common in development environments
-                !stderr.includes('No such file or directory') &&
-                !stderr.includes('head: illegal option') &&
-                !stderr.includes('head: |: No such file or directory') &&
-                !stderr.includes('head: cat: No such file or directory') &&
-                !/^head:\s+/.test(stderr) && // Ignore all head command errors (shell conflicts)
-                !/^\s*head:\s+/.test(stderr) && // Ignore head errors with leading whitespace
+                // Ignore shell configuration conflicts but preserve GitHub API errors
+                !isShellConfigurationError(stderr) &&
                 stderr.trim() !== '';
         if (shouldTreatAsError) {
             const errorType = type === 'npm' ? 'NPM command error' : 'GitHub CLI command error';
@@ -929,10 +970,7 @@ function createToolSuggestion(currentTool, suggestedTools) {
 }
 
 const API_STATUS_CHECK_TOOL_NAME = 'apiStatusCheck';
-const DESCRIPTION$9 = `initial tool to verify user connections
-
-- Github: check gh login status and list available organizations.
-- Npm: check npm login status and list npm registry.`;
+const DESCRIPTION$9 = `Check user status: GitHub/NPM connections, organizations, and current timestamp. Essential for understanding user's data access and API capabilities.`;
 // Helper function to parse execution results with proper typing
 function parseExecResult(result) {
     if (!result.isError && result.content?.[0]?.text) {
@@ -1053,6 +1091,7 @@ function registerApiStatusCheckTool(server) {
             }
             return createResult({
                 data: {
+                    timestamp: new Date().toISOString(),
                     login: {
                         github: {
                             connected: githubConnected,
@@ -1090,24 +1129,12 @@ const GITHUB_SEARCH_CODE_TOOL_NAME = 'githubSearchCode';
 const DESCRIPTION$8 = `Search code across GitHub repositories using GitHub's code search API via GitHub CLI.
 
 SEARCH STRATEGY FOR BEST RESULTS:
-
-EXACT vs TERMS (Choose ONE):
-- exactQuery: Use for exact phrase matching
-- queryTerms: Use minimal words for broader coverage
-
-TERM OPTIMIZATION:
-- BEST: Single terms for maximum coverage
-- GOOD: 2-3 minimal terms 
-- AVOID: Long phrases in queryTerms
-
-MULTI-SEARCH STRATEGY:
+- use 'exactQuery' for exact phrase matching
+- use 'queryTerms' for minimal words for broader coverage (recommended: 2-3 terms)
+- queryTerms can be exacts strings or words (e.g. term1, "term2 exact string"...)
 - Use separate searches for different aspects
 - Separate searches provide broader coverage than complex queries
-
-Filter Usage:
-- Use filters to narrow scope: language, owner, repo, filename
-- Combine filters strategically: language + owner for organization-wide searches
-- Never use filters on exploratory searches - use to refine results`;
+- Use filters to narrow scope (never use filters on exploratory searches - use to refine results)`;
 function registerGitHubSearchCodeTool(server) {
     server.registerTool(GITHUB_SEARCH_CODE_TOOL_NAME, {
         description: DESCRIPTION$8,
@@ -111960,7 +111987,10 @@ 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 isCommitSha = branch.match(/^[0-9a-f]{40}$/);
+            const apiPath = isCommitSha
+                ? `/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}` // Use contents API with ref for commit SHA
+                : `/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}`; // Use contents API for branches/tags
             const result = await executeGitHubCommand('api', [apiPath], {
                 cache: false,
             });
@@ -112297,14 +112327,19 @@ async function suggestCodeSearchFallback(owner, filePath) {
 const GITHUB_SEARCH_REPOSITORIES_TOOL_NAME = 'githubSearchRepositories';
 const DESCRIPTION$6 = `Search GitHub repositories using gh search repos CLI.
 
+THREE SEARCH APPROACHES:
+- exactQuery: Single exact phrase/word search
+- queryTerms: Multiple search terms (broader coverage)  
+- topic: Find repositories by technology/subject
+
 BEST PRACTICES:
-- Use topic for discovering repositories by technology/purpose
-- Use query for searching by repository name
-- Use owner to explore specific organizations
-- Use language to filter by programming language
-- Use quality filters (stars, forks) for refinement
+- Use exactQuery for specific repository names
+- Use queryTerms with minimal words for broader results
+- Use topic for technology/subject discovery
+- Use owner for organization exploration
+- Use filters (language, stars, forks) for refinement
 
-Separate searches for different topics and use minimal filters to get the most relevant results`;
+Multiple focused searches work better than complex single queries.`;
 /**
  * Extract owner/repo information from various query formats
  */
@@ -112339,10 +112374,14 @@ function registerSearchGitHubReposTool(server) {
     server.registerTool(GITHUB_SEARCH_REPOSITORIES_TOOL_NAME, {
         description: DESCRIPTION$6,
         inputSchema: {
-            query: z
+            exactQuery: z
                 .string()
                 .optional()
-                .describe('Search by repository name. Use minimal words for repository names or specific projects. For topic discovery, use topic parameter instead.'),
+                .describe('Single exact phrase/word search'),
+            queryTerms: z
+                .array(z.string())
+                .optional()
+                .describe('Multiple search terms for broader coverage'),
             // CORE FILTERS (GitHub CLI flags)
             owner: z
                 .union([z.string(), z.array(z.string())])
@@ -112364,7 +112403,7 @@ function registerSearchGitHubReposTool(server) {
             topic: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Discover repositories by topic. Use for exploring unknown domains and finding projects by technology or purpose.'),
+                .describe('Find repositories by technology/subject'),
             forks: z
                 .union([
                 z.number().int().min(0),
@@ -112487,15 +112526,29 @@ function registerSearchGitHubReposTool(server) {
             openWorldHint: true,
         },
     }, async (args) => {
+        // Validate that exactly one search parameter is provided (not both)
+        const hasExactQuery = !!args.exactQuery;
+        const hasQueryTerms = args.queryTerms && args.queryTerms.length > 0;
+        if (hasExactQuery && hasQueryTerms) {
+            return createResult({
+                error: 'Use either exactQuery OR queryTerms, not both. Choose one search approach.',
+            });
+        }
         try {
             // Extract owner/repo from query if present
-            const queryInfo = args.query
-                ? extractOwnerRepoFromQuery(args.query)
-                : {
-                    cleanedQuery: '',
-                    extractedOwner: undefined,
-                    extractedRepo: undefined,
-                };
+            const queryInfo = args.exactQuery
+                ? extractOwnerRepoFromQuery(args.exactQuery)
+                : args.queryTerms
+                    ? {
+                        cleanedQuery: args.queryTerms.join(' '),
+                        extractedOwner: undefined,
+                        extractedRepo: undefined,
+                    }
+                    : {
+                        cleanedQuery: '',
+                        extractedOwner: undefined,
+                        extractedRepo: undefined,
+                    };
             // Merge extracted owner with explicit owner parameter
             let finalOwner = args.owner;
             if (queryInfo.extractedOwner && !finalOwner) {
@@ -112504,11 +112557,13 @@ function registerSearchGitHubReposTool(server) {
             // Update parameters with extracted information
             const enhancedArgs = {
                 ...args,
-                query: queryInfo.cleanedQuery || args.query,
+                exactQuery: args.exactQuery ? queryInfo.cleanedQuery : undefined,
+                queryTerms: args.queryTerms,
                 owner: finalOwner,
             };
             // Enhanced validation logic for primary filters
-            const hasPrimaryFilter = enhancedArgs.query?.trim() ||
+            const hasPrimaryFilter = enhancedArgs.exactQuery?.trim() ||
+                (enhancedArgs.queryTerms && enhancedArgs.queryTerms.length > 0) ||
                 enhancedArgs.owner ||
                 enhancedArgs.language ||
                 enhancedArgs.topic ||
@@ -112516,11 +112571,14 @@ function registerSearchGitHubReposTool(server) {
                 enhancedArgs.forks;
             if (!hasPrimaryFilter) {
                 return createResult({
-                    error: `Repository search requires at least one filter. Try these patterns:
-• Topic exploration: { topic: ["react", "typescript"] }
-• Organization search: { owner: "microsoft", visibility: "public" }
-• Language + quality: { language: "go", "good-first-issues": ">=10" }
-• Simple query: { query: "cli shell" }`,
+                    error: `Repository search requires at least one filter. Try:
+• Topic search: { topic: "react" }
+• Exact search: { exactQuery: "cli shell" }  
+• Multiple terms: { queryTerms: ["react", "hooks"] }
+• Organization: { owner: "microsoft" }
+• Language filter: { language: "go" }
+
+Alternative: Use npm search for package discovery.`,
                 });
             }
             // First attempt: Search with current parameters
@@ -112530,19 +112588,21 @@ function registerSearchGitHubReposTool(server) {
                 // Smart fallbacks based on error type
                 if (errorMsg.includes('rate limit')) {
                     return createResult({
-                        error: `GitHub API rate limit. Smart alternatives:
-• Try npm package search for package discovery
-• Use broader filters (remove stars/forks constraints)
-• Search fewer organizations at once
+                        error: `GitHub API rate limit exceeded. Alternatives:
+• Use npm search for package discovery
+• Remove quality filters (stars/forks)  
+• Search fewer organizations
 • Wait 5-10 minutes and retry`,
                     });
                 }
                 if (errorMsg.includes('authentication')) {
                     return createResult({
-                        error: `Authentication required. Quick fix:
-1. Run: gh auth login
-2. For private repos: use api_status_check to verify access
-3. Public repos should work without auth - check query`,
+                        error: `Authentication required:
+• Run: gh auth login
+• For private repos: use api_status_check tool
+• Public repos work without auth
+
+Alternative: Use npm search for packages.`,
                     });
                 }
                 return result; // Return original error for other cases
@@ -112552,31 +112612,26 @@ function registerSearchGitHubReposTool(server) {
             const hasResults = resultData.total_count > 0;
             // Smart fallback strategies for no results
             if (!hasResults) {
-                const fallbackSuggestions = [];
-                if (enhancedArgs.query) {
-                    fallbackSuggestions.push('• Try broader search terms or remove query filter');
+                const suggestions = [];
+                if (enhancedArgs.exactQuery) {
+                    suggestions.push('• Try broader search terms');
                 }
                 if (enhancedArgs.language) {
-                    fallbackSuggestions.push('• Remove language filter for broader discovery');
+                    suggestions.push('• Remove language filter');
                 }
                 if (enhancedArgs.stars || enhancedArgs.forks) {
-                    fallbackSuggestions.push('• Lower quality thresholds (stars/forks)');
+                    suggestions.push('• Lower quality thresholds');
                 }
                 if (!enhancedArgs.topic) {
-                    fallbackSuggestions.push('• 🎯 Try topic exploration: { topic: ["web", "api"] }');
+                    suggestions.push('• Try topic search: { topic: "react" }');
                 }
                 if (enhancedArgs.owner) {
-                    fallbackSuggestions.push('• Search without owner filter for global discovery');
-                    fallbackSuggestions.push('• Use npm package search if looking for packages');
+                    suggestions.push('• Remove owner filter for global search');
                 }
+                suggestions.push('• Use npm search for package discovery');
                 return createResult({
-                    error: `No repositories found. Try these alternatives:
-${fallbackSuggestions.join('\n')}
-
-Quick discovery patterns:
-• 🎯 Topic exploration: { topic: ["react"] }
-• Organization search: { owner: "microsoft" }
-• Quality filter: { stars: ">100", language: "python" }`,
+                    error: `No repositories found. Try:
+${suggestions.join('\n')}`,
                 });
             }
             // Fallback for private repositories: If no results and owner is specified, try with private visibility
@@ -112706,13 +112761,19 @@ async function searchGitHubRepos(params) {
     });
 }
 function buildGitHubReposSearchCommand(params) {
-    const query = params.query?.trim() || '';
     const args = ['repos'];
-    const hasEmbeddedQualifiers = query &&
-        /\b(stars|language|org|repo|topic|user|created|updated|size|license|archived|fork|good-first-issues|help-wanted-issues):/i.test(query);
-    if (query) {
-        args.push(query);
+    let queryForQualifierCheck = '';
+    if (params.exactQuery) {
+        args.push(params.exactQuery.trim());
+        queryForQualifierCheck = params.exactQuery.trim();
+    }
+    else if (params.queryTerms && params.queryTerms.length > 0) {
+        // Add each term as separate argument for AND logic
+        params.queryTerms.forEach(term => args.push(term.trim()));
+        queryForQualifierCheck = params.queryTerms.join(' ');
     }
+    const hasEmbeddedQualifiers = queryForQualifierCheck &&
+        /\b(stars|language|org|repo|topic|user|created|updated|size|license|archived|fork|good-first-issues|help-wanted-issues):/i.test(queryForQualifierCheck);
     args.push('--json=name,fullName,description,language,stargazersCount,forksCount,updatedAt,createdAt,url,owner,isPrivate,license,hasIssues,openIssuesCount,isArchived,isFork,visibility');
     const addArg = (paramName, cliFlag, condition = true, formatter) => {
         const value = params[paramName];
@@ -112763,12 +112824,13 @@ function buildGitHubReposSearchCommand(params) {
 }
 
 const GITHUB_SEARCH_COMMITS_TOOL_NAME = 'githubSearchCommits';
-const DESCRIPTION$5 = `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.
+const DESCRIPTION$5 = `Search GitHub commits by message, author, or date. Returns SHAs for github_fetch_content (branch=SHA). Can fetch commit content changes (diffs/patches) when getChangesContent=true.
 
-INTEGRATION WORKFLOW:
-- Returned commit SHAs can be used directly with github fetch content (branch=SHA)
-- Use SHA as 'branch' parameter to view files from specific commits
-- Perfect for examining code changes and historical versions`;
+SEARCH STRATEGY FOR BEST RESULTS:
+- Use minimal search terms for broader coverage (2-3 words max)
+- Separate searches for different aspects vs complex queries
+- Use filters to narrow scope after getting initial results
+- getChangesContent=true only when analyzing actual code changes`;
 function registerGitHubSearchCommitsTool(server) {
     server.registerTool(GITHUB_SEARCH_COMMITS_TOOL_NAME, {
         description: DESCRIPTION$5,
@@ -112776,16 +112838,16 @@ function registerGitHubSearchCommitsTool(server) {
             query: z
                 .string()
                 .optional()
-                .describe('Search terms. Start simple: "bug fix", "refactor". Use quotes for exact phrases.'),
+                .describe('Commit message search terms (keep minimal for broader results)'),
             // Repository filters
             owner: z
                 .string()
                 .optional()
-                .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.'),
+                .describe('Repository owner (use with repo param)'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
+                .describe('Repository name (use with owner param)'),
             // Author filters
             author: z
                 .string()
@@ -112813,11 +112875,11 @@ function registerGitHubSearchCommitsTool(server) {
             'author-date': z
                 .string()
                 .optional()
-                .describe('When authored. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
+                .describe('Filter by author date (e.g., >2020-01-01)'),
             'committer-date': z
                 .string()
                 .optional()
-                .describe('When committed. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
+                .describe('Filter by commit date (e.g., >2020-01-01)'),
             // Hash filters
             hash: z.string().optional().describe('Commit SHA (full or partial)'),
             parent: z.string().optional().describe('Parent commit SHA'),
@@ -112840,19 +112902,24 @@ function registerGitHubSearchCommitsTool(server) {
                 .max(50)
                 .optional()
                 .default(25)
-                .describe('Results limit (1-50). Default: 25'),
+                .describe('Maximum number of results to fetch'),
             sort: z
                 .enum(['author-date', 'committer-date'])
                 .optional()
-                .describe('Sort by date. Default: best match'),
+                .describe('Sort by date field'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Sort order. Default: desc'),
+                .describe('Sort order'),
+            getChangesContent: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Get actual code diffs - only use when analyzing changes, not for commit identification'),
         },
         annotations: {
-            title: 'GitHub Commit Search - Smart History Analysis',
+            title: 'GitHub Commit Search - Smart & Effective',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -112870,12 +112937,65 @@ function registerGitHubSearchCommitsTool(server) {
             const items = Array.isArray(commits) ? commits : [];
             // Smart handling for no results - provide actionable suggestions
             if (items.length === 0) {
+                // Progressive simplification strategy based on current search complexity
+                const simplificationSteps = [];
+                let hasFilters = false;
+                // Check for active filters
+                const activeFilters = [];
+                if (args.owner && args.repo)
+                    activeFilters.push('repo');
+                if (args.author)
+                    activeFilters.push('author');
+                if (args['author-email'])
+                    activeFilters.push('author-email');
+                if (args.hash)
+                    activeFilters.push('hash');
+                if (args['author-date'])
+                    activeFilters.push('date');
+                if (args.visibility)
+                    activeFilters.push('visibility');
+                hasFilters = activeFilters.length > 0;
+                // Step 1: If complex query, simplify search terms
+                if (args.query && args.query.trim().split(' ').length > 2) {
+                    const words = args.query.trim().split(' ');
+                    const simplified = words.slice(0, 1).join(' '); // Take first word only
+                    simplificationSteps.push(`Try simpler search: "${simplified}" instead of "${args.query}"`);
+                }
+                // Step 2: Remove filters progressively
+                if (hasFilters) {
+                    if (activeFilters.length > 1) {
+                        simplificationSteps.push(`Remove some filters (currently: ${activeFilters.join(', ')}) and keep only the most important one`);
+                    }
+                    else {
+                        simplificationSteps.push(`Remove the ${activeFilters[0]} filter and search more broadly`);
+                    }
+                }
+                // Step 3: Alternative approaches
+                if (!args.query && hasFilters) {
+                    simplificationSteps.push('Add basic search terms like "fix", "update", or "add" with your filters');
+                }
+                // Step 4: Ask for user guidance if no obvious simplification
+                if (simplificationSteps.length === 0) {
+                    simplificationSteps.push("Try different keywords or ask the user to be more specific about what commits they're looking for");
+                }
                 return createResult({
-                    error: createNoResultsError('commits'),
+                    error: `${createNoResultsError('commits')}
+
+Try these simplified searches:
+${simplificationSteps.map(step => `• ${step}`).join('\n')}
+
+Or ask the user:
+• "What specific type of commits are you looking for?" 
+• "Can you provide different keywords to search for?"
+• "Should I search in a specific repository instead?"
+
+Alternative tools:
+• Use github_search_code for file-specific commits
+• Use github_search_repos to find repositories first`,
                 });
             }
             // Transform to optimized format
-            const optimizedResult = transformCommitsToOptimizedFormat(items, args);
+            const optimizedResult = await transformCommitsToOptimizedFormat(items, args);
             return createResult({ data: optimizedResult });
         }
         catch (error) {
@@ -112899,22 +113019,75 @@ function registerGitHubSearchCommitsTool(server) {
 /**
  * Transform GitHub CLI response to optimized format
  */
-function transformCommitsToOptimizedFormat(items, _params) {
+async function transformCommitsToOptimizedFormat(items, params) {
     // Extract repository info if single repo search
     const singleRepo = extractSingleRepository(items);
+    // Fetch diff information if requested and this is a repo-specific search
+    const shouldFetchDiff = params.getChangesContent && params.owner && params.repo;
+    const diffData = new Map();
+    if (shouldFetchDiff && items.length > 0) {
+        // Fetch diff info for each commit (limit to first 10 to avoid rate limits)
+        const commitShas = items.slice(0, 10).map(item => item.sha);
+        const diffPromises = commitShas.map(async (sha) => {
+            try {
+                const diffResult = await executeGitHubCommand('api', [`/repos/${params.owner}/${params.repo}/commits/${sha}`], { cache: false });
+                if (!diffResult.isError) {
+                    const diffExecResult = JSON.parse(diffResult.content[0].text);
+                    return { sha, commitData: diffExecResult.result };
+                }
+            }
+            catch (e) {
+                // Ignore diff fetch errors
+            }
+            return { sha, commitData: null };
+        });
+        const diffResults = await Promise.all(diffPromises);
+        diffResults.forEach(({ sha, commitData }) => {
+            if (commitData) {
+                diffData.set(sha, commitData);
+            }
+        });
+    }
     const optimizedCommits = items
-        .map(item => ({
-        sha: item.sha,
-        message: getCommitTitle(item.commit?.message ?? ''),
-        author: item.commit?.author?.name ?? item.author?.login ?? 'Unknown',
-        date: toDDMMYYYY(item.commit?.author?.date ?? ''),
-        repository: singleRepo
-            ? undefined
-            : simplifyRepoUrl(item.repository?.url || ''),
-        url: singleRepo
-            ? item.sha
-            : `${simplifyRepoUrl(item.repository?.url || '')}@${item.sha}`,
-    }))
+        .map(item => {
+        const commitObj = {
+            sha: item.sha, // Use as branch parameter in github_fetch_content
+            message: getCommitTitle(item.commit?.message ?? ''),
+            author: item.commit?.author?.name ?? item.author?.login ?? 'Unknown',
+            date: toDDMMYYYY(item.commit?.author?.date ?? ''),
+            repository: singleRepo
+                ? undefined
+                : simplifyRepoUrl(item.repository?.url || ''),
+            url: singleRepo
+                ? item.sha
+                : `${simplifyRepoUrl(item.repository?.url || '')}@${item.sha}`,
+        };
+        // Add diff information if available
+        if (shouldFetchDiff && diffData.has(item.sha)) {
+            const commitData = diffData.get(item.sha);
+            const files = commitData.files || [];
+            commitObj.diff = {
+                changed_files: files.length,
+                additions: commitData.stats?.additions || 0,
+                deletions: commitData.stats?.deletions || 0,
+                total_changes: commitData.stats?.total || 0,
+                files: files
+                    .map((f) => ({
+                    filename: f.filename,
+                    status: f.status,
+                    additions: f.additions,
+                    deletions: f.deletions,
+                    changes: f.changes,
+                    patch: f.patch
+                        ? f.patch.substring(0, 1000) +
+                            (f.patch.length > 1000 ? '...' : '')
+                        : undefined,
+                }))
+                    .slice(0, 5), // Limit to 5 files per commit
+            };
+        }
+        return commitObj;
+    })
         .map(commit => {
         // Remove undefined fields
         const cleanCommit = {};
@@ -113036,13 +113209,13 @@ function buildGitHubCommitCliArgs(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$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.
+const DESCRIPTION$4 = `Search GitHub PRs by keywords, state, or author. Returns head/base SHAs for github_fetch_content (branch=SHA). Can fetch PR content changes (diffs/patches) when getChangesContent=true.
 
-INTEGRATION WORKFLOW:
-- Use PR head/base branch names with github_fetch_content to view PR code
-- Repository-specific searches return commit SHAs (head_sha, base_sha) for direct use with github fetch content (branch=SHA)
-- Combine with github_search_commits to find specific commit SHAs from PR
-- Perfect for reviewing implementations and understanding changes`;
+SEARCH STRATEGY FOR BEST RESULTS:
+- Use minimal search terms for broader coverage (2-3 words max)
+- Separate searches for different aspects vs complex queries  
+- Use filters to narrow scope after getting initial results
+- getChangesContent=true only when analyzing actual code changes`;
 function registerSearchGitHubPullRequestsTool(server) {
     server.registerTool(GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME, {
         description: DESCRIPTION$4,
@@ -113050,15 +113223,15 @@ function registerSearchGitHubPullRequestsTool(server) {
             query: z
                 .string()
                 .min(1, 'Search query is required and cannot be empty')
-                .describe('Search terms. Start simple: "refactor", "optimization". Use quotes for exact phrases.'),
+                .describe('Search query for PR content (keep minimal for broader results)'),
             owner: z
                 .string()
                 .optional()
-                .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.'),
+                .describe('Repository owner (use with repo param)'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name only (e.g., "react", "vscode"). Do NOT include owner prefix. Must be used together with owner parameter.'),
+                .describe('Repository name (use with owner param)'),
             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'),
@@ -113075,48 +113248,45 @@ function registerSearchGitHubPullRequestsTool(server) {
             state: z
                 .enum(['open', 'closed'])
                 .optional()
-                .describe('PR state. Default: all'),
-            head: z.string().optional().describe('Source branch name'),
-            base: z.string().optional().describe('Target branch name'),
+                .describe('Filter by state: open or closed'),
+            head: z.string().optional().describe('Filter on head branch name'),
+            base: z.string().optional().describe('Filter on base branch name'),
             language: z.string().optional().describe('Repository language'),
             created: z
                 .string()
                 .optional()
-                .describe('When created. Format: >2020-01-01'),
+                .describe('Filter by created date (e.g., >2020-01-01)'),
             updated: z
                 .string()
                 .optional()
-                .describe('When updated. Format: >2020-01-01'),
+                .describe('Filter by updated date (e.g., >2020-01-01)'),
             'merged-at': z
                 .string()
                 .optional()
-                .describe('When merged. Format: >2020-01-01'),
+                .describe('Filter by merged date (e.g., >2020-01-01)'),
             closed: z
                 .string()
                 .optional()
-                .describe('When closed. Format: >2020-01-01'),
-            draft: z.boolean().optional().describe('Draft PR status'),
+                .describe('Filter by closed date (e.g., >2020-01-01)'),
+            draft: z.boolean().optional().describe('Filter by draft state'),
             checks: z
                 .enum(['pending', 'success', 'failure'])
                 .optional()
-                .describe('CI/CD check status'),
-            merged: z
-                .boolean()
-                .optional()
-                .describe('Only merged PRs (true) or unmerged (false)'),
+                .describe('Filter by checks status'),
+            merged: z.boolean().optional().describe('Filter by merged state'),
             review: z
                 .enum(['none', 'required', 'approved', 'changes_requested'])
                 .optional()
-                .describe('Review status filter'),
-            app: z.string().optional().describe('GitHub App that created the PR'),
+                .describe('Filter by review status'),
+            app: z.string().optional().describe('Filter by GitHub App author'),
             archived: z
                 .boolean()
                 .optional()
-                .describe('Include archived repositories'),
+                .describe('Filter by repository archived state'),
             comments: z
                 .number()
                 .optional()
-                .describe('Comment count filter. Format: >10, <5, 5..10'),
+                .describe('Filter by number of comments'),
             interactions: z
                 .number()
                 .optional()
@@ -113124,23 +113294,32 @@ function registerSearchGitHubPullRequestsTool(server) {
             'team-mentions': z
                 .string()
                 .optional()
-                .describe('Team mentioned in PR (@org/team-name)'),
+                .describe('Filter by team mentions'),
             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'),
+                .describe('Filter by number of reactions'),
+            locked: z
+                .boolean()
+                .optional()
+                .describe('Filter by locked conversation status'),
+            'no-assignee': z
+                .boolean()
+                .optional()
+                .describe('Filter by missing assignee'),
+            'no-label': z.boolean().optional().describe('Filter by missing label'),
             'no-milestone': z
                 .boolean()
                 .optional()
-                .describe('PRs without milestone'),
-            'no-project': z.boolean().optional().describe('PRs not in projects'),
+                .describe('Filter by missing milestone'),
+            'no-project': z
+                .boolean()
+                .optional()
+                .describe('Filter by missing project'),
             label: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Label names. Can be single string or array.'),
+                .describe('Filter by label'),
             milestone: z.string().optional().describe('Milestone title'),
             project: z.string().optional().describe('Project board owner/number'),
             visibility: z
@@ -113148,17 +113327,17 @@ function registerSearchGitHubPullRequestsTool(server) {
                 .optional()
                 .describe('Repository visibility'),
             match: z
-                .enum(['title', 'body', 'comments'])
+                .array(z.enum(['title', 'body', 'comments']))
                 .optional()
-                .describe('Search scope. Default: title and body'),
+                .describe('Restrict search to specific fields'),
             limit: z
                 .number()
                 .int()
                 .min(1)
-                .max(50)
+                .max(100)
                 .optional()
-                .default(25)
-                .describe('Results limit (1-50). Default: 25'),
+                .default(30)
+                .describe('Maximum number of results to fetch'),
             sort: z
                 .enum([
                 'comments',
@@ -113174,15 +113353,20 @@ function registerSearchGitHubPullRequestsTool(server) {
                 'updated',
             ])
                 .optional()
-                .describe('Sort by activity or reactions. Default: best match'),
+                .describe('Sort fetched results'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Sort order. Default: desc'),
+                .describe('Order of results (requires --sort)'),
+            getChangesContent: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Get actual code diffs - only use when analyzing changes, not for PR identification'),
         },
         annotations: {
-            title: 'GitHub PR Search - Implementation Discovery',
+            title: 'GitHub PR Search - Smart & Effective',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -113215,6 +113399,52 @@ async function searchGitHubPullRequests(params) {
         const { command, args } = buildGitHubPullRequestsAPICommand(params);
         const result = await executeGitHubCommand(command, args, { cache: false });
         if (result.isError) {
+            const errorMsg = result.content[0].text;
+            // Enhanced error handling for repository-specific searches
+            if (params.owner && params.repo) {
+                // Handle 404 errors with repository and branch checking
+                if (errorMsg.includes('404')) {
+                    // Single repository check to avoid duplicate API calls
+                    const repoCheckResult = await executeGitHubCommand('api', [`/repos/${params.owner}/${params.repo}`], { cache: false });
+                    if (repoCheckResult.isError) {
+                        // Repository doesn't exist
+                        return createResult({
+                            error: `Repository "${params.owner}/${params.repo}" not found. Use github_search_repositories to find the correct repository name.`,
+                        });
+                    }
+                    // Repository exists, check if it's a branch-related error
+                    if (params.head || params.base) {
+                        try {
+                            const repoData = JSON.parse(repoCheckResult.content[0].text);
+                            const defaultBranch = repoData.result?.default_branch || 'main';
+                            let branchSuggestion = '';
+                            if (params.head && params.head !== defaultBranch) {
+                                branchSuggestion = `\n\nNote: Branch "${params.head}" may not exist. Repository default branch is "${defaultBranch}".`;
+                                branchSuggestion += `\nTry searching without head branch filter or use head="${defaultBranch}".`;
+                            }
+                            if (params.base && params.base !== defaultBranch) {
+                                branchSuggestion += `\n\nNote: Branch "${params.base}" may not exist. Repository default branch is "${defaultBranch}".`;
+                                branchSuggestion += `\nTry searching without base branch filter or use base="${defaultBranch}".`;
+                            }
+                            if (branchSuggestion) {
+                                return createResult({
+                                    error: createNoResultsError('pull_requests') + branchSuggestion,
+                                });
+                            }
+                        }
+                        catch (e) {
+                            // Continue with original error if parsing fails
+                        }
+                    }
+                }
+                // Handle rate limit errors
+                if (errorMsg.includes('rate limit') ||
+                    errorMsg.includes('API rate limit')) {
+                    return createResult({
+                        error: ERROR_MESSAGES.RATE_LIMIT_EXCEEDED,
+                    });
+                }
+            }
             return result;
         }
         const execResult = JSON.parse(result.content[0].text);
@@ -113224,8 +113454,97 @@ async function searchGitHubPullRequests(params) {
             ? execResult.result
             : execResult.result?.items || [];
         if (pullRequests.length === 0) {
+            // Progressive simplification strategy based on current search complexity
+            const simplificationSteps = [];
+            let hasFilters = false;
+            // Check for active filters
+            const activeFilters = [];
+            if (params.owner && params.repo)
+                activeFilters.push('repo');
+            if (params.author)
+                activeFilters.push('author');
+            if (params.state)
+                activeFilters.push('state');
+            if (params.label)
+                activeFilters.push('label');
+            if (params.head)
+                activeFilters.push('head-branch');
+            if (params.base)
+                activeFilters.push('base-branch');
+            if (params.assignee)
+                activeFilters.push('assignee');
+            if (params.created)
+                activeFilters.push('date');
+            hasFilters = activeFilters.length > 0;
+            // Step 1: If complex query, simplify search terms
+            if (params.query && params.query.trim().split(' ').length > 2) {
+                const words = params.query.trim().split(' ');
+                const simplified = words.slice(0, 1).join(' '); // Take first word only
+                simplificationSteps.push(`Try simpler search: "${simplified}" instead of "${params.query}"`);
+            }
+            // Step 2: Remove filters progressively
+            if (hasFilters) {
+                if (activeFilters.length > 2) {
+                    simplificationSteps.push(`Remove some filters (currently: ${activeFilters.join(', ')}) and keep only the most important ones`);
+                }
+                else if (activeFilters.length > 1) {
+                    simplificationSteps.push(`Remove one filter (currently: ${activeFilters.join(', ')}) to broaden search`);
+                }
+                else {
+                    simplificationSteps.push(`Remove the ${activeFilters[0]} filter and search more broadly`);
+                }
+            }
+            // Step 3: Alternative approaches
+            if (!params.query && hasFilters) {
+                simplificationSteps.push('Add basic search terms like "fix", "feature", "bug", or "update" with your filters');
+            }
+            // Step 4: Repository-specific guidance
+            if (!params.owner && !params.repo) {
+                simplificationSteps.push('Try searching in a specific repository first using owner and repo parameters');
+            }
+            // Step 5: Ask for user guidance if no obvious simplification
+            if (simplificationSteps.length === 0) {
+                simplificationSteps.push("Try different keywords or ask the user to be more specific about what PRs they're looking for");
+            }
             return createResult({
-                error: createNoResultsError('pull_requests'),
+                error: `${createNoResultsError('pull_requests')}
+
+Try these simplified searches:
+${simplificationSteps.map(step => `• ${step}`).join('\n')}
+
+Or ask the user:
+• "What specific type of pull requests are you looking for?"
+• "Can you provide different keywords to search for?"
+• "Should I search in a specific repository instead?"
+• "Are you looking for open or closed PRs?"
+
+Alternative tools:
+• Use github_search_code for PR-related file changes
+• Use github_search_repos to find repositories first`,
+            });
+        }
+        // Fetch diff information if requested and this is a repo-specific search
+        const shouldFetchDiff = params.getChangesContent && params.owner && params.repo;
+        const diffData = new Map();
+        if (shouldFetchDiff && pullRequests.length > 0) {
+            // Fetch diff info for each PR (limit to first 10 to avoid rate limits)
+            const prNumbers = pullRequests.slice(0, 10).map((pr) => pr.number);
+            const diffPromises = prNumbers.map(async (prNumber) => {
+                try {
+                    const diffResult = await executeGitHubCommand('api', [`/repos/${params.owner}/${params.repo}/pulls/${prNumber}/files`], { cache: false });
+                    if (!diffResult.isError) {
+                        const diffExecResult = JSON.parse(diffResult.content[0].text);
+                        return { prNumber, files: diffExecResult.result };
+                    }
+                }
+                catch (e) {
+                    // Ignore diff fetch errors
+                }
+                return { prNumber, files: [] };
+            });
+            const diffResults = await Promise.all(diffPromises);
+            diffResults.forEach(({ prNumber, files }) => {
+                diffData.set(prNumber, files);
             });
         }
         const cleanPRs = pullRequests.map((pr) => {
@@ -113245,15 +113564,38 @@ async function searchGitHubPullRequests(params) {
                     reactions: 0, // Not available in list format
                     draft: pr.isDraft || false,
                 };
-                // Add commit SHAs - this is the key enhancement!
+                // Add commit SHAs for use with github_fetch_content
+                // Use head_sha/base_sha as branch parameter to view PR files
                 if (pr.headRefName)
                     result.head = pr.headRefName;
                 if (pr.headRefOid)
-                    result.head_sha = pr.headRefOid;
+                    result.head_sha = pr.headRefOid; // Use as branch=SHA
                 if (pr.baseRefName)
                     result.base = pr.baseRefName;
                 if (pr.baseRefOid)
-                    result.base_sha = pr.baseRefOid;
+                    result.base_sha = pr.baseRefOid; // Use as branch=SHA
+                // Add diff information if available
+                if (shouldFetchDiff && diffData.has(pr.number)) {
+                    const files = diffData.get(pr.number);
+                    result.diff = {
+                        changed_files: files.length,
+                        additions: files.reduce((sum, f) => sum + (f.additions || 0), 0),
+                        deletions: files.reduce((sum, f) => sum + (f.deletions || 0), 0),
+                        files: files
+                            .map((f) => ({
+                            filename: f.filename,
+                            status: f.status,
+                            additions: f.additions,
+                            deletions: f.deletions,
+                            changes: f.changes,
+                            patch: f.patch
+                                ? f.patch.substring(0, 1000) +
+                                    (f.patch.length > 1000 ? '...' : '')
+                                : undefined,
+                        }))
+                            .slice(0, 5), // Limit to 5 files per PR
+                    };
+                }
                 return result;
             }
             // Handle search API format
@@ -113280,6 +113622,28 @@ async function searchGitHubPullRequests(params) {
                 result.head = pr.head.ref;
             if (pr.base?.ref)
                 result.base = pr.base.ref;
+            // Add diff information if available (search API format)
+            if (shouldFetchDiff && diffData.has(pr.number)) {
+                const files = diffData.get(pr.number);
+                result.diff = {
+                    changed_files: files.length,
+                    additions: files.reduce((sum, f) => sum + (f.additions || 0), 0),
+                    deletions: files.reduce((sum, f) => sum + (f.deletions || 0), 0),
+                    files: files
+                        .map((f) => ({
+                        filename: f.filename,
+                        status: f.status,
+                        additions: f.additions,
+                        deletions: f.deletions,
+                        changes: f.changes,
+                        patch: f.patch
+                            ? f.patch.substring(0, 1000) +
+                                (f.patch.length > 1000 ? '...' : '')
+                            : undefined,
+                    }))
+                        .slice(0, 5), // Limit to 5 files per PR
+                };
+            }
             return result;
         });
         const searchResult = {
@@ -113288,11 +113652,25 @@ async function searchGitHubPullRequests(params) {
                 ? cleanPRs.length
                 : execResult.result?.total_count || cleanPRs.length,
         };
-        return createResult({ data: searchResult });
+        // Add helpful context if filtering by branches that might not exist
+        let additionalContext = '';
+        if (cleanPRs.length === 0 &&
+            params.owner &&
+            params.repo &&
+            (params.head || params.base)) {
+            additionalContext =
+                '\n\nNote: No PRs found with specified branch filters. Consider removing head/base filters or checking if branches exist.';
+        }
+        return createResult({
+            data: searchResult,
+            ...(additionalContext && { message: additionalContext }),
+        });
     });
 }
 function buildGitHubPullRequestsAPICommand(params) {
-    // For repository-specific searches, use gh pr list to get commit SHAs
+    // For repository-specific searches, use gh pr list instead of search API
+    // This provides commit SHAs (head_sha, base_sha) which are essential for
+    // integrating with github_fetch_content to view PR code at specific commits
     if (params.owner && params.repo) {
         return buildGitHubPullRequestsListCommand(params);
     }
@@ -113370,10 +113748,13 @@ function buildGitHubPullRequestsAPICommand(params) {
         queryParts.push(`milestone:"${params.milestone}"`);
     if (params.project)
         queryParts.push(`project:${params.project}`);
+    if (params.match) {
+        params.match.forEach(field => queryParts.push(`in:${field}`));
+    }
     // Add type qualifier to search only pull requests
     queryParts.push('type:pr');
     const query = queryParts.filter(Boolean).join(' ');
-    const limit = Math.min(params.limit || 25, 100);
+    const limit = Math.min(params.limit || 30, 100);
     let apiPath = `search/issues?q=${encodeURIComponent(query)}&per_page=${limit}`;
     if (params.sort)
         apiPath += `&sort=${params.sort}`;
@@ -113389,7 +113770,7 @@ function buildGitHubPullRequestsListCommand(params) {
         '--json',
         'number,title,headRefName,headRefOid,baseRefName,baseRefOid,state,author,labels,createdAt,updatedAt,url,comments,isDraft',
         '--limit',
-        String(Math.min(params.limit || 25, 100)),
+        String(Math.min(params.limit || 30, 100)),
     ];
     // Add filters
     if (params.state) {
@@ -113725,8 +114106,10 @@ async function viewRepositoryStructure(params) {
         try {
             // Clean up path
             const cleanPath = path.startsWith('/') ? path.substring(1) : path;
-            // Try the requested branch first
-            const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${branch}`;
+            // Try the requested branch first - handle empty path correctly
+            const apiPath = cleanPath
+                ? `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${branch}`
+                : `/repos/${owner}/${repo}/contents?ref=${branch}`;
             const result = await executeGitHubCommand('api', [apiPath], {
                 cache: false,
             });