octocode-mcp 2.3.10 → 2.3.11

package/README.md

@@ -3,7 +3,7 @@
 **The Perfect AI Code Assistant - Advanced Search & Discovery Across GitHub & NPM**
 
 <div>
-  <img src="./assets/logo.png">
+  <img src="./assets/logo.png" width="400px">
   
   [![Version](https://img.shields.io/badge/version-2.3.2-blue.svg)](./package.json)
   [![License](https://img.shields.io/badge/license-MIT-green.svg)](./package.json)
@@ -13,44 +13,25 @@
 
 ## What is Octocode? 🐙
 
-**The perfect code assistant that can help understand anything.** Octocode was built to understand connections between repositories and NPM packages under any privilege level you have. With **AI-powered advanced search**, heuristic discovery, and smart fallbacks, it makes GitHub's vast repository of knowledge truly searchable and analyzable.
-
-Instead of manually browsing repositories, you can ask questions like:
+**The perfect code assistant that can help understand anything.** Octocode provides AI-powered advanced search with heuristic discovery and smart fallbacks to understand connections between repositories and NPM packages across any privilege level you have.
 
+Instead of manually browsing repositories, ask questions like:
 - *"How did React implement concurrent rendering?"*
 - *"Show me authentication patterns in Next.js applications"*
 - *"Find examples of how to use this specific API"*
 - *"What's the architecture of this library?"*
 - *"How do I use this MCP tool effectively?"*
 
-## Recommended Use Cases
-
-**Use Octocode when you need to:**
-
-- **🔍 Understand implementations** - See how features work across different repositories
-- **📚 Find real code examples** - Discover patterns and best practices from production code  
-- **🏗️ Analyze architecture** - Explore how systems are designed and structured
-- **🔬 Research approaches** - Compare different implementation strategies
-- **💡 Learn from code** - Deep-dive into technical details and understand "how does this work?"
-
 ## Unique Value Proposition
 
 **The most advanced AI-powered code assistant for understanding connections across the entire GitHub & NPM ecosystem.** While other GitHub MCPs focus on project management or basic operations, Octocode provides unparalleled depth for code discovery and technical research.
 
-**🚀 Out-of-the-Box Advanced Search (Powered by AI):**
-- **🧠 Heuristic Search** - Intelligent pattern recognition that finds relevant code even with vague queries
-- **🔄 Smart Fallbacks** - Automatic retry with alternative search strategies when initial searches fail
-- **🎯 Smart Discovery** - AI-guided exploration that uncovers hidden connections and patterns
-- **🔗 Connection Intelligence** - Understands relationships between repositories, packages, and dependencies
-- **📊 Multi-dimensional Analysis** - Combines code, commits, issues, discussions, and package data
-
 **Key Differentiators:**
-- **🧠 Advanced AI Search** - Heuristic algorithms that understand code context and connections
-- **🔐 Secure & Simple** - No personal access tokens needed, uses [GitHub CLI](https://cli.github.com/) authentication
-- **🔗 Connected Discovery** - Maps NPM packages to repositories, traces dependencies, finds related code
-- **🌐 Cross-Ecosystem Understanding** - Works across any privilege level you have (public, private, organization)
-
-It's the tool you reach for when you need to understand *"how does this work?"* rather than *"how do I manage this project?"*
+- **🧠 AI-Powered Search** - Heuristic algorithms with smart fallbacks that understand code context and find relevant code even with vague queries
+- **🔐 Zero-Config Security** - Uses GitHub CLI authentication - no personal access tokens needed
+- **🔗 Connection Intelligence** - Maps NPM packages to repositories, traces dependencies, finds related implementations
+- **🌐 Universal Access** - Works seamlessly with public, private, and organization repositories
+- **⚡ LLM Optimized** - Advanced content minification and partial fetching reduces token usage by 80-90%
 
 ## Quick Start 🚀
 
@@ -74,13 +55,11 @@ gh auth login
 npm login
 ```
 
-**🔐 GitHub Authentication via CLI:**
-- ✅ **No personal access tokens needed** - Uses [GitHub CLI](https://cli.github.com/) behind the scenes
-- ✅ **Secure OAuth flow** - Browser-based authentication, no tokens to store
+**🔐 Authentication Benefits:**
+- ✅ **No personal access tokens** - Uses GitHub CLI OAuth flow
 - ✅ **Enterprise ready** - Works with SSO, 2FA, and organization access
-- ✅ **Private repository access** - Automatically detects your organizations and accesses private repos
-- ✅ **Zero configuration** - Uses your existing `gh` CLI permissions
-
+- ✅ **Automatic organization detection** - Instantly accesses your private repositories
+- ✅ **Zero configuration** - Uses existing `gh` CLI permissions
 
 ### 3. Add to MCP Configuration
 ```json
@@ -92,157 +71,95 @@ npm login
 }
 ```
 
-**That's it!** No personal access tokens, no config files, no complex setup. Octocode leverages [GitHub CLI](https://cli.github.com/) authentication behind the scenes and **automatically works with your organization's private repositories**.
+**That's it!** Octocode automatically works with your organization's private repositories.
 
-## How Octocode Works 🔄
+## How It Works 🔄
 
 **Smart Discovery Flow:**
-1. **🔍 Query Analysis** → AI determines the best search strategy based on your question
-2. **⚡ Multi-Tool Orchestration** → Intelligently combines 10 specialized tools across GitHub + NPM
-3. **🔄 Smart Fallbacks** → Automatically retries with different approaches if initial search fails
-4. **🔗 Cross-Reference Discovery** → Links packages to repositories, finds related implementations with commit SHA integration
-5. **🎯 Context Synthesis** → Provides comprehensive understanding across multiple sources
+1. **🔍 Query Analysis** → AI determines the best search strategy
+2. **⚡ Multi-Tool Orchestration** → Intelligently combines 10 specialized tools
+3. **🔄 Smart Fallbacks** → Automatically retries with different approaches
+4. **🔗 Cross-Reference Discovery** → Links packages to repositories with commit SHA integration
+5. **🎯 Context Synthesis** → Provides comprehensive understanding
 
 ## Example Flows
 
 ### Example 1: LangGraph Node.js Implementation Tutorial
 **Query:** "Show implementations of langgraph in node js. Make a tutorial for how to implement a simple agent using OpenAI API."
 
-[![LangGraph Node.js Tutorial](assets/langchainTutorial.gif)](https://youtu.be/E5HUlRckpvg?si=XXLle59C92esDscS)
+<a href="https://youtu.be/E5HUlRckpvg?si=XXLle59C92esDscS"><img src="assets/langchainTutorial.gif" alt="LangGraph Node.js Tutorial" width="50%"></a>
 
 ### Example 2: Zustand React State Management
 **Query:** "Show me how to add zustand to react application. Show examples and best practices"
 
-[![Zustand React State Management](assets/reactZustand.gif)](https://youtu.be/EgYbsuWmqsI?si=CN_KwCPgwprImynU)
+<a href="https://youtu.be/EgYbsuWmqsI?si=CN_KwCPgwprImynU"><img src="assets/reactZustand.gif" alt="Zustand React State Management" width="50%"></a>
 
 ### Example 3: React vs Vue.js Rendering Comparison
 **Query:** "How did React implement their concurrent rendering flows? How is it different from Vue.js rendering mechanism? Which is better?"
 
-[![React vs Vue.js Rendering Comparison](assets/reactVSVueJS.gif)](https://youtu.be/-_pbCbLXKDc?si=KiPeGCzmwWtb6G3r)
+<a href="https://youtu.be/-_pbCbLXKDc?si=KiPeGCzmwWtb6G3r"><img src="assets/reactVSVueJS.gif" alt="React vs Vue.js Rendering Comparison" width="50%"></a>
 
 ## Core Features 🛠️
 
-### 🧠 AI-Powered Advanced Search
-- **Heuristic Pattern Recognition** - Finds relevant code even with vague or incomplete queries
-- **Smart Fallback Strategies** - Automatically tries alternative approaches when searches fail with actionable suggestions
-- **Boolean Search Intelligence** - Automatic query optimization with smart boolean operators (3-5x performance improvement)
-- **Context-Aware Discovery** - Understands code relationships and suggests related implementations
-- **Multi-Strategy Search** - Combines semantic, syntactic, and dependency-based search methods
-- **Graceful Error Recovery** - Comprehensive error handling with intelligent retry mechanisms
-
-### 🔗 Connection Intelligence
-- **Repository-Package Mapping** - Automatically links NPM packages to their GitHub repositories
-- **Dependency Tracing** - Follows dependency chains across the entire ecosystem
-- **Cross-Reference Analysis** - Finds how different projects implement similar patterns
-- **Ecosystem Understanding** - Maps relationships between libraries, frameworks, and tools
-
-### 🌐 Universal Access & Discovery
-- **Cross-Privilege Search** - Works with any access level you have (public, private, organization)
-- **Organization-Aware** - Automatically detects and uses your GitHub organization memberships
-- **Smart Repository Discovery** - Finds relevant repositories even when you don't know they exist
-- **Progressive Refinement** - AI-guided search that gets more precise with each iteration
-
-### 📊 Multi-Dimensional Analysis
-- **Code + Context** - Combines source code with commits, issues, discussions, and documentation
-- **Historical Understanding** - Tracks how implementations evolved over time
-- **Community Insights** - Discovers patterns from real-world usage and discussions
-- **Quality Signals** - Uses NPM publication and GitHub activity as quality indicators
+### 🧠 AI-Powered Intelligence
+- **Advanced Search** - Heuristic pattern recognition with automatic fallback strategies
+- **Connection Mapping** - Automatically links NPM packages to GitHub repositories
+- **Cross-Reference Analysis** - Discovers how different projects implement similar patterns
+- **Progressive Refinement** - AI-guided search that improves with each iteration
+- **Context-Aware Discovery** - Understands relationships between code, commits, issues, and discussions
 
 ### 🔗 Commit SHA Integration
-- **Time Travel Code Viewing** - View files from specific commits and pull requests using commit SHAs
-- **PR Code Analysis** - Automatically fetch commit SHAs from pull requests for precise code comparison
-- **Historical Implementation** - Compare how code evolved across different commits and versions
-- **Cross-Reference Discovery** - Link commits, pull requests, and current implementations seamlessly
-
-### ⚡ LLM Content Optimization
-- **Intelligent Content Selection** - Automatically identifies and extracts only relevant code sections for research
-- **Smart Minification** - Advanced content compression that preserves meaning while reducing tokens by 80-90%
-- **Partial File Access** - Fetches targeted line ranges from search results, avoiding full file downloads
-- **Context-Aware Processing** - Indentation-aware minification for 15+ programming languages
-- **Binary Detection & Filtering** - Automatically skips non-text files and suggests alternatives
-- **Token Efficiency** - Optimizes content for maximum LLM comprehension with minimal token usage
-- **Line Number Preservation** - Maintains precise line references for code navigation and debugging
-
-**Optimization Workflow:**
-1. **🎯 Smart Targeting** → Extract specific line ranges from search results
-2. **🧹 Content Filtering** → Remove comments, whitespace, and non-essential elements
-3. **🗜️ Intelligent Compression** → Language-aware minification preserving code structure
-4. **📍 Context Preservation** → Keep essential context and line number references
-5. **⚡ Token Optimization** → Deliver maximum code insight with minimal LLM token consumption
+- **Time Travel Code Viewing** - View files from specific commits and pull requests
+- **PR Code Analysis** - Automatically fetch commit SHAs for precise code comparison
+- **Historical Implementation** - Compare code evolution across versions
 
-## Available Tools 🛠️
+### ⚡ Performance Optimization
+- **Smart Content Selection** - Extracts only relevant code sections
+- **Advanced Minification** - Language-aware compression preserving meaning
+- **Partial File Access** - Fetches targeted line ranges
+- **Token Efficiency** - 80-90% reduction in LLM token usage
 
-Octocode provides **10 specialized tools** that work together intelligently:
+## Available Tools
 
-**🔍 Discovery Tools:**
-- **Repository Search** - Find repositories by topic, language, stars, and organization
-- **Package Search** - Discover NPM packages by functionality and keywords
+**10 specialized tools** working together intelligently:
 
-**📊 Analysis Tools:**
-- **Code Search** - Smart search across GitHub repositories with heuristic pattern recognition
-- **Package Analysis** - Detailed NPM package analysis with repository linking
-- **Repository Structure** - Explore directory structures and file organization
+**Discovery:** Repository Search, Package Search  
+**Analysis:** Code Search, Package Analysis, Repository Structure  
+**Activity:** Commit Search, Pull Request Search, Issue Search  
+**Content:** File Content Fetching, API Status Check  
 
-**📈 Activity Tools:**
-- **Commit Search** - Find commits by message, author, and date with SHA integration
-- **Pull Request Search** - Discover PRs with automatic commit SHA extraction
-- **Issue Search** - Find bug reports, feature requests, and discussions
+All tools feature automatic cross-referencing and intelligent fallbacks.
 
-**📁 Content Tools:**
-- **File Content Fetching** - Read files from any commit, branch, or PR using commit SHAs
-- **API Status Check** - Verify authentication and discover organization access
-
-**Smart Integration:** All tools work together through intelligent workflows - from package discovery → repository analysis → commit history → file content, with automatic fallbacks and cross-referencing.
-
-## Privacy & Security 🛡️
+## Security & Privacy 🛡️
 
+### Local-First Architecture
 - **🏠 100% Local** - Runs entirely on your machine
-- **🚫 Zero Data Collection** - No telemetry, logging, or data transmission
-- **🔑 No Token Management** - Uses [GitHub CLI](https://cli.github.com/) authentication, no personal access tokens needed
-- **🛡️ Privacy by Design** - All API calls use your existing `gh` CLI permissions directly
-
-### Command Execution Security 🔒
-
-**Robust protection against prompt injections and malicious command execution:**
-
-- **⚪ Allowlisted Commands Only** - Only pre-approved, safe NPM and GitHub CLI commands are executable
-  - NPM: `view`, `search`, `config`, `whoami` 
-  - GitHub CLI: `search`, `api`, `auth`, `org`, `pr`
-- **🛡️ Argument Sanitization** - All command arguments are properly escaped to prevent shell injection attacks
-- **✅ Pre-execution Validation** - Every command is validated against allowed lists before execution
-- **🔧 Controlled Environment** - Commands run in a secure, cross-platform shell environment with controlled variables
-  - **Cross-platform shells**: Uses `/bin/sh` on Unix/macOS, `cmd.exe` or `powershell.exe` on Windows - minimal, standard shells
-  - **PowerShell support**: Modern Windows environments can optionally use PowerShell with enhanced security
-  - **Why minimal shells are safe**: Avoids user's potentially customized shells with aliases, functions, plugins, or advanced features
-  - **Controlled variables**: Only essential environment variables (`PATH`, `SHELL`) are passed, preventing environment-based attacks
-  - **Platform-specific escaping**: Uses appropriate argument escaping for each platform (single quotes on Unix, double quotes for CMD, single quotes for PowerShell)
-- **🚫 No Arbitrary Execution** - System cannot execute arbitrary shell commands or scripts
-- **⏱️ Timeout Protection** - All commands have execution timeouts to prevent resource exhaustion
+- **🚫 Zero Data Collection** - No telemetry or data transmission
+- **🔑 No Token Management** - Uses GitHub CLI authentication
 
-## Best Practices 💡
+### Command Execution Security
+- **⚪ Allowlisted Commands Only** - Pre-approved safe commands
+- **🛡️ Argument Sanitization** - Prevents shell injection attacks
+- **✅ Pre-execution Validation** - Every command is validated
+- **🔧 Controlled Environment** - Cross-platform secure shell execution
+- **⏱️ Timeout Protection** - Prevents resource exhaustion
 
-**AI-Powered Search Tips:**
-- **Let AI guide you** - Start with natural language questions, the heuristic search will find relevant code
-- **Trust the smart fallbacks** - If initial search doesn't work, AI automatically tries alternative strategies
-- **Explore connections** - Ask about relationships between packages, libraries, and implementations
-- **Use any privilege level** - Works seamlessly across public repos, private repos, and organization repositories
-- **Keep research along the MCP** - Build upon previous searches and maintain context across multiple queries for deeper exploration
+## Best Practices 💡
 
 **Effective Questions:**
-- **Vague is OK** - "How does authentication work?" → AI finds relevant patterns across repositories
-- **Ask for connections** - "What libraries use this pattern?" → Discovers related implementations
-- **Cross-ecosystem queries** - "NPM packages that implement X" → Links packages to their repositories
-- **Evolution questions** - "How has this approach changed?" → Traces implementation history
+- Start with natural language - "How does authentication work?"
+- Ask for connections - "What libraries use this pattern?"
+- Cross-ecosystem queries - "NPM packages that implement X"
+- Evolution questions - "How has this approach changed?"
 
-**Advanced Search Features:**
-- **Automatic fallbacks** - No need to retry failed searches, AI handles it automatically
-- **Smart discovery** - Finds repositories and packages you didn't know existed
-- **Connection mapping** - Understands relationships between different codebases
-- **Context preservation** - Maintains search context across multiple queries
+**Pro Tips:**
+- Let AI guide discovery - vague queries work great
+- Trust smart fallbacks - automatic retry with alternatives
+- Build on previous searches - maintain context for deeper exploration
+- Works everywhere - public, private, and organization repositories
 
 ## Troubleshooting 🔧
 
-**Authentication Issues:**
 ```bash
 # Check GitHub CLI status
 gh auth status
@@ -252,43 +169,24 @@ gh auth logout && gh auth login
 
 # Check NPM access
 npm whoami
+
+# Clear NPX cache if needed
+rm -rf ~/.npm/_npx
 ```
 
 **Common Solutions:**
 - No results? Try broader search terms
-- Private repos not found? Check organization membership with `gh auth status`
-- NPX issues? Clear cache: `rm -rf ~/.npm/_npx`
-
-**🏢 Organization & Private Repository Access:**
-- **Automatic detection** - Octocode automatically discovers your GitHub organizations
-- **No additional setup** - If you have access to private repos through your organization, they work immediately
-- **Verify access** - Run `gh auth status` to see your organization memberships
-
-**💻 Windows PowerShell Support:**
-- **Modern shell support** - Optionally use PowerShell instead of cmd.exe on Windows
-- **Enhanced security** - PowerShell provides better argument escaping and modern features
-- **Automatic detection** - The system automatically detects Windows and applies appropriate shell configurations
-- **Zero configuration** - Works seamlessly with existing setups, no additional configuration needed
-
-**Why GitHub CLI Authentication?**
-- ✅ **No token creation** - GitHub CLI handles OAuth flow automatically
-- ✅ **Enterprise compatible** - Works with SSO, SAML, and 2FA out of the box
-- ✅ **Organization auto-detection** - Automatically discovers your GitHub organizations and private repo access
-- ✅ **Works out of the box** - If you work for an organization, private repositories are immediately accessible
-- ❌ **vs Personal Access Tokens** - No manual creation, rotation, or security risks
+- Private repos not found? Check `gh auth status` for organization membership
+- Windows users? PowerShell is automatically supported
 
 ## Background 💭
 
-This project started as a personal tool while working at Wix, born from the challenge of navigating large codebases and keeping up with rapidly evolving technology landscapes. What began as a side project to solve daily development challenges evolved into **the perfect code assistant that can help understand anything**.
-
-The goal was simple: **make code exploration as intelligent as having a senior developer guide you through any codebase.** Built specifically to understand connections between many repositories and NPM packages under any privilege the user has, with AI-powered heuristic search, smart fallbacks, and intelligent discovery.
+This project started as a personal tool while working at Wix, born from the challenge of navigating large codebases and keeping up with rapidly evolving technology landscapes. What began as a side project evolved into **the perfect code assistant that can help understand anything**.
 
+The goal: **make code exploration as intelligent as having a senior developer guide you through any codebase.**
 
 ## License 📄
 
 MIT License - See [LICENSE](./LICENSE.md) for details.
 
----
-
-
-
+---

package/build/index.js

@@ -112050,15 +112050,44 @@ async function fetchGitHubFileContent(params) {
                         });
                     }
                 }
-                // Try fallback branches if original branch fails
-                if (errorMsg.includes('404') &&
-                    branch !== 'main' &&
-                    branch !== 'master') {
-                    const fallbackBranches = ['main', 'master'];
+                // Enhanced fallback strategy for 404 errors
+                if (errorMsg.includes('404')) {
+                    // Get the actual default branch from the repo info we already fetched
+                    let defaultBranch = 'main';
+                    let repoDefaultBranchFound = false;
+                    if (!repoCheckResult.isError) {
+                        try {
+                            const repoData = JSON.parse(repoCheckResult.content[0].text);
+                            defaultBranch = repoData.default_branch || 'main';
+                            repoDefaultBranchFound = true;
+                        }
+                        catch (e) {
+                            // Keep default as 'main' if parsing fails
+                        }
+                    }
+                    // If we found the actual default branch, try it first
+                    if (repoDefaultBranchFound && defaultBranch !== branch) {
+                        const defaultBranchPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${defaultBranch}`;
+                        const defaultBranchResult = await executeGitHubCommand('api', [defaultBranchPath], {
+                            cache: false,
+                        });
+                        if (!defaultBranchResult.isError) {
+                            return await processFileContent(defaultBranchResult, owner, repo, defaultBranch, filePath, params.minified, params.startLine, params.endLine, params.contextLines);
+                        }
+                    }
+                    // Comprehensive fallback list (excluding default branch since we tried it)
+                    const fallbackBranches = [
+                        'main',
+                        'master',
+                        'develop',
+                        'dev',
+                        'trunk',
+                    ].filter(b => b !== defaultBranch && b !== branch);
                     const triedBranches = [branch];
+                    if (repoDefaultBranchFound && defaultBranch !== branch) {
+                        triedBranches.push(`${defaultBranch} (default)`);
+                    }
                     for (const fallbackBranch of fallbackBranches) {
-                        if (triedBranches.includes(fallbackBranch))
-                            continue;
                         triedBranches.push(fallbackBranch);
                         const fallbackPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${fallbackBranch}`;
                         const fallbackResult = await executeGitHubCommand('api', [fallbackPath], {
@@ -112068,8 +112097,19 @@ async function fetchGitHubFileContent(params) {
                             return await processFileContent(fallbackResult, owner, repo, fallbackBranch, filePath, params.minified, params.startLine, params.endLine, params.contextLines);
                         }
                     }
+                    const defaultBranchInfo = repoDefaultBranchFound
+                        ? `\nRepository default branch: "${defaultBranch}"`
+                        : `\nCould not determine default branch - repository info unavailable`;
                     return createResult({
-                        error: `File not found in any common branches (tried: ${triedBranches.join(', ')}). File might have been moved or deleted. Use github_search_code to find current location.`,
+                        error: `File not found in any common branches (tried: ${triedBranches.join(', ')}).${defaultBranchInfo}
+
+Quick solution: Use the correct branch name:
+{"owner": "${owner}", "repo": "${repo}", "branch": "${defaultBranch}", "filePath": "${filePath}"}
+
+Alternative solutions:
+• Check repository structure: github_view_repo_structure with {"owner": "${owner}", "repo": "${repo}", "branch": "main", "path": ""}
+• Search for file: github_search_code with query="filename:${filePath.split('/').pop()}" owner="${owner}"
+• Find file path: github_search_code with query="path:${filePath}"`,
                     });
                 }
                 // Handle common errors with more context
@@ -113754,125 +113794,78 @@ async function viewRepositoryStructure(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 the requested branch first
+            const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${branch}`;
+            const result = await executeGitHubCommand('api', [apiPath], {
+                cache: false,
+            });
+            if (!result.isError) {
+                const execResult = JSON.parse(result.content[0].text);
+                const apiItems = execResult.result;
+                const items = Array.isArray(apiItems) ? apiItems : [apiItems];
+                return formatRepositoryStructure(owner, repo, branch, cleanPath, items);
+            }
+            // If initial request failed, start enhanced fallback mechanism
+            const errorMsg = result.content[0].text;
+            // Check repository existence first
+            const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+                cache: false,
+            });
+            if (repoCheckResult.isError) {
+                return handleRepositoryNotFound(owner, repo, repoCheckResult.content[0].text);
+            }
+            // Enhanced fallback strategy for branch/path errors
+            if (errorMsg.includes('404')) {
+                // Get the actual default branch from the repo info we already fetched
+                let defaultBranch = 'main';
+                let repoDefaultBranchFound = false;
                 try {
-                    const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
-                    const result = await executeGitHubCommand('api', [apiPath], {
+                    const repoData = JSON.parse(repoCheckResult.content[0].text);
+                    defaultBranch = repoData.default_branch || 'main';
+                    repoDefaultBranchFound = true;
+                }
+                catch (e) {
+                    // Keep default as 'main' if parsing fails
+                }
+                // If we found the actual default branch, try it first
+                if (repoDefaultBranchFound && defaultBranch !== branch) {
+                    const defaultBranchPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${defaultBranch}`;
+                    const defaultBranchResult = await executeGitHubCommand('api', [defaultBranchPath], {
                         cache: false,
                     });
-                    if (!result.isError) {
-                        const execResult = JSON.parse(result.content[0].text);
+                    if (!defaultBranchResult.isError) {
+                        const execResult = JSON.parse(defaultBranchResult.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 items = Array.isArray(apiItems) ? apiItems : [apiItems];
+                        return formatRepositoryStructure(owner, repo, defaultBranch, cleanPath, items);
                     }
                 }
-                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.`,
-                        });
-                    }
+                // Try additional common branches
+                const commonBranches = ['main', 'master', 'develop'];
+                const triedBranches = [branch];
+                if (repoDefaultBranchFound) {
+                    triedBranches.push(defaultBranch);
                 }
-                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}`,
+                for (const tryBranch of commonBranches) {
+                    if (triedBranches.includes(tryBranch))
+                        continue;
+                    const tryBranchPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
+                    const tryBranchResult = await executeGitHubCommand('api', [tryBranchPath], {
+                        cache: false,
                     });
+                    triedBranches.push(tryBranch);
+                    if (!tryBranchResult.isError) {
+                        const execResult = JSON.parse(tryBranchResult.content[0].text);
+                        const apiItems = execResult.result;
+                        const items = Array.isArray(apiItems) ? apiItems : [apiItems];
+                        return formatRepositoryStructure(owner, repo, tryBranch, cleanPath, items);
+                    }
                 }
+                // All branches failed - return helpful error
+                return handlePathNotFound(owner, repo, cleanPath, triedBranches, defaultBranch, repoDefaultBranchFound);
             }
-            // 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,
-                    },
-                },
-            });
+            // Handle other errors (403, etc.)
+            return handleOtherErrors(owner, repo, errorMsg);
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
@@ -113883,62 +113876,114 @@ async function viewRepositoryStructure(params) {
     });
 }
 /**
- * Smart branch detection with automatic fallback to common branch names.
- * Now includes more comprehensive branch detection and better error handling.
+ * Format the repository structure response
  */
-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,
+function formatRepositoryStructure(owner, repo, branch, path, items) {
+    // 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: branch,
+            path: path || '/',
+            githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
+            files: {
+                count: files.length,
+                files: files,
+            },
+            folders: {
+                count: folders.length,
+                folders: folders,
+            },
+        },
+    });
+}
+/**
+ * Handle repository not found errors
+ */
+function handleRepositoryNotFound(owner, repo, errorMsg) {
+    if (errorMsg.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.`,
         });
-        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;
+    else if (errorMsg.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.`,
+        });
+    }
+    return createResult({
+        error: `Failed to access repository "${owner}/${repo}": ${errorMsg}. Verify repository exists and is accessible.`,
     });
-    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}"`;
-            }
-        }
+/**
+ * Handle path not found errors with helpful suggestions
+ */
+function handlePathNotFound(owner, repo, path, triedBranches, defaultBranch, repoDefaultBranchFound) {
+    const defaultBranchInfo = repoDefaultBranchFound
+        ? `\nRepository default branch: "${defaultBranch}"`
+        : `\nCould not determine default branch - repository info unavailable`;
+    if (path) {
+        return createResult({
+            error: `Path "${path}" not found in any branch (tried: ${triedBranches.join(', ')}).${defaultBranchInfo}
+
+Quick solution: Use the correct branch name:
+{"owner": "${owner}", "repo": "${repo}", "branch": "${defaultBranch}", "path": "${path}"}
+
+Alternative solutions:
+• Search for path: github_search_code with query="path:${path}" owner="${owner}"
+• Search for directory: github_search_code with query="${path.split('/').pop()}" owner="${owner}"
+• Check root structure: github_view_repo_structure with {"owner": "${owner}", "repo": "${repo}", "branch": "${defaultBranch}", "path": ""}`,
+        });
     }
-    catch {
-        // Fallback to generic message if search fails
+    else {
+        return createResult({
+            error: `Repository "${owner}/${repo}" structure not accessible in any branch (tried: ${triedBranches.join(', ')}).${defaultBranchInfo}
+
+Repository might be empty, private, or you might not have sufficient permissions.
+
+Alternative solutions:
+• Verify permissions: api_status_check
+• Search accessible repos: github_search_code with owner="${owner}"
+• Try different branch: github_view_repo_structure with {"owner": "${owner}", "repo": "${repo}", "branch": "${defaultBranch}", "path": ""}`,
+        });
+    }
+}
+/**
+ * Handle other types of errors (403, rate limits, etc.)
+ */
+function handleOtherErrors(owner, repo, errorMsg) {
+    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 {
+        return createResult({
+            error: `Failed to access "${owner}/${repo}": ${errorMsg}. Check network connection and repository permissions.`,
+        });
     }
-    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_SEARCH_ISSUES_TOOL_NAME = 'githubSearchIssues';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-mcp",
-  "version": "2.3.10",
+  "version": "2.3.11",
   "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://octocode.ai",