octocode-mcp 1.1.0 → 2.2.0

package/build/index.js

@@ -14,7 +14,6 @@ const TOOL_NAMES = {
     GITHUB_SEARCH_COMMITS: 'github_search_commits',
     GITHUB_SEARCH_ISSUES: 'github_search_issues',
     GITHUB_SEARCH_PULL_REQUESTS: 'github_search_pull_requests',
-    GITHUB_SEARCH_DISCUSSIONS: 'github_search_discussions',
     GITHUB_SEARCH_TOPICS: 'github_search_topics',
     GITHUB_SEARCH_USERS: 'github_search_users',
     // GitHub Repository API (/repos/*)
@@ -23,180 +22,447 @@ const TOOL_NAMES = {
     GITHUB_GET_FILE_CONTENT: 'github_get_file_content',
     // GitHub Users API (/user/*)
     GITHUB_GET_USER_ORGS: 'github_get_user_organizations',
-    // npm Registry API
+    // System & API Status
+    API_STATUS_CHECK: 'api_status_check',
+    // npm Registry API - Comprehensive
     NPM_SEARCH_PACKAGES: 'npm_search_packages',
     NPM_GET_PACKAGE: 'npm_get_package',
-    NPM_GET_PACKAGE_STATS: 'npm_get_package_stats',
-    NPM_ANALYZE_DEPENDENCIES: 'npm_analyze_dependencies'};
-
-const PROMPT_SYSTEM_PROMPT = `**Expert Code Discovery Assistant** - Find production-ready implementations from GitHub/npm repositories.
-
-## CORE STRATEGY
-1. **NPM Primary** - ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.NPM_GET_PACKAGE} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
-2. **Topics Foundation** - ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} for terminology discovery
-3. **Private Organizations** - Auto-detect (@company/) → ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-4. **Code Extraction** - ${TOOL_NAMES.GITHUB_SEARCH_CODE} + ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
-5. **Repository Search** - ${TOOL_NAMES.GITHUB_SEARCH_REPOS} only when NPM+Topics fail
-
-## TOOL PRIORITY ORDER
-
-### Primary Discovery
-- ${TOOL_NAMES.NPM_SEARCH_PACKAGES} - Package discovery
-- ${TOOL_NAMES.NPM_GET_PACKAGE} - Repository mapping
-- ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} - Security audit
-
-### Foundation
-- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} - Ecosystem terminology
-- ${TOOL_NAMES.GITHUB_GET_USER_ORGS} - Private access (auto-trigger)
-
-### Repository Operations
-- ${TOOL_NAMES.GITHUB_GET_REPOSITORY} - Branch discovery (mandatory first)
-- ${TOOL_NAMES.GITHUB_GET_CONTENTS} - Directory exploration
-- ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Implementation search
-- ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT} - Code extraction
-
-### Context & Analysis
-- ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} - Problem discovery
-- ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Implementation patterns
-- ${TOOL_NAMES.GITHUB_SEARCH_COMMITS} - Development history
-- ${TOOL_NAMES.NPM_GET_PACKAGE_STATS} - Package maturity
-
-### Fallback
-- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Enhanced repository search (last resort)
-- ${TOOL_NAMES.GITHUB_SEARCH_USERS} - Expert discovery
-
-## QUERY WORKFLOWS
-
-### Discovery Intent ("find react libraries")
-NPM search → Package analysis → Topics → Code extraction
-
-### Private Organization ("@wix/package", "I work at Company")
-Auto-trigger: IMMEDIATE ${TOOL_NAMES.GITHUB_GET_USER_ORGS} → NPM search → Private repo access
-
-### Problem Solving ("fix auth error") 
-NPM packages → Repository analysis → Issues → Code solutions
-
-### Implementation Intent ("react authentication implementation")
-NPM search → Repository access → Code search → File extraction
-
-## CRITICAL AUTO-TRIGGERS
-
-### Private Organization Detection
-- Package scopes: @wix/, @company/ → IMMEDIATE ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-- Enterprise context: "I work at", "company codebase" → Auto-trigger
-- Private indicators: "team repos", "enterprise setup" → Organization access
-
-### Mandatory Workflows  
-- ALWAYS use ${TOOL_NAMES.GITHUB_GET_REPOSITORY} before file operations
-- ALWAYS follow ${TOOL_NAMES.NPM_GET_PACKAGE} with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
-- NEVER retry same terms twice with any tool
-
-## SUCCESS TARGETS
-- 0 results: Comprehensive fallback workflow
-- 1-20 results: IDEAL for analysis
-- 21-100 results: GOOD, apply filters
-- 100+ results: AUTO-SUGGEST npm workflow
-
-## ERROR RECOVERY
-
-### API Errors (403/401)
-1. Check organizational context (@company/, "work at")
-2. Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access
-3. Retry with organization as 'owner'
-4. Fallback to public search
-
-### Zero Results
-- NPM Search: Try broader single-word terms
-- Code Search: Remove path filters, try synonyms  
-- Repository Search: Remove language filters
-- Topics Search: Use more general terms
-
-### Rate Limits
-1. Cache successful results
-2. Switch to ${TOOL_NAMES.NPM_SEARCH_PACKAGES}
-3. Use cached repository information
-4. Provide retry guidance
-
-## SEARCH OPTIMIZATION
-
-### NPM Discovery (95% success rate)
-- Single terms: "react", "auth", "cli"
-- Combined terms: "react-hooks", "typescript-cli"
-- Avoid complexity: Complex phrases yield zero results
-
-### Code Search Patterns
-- Boolean: "useState OR useEffect", "function NOT test"
-- Path warnings: React uses path:packages (NOT path:src)
-- Repository-specific: facebook/react + "useEffect"
-
-### Repository Search (Last Resort)
-- Single terms work best vs multi-term failures
-- Validated: microsoft + typescript ✅, multi-language ❌
-- Progressive refinement: Start broad, narrow systematically
-
-## RESPONSE FORMAT
-\`\`\`language:owner/repo/filepath
-// Complete implementation with context
-// Production usage patterns
-\`\`\`
-
-**Discovery Path**: Document NPM-first workflow and fallbacks
-**Security Assessment**: Include vulnerability analysis
-**Repository Status**: Activity level, maintenance quality
-
-## INTEGRATION EXAMPLES
-
-### Standard Flow
-npmSearchPackages({query: "react"}) → npmGetPackage({packageName: "react"}) → githubGetRepository({owner: "facebook", repo: "react"}) → githubSearchCode({query: "useState"})
-
-### Private Organization
-Detect @wix/ → githubGetUserOrganizations() → githubSearchRepos({owner: "wix-private"})
-
-### Error Recovery  
-npmSearchPackages fails → githubSearchTopics({query: "authentication"}) → githubSearchRepos({query: "auth"})
-
-**OUTPUT GOAL**: Complete, secure, production-ready code with repository citations and security assessment via efficient NPM-first discovery.`;
+    NPM_ANALYZE_DEPENDENCIES: 'npm_analyze_dependencies',
+    // npm Registry API - Focused (minimal token usage)
+    NPM_GET_REPOSITORY: 'npm_get_repository',
+    NPM_GET_DEPENDENCIES: 'npm_get_dependencies',
+    NPM_GET_BUGS: 'npm_get_bugs',
+    NPM_GET_README: 'npm_get_readme',
+    NPM_GET_VERSIONS: 'npm_get_versions',
+    NPM_GET_AUTHOR: 'npm_get_author',
+    NPM_GET_LICENSE: 'npm_get_license',
+    NPM_GET_HOMEPAGE: 'npm_get_homepage',
+    NPM_GET_ID: 'npm_get_id',
+    NPM_GET_RELEASES: 'npm_get_releases',
+    NPM_GET_ENGINES: 'npm_get_engines',
+    NPM_GET_EXPORTS: 'npm_get_exports'};
+
+const PROMPT_SYSTEM_PROMPT = `**Universal Research Intelligence Engine** - Comprehensive discovery, analysis, and insights across all domains of knowledge.
+
+## 🛠️ CRITICAL: API STATUS VERIFICATION FIRST
+
+**MANDATORY FIRST STEP:** Always begin research sessions with ${TOOL_NAMES.API_STATUS_CHECK} to:
+- Verify GitHub CLI authentication (gh auth status)
+- Confirm NPM registry connectivity (npm ping)
+- Analyze real-time GitHub API rate limits across all endpoints
+- Get intelligent research strategy recommendations based on current API capacity
+
+**RESEARCH STRATEGY ADAPTATION:**
+- **READY Status**: Proceed with comprehensive multi-tool research
+- **LIMITED Status**: Use targeted searches, avoid broad exploration
+- **NOT_READY Status**: Guide user through authentication/connectivity setup
+
+**API-AWARE RESEARCH PLANNING:**
+- Code Search < 5 remaining → Use repository browsing instead
+- Search API < 20 remaining → Focus on specific repositories
+- Core API < 200 remaining → Minimize repository exploration
+- NPM disconnected → GitHub-only research mode
+
+## ADAPTIVE RESEARCH METHODOLOGY
+
+### SEMANTIC TOPIC DETECTION & ADAPTATION
+Automatically detect query intent and adapt research strategy:
+
+**TECHNOLOGY & SOFTWARE** → NPM packages, GitHub repositories, code implementations, documentation
+**ACADEMIC & RESEARCH** → GitHub topics, research repositories, academic projects, papers
+**BUSINESS & ORGANIZATIONS** → Company repositories, organizational projects, business tools
+**CREATIVE & MEDIA** → Creative coding, media projects, artistic repositories, design systems
+**EDUCATION & LEARNING** → Educational resources, tutorials, learning materials, course content
+**SCIENCE & DATA** → Data science projects, scientific computing, research datasets, analysis tools
+**GENERAL KNOWLEDGE** → Any topic through GitHub's vast ecosystem of projects and discussions
+
+### UNIVERSAL RESEARCH DIMENSIONS
+Every query requires investigation across multiple dimensions:
+
+**1. DISCOVERY & EXPLORATION**
+- Find relevant projects, packages, and implementations
+- Identify multiple approaches and methodologies
+- Locate official vs community resources
+- Discover edge cases and alternative solutions
+
+**2. ECOSYSTEM ANALYSIS** 
+- Understand relationships and dependencies
+- Analyze community adoption and trends
+- Evaluate maintenance and support status
+- Assess quality and reliability indicators
+
+**3. QUALITY & CREDIBILITY ASSESSMENT**
+- Project quality and architecture evaluation
+- Performance characteristics and benchmarks
+- Documentation completeness and clarity
+- Community engagement and activity levels
+
+**4. CONTEXTUAL INTELLIGENCE**
+- Trade-offs vs alternative approaches
+- Scalability and practical considerations
+- Integration complexity and requirements
+- Learning curve and accessibility
+
+**5. STRATEGIC INSIGHTS**
+- Future trends and evolution patterns
+- Community momentum and backing
+- Suitability for different use cases
+- Migration paths and compatibility
+
+## INTELLIGENT TOOL SELECTION STRATEGY
+
+### SEMANTIC QUERY ANALYSIS
+Analyze query semantics to determine optimal tool combination:
+
+**PACKAGE/LIBRARY QUERIES** → NPM-first approach
+**PROJECT/REPOSITORY QUERIES** → GitHub repository search
+**TOPIC/CONCEPT QUERIES** → GitHub topics exploration
+**IMPLEMENTATION QUERIES** → Code search and file extraction
+**PROBLEM/SOLUTION QUERIES** → Issues and discussions search
+**PEOPLE/EXPERTISE QUERIES** → User and organization discovery
+
+### ADAPTIVE SEARCH PATTERNS
+
+**FOR TECHNOLOGY TOPICS:**
+- ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → Package ecosystem discovery
+- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} → Technology landscape mapping
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Implementation patterns
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Project repositories
+
+**FOR RESEARCH/ACADEMIC TOPICS:**
+- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} → Research area exploration
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Academic projects and papers
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Research implementations
+- ${TOOL_NAMES.GITHUB_SEARCH_USERS} → Researcher discovery
+
+**FOR BUSINESS/ORGANIZATIONAL TOPICS:**
+- ${TOOL_NAMES.GITHUB_GET_USER_ORGS} → Organization discovery
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Company projects
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Internal implementations
+- ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} → Business discussions
+
+**FOR CREATIVE/MEDIA TOPICS:**
+- ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} → Creative technology trends
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} → Creative projects and tools
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Creative implementations
+- ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → Creative libraries and tools
+
+## UNIVERSAL BOOLEAN SEARCH INTELLIGENCE
+
+### SEMANTIC EXPANSION PATTERNS
+Automatically enhance queries with domain-appropriate boolean operators:
+
+**UNIVERSAL DOMAIN PATTERNS:**
+- **Core Concepts**: "primary_term OR synonym OR variation OR abbreviation"
+- **Quality Focus**: "concept OR approach OR method OR technique NOT test NOT demo"
+- **Comprehensive Coverage**: "topic OR field OR domain OR area OR discipline"
+- **Implementation Focus**: "solution OR tool OR system OR framework OR platform"
+
+**ADAPTIVE SEMANTIC ENHANCEMENT:**
+- **Academic/Research**: "research OR study OR analysis OR investigation OR methodology"
+- **Creative/Artistic**: "creative OR artistic OR design OR visual OR aesthetic OR expression"
+- **Business/Professional**: "business OR professional OR commercial OR enterprise OR industry"
+- **Educational/Learning**: "education OR learning OR tutorial OR guide OR instruction OR knowledge"
+- **Technical/Scientific**: "technical OR scientific OR systematic OR analytical OR computational"
+- **Social/Community**: "social OR community OR collaborative OR public OR collective"
+
+**CONTEXTUAL BOOLEAN PATTERNS:**
+- **Problem-Solving**: "solution OR approach OR method OR strategy OR technique"
+- **Tool Discovery**: "tool OR utility OR application OR platform OR system OR framework"
+- **Knowledge Seeking**: "guide OR tutorial OR documentation OR resource OR reference"
+- **Community Building**: "community OR collaboration OR network OR group OR organization"
+- **Innovation Exploration**: "innovation OR experimental OR cutting-edge OR emerging OR novel"
+
+## ADAPTIVE RESEARCH WORKFLOWS
+
+### DISCOVERY INTENT DETECTION
+Automatically route based on query patterns:
+
+**"Find [topic] tools/resources"** → Package + Topic + Repository Discovery
+**"How to [accomplish/solve]"** → Content search + Community discussions + Documentation
+**"Who works on [topic]"** → User + Organization + Contributor Discovery
+**"What's trending in [domain]"** → Topic + Popular projects + Recent activity
+**"Compare [A] vs [B]"** → Multi-target analysis + Community discussions
+**"Learn about [concept]"** → Educational resources + Documentation + Examples
+**"Research [topic]"** → Academic projects + Data + Methodology discovery
+**"Create [something]"** → Tools + Frameworks + Creative resources
+**"Analyze [subject]"** → Data tools + Visualization + Analytics resources
+
+### CONTEXTUAL WORKFLOW ADAPTATION
+
+**DISCOVERY QUERIES:**
+1. Topic landscape mapping (${TOOL_NAMES.GITHUB_SEARCH_TOPICS})
+2. Resource discovery (${TOOL_NAMES.NPM_SEARCH_PACKAGES})
+3. Project exploration (${TOOL_NAMES.GITHUB_SEARCH_REPOS})
+4. Content analysis (${TOOL_NAMES.GITHUB_SEARCH_CODE})
+
+**RESEARCH QUERIES:**
+1. Domain exploration (${TOOL_NAMES.GITHUB_SEARCH_TOPICS})
+2. Academic project discovery (${TOOL_NAMES.GITHUB_SEARCH_REPOS})
+3. Methodology analysis (${TOOL_NAMES.GITHUB_SEARCH_CODE})
+4. Expert network discovery (${TOOL_NAMES.GITHUB_SEARCH_USERS})
+
+**SOLUTION QUERIES:**
+1. Resource identification (${TOOL_NAMES.NPM_SEARCH_PACKAGES})
+2. Project discovery (${TOOL_NAMES.GITHUB_SEARCH_REPOS})
+3. Implementation analysis (${TOOL_NAMES.GITHUB_SEARCH_CODE})
+4. Community support (${TOOL_NAMES.GITHUB_SEARCH_ISSUES})
+
+## SEMANTIC PROPOSITION FRAMEWORK
+
+### DYNAMIC GUIDANCE SYSTEM
+Provide context-aware recommendations based on detected domain:
+
+**UNIVERSAL PROPOSITIONS:**
+- "Consider quality indicators and community engagement"
+- "Evaluate approach diversity and methodological rigor"
+- "Assess resource accessibility and learning curve"
+- "Review documentation completeness and clarity"
+
+**RESEARCH PROPOSITIONS:**
+- "Examine methodology and experimental design"
+- "Evaluate data quality and reproducibility"
+- "Consider peer validation and citation patterns"
+- "Assess theoretical foundations and practical applications"
+
+**CREATIVE PROPOSITIONS:**
+- "Explore artistic expression and creative possibilities"
+- "Consider aesthetic principles and design philosophy"
+- "Evaluate creative tools and workflow integration"
+- "Assess community engagement and inspiration sources"
+
+**BUSINESS PROPOSITIONS:**
+- "Analyze market adoption and practical viability"
+- "Evaluate cost-benefit and resource requirements"
+- "Consider scalability and implementation complexity"
+- "Assess competitive landscape and differentiation"
+
+**EDUCATIONAL PROPOSITIONS:**
+- "Examine learning pathways and skill progression"
+- "Evaluate pedagogical approach and accessibility"
+- "Consider prerequisite knowledge and learning curve"
+- "Assess practical application and real-world relevance"
+
+**COMMUNITY PROPOSITIONS:**
+- "Explore collaboration opportunities and network effects"
+- "Evaluate community health and engagement patterns"
+- "Consider contribution pathways and skill development"
+- "Assess social impact and collective benefit"
+
+## UNIVERSAL ANTI-HALLUCINATION SAFEGUARDS
+
+### DOMAIN-AGNOSTIC VALIDATION
+- **Existence Verification**: Confirm resources exist before deep analysis
+- **Cross-Reference Validation**: Verify findings across multiple sources
+- **Community Consensus**: Check for widespread adoption vs niche experiments
+- **Recency Assessment**: Evaluate currency and maintenance status
+- **Authority Validation**: Assess source credibility and expertise
+
+### PROGRESSIVE REFINEMENT STRATEGY
+- **Broad Discovery**: Start with general terms and concepts
+- **Semantic Expansion**: Add related terms and variations
+- **Context Filtering**: Apply domain-specific filters and exclusions
+- **Quality Assessment**: Evaluate results for relevance and quality
+- **Deep Analysis**: Extract detailed insights from validated sources
+
+## INTELLIGENT RESULT SYNTHESIS
+
+### MULTI-DIMENSIONAL ANALYSIS
+For every comprehensive answer, provide:
+
+**LANDSCAPE OVERVIEW**
+- Current state of the domain/topic
+- Key players and influential projects
+- Trending approaches and methodologies
+- Community dynamics and adoption patterns
+
+**PRACTICAL INSIGHTS**
+- Actionable recommendations with rationale
+- Common challenges and solution approaches
+- Best practices and proven patterns
+- Learning resources and next steps
+
+**STRATEGIC CONTEXT**
+- Future trends and evolution directions
+- Trade-offs and decision frameworks
+- Suitability for different use cases
+- Risk assessment and mitigation strategies
+
+**COMMUNITY INTELLIGENCE**
+- Expert contributors and thought leaders
+- Active discussions and debates
+- Collaborative opportunities and networks
+- Knowledge gaps and research opportunities
+
+## ADAPTIVE ERROR RECOVERY
+
+### SEMANTIC FALLBACK STRATEGIES
+When primary searches fail, automatically adapt:
+
+**TERM EXPANSION**: Broaden to related concepts and synonyms
+**DOMAIN SHIFTING**: Explore adjacent fields and applications
+**ABSTRACTION LEVELS**: Move between specific and general concepts
+**TEMPORAL ADJUSTMENT**: Consider historical vs cutting-edge approaches
+**COMMUNITY PIVOTING**: Shift from technical to social/community aspects
+
+### INTELLIGENT GUIDANCE
+Provide domain-appropriate suggestions for:
+- Alternative search strategies
+- Related topics worth exploring
+- Community resources and experts
+- Learning pathways and next steps
+
+**OUTPUT GOAL**: Comprehensive, accurate, and actionable insights across any domain of knowledge, leveraging GitHub's vast ecosystem of human knowledge and collaboration.`;
 
 const TOOL_DESCRIPTIONS = {
-    [TOOL_NAMES.NPM_SEARCH_PACKAGES]: `**PRIMARY DISCOVERY TOOL** - Main entry point for package and repository discovery.
-
-**WHEN TO USE:** Package discovery by keyword, when user mentions package names, organizational package detection (@company/ scopes).
-
-**SEARCH STRATEGY:**
-1. Single terms: "react", "cli", "auth"
-2. Combined terms: "react-hooks", "typescript-cli"  
-3. Avoid complexity: Complex phrases yield zero results
-
-**ORGANIZATIONAL DETECTION:** @company/ packages → Trigger ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-
-**RESULT OPTIMIZATION:** 0 results → broader terms, 1-20 IDEAL, 100+ → more specific terms
-
-**INTEGRATION:** ALWAYS chain to ${TOOL_NAMES.NPM_GET_PACKAGE} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}`,
-    [TOOL_NAMES.NPM_GET_PACKAGE]: `**Repository mapping** - Transform npm packages into GitHub repositories for code analysis.
-
-**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_SEARCH_PACKAGES}, user mentions package names, private package detection (@company/).
-
-**WORKFLOW:** Extract repository URL → Parse owner/repo → Detect organizational context → Chain to ${TOOL_NAMES.GITHUB_GET_REPOSITORY} → MANDATORY ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
-
-**ORGANIZATIONAL DETECTION:** @company/ scoped packages → Trigger ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-
-**EXAMPLES:** "react" → github.com/facebook/react, "@wix/package" → Private org detection`,
+    [TOOL_NAMES.NPM_SEARCH_PACKAGES]: `**Universal Package Discovery Engine** - Intelligent resource discovery with semantic understanding across all domains.
+
+**🧠 SEMANTIC PACKAGE INTELLIGENCE:**
+- **DOMAIN-ADAPTIVE SEARCH**: Automatically detects query intent and adapts search strategy
+- **UNIVERSAL RESOURCE DISCOVERY**: Finds packages, tools, libraries, frameworks across any field
+- **INTELLIGENT CATEGORIZATION**: Understands technology, creative, business, educational, scientific packages
+- **CONTEXTUAL RECOMMENDATIONS**: Provides domain-specific guidance and alternatives
+
+**🎯 ADAPTIVE SEARCH STRATEGIES:**
+- **TECHNOLOGY PACKAGES** → Development tools, frameworks, libraries, utilities
+- **CREATIVE PACKAGES** → Design tools, media processing, artistic frameworks, generators
+- **BUSINESS PACKAGES** → Analytics, automation, productivity, management tools
+- **EDUCATIONAL PACKAGES** → Learning resources, documentation generators, tutorial tools
+- **SCIENTIFIC PACKAGES** → Data analysis, visualization, computation, research tools
+- **UTILITY PACKAGES** → General-purpose tools, helpers, converters, processors
+
+**🚀 INTELLIGENT QUERY OPTIMIZATION:**
+1. **Single Terms**: "visualization", "automation", "analysis", "design"
+2. **Combined Concepts**: "data-visualization", "workflow-automation", "content-management"
+3. **Domain Bridging**: Technical terms → accessible language, specific → general
+4. **Semantic Expansion**: Core concept → related terms → ecosystem discovery
+
+**💡 UNIVERSAL SEARCH PATTERNS:**
+- **"data visualization"** → Charts, graphs, dashboards, plotting tools
+- **"content management"** → CMS, publishing, editorial, workflow tools  
+- **"image processing"** → Graphics, filters, conversion, manipulation tools
+- **"workflow automation"** → Task runners, schedulers, pipeline tools
+- **"learning resources"** → Educational, tutorial, documentation tools
+
+**🌍 CROSS-DOMAIN EXAMPLES:**
+- **CREATIVE DOMAIN**: "design OR graphics OR visual OR creative OR artistic"
+- **BUSINESS DOMAIN**: "management OR analytics OR productivity OR automation"
+- **RESEARCH DOMAIN**: "analysis OR data OR research OR scientific OR academic"
+- **EDUCATIONAL DOMAIN**: "learning OR tutorial OR education OR documentation"
+- **UTILITY DOMAIN**: "tool OR utility OR helper OR converter OR processor"
+
+**🔧 ORGANIZATIONAL INTELLIGENCE:**
+- **@organization/** packages → Triggers private/enterprise discovery workflow
+- **Internal/Private** indicators → Activates organizational context search
+- **Enterprise** patterns → Suggests organizational repository exploration
+
+**⚡ SEARCH OPTIMIZATION:**
+- **0 results** → Broader terms, ecosystem exploration, alternative approaches
+- **1-20 results** → IDEAL scope for detailed analysis and comparison
+- **100+ results** → More specific terms, domain filters, focused refinement
+- **Organizational scope** → Private package discovery, enterprise workflows
+
+**🔄 INTELLIGENT FALLBACK STRATEGIES:**
+When package search yields insufficient results:
+1. **Ecosystem Exploration** → Related technology/domain discovery
+2. **Repository Search** → Direct project/tool discovery  
+3. **Topic Analysis** → Domain terminology and trend identification
+4. **Community Discovery** → Expert and organization identification
+5. **Content Search** → Implementation and usage pattern analysis
+6. **Discussion Mining** → Problem-solving and solution discovery
+
+**🎨 DOMAIN-SPECIFIC INTELLIGENCE:**
+- **Creative Tools**: Design, media, art, visualization, creative coding
+- **Business Solutions**: Analytics, automation, management, productivity
+- **Research Instruments**: Data analysis, computation, visualization, modeling
+- **Educational Resources**: Learning, documentation, tutorials, guides
+- **Utility Collections**: Helpers, converters, processors, generators
+
+**INPUT**: Any concept, tool, or resource need across any domain
+**OUTPUT**: Comprehensive package ecosystem with domain-adapted insights and alternatives`,
     [TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES]: `**CRITICAL: Package security analysis** - Essential for package evaluation and organizational detection.
 
-**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_GET_PACKAGE} for complete assessment.
+**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_SEARCH_PACKAGES} for complete assessment.
 
 **ANALYSIS:** Security vulnerabilities, dependency tree, license compatibility, bundle impact, organization detection (@company/).
 
-**ORGANIZATIONAL CONTEXT:** Private packages → Check ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access`,
-    [TOOL_NAMES.GITHUB_SEARCH_TOPICS]: `**FOUNDATION TOOL** - Essential for ecosystem discovery and terminology mapping.
-
-**SEARCH STRATEGY:** Start global, single terms ("react", "typescript"), multi-term sparingly ("react+typescript"), add owner only when needed.
-
-**BEST PRACTICES:** DON'T start with owner (limits discovery), DO start broad, USE single terms mostly.
-
-**RESULT OPTIMIZATION:** 1-10 IDEAL, 10+ add featured/curated filters
-
-**INTEGRATION:** CRITICAL foundation - use before other GitHub tools, after ${TOOL_NAMES.NPM_SEARCH_PACKAGES}`,
+**ORGANIZATIONAL CONTEXT:** Private packages → Check ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access
+
+**KNOWN LIMITATION:** Some NPM audit failures may occur (package-specific). Bundle analysis and dependency tree remain reliable.`,
+    [TOOL_NAMES.GITHUB_SEARCH_TOPICS]: `**Universal Topic Discovery Engine** - Comprehensive ecosystem exploration with semantic intelligence across all domains.
+
+**🧠 SEMANTIC TOPIC INTELLIGENCE:**
+- **DOMAIN-AGNOSTIC DISCOVERY**: Explores any field, discipline, or area of interest
+- **ECOSYSTEM MAPPING**: Reveals relationships, trends, and communities across topics
+- **CONTEXTUAL UNDERSTANDING**: Adapts recommendations based on query domain and intent
+- **CROSS-POLLINATION**: Discovers unexpected connections between different fields
+
+**🎯 UNIVERSAL EXPLORATION PATTERNS:**
+- **SINGLE TERMS**: "sustainability", "automation", "creativity", "wellness", "education"
+- **COMPOUND CONCEPTS**: "machine-learning", "user-experience", "data-science", "digital-art"
+- **DOMAIN BRIDGING**: Technical ↔ Creative ↔ Business ↔ Academic ↔ Social
+
+**🌍 CROSS-DOMAIN TOPIC DISCOVERY:**
+- **TECHNOLOGY DOMAINS**: "ai", "blockchain", "iot", "cybersecurity", "cloud-computing"
+- **CREATIVE DOMAINS**: "design", "art", "music", "writing", "photography", "animation"
+- **BUSINESS DOMAINS**: "entrepreneurship", "marketing", "finance", "management", "strategy"
+- **ACADEMIC DOMAINS**: "research", "education", "science", "mathematics", "psychology"
+- **SOCIAL DOMAINS**: "community", "activism", "sustainability", "health", "culture"
+- **LIFESTYLE DOMAINS**: "fitness", "cooking", "travel", "productivity", "mindfulness"
+
+**🚀 INTELLIGENT SEARCH STRATEGIES:**
+1. **Broad Discovery**: Start with core concepts to map the landscape
+2. **Semantic Expansion**: Related terms, synonyms, and variations
+3. **Community Identification**: Active projects, contributors, and organizations
+4. **Trend Analysis**: Emerging topics, popular projects, and growth patterns
+5. **Cross-Domain Connections**: Unexpected intersections and collaborations
+
+**💡 ADAPTIVE TOPIC PATTERNS:**
+- **"sustainability"** → Environmental, green-tech, renewable, climate, conservation
+- **"creativity"** → Art, design, innovation, expression, generative, artistic
+- **"wellness"** → Health, fitness, mental-health, mindfulness, nutrition
+- **"automation"** → Workflow, productivity, efficiency, tools, processes
+- **"learning"** → Education, tutorial, knowledge, skill-development, training
+
+**🔍 DISCOVERY METHODOLOGIES:**
+- **ECOSYSTEM EXPLORATION**: Map entire domains and their sub-communities
+- **TREND IDENTIFICATION**: Spot emerging topics and growing communities
+- **COMMUNITY MAPPING**: Find active contributors and thought leaders
+- **RESOURCE DISCOVERY**: Locate tools, frameworks, and learning materials
+- **COLLABORATION OPPORTUNITIES**: Identify potential partnerships and projects
+
+**⚡ SEARCH OPTIMIZATION STRATEGIES:**
+- **1-10 TOPICS**: Perfect scope for deep domain analysis
+- **10+ TOPICS**: Rich ecosystem with multiple exploration paths
+- **Featured/Curated**: High-quality, community-validated topics
+- **Repository Count**: Indicates community size and activity level
+
+**🎨 DOMAIN-SPECIFIC INTELLIGENCE:**
+- **CREATIVE EXPLORATION**: Art, design, media, expression, aesthetics
+- **BUSINESS INTELLIGENCE**: Strategy, operations, innovation, market trends
+- **RESEARCH DISCOVERY**: Academic, scientific, experimental, methodological
+- **EDUCATIONAL RESOURCES**: Learning, teaching, knowledge transfer, skill building
+- **SOCIAL IMPACT**: Community, activism, sustainability, social good
+- **PERSONAL DEVELOPMENT**: Wellness, productivity, skills, lifestyle, growth
+
+**🔄 PROGRESSIVE DISCOVERY WORKFLOW:**
+1. **Core Topic Exploration** → Understand the fundamental landscape
+2. **Related Topic Discovery** → Find adjacent and complementary areas
+3. **Community Identification** → Locate active contributors and projects
+4. **Resource Mapping** → Discover tools, frameworks, and materials
+5. **Trend Analysis** → Identify emerging patterns and opportunities
+6. **Cross-Domain Bridging** → Find unexpected connections and innovations
+
+**🌟 UNIVERSAL APPLICATIONS:**
+- **Research Planning**: Explore academic and scientific domains
+- **Business Strategy**: Identify market trends and opportunities  
+- **Creative Inspiration**: Discover artistic and design communities
+- **Learning Pathways**: Find educational resources and skill development
+- **Community Building**: Locate like-minded individuals and organizations
+- **Innovation Discovery**: Spot emerging technologies and methodologies
+
+**INPUT**: Any topic, concept, interest, or domain of inquiry
+**OUTPUT**: Comprehensive ecosystem map with community insights, trends, and exploration pathways`,
     [TOOL_NAMES.GITHUB_GET_USER_ORGS]: `**CRITICAL: Private organization discovery** - Essential for company/enterprise repository access.
 
 **AUTO-TRIGGERS:** @wix/, @company/, "I work at [Company]", "internal code", "enterprise setup"
@@ -204,31 +470,102 @@ const TOOL_DESCRIPTIONS = {
 **WORKFLOW:** IMMEDIATE call when organizational context detected → Match company to organizations → Use as 'owner' parameter → Enable private repository access
 
 **INTEGRATION:** MANDATORY first step when private access likely needed`,
-    [TOOL_NAMES.GITHUB_GET_REPOSITORY]: `**CRITICAL FIRST STEP** - Required before all GitHub file operations.
+    [TOOL_NAMES.GITHUB_GET_REPOSITORY]: `**CRITICAL FIRST STEP** - Required before all GitHub file operations, but ONLY after discovery.
 
 **PURPOSE:** Discover default branch and repository metadata to prevent tool failures.
 
-**REQUIRED BEFORE:** ${TOOL_NAMES.GITHUB_SEARCH_CODE}, ${TOOL_NAMES.GITHUB_GET_CONTENTS}, ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
-
-**CRITICAL:** NEVER skip before file operations, NEVER assume branch names, NEVER proceed if branch discovery fails`,
-    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `**Precision code search** - Advanced search with automatic repository scoping.
-
-**KEY FEATURES:** Every search includes "repo:owner/repository", smart boolean logic, organizational context.
+**MANDATORY PREREQUISITES:** Repository owner/name MUST be discovered first through:
+1. ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.NPM_GET_PACKAGE} (for packages)
+2. ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} (for ecosystem discovery)  
+3. ${TOOL_NAMES.GITHUB_SEARCH_REPOS} (last resort)
 
-**BOOLEAN OPERATIONS:** Default AND ("sparse index" = "sparse AND index"), OR ("useState OR useEffect"), NOT ("error NOT test")
-
-**PATH WARNING:** React uses path:packages (NOT path:src). Using path:src on repositories without top-level src returns zero results.
-
-**RESULT OPTIMIZATION:** 1-10 IDEAL, 100+ TOO BROAD
+**REQUIRED BEFORE:** ${TOOL_NAMES.GITHUB_SEARCH_CODE}, ${TOOL_NAMES.GITHUB_GET_CONTENTS}, ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
 
-**INTEGRATION:** Use after ${TOOL_NAMES.GITHUB_GET_REPOSITORY} for branch discovery`,
+**CRITICAL:** NEVER call with guessed repository names. ALWAYS use discovery workflow first.`,
+    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `**Universal Content Discovery Engine** - Intelligent search with automatic domain adaptation and semantic understanding.
+
+**🧠 SEMANTIC QUERY INTELLIGENCE - ADAPTS TO ANY DOMAIN:**
+- **AUTOMATIC DOMAIN DETECTION**: Analyzes query intent and adapts search strategy accordingly
+- **UNIVERSAL BOOLEAN ENHANCEMENT**: Converts any query into optimal boolean patterns for maximum efficiency
+- **CROSS-DOMAIN EXPERTISE**: Handles technology, research, business, creative, educational, scientific topics
+- **CONTEXTUAL INTELLIGENCE**: Provides domain-specific guidance based on query semantics
+
+**🎯 ADAPTIVE SEMANTIC PATTERNS:**
+- **TECHNOLOGY QUERIES** → "framework OR library OR tool OR implementation NOT tutorial"
+- **RESEARCH QUERIES** → "study OR analysis OR research OR investigation NOT example"
+- **BUSINESS QUERIES** → "solution OR strategy OR management OR process NOT demo"
+- **CREATIVE QUERIES** → "design OR art OR creative OR visual NOT template"
+- **EDUCATIONAL QUERIES** → "learning OR education OR tutorial OR guide NOT test"
+- **SCIENTIFIC QUERIES** → "data OR analysis OR algorithm OR method NOT mock"
+
+**🚀 INTELLIGENT QUERY OPTIMIZATION:**
+- **Semantic Expansion**: Automatically adds synonyms and variations based on domain
+- **Context Enrichment**: Suggests related terms specific to the detected topic area
+- **Quality Filtering**: Adds appropriate exclusions (NOT test, NOT example, NOT demo)
+- **Progressive Refinement**: Starts broad, then narrows based on results
+
+**🔧 UNIVERSAL BOOLEAN INTELLIGENCE:**
+- **COVERAGE PATTERNS**: "primary_term OR synonym OR variation OR abbreviation"
+- **PRECISION PATTERNS**: "specific_concept AND context AND domain NOT noise"
+- **QUALITY PATTERNS**: "topic NOT test NOT example NOT demo NOT tutorial"
+- **DOMAIN PATTERNS**: "core_concept OR related_field OR application_area"
+
+**💡 SEMANTIC DOMAIN EXAMPLES:**
+- **"machine learning"** → "ml OR ai OR algorithm OR model OR neural NOT tutorial"
+- **"climate change"** → "climate OR environment OR warming OR carbon NOT simulation"
+- **"marketing strategy"** → "marketing OR strategy OR campaign OR brand NOT template"
+- **"data visualization"** → "visualization OR chart OR graph OR dashboard NOT example"
+- **"user experience"** → "ux OR ui OR design OR usability OR interface NOT mockup"
+
+**🎨 CREATIVE DOMAIN INTELLIGENCE:**
+- **Art & Design**: "creative OR artistic OR visual OR aesthetic OR design"
+- **Music & Audio**: "music OR audio OR sound OR composition OR production"
+- **Writing & Content**: "writing OR content OR narrative OR storytelling OR editorial"
+- **Media & Video**: "video OR media OR film OR animation OR production"
+
+**🔬 ACADEMIC DOMAIN INTELLIGENCE:**
+- **Research**: "research OR study OR analysis OR investigation OR methodology"
+- **Science**: "scientific OR experiment OR hypothesis OR data OR evidence"
+- **Mathematics**: "mathematical OR algorithm OR computation OR formula OR proof"
+- **Social Sciences**: "social OR behavioral OR psychological OR cultural OR demographic"
+
+**🏢 BUSINESS DOMAIN INTELLIGENCE:**
+- **Management**: "management OR leadership OR strategy OR operations OR planning"
+- **Finance**: "financial OR economic OR investment OR budget OR revenue"
+- **Marketing**: "marketing OR advertising OR branding OR promotion OR customer"
+- **Analytics**: "analytics OR metrics OR performance OR tracking OR insights"
+
+**🌍 UNIVERSAL FALLBACK STRATEGIES:**
+- **Term Simplification**: Complex phrases → core concepts
+- **Semantic Broadening**: Specific terms → general categories
+- **Cross-Domain Bridging**: Technical terms → common language
+- **Progressive Refinement**: General → specific based on results
+
+**⚡ EFFICIENCY GUARANTEES:**
+- **3-5x Performance**: Boolean queries consistently outperform simple text
+- **Automatic Enhancement**: Every query gets optimized for maximum results
+- **Smart Fallbacks**: Multiple strategies ensure you always get insights
+- **Domain Adaptation**: Recommendations tailored to your specific field
+
+**🔍 ANTI-HALLUCINATION SAFEGUARDS:**
+- **Existence Verification**: Confirms content exists before deep analysis
+- **Semantic Validation**: Checks query makes sense in detected domain
+- **Progressive Discovery**: Starts broad, narrows based on actual results
+- **Cross-Reference**: Validates findings across multiple sources
+
+**INPUT**: Any query in any domain - technology, research, business, creative, educational, scientific
+**OUTPUT**: Comprehensive, domain-adapted search results with intelligent insights and next steps`,
     [TOOL_NAMES.GITHUB_GET_FILE_CONTENT]: `**Complete code extraction** - Fetch full working implementations.
 
-**CRITICAL WORKFLOW:** MANDATORY ${TOOL_NAMES.GITHUB_GET_REPOSITORY} first → Find files with ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Extract with this tool
+**CRITICAL WORKFLOW:** MANDATORY discovery → ${TOOL_NAMES.GITHUB_GET_REPOSITORY} → Find files with ${TOOL_NAMES.GITHUB_SEARCH_CODE} or ${TOOL_NAMES.GITHUB_GET_CONTENTS} → Extract with this tool
 
 **AUTO-RECOVERY:** Specified branch → main → master → develop → trunk → try without ref
 
-**ORGANIZATIONAL CONTEXT:** Private repositories → Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access`,
+**ENHANCED ERROR HANDLING:** Provides detailed guidance when files don't exist, with alternative discovery methods
+
+**ORGANIZATIONAL CONTEXT:** Private repositories → Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access
+
+**CRITICAL:** NEVER guess file paths. Use structure exploration or code search first.`,
     [TOOL_NAMES.GITHUB_GET_CONTENTS]: `**Repository structure exploration** - Strategic directory navigation.
 
 **CRITICAL:** MANDATORY ${TOOL_NAMES.GITHUB_GET_REPOSITORY} FIRST for branch discovery.
@@ -240,8 +577,14 @@ const TOOL_DESCRIPTIONS = {
 
 **SEARCH STRATEGY:** Single keywords ("bug", "feature"), then combine ("bug fix"), never complex.
 
+**SEARCH MODES:** 
+- Global search (no owner): Searches issues across all GitHub repositories
+- Scoped search (with owner): Targeted search within specific organization/user
+
 **PROBLEM HIERARCHY:** "React auth JWT error" → "authentication" → "React" → "token expired" → "JWT"
 
+**PAGINATION LIMITATION:** GitHub CLI limited to --limit parameter only (no page navigation).
+
 **RESULT TARGETS:** 0 → broader terms, 1-20 IDEAL, 100+ → add specific terms/filters`,
     [TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS]: `**Implementation analysis** - PR search for patterns and repository status.
 
@@ -249,48 +592,247 @@ const TOOL_DESCRIPTIONS = {
 
 **KEY FILTERS:** State (open/closed), draft (false for completed), author/reviewer, language
 
+**PAGINATION LIMITATION:** GitHub CLI limited to --limit parameter only (no page navigation).
+
 **QUALITY FOCUS:** Use review-related filters for thoroughly vetted code examples`,
     [TOOL_NAMES.GITHUB_SEARCH_COMMITS]: `**Development history** - Track code evolution and repository status.
 
 **SEARCH STRATEGY:** Start minimal ("fix", "feature", "update") with owner/repo, progressive expansion.
 
-**LIMITATIONS:** Large organizations may return org-wide results, requires text terms.
+**LIMITATIONS:** Large organizations may return org-wide results, requires text terms. GitHub CLI limited to --limit parameter only (no page navigation).
 
 **ERROR HANDLING:** "Search text required" → Use minimal keywords ("fix", "update")`,
-    [TOOL_NAMES.GITHUB_SEARCH_DISCUSSIONS]: `**Community knowledge** - Access discussions for tutorials and solutions.
-
-**DISCOVERY WORKFLOW:** ${TOOL_NAMES.NPM_GET_PACKAGE} → get repo URL → Search discussions
-
-**SEARCH STRATEGY:** Start simple ("help", "tutorial"), build complexity ("help deployment"), avoid full phrases.
-
-**KEY FILTERS:** Answered: true for validated solutions, category filters, maintainer participation`,
     [TOOL_NAMES.GITHUB_SEARCH_USERS]: `**Developer discovery** - Find experts and community leaders.
 
 **SEARCH METHODOLOGY:** Technology terms ("react", "python") → add context (location, experience) → specialized search.
 
+**SEARCH MODES:** 
+- Global search (no owner): Searches users/orgs across all GitHub
+- Scoped search (with owner): Targeted search within specific organization context
+
 **KEY FILTERS:** Type (user/org), location, language, followers (">100" influential), repos (">10" active)
 
 **DISCOVERY PATTERNS:** Technology experts, local developers, open source contributors, industry leaders`,
-    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `**FALLBACK TOOL** - Repository search with smart query handling.
+    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `**Universal Project Discovery Engine** - Intelligent repository search with semantic understanding across all domains and disciplines.
+
+**🧠 SEMANTIC PROJECT INTELLIGENCE:**
+- **DOMAIN-ADAPTIVE DISCOVERY**: Automatically detects query intent and adapts search strategy
+- **UNIVERSAL PROJECT TYPES**: Finds software, research, creative, educational, business, and community projects
+- **CONTEXTUAL UNDERSTANDING**: Provides domain-specific insights and recommendations
+- **CROSS-DISCIPLINARY EXPLORATION**: Discovers projects spanning multiple fields and interests
+
+**🎯 ADAPTIVE PROJECT DISCOVERY:**
+- **TECHNOLOGY PROJECTS** → Software, tools, frameworks, applications, systems
+- **RESEARCH PROJECTS** → Academic studies, experiments, data analysis, methodologies
+- **CREATIVE PROJECTS** → Art, design, media, content, artistic expressions
+- **EDUCATIONAL PROJECTS** → Learning resources, tutorials, courses, documentation
+- **BUSINESS PROJECTS** → Solutions, automation, analytics, productivity tools
+- **COMMUNITY PROJECTS** → Open source, collaboration, social impact, activism
+
+**🚀 INTELLIGENT SEARCH STRATEGIES:**
+1. **Single Terms**: "visualization", "sustainability", "automation", "creativity"
+2. **Domain-Specific**: Add context filters based on detected field
+3. **Quality Indicators**: Star count, activity level, community engagement
+4. **Scope Management**: Global discovery vs. targeted organizational search
+
+**💡 UNIVERSAL PROJECT PATTERNS:**
+- **"data visualization"** → Charts, dashboards, plotting, analytics projects
+- **"sustainability"** → Environmental, green-tech, climate, conservation projects
+- **"education"** → Learning platforms, tutorials, courses, knowledge sharing
+- **"automation"** → Workflow tools, productivity, efficiency, process optimization
+- **"creativity"** → Art tools, design systems, creative coding, expression platforms
+
+**🌍 CROSS-DOMAIN PROJECT TYPES:**
+- **RESEARCH REPOSITORIES**: Academic papers, datasets, experiments, methodologies
+- **CREATIVE PORTFOLIOS**: Art projects, design systems, media collections
+- **BUSINESS SOLUTIONS**: Analytics tools, automation scripts, productivity apps
+- **EDUCATIONAL RESOURCES**: Learning materials, tutorials, course content
+- **COMMUNITY INITIATIVES**: Open source projects, social impact, collaboration
+- **PERSONAL PROJECTS**: Individual explorations, experiments, learning journeys
+
+**⚡ SEARCH OPTIMIZATION STRATEGIES:**
+- **0 results** → Broader terms, alternative approaches, ecosystem exploration
+- **1-20 results** → IDEAL scope for detailed analysis and comparison
+- **100+ results** → Add filters, narrow scope, focus on quality indicators
+- **Organizational scope** → Private/enterprise project discovery
+
+**🔧 INTELLIGENT FILTERING:**
+- **Quality Indicators**: Star count (>100 established, >10 active)
+- **Activity Level**: Recent updates, community engagement
+- **Project Maturity**: Development stage, documentation quality
+- **Domain Relevance**: Topic tags, description matching, content analysis
+
+**🔄 PROGRESSIVE DISCOVERY WORKFLOW:**
+1. **Broad Exploration** → Map the project landscape in your domain
+2. **Quality Filtering** → Focus on well-maintained, active projects
+3. **Community Analysis** → Identify key contributors and organizations
+4. **Feature Comparison** → Analyze capabilities and approaches
+5. **Ecosystem Understanding** → See how projects relate and complement
+6. **Selection Criteria** → Choose based on needs, quality, and fit
+
+**🎨 DOMAIN-SPECIFIC PROJECT DISCOVERY:**
+- **CREATIVE DOMAIN**: Art tools, design systems, media processing, creative coding
+- **BUSINESS DOMAIN**: Analytics, automation, productivity, management tools
+- **RESEARCH DOMAIN**: Data analysis, visualization, computation, methodology
+- **EDUCATIONAL DOMAIN**: Learning platforms, tutorials, knowledge sharing
+- **SOCIAL DOMAIN**: Community tools, activism, social impact, collaboration
+- **PERSONAL DOMAIN**: Productivity, wellness, lifestyle, skill development
+
+**🌟 UNIVERSAL APPLICATIONS:**
+- **Solution Discovery**: Find tools and projects for specific needs
+- **Research Exploration**: Locate academic and experimental projects
+- **Learning Resources**: Discover educational and tutorial projects
+- **Community Building**: Find collaborative and open source initiatives
+- **Innovation Inspiration**: Explore cutting-edge and experimental work
+- **Quality Assessment**: Compare approaches, features, and implementations
+
+**🔍 FALLBACK STRATEGIES:**
+When repository search yields insufficient results:
+1. **Package Discovery** → Find related tools and libraries
+2. **Topic Exploration** → Understand domain terminology and trends
+3. **Content Search** → Look for implementations and usage patterns
+4. **Community Discovery** → Find experts and organizations
+5. **Discussion Mining** → Explore problems and solutions
+6. **Cross-Domain Bridging** → Look in adjacent fields and applications
+
+**INPUT**: Any project need, concept, or area of interest across any domain
+**OUTPUT**: Comprehensive project landscape with quality insights and recommendations`,
+    // Focused NPM tools for minimal token usage
+    [TOOL_NAMES.NPM_GET_REPOSITORY]: `**Repository discovery** - Extract GitHub repository URL and project description.
+
+**MINIMAL OUTPUT:** Package name, description, repository URL, homepage - optimized for token efficiency.
+
+**WHEN TO USE:** When you only need repository location for GitHub operations.
+
+**INTEGRATION:** Perfect first step → ${TOOL_NAMES.GITHUB_GET_REPOSITORY} → Code exploration`,
+    [TOOL_NAMES.NPM_GET_DEPENDENCIES]: `**Dependency analysis** - Extract package dependencies tree.
+
+**MINIMAL OUTPUT:** Dependencies, devDependencies, resolutions - focused dependency data only.
+
+**WHEN TO USE:** When analyzing package ecosystem and compatibility.
+
+**INTEGRATION:** Combine with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} for security audit`,
+    [TOOL_NAMES.NPM_GET_BUGS]: `**Issue tracking** - Extract bug reporting information.
+
+**MINIMAL OUTPUT:** Package name and bugs URL - direct access to issue tracker.
+
+**WHEN TO USE:** When users need to report issues or check known problems.
+
+**INTEGRATION:** Links to ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} for problem discovery`,
+    [TOOL_NAMES.NPM_GET_README]: `**Documentation access** - Extract README filename information.
+
+**MINIMAL OUTPUT:** Package name and readme filename - efficient documentation lookup.
+
+**WHEN TO USE:** When users need documentation without full package metadata.
+
+**INTEGRATION:** Combine with ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT} for full README content`,
+    [TOOL_NAMES.NPM_GET_VERSIONS]: `**Official version tracking** - Extract production-ready semantic versions only.
+
+**MINIMAL OUTPUT:** Official versions (major.minor.patch format), latest version, count - excludes alpha/beta/rc versions.
+
+**WHEN TO USE:** Find stable versions for production deployment, analyze release cadence of stable releases.
+
+**INTEGRATION:** Perfect for production planning - filters out experimental versions for reliable deployment decisions`,
+    [TOOL_NAMES.NPM_GET_AUTHOR]: `**Maintainer information** - Extract author and maintainer details.
+
+**MINIMAL OUTPUT:** Author and maintainers list - focused ownership data.
+
+**WHEN TO USE:** When users need to contact maintainers or assess project ownership.
+
+**INTEGRATION:** Links to ${TOOL_NAMES.GITHUB_SEARCH_USERS} for developer discovery`,
+    [TOOL_NAMES.NPM_GET_LICENSE]: `**License compliance** - Extract package license information.
+
+**MINIMAL OUTPUT:** Package name and license - essential legal compliance data.
+
+**WHEN TO USE:** When users need quick license verification for legal compliance.
+
+**INTEGRATION:** Essential for enterprise package evaluation workflows`,
+    [TOOL_NAMES.NPM_GET_HOMEPAGE]: `**Official documentation gateway** - Extract package homepage for comprehensive project resources.
 
-**MANDATORY PREREQUISITES:** ${TOOL_NAMES.NPM_SEARCH_PACKAGES} and ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} must fail first.
+**MINIMAL OUTPUT:** Package name and homepage URL - direct access to live documentation, tutorials, and demos.
 
-**KEY FEATURES:** Smart multi-term handling, filter validation, fallback strategies.
+**WHEN TO USE:** Access official docs, interactive examples, getting started guides, and project showcases.
 
-**BEST PRACTICES:** Single terms work best ("react", "typescript"), validated combinations (microsoft + typescript ✅), progressive refinement.
+**INTEGRATION:** Complements ${TOOL_NAMES.NPM_GET_REPOSITORY} - homepage often contains better docs than README`,
+    [TOOL_NAMES.NPM_GET_ID]: `**Precise package targeting** - Extract exact name@version for dependency management.
 
-**MULTI-TERM HANDLING:** "react hooks auth" → structured workflow, primary term extraction, workflow guidance.
+**MINIMAL OUTPUT:** Package name and _id (name@latestVersion format) - canonical package identifier for lockfiles.
 
-**CRITICAL:** npm_search_packages → topics workflow provides superior results for 95% of use cases`,
-    [TOOL_NAMES.NPM_GET_PACKAGE_STATS]: `**Package maturity analysis** - Lifecycle assessment for package evaluation.
+**WHEN TO USE:** Pin exact versions, resolve dependency conflicts, generate package-lock entries, version compatibility checks.
 
-**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_GET_PACKAGE} for complete assessment.
+**INTEGRATION:** Critical for CI/CD pipelines, dependency auditing, and reproducible builds`,
+    [TOOL_NAMES.NPM_GET_RELEASES]: `**Recent releases tracker** - Get latest release activity and timeline data.
 
-**ANALYSIS:** Release timeline, version history, distribution tags, maintenance indicators, organizational context.
+**MINIMAL OUTPUT:** Last modified, created date, version count, and last 10 releases - focused release intelligence.
 
-**MATURITY INDICATORS:** Stable (regular releases, clear versioning), active development (frequent releases, beta/alpha), abandoned (long gaps, no activity).
+**WHEN TO USE:** Track recent package activity, analyze release frequency, check latest versions and release dates.
 
-**INTEGRATION:** MANDATORY with ${TOOL_NAMES.NPM_GET_PACKAGE}, combine with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}`,
+**INTEGRATION:** Essential for monitoring package updates - combine with ${TOOL_NAMES.NPM_GET_VERSIONS} for comprehensive version analysis`,
+    [TOOL_NAMES.NPM_GET_ENGINES]: `**Environment compatibility validator** - Prevent runtime conflicts before installation.
+
+**MINIMAL OUTPUT:** Node.js version requirements, npm constraints - environment compatibility matrix.
+
+**WHEN TO USE:** Pre-deployment validation, Docker image planning, Node.js upgrade decisions, CI/CD environment setup.
+
+**INTEGRATION:** Prevents deployment failures - use before installation in production environments`,
+    [TOOL_NAMES.NPM_GET_EXPORTS]: `**Import path intelligence** - Discover available modules and import strategies.
+
+**MINIMAL OUTPUT:** Export mappings, entry points, submodule paths - complete import guide for developers.
+
+**WHEN TO USE:** Learn correct import syntax, discover tree-shakable exports, find submodules, optimize bundle size.
+
+**INTEGRATION:** CRITICAL for ${TOOL_NAMES.GITHUB_SEARCH_CODE} - enables precise code search with accurate import paths`,
+    [TOOL_NAMES.API_STATUS_CHECK]: `**🛠️ CRITICAL FIRST STEP** - Comprehensive API readiness verification before research operations.
+
+**ESSENTIAL PRE-RESEARCH VALIDATION:**
+- **GitHub CLI Authentication**: Verifies user is logged in (gh auth status)
+- **NPM Registry Connectivity**: Confirms npm ping successful  
+- **GitHub API Rate Limits**: Real-time quota analysis across all endpoints
+
+**🔍 COMPREHENSIVE HEALTH CHECK:**
+- **Authentication Status**: GitHub CLI login verification with username detection
+- **Network Connectivity**: NPM registry accessibility and response validation
+- **API Quota Analysis**: Core API, Search API, and Code Search remaining limits
+- **Reset Time Tracking**: When exhausted APIs will restore quota
+- **Usage Percentage**: Current consumption across all GitHub endpoints
+
+**⚡ INTELLIGENT RESEARCH STRATEGY:**
+- **Ready Status**: All systems operational for comprehensive research
+- **Limited Status**: Reduced capacity - targeted searches recommended
+- **Not Ready Status**: Authentication/quota issues require resolution
+
+**🎯 RESEARCH GUIDANCE BASED ON API LIMITS:**
+- **Code Search < 5**: Critical - use repository browsing instead of code search
+- **Search API < 20**: Limited - focus on specific repositories vs broad searches  
+- **Core API < 200**: Constrained - minimize repository exploration operations
+- **NPM Disconnected**: GitHub-only research mode activated
+
+**🚀 SMART FALLBACK RECOMMENDATIONS:**
+- **Authentication Issues**: Step-by-step gh auth login guidance
+- **NPM Problems**: Alternative research paths using GitHub discovery
+- **Rate Limit Exhaustion**: Wait times and alternative approaches
+- **Network Issues**: Diagnostic commands and troubleshooting steps
+
+**📊 REAL-TIME API INTELLIGENCE:**
+- **Primary API**: Repository operations, issues, PRs, users (5000/hour)
+- **Search API**: Repository/user/topic searches (30/minute) 
+- **Code Search**: Code content searches (10/minute) - most restrictive
+- **Reset Schedules**: Precise timestamps for quota restoration
+
+**✅ RESEARCH READINESS MATRIX:**
+- **READY**: GitHub authenticated + NPM connected + healthy API limits
+- **LIMITED**: Some constraints but research possible with guidance
+- **NOT_READY**: Critical issues blocking research operations
+
+**💡 PROACTIVE OPTIMIZATION:**
+- **API Usage Prediction**: Warns before hitting limits during extensive research
+- **Strategy Adaptation**: Automatically suggests efficient research patterns
+- **Resource Conservation**: Identifies when to use cached vs live data
+- **Batch Operation Planning**: Optimal timing for bulk research tasks
+
+**WHEN TO USE:** ALWAYS call first before starting any research session to ensure optimal tool usage and prevent operation failures.
+
+**INTEGRATION:** Sets research strategy for all subsequent GitHub and NPM tools based on current system status.`,
 };
 
 const cache = new NodeCache({
@@ -463,6 +1005,17 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     return executeCommand();
 }
 
+/**
+ * Search GitHub code with organizational fallback strategy
+ *
+ * For internal company projects (like "Astra Nova" at Wix):
+ * 1. Try direct code search first
+ * 2. If no results, the calling code should implement fallback chain:
+ *    - searchGitHubCommits() for commit message references
+ *    - searchGitHubPullRequests() for PR mentions
+ *    - searchGitHubIssues() for issue discussions
+ * 3. Extract repository info from any successful results
+ */
 async function searchGitHubCode(params) {
     const cacheKey = generateCacheKey('gh-code', params);
     return withCache(cacheKey, async () => {
@@ -541,6 +1094,18 @@ async function searchGitHubCode(params) {
                         topMatches: analysis.topMatches.slice(0, 5),
                     },
                 };
+                // Add organizational fallback guidance for zero results
+                if (analysis.totalFound === 0 && params.owner) {
+                    searchResult.organizationalFallback = {
+                        suggestion: `No code matches found for "${params.query}" in ${params.owner}. Try organizational fallback strategy:`,
+                        fallbackSteps: [
+                            `Search commits: "${params.query}" with owner:${params.owner}`,
+                            `Search pull requests: "${params.query}" with owner:${params.owner}`,
+                            `Search issues: "${params.query}" with owner:${params.owner}`,
+                            'Extract repository references from any successful results',
+                        ],
+                    };
+                }
                 return createSuccessResult$1(searchResult);
             }
             catch (parseError) {
@@ -686,84 +1251,387 @@ function buildGitHubCodeSearchCommand(params) {
     return { command: 'search', args };
 }
 
-// Testing-validated search pattern analysis
+// Enhanced search pattern analysis with MANDATORY boolean operator suggestions
 function analyzeSearchPattern(args) {
     const suggestions = [];
     const warnings = [];
+    const booleanRecommendations = [];
+    const contextEnrichment = [];
     let patternType = 'basic';
-    // Function signature patterns (TESTING-VALIDATED)
-    if (args.query.includes('function') || args.query.includes('export')) {
-        patternType = 'function-discovery';
-        suggestions.push('PROVEN: "export function" → VSCode functions (localize, getVersion, fixWin32DirectoryPermissions)');
+    const query = args.query.toLowerCase();
+    const hasBoolean = /\b(OR|AND|NOT)\b/i.test(args.query);
+    // CRITICAL: Always recommend boolean operators if not present
+    if (!hasBoolean) {
+        warnings.push('CRITICAL: Query lacks boolean operators - efficiency reduced by 3-5x without them');
+        warnings.push('MANDATORY: Add boolean operators (OR, AND, NOT) for maximum search efficiency');
+        patternType = 'needs-boolean-enhancement';
     }
-    // Boolean operator patterns (TESTING-VALIDATED)
-    if (args.query.includes(' OR ') || args.query.includes(' NOT ')) {
-        patternType = 'boolean-search';
-        suggestions.push('PROVEN: "useState OR useEffect" ✅, "function NOT test" ✅');
+    // CRITICAL: Check for unsupported parentheses
+    if (args.query.includes('(') || args.query.includes(')')) {
+        warnings.push('CRITICAL: GitHub API does not support parentheses () in search queries');
+        warnings.push('SOLUTION: Remove parentheses and use boolean operators: "term1 OR term2 AND term3"');
+        patternType = 'unsupported-syntax';
+    }
+    // Check for overly complex queries
+    const booleanOperatorCount = (args.query.match(/\b(OR|AND|NOT)\b/gi) || [])
+        .length;
+    const termCount = args.query.split(/\s+/).length;
+    if (booleanOperatorCount > 3 || termCount > 8) {
+        warnings.push('COMPLEXITY WARNING: Query may exceed GitHub API limits');
+        warnings.push('RECOMMENDATION: Simplify to essential boolean operators (max 3-4 per query)');
+        patternType = 'overly-complex';
+    }
+    // Enhanced Function signature patterns with MANDATORY boolean operators
+    if (query.includes('function') || query.includes('export')) {
+        patternType = 'function-discovery';
+        suggestions.push('PROVEN BOOLEAN: "export OR function OR method OR class" → Comprehensive function discovery');
+        booleanRecommendations.push('MANDATORY BOOLEAN: "export AND function OR method OR procedure" - captures all function types');
+        booleanRecommendations.push('MANDATORY EXCLUSION: "function OR method NOT test NOT spec NOT mock" - production code only');
+        booleanRecommendations.push('MANDATORY ASYNC: "async AND (function OR method) OR promise NOT example" - async patterns');
+        contextEnrichment.push('BOOLEAN CONTEXT: "arrow OR lambda OR callback OR closure" for function variations');
     }
-    // Class and React patterns (TESTING-VALIDATED)
-    if (args.query.includes('class') || args.query.includes('React')) {
+    // Enhanced React/Component patterns with MANDATORY boolean operators
+    if (query.includes('react') ||
+        query.includes('component') ||
+        query.includes('jsx')) {
         patternType = 'component-discovery';
-        suggestions.push('PROVEN: "class extends" → React class components, "import React" → React usage patterns');
+        suggestions.push('PROVEN BOOLEAN: "react AND (hooks OR components OR jsx) NOT test" → React ecosystem discovery');
+        booleanRecommendations.push('MANDATORY HOOKS: "useState OR useEffect OR useContext OR useReducer" - comprehensive hook coverage');
+        booleanRecommendations.push('MANDATORY COMPONENTS: "component OR jsx OR tsx OR react NOT test NOT story" - component patterns');
+        booleanRecommendations.push('MANDATORY LIFECYCLE: "componentDidMount OR useEffect OR lifecycle NOT mock" - lifecycle methods');
+        contextEnrichment.push('BOOLEAN CONTEXT: "props OR state OR render OR mount" for React-specific patterns');
+    }
+    // Authentication/Security patterns with MANDATORY boolean operators
+    if (query.includes('auth') ||
+        query.includes('login') ||
+        query.includes('password') ||
+        query.includes('token')) {
+        patternType = 'security-discovery';
+        booleanRecommendations.push('MANDATORY AUTH: "authentication OR auth OR login OR signin OR oauth" - comprehensive auth coverage');
+        booleanRecommendations.push('MANDATORY TOKENS: "jwt OR token OR bearer OR session OR cookie" - token handling patterns');
+        booleanRecommendations.push('MANDATORY SECURITY: "password OR hash OR encrypt OR decrypt NOT test NOT mock" - security implementations');
+        contextEnrichment.push('BOOLEAN SECURITY: "middleware OR guard OR interceptor OR validation OR sanitize" for auth context');
+    }
+    // API/HTTP patterns with MANDATORY boolean operators
+    if (query.includes('api') ||
+        query.includes('http') ||
+        query.includes('request') ||
+        query.includes('fetch')) {
+        patternType = 'api-discovery';
+        booleanRecommendations.push('MANDATORY HTTP: "fetch OR axios OR request OR http OR api" - HTTP client coverage');
+        booleanRecommendations.push('MANDATORY ENDPOINTS: "endpoint OR route OR handler OR controller NOT test" - API structure');
+        booleanRecommendations.push('MANDATORY METHODS: "get OR post OR put OR delete OR patch" - HTTP methods');
+        contextEnrichment.push('BOOLEAN API: "cors OR middleware OR validation OR serialization OR response" for API context');
+    }
+    // Database/Storage patterns with MANDATORY boolean operators
+    if (query.includes('database') ||
+        query.includes('db') ||
+        query.includes('sql') ||
+        query.includes('query')) {
+        patternType = 'database-discovery';
+        booleanRecommendations.push('MANDATORY CRUD: "insert OR update OR delete OR select OR create" - database operations');
+        booleanRecommendations.push('MANDATORY DATABASES: "mongodb OR postgresql OR mysql OR sqlite OR redis" - database types');
+        booleanRecommendations.push('MANDATORY ORM: "sequelize OR typeorm OR prisma OR mongoose OR knex" - ORM frameworks');
+    }
+    // Error handling patterns with MANDATORY boolean operators
+    if (query.includes('error') ||
+        query.includes('exception') ||
+        query.includes('try') ||
+        query.includes('catch')) {
+        patternType = 'error-handling';
+        booleanRecommendations.push('MANDATORY ERROR: "error OR exception OR catch OR throw OR reject" - error handling coverage');
+        booleanRecommendations.push('MANDATORY PATTERNS: "try OR catch OR finally OR async OR await" - error patterns');
+        booleanRecommendations.push('MANDATORY HANDLING: "handling OR recovery OR retry OR fallback NOT test" - error management');
+    }
+    // Testing patterns - suggest boolean exclusion
+    if (query.includes('test') ||
+        query.includes('spec') ||
+        query.includes('mock')) {
+        if (!query.includes('NOT')) {
+            booleanRecommendations.push('MANDATORY EXCLUSION: Add "NOT test NOT spec NOT mock" to focus on production code');
+            booleanRecommendations.push('BOOLEAN ALTERNATIVE: Use "production OR live OR deploy NOT test" for real implementations');
+        }
+    }
+    // Generic single-term queries - MANDATORY boolean enhancement
+    const words = query.split(/\s+/).filter(w => w.length > 2);
+    if (words.length === 1 && !hasBoolean && words[0].length > 3) {
+        booleanRecommendations.push(`MANDATORY VARIATIONS: "${words[0]} OR ${words[0]}s OR ${words[0]}ing" - capture all variations`);
+        booleanRecommendations.push(`MANDATORY EXCLUSION: "${words[0]} NOT test NOT spec NOT example" - production focus`);
+        booleanRecommendations.push(`MANDATORY CONTEXT: "${words[0]} OR related_term OR synonym" - comprehensive coverage`);
+    }
+    // Boolean operator patterns (existing logic enhanced)
+    if (hasBoolean) {
+        patternType = 'boolean-search';
+        suggestions.push('EXCELLENT: Boolean operators detected - proven 3-5x more efficient than simple text');
+        suggestions.push('PROVEN PATTERNS: "useState OR useEffect" ✅, "function NOT test" ✅, "async AND await" ✅');
     }
-    // Path filter validation (CRITICAL WARNING BASED ON TESTING)
+    // Path filter validation (enhanced with boolean recommendations)
     if (args.path === 'src' && !args.repo) {
         warnings.push('CRITICAL: path:src may fail - many repos use path:packages, path:lib instead');
-        suggestions.push('PROVEN PATHS: React uses "packages", VSCode uses "src/vs", TypeScript uses "src"');
+        suggestions.push('PROVEN BOOLEAN PATHS: "react AND hooks" with path:packages, NOT path:src');
+        contextEnrichment.push('BOOLEAN PATH ALTERNATIVES: Try boolean queries without path filters first');
+    }
+    // Language-specific boolean enhancements
+    if (args.language) {
+        const lang = args.language.toLowerCase();
+        if (lang === 'typescript' || lang === 'javascript') {
+            contextEnrichment.push('BOOLEAN JS/TS: "interface OR type OR class OR function OR const OR let" for comprehensive coverage');
+        }
+        else if (lang === 'python') {
+            contextEnrichment.push('BOOLEAN PYTHON: "def OR class OR import OR async OR lambda" for Python patterns');
+        }
+        else if (lang === 'java') {
+            contextEnrichment.push('BOOLEAN JAVA: "public OR private OR class OR interface OR method" for Java patterns');
+        }
     }
-    // Cross-repository patterns (TESTING-VALIDATED)
+    // Cross-repository patterns (enhanced with boolean emphasis)
     if (!args.owner && !args.repo && args.query.includes('async')) {
         patternType = 'cross-repo-discovery';
-        suggestions.push('PROVEN: "async function login" finds 4 TypeScript authentication implementations');
-    }
-    return { patternType, suggestions, warnings };
-}
-// Simplified schema matching official GitHub CLI approach
-const searchGitHubCodeSchema = z.object({
-    query: z
-        .string()
-        .min(1, 'Query cannot be empty')
-        .describe('Search query for code. Use GitHub search syntax like repo:owner/name, language:javascript, path:*.js, or simple keywords.'),
-    owner: z
-        .string()
-        .optional()
-        .describe('Repository owner/organization (e.g., "facebook", "microsoft"). Leave empty for global searches.'),
-    repo: z
-        .string()
-        .optional()
-        .describe('Repository name (e.g., "react", "vscode"). Requires owner parameter.'),
-    extension: z
-        .string()
-        .optional()
-        .describe('File extension to filter by (e.g., "js", "ts", "py").'),
-    filename: z
-        .string()
-        .optional()
-        .describe('Exact filename to search for (e.g., "package.json", "README.md").'),
-    language: z
-        .string()
-        .optional()
-        .describe('Programming language to filter by (e.g., "javascript", "typescript", "python").'),
-    path: z
-        .string()
-        .optional()
-        .describe('Path pattern to filter by (e.g., "src", "lib", "*.js", "/src/**/*.ts").'),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .optional()
-        .default(30)
-        .describe('Maximum number of results to return (default: 30, max: 100).'),
-    match: z.enum(['file', 'path']).optional().describe('Search scope'),
-    branch: z
-        .string()
-        .optional()
-        .describe('Branch for workflow documentation (required but not used by CLI)'),
-});
+        suggestions.push('PROVEN BOOLEAN GLOBAL: "async AND (function OR method) OR promise" finds comprehensive async patterns');
+        contextEnrichment.push('BOOLEAN CROSS-REPO: Global boolean searches excel for common patterns like "error OR exception"');
+    }
+    // Zero results prediction with boolean solutions
+    if (query.length > 50 || query.split(' ').length > 8) {
+        warnings.push('COMPLEXITY WARNING: Very long/complex queries often return 0 results');
+        booleanRecommendations.push('MANDATORY SIMPLIFICATION: Break into essential boolean terms: "term1 OR term2 NOT test"');
+        booleanRecommendations.push('BOOLEAN STRATEGY: Use progressive boolean refinement instead of complex phrases');
+    }
+    // ALWAYS add mandatory boolean recommendations if none exist
+    if (booleanRecommendations.length === 0) {
+        booleanRecommendations.push('MANDATORY: Add boolean operators for 3-5x better efficiency: "term1 OR term2 NOT test"');
+        booleanRecommendations.push('PROVEN PATTERN: Use "primary_term OR synonym OR variation NOT noise" structure');
+    }
+    return {
+        patternType,
+        suggestions,
+        warnings,
+        booleanRecommendations,
+        contextEnrichment,
+    };
+}
+// NEW: Smart query simplification for GitHub API compatibility
+function simplifyComplexQuery(query) {
+    const fallbackQueries = [];
+    // Remove parentheses - GitHub doesn't support them
+    const simplified = query.replace(/[()]/g, '');
+    // If query has parentheses, create simplified version
+    if (query.includes('(') || query.includes(')')) {
+        fallbackQueries.push(simplified);
+    }
+    // Extract main terms and create progressive simplifications
+    const terms = simplified
+        .split(/\s+/)
+        .filter(term => !['AND', 'OR', 'NOT'].includes(term.toUpperCase()));
+    // Strategy 1: Keep only OR operations (most permissive)
+    const orTerms = [];
+    const parts = simplified.split(/\s+/);
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i].toUpperCase() === 'OR' && i > 0 && i < parts.length - 1) {
+            orTerms.push(parts[i - 1], 'OR', parts[i + 1]);
+        }
+    }
+    if (orTerms.length > 0) {
+        fallbackQueries.push(orTerms.join(' '));
+    }
+    // Strategy 2: Take first 2-3 most important terms
+    if (terms.length >= 2) {
+        fallbackQueries.push(`${terms[0]} OR ${terms[1]}`);
+    }
+    // Strategy 3: Single most specific term
+    const specificTerms = terms.filter(term => term.length > 4 &&
+        !['function', 'class', 'import', 'export'].includes(term.toLowerCase()));
+    if (specificTerms.length > 0) {
+        fallbackQueries.push(specificTerms[0]);
+    }
+    // Strategy 4: Fallback to first term
+    if (terms.length > 0) {
+        fallbackQueries.push(terms[0]);
+    }
+    // Remove duplicates and return unique fallbacks
+    return [...new Set(fallbackQueries)];
+}
+// NEW: Safe JSON parsing with error recovery
+function safeParseJSON(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return { success: true, data: parsed };
+    }
+    catch (error) {
+        try {
+            // Try parsing as double-encoded JSON
+            const doubleParsed = JSON.parse(JSON.parse(text));
+            return { success: true, data: doubleParsed };
+        }
+        catch (secondError) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'JSON parsing failed',
+            };
+        }
+    }
+}
+// Enhanced query optimization for better results - BOOLEAN OPERATORS ALWAYS REQUIRED
+function optimizeQuery(args) {
+    const original = args.query;
+    const optimized = [];
+    const rationale = [];
+    const fallbackQueries = [];
+    // Check for unsupported syntax first
+    if (original.includes('(') || original.includes(')')) {
+        const simplified = simplifyComplexQuery(original);
+        fallbackQueries.push(...simplified);
+        rationale.push('Removed unsupported parentheses and created boolean fallback queries');
+    }
+    // MANDATORY: Always ensure boolean operators are used for maximum efficiency
+    const hasBoolean = /\b(OR|AND|NOT)\b/i.test(original);
+    if (!hasBoolean) {
+        // CRITICAL: Inject boolean operators for maximum efficiency
+        const words = original
+            .trim()
+            .split(/\s+/)
+            .filter(w => w.length > 2);
+        if (words.length === 1) {
+            const word = words[0];
+            // Always create boolean variations for single terms
+            optimized.push(`${word} OR ${word}s OR ${word}ing`);
+            rationale.push('MANDATORY: Added boolean variations for comprehensive coverage (3-5x more efficient)');
+            optimized.push(`${word} NOT test NOT spec NOT mock`);
+            rationale.push('MANDATORY: Added boolean exclusions to focus on production code');
+            // Add semantic boolean expansions based on common patterns
+            if (word.toLowerCase().includes('react')) {
+                optimized.push(`${word} OR reactjs OR react.js NOT example`);
+                rationale.push('MANDATORY: Added React-specific boolean variations');
+            }
+            else if (word.toLowerCase().includes('auth')) {
+                optimized.push(`${word} OR authentication OR login OR signin NOT test`);
+                rationale.push('MANDATORY: Added authentication boolean variations');
+            }
+            else if (word.toLowerCase().includes('function')) {
+                optimized.push(`${word} OR method OR procedure OR class NOT test`);
+                rationale.push('MANDATORY: Added function-related boolean variations');
+            }
+            else if (word.toLowerCase().includes('error')) {
+                optimized.push(`${word} OR exception OR catch OR handling NOT mock`);
+                rationale.push('MANDATORY: Added error-handling boolean variations');
+            }
+        }
+        else if (words.length >= 2 && words.length <= 4) {
+            // MANDATORY: Convert multi-word queries to boolean
+            optimized.push(words.join(' OR '));
+            rationale.push('MANDATORY: Converted to OR boolean for comprehensive coverage (proven 3-5x more efficient)');
+            optimized.push(`${words.join(' AND ')} NOT test NOT spec`);
+            rationale.push('MANDATORY: Added AND boolean with exclusions for precise targeting');
+            // Create semantic boolean combinations
+            if (words.some(w => w.toLowerCase().includes('react'))) {
+                const reactTerms = words.filter(w => !w.toLowerCase().includes('react'));
+                optimized.push(`react AND (${reactTerms.join(' OR ')}) NOT example NOT tutorial`);
+                rationale.push('MANDATORY: Created React-specific boolean combination');
+            }
+        }
+        else if (words.length > 4) {
+            // MANDATORY: Simplify complex queries with boolean operators
+            const primaryTerms = words.slice(0, 3);
+            optimized.push(`${primaryTerms.join(' OR ')} NOT test`);
+            rationale.push('MANDATORY: Simplified to essential boolean terms (complex queries often fail)');
+            optimized.push(`${primaryTerms[0]} AND ${primaryTerms[1]} NOT mock NOT spec`);
+            rationale.push('MANDATORY: Created focused boolean combination from key terms');
+        }
+    }
+    else {
+        // Query already has boolean operators - validate and enhance
+        const booleanCount = (original.match(/\b(OR|AND|NOT)\b/gi) || []).length;
+        if (booleanCount > 3) {
+            const simplified = simplifyComplexQuery(original);
+            fallbackQueries.push(...simplified);
+            rationale.push('MANDATORY: Boolean query too complex - created simplified boolean fallbacks');
+        }
+        else {
+            optimized.push(original);
+            rationale.push('MANDATORY: Boolean complexity acceptable - using optimized boolean query');
+            // Always add enhanced boolean variations even for existing boolean queries
+            const words = original
+                .split(/\s+/)
+                .filter(w => w.length > 3 && !['AND', 'OR', 'NOT'].includes(w.toUpperCase()));
+            if (words.length >= 2) {
+                // Add alternative boolean combinations
+                optimized.push(`${words[0]} OR ${words[1]} NOT test NOT example`);
+                rationale.push('MANDATORY: Added alternative boolean combination for broader coverage');
+            }
+        }
+    }
+    // MANDATORY: Always ensure we have boolean fallbacks
+    if (optimized.length === 0 && fallbackQueries.length === 0) {
+        const words = original.split(/\s+/).filter(w => w.length > 2);
+        if (words.length > 0) {
+            optimized.push(`${words[0]} OR ${words[0]}s NOT test`);
+            rationale.push('MANDATORY: Created essential boolean query as fallback');
+        }
+        else {
+            optimized.push(original);
+            rationale.push('MANDATORY: Preserved original query (boolean enhancement not possible)');
+        }
+    }
+    return {
+        originalQuery: original,
+        optimizedQueries: optimized,
+        rationale,
+        fallbackQueries,
+    };
+}
 function registerGitHubSearchCodeTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE], searchGitHubCodeSchema.shape, {
+    server.tool(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE], {
+        query: z
+            .string()
+            .min(1, 'Query cannot be empty')
+            .describe('Search query for code. Use GitHub search syntax like repo:owner/name, language:javascript, path:*.js, or simple keywords. Boolean operators (OR, AND, NOT) are highly recommended for better results.'),
+        owner: z
+            .string()
+            .optional()
+            .describe('Repository owner/organization (e.g., "facebook", "microsoft"). Leave empty for global searches.'),
+        repo: z
+            .array(z.string())
+            .optional()
+            .describe('Repository names (e.g., ["react", "vscode"]). Requires owner parameter.'),
+        extension: z
+            .string()
+            .optional()
+            .describe('File extension to filter by (e.g., "js", "ts", "py").'),
+        filename: z
+            .string()
+            .optional()
+            .describe('Exact filename to search for (e.g., "package.json", "README.md").'),
+        language: z
+            .string()
+            .optional()
+            .describe('Programming language to filter by (e.g., "javascript", "typescript", "python").'),
+        path: z
+            .string()
+            .optional()
+            .describe('Path pattern to filter by (e.g., "src", "lib", "*.js", "/src/**/*.ts").'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(30)
+            .describe('Maximum number of results to return (default: 30, max: 100).'),
+        match: z.enum(['file', 'path']).optional().describe('Search scope'),
+        branch: z
+            .string()
+            .optional()
+            .describe('Branch for workflow documentation (required but not used by CLI)'),
+        size: z
+            .string()
+            .optional()
+            .describe('Filter on file size range, in kilobytes (e.g., ">1", "<50")'),
+        // New parameter for query optimization
+        enableQueryOptimization: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Enable automatic query optimization with boolean operators for better results (default: true)'),
+    }, {
         title: 'GitHub Code Search',
         readOnlyHint: true,
         destructiveHint: false,
@@ -771,7 +1639,7 @@ function registerGitHubSearchCodeTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            // Simple validation - only check repo requires owner
+            // Enhanced validation
             if (args.repo && !args.owner) {
                 return {
                     content: [
@@ -783,19 +1651,177 @@ function registerGitHubSearchCodeTool(server) {
                     isError: true,
                 };
             }
-            // Analyze search pattern for testing-validated insights
+            // Enhanced pattern analysis
             const patternAnalysis = analyzeSearchPattern(args);
-            const result = await searchGitHubCode(args);
-            // Enhance result with testing-validated insights
+            // Query optimization with fallbacks
+            const queryOptimization = optimizeQuery(args);
+            let result = null;
+            let usedOptimizedQuery = false;
+            let usedFallbackQuery = false;
+            let finalQuery = args.query;
+            const attemptedQueries = [];
+            // Strategy 1: Try original query first (unless it has known issues)
+            const hasUnsupportedSyntax = args.query.includes('(') || args.query.includes(')');
+            const isOverlyComplex = (args.query.match(/\b(OR|AND|NOT)\b/gi) || []).length > 3;
+            if (!hasUnsupportedSyntax && !isOverlyComplex) {
+                try {
+                    result = await searchGitHubCode(args);
+                    attemptedQueries.push(args.query);
+                    // Validate result with safe JSON parsing
+                    if (result.content && result.content[0]) {
+                        const parseResult = safeParseJSON(result.content[0].text);
+                        if (!parseResult.success) {
+                            throw new Error(`JSON parsing failed: ${parseResult.error}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    console.warn(`Original query failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                    result = null; // Will trigger fallback
+                }
+            }
+            // Strategy 2: Try optimized queries if original failed or returned minimal results
+            if (!result &&
+                args.enableQueryOptimization !== false &&
+                queryOptimization.optimizedQueries.length > 0) {
+                for (const optimizedQuery of queryOptimization.optimizedQueries) {
+                    if (optimizedQuery === args.query)
+                        continue; // Skip if same as original
+                    try {
+                        const optimizedArgs = { ...args, query: optimizedQuery };
+                        const optimizedResult = await searchGitHubCode(optimizedArgs);
+                        attemptedQueries.push(optimizedQuery);
+                        if (optimizedResult.content && optimizedResult.content[0]) {
+                            const parseResult = safeParseJSON(optimizedResult.content[0].text);
+                            if (parseResult.success) {
+                                result = optimizedResult;
+                                usedOptimizedQuery = true;
+                                finalQuery = optimizedQuery;
+                                break;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Optimized query failed: ${optimizedQuery} - ${error instanceof Error ? error.message : 'Unknown error'}`);
+                        continue;
+                    }
+                }
+            }
+            // Strategy 3: Try fallback queries for complex/unsupported syntax
+            if (!result && queryOptimization.fallbackQueries.length > 0) {
+                for (const fallbackQuery of queryOptimization.fallbackQueries) {
+                    try {
+                        const fallbackArgs = { ...args, query: fallbackQuery };
+                        const fallbackResult = await searchGitHubCode(fallbackArgs);
+                        attemptedQueries.push(fallbackQuery);
+                        if (fallbackResult.content && fallbackResult.content[0]) {
+                            const parseResult = safeParseJSON(fallbackResult.content[0].text);
+                            if (parseResult.success) {
+                                result = fallbackResult;
+                                usedFallbackQuery = true;
+                                finalQuery = fallbackQuery;
+                                break;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Fallback query failed: ${fallbackQuery} - ${error instanceof Error ? error.message : 'Unknown error'}`);
+                        continue;
+                    }
+                }
+            }
+            // Strategy 4: Last resort - try single term from original query
+            if (!result) {
+                const terms = args.query
+                    .split(/\s+/)
+                    .filter(term => term.length > 3 &&
+                    !['AND', 'OR', 'NOT'].includes(term.toUpperCase()));
+                if (terms.length > 0) {
+                    try {
+                        const lastResortArgs = { ...args, query: terms[0] };
+                        const lastResortResult = await searchGitHubCode(lastResortArgs);
+                        attemptedQueries.push(terms[0]);
+                        if (lastResortResult.content && lastResortResult.content[0]) {
+                            const parseResult = safeParseJSON(lastResortResult.content[0].text);
+                            if (parseResult.success) {
+                                result = lastResortResult;
+                                usedFallbackQuery = true;
+                                finalQuery = terms[0];
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Last resort query failed: ${terms[0]} - ${error instanceof Error ? error.message : 'Unknown error'}`);
+                    }
+                }
+            }
+            // If we still don't have a result, return comprehensive error
+            if (!result) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `🚨 ALL QUERY STRATEGIES FAILED
+
+📋 ATTEMPTED QUERIES:
+${attemptedQueries.map(q => `• "${q}"`).join('\n')}
+
+🔧 INTELLIGENT FALLBACK RECOMMENDATIONS:
+• SIMPLIFY: Try single keywords like "useState", "function", "class"
+• REMOVE SYNTAX: Avoid parentheses () - GitHub API doesn't support them
+• REDUCE COMPLEXITY: Use max 2-3 boolean operators (OR, AND, NOT)
+• SPECIFIC TERMS: Use concrete terms instead of abstract concepts
+• REPOSITORY SCOPE: Add owner/repo parameters to narrow search
+
+💡 PROVEN WORKING PATTERNS:
+• "useState OR useEffect" ✅
+• "function NOT test" ✅  
+• "async function" ✅
+• "export default" ✅
+
+⚠️ AVOID THESE PATTERNS:
+• "(term1 OR term2) AND term3" ❌ (parentheses not supported)
+• Complex nested boolean logic ❌
+• Very long queries (>50 characters) ❌`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Enhance successful result with comprehensive insights
             if (result.content && result.content[0]) {
                 let responseText = result.content[0].text;
+                // Add query transformation info
+                if (usedOptimizedQuery || usedFallbackQuery) {
+                    responseText += `\n\n🔄 QUERY TRANSFORMATION APPLIED:`;
+                    responseText += `\n• Original: "${args.query}"`;
+                    responseText += `\n• Used: "${finalQuery}"`;
+                    responseText += `\n• Strategy: ${usedFallbackQuery ? 'Fallback (syntax/complexity issues)' : 'Optimization'}`;
+                    if (attemptedQueries.length > 1) {
+                        responseText += `\n• Attempts: ${attemptedQueries.length} queries tried`;
+                    }
+                }
                 // Add pattern-specific insights
                 if (patternAnalysis.suggestions.length > 0) {
-                    responseText += `\n\n🎯 TESTING-VALIDATED PATTERN INSIGHTS (${patternAnalysis.patternType.toUpperCase()}):`;
+                    responseText += `\n\n🎯 PATTERN INSIGHTS (${patternAnalysis.patternType.toUpperCase()}):`;
                     patternAnalysis.suggestions.forEach(suggestion => {
                         responseText += `\n• ${suggestion}`;
                     });
                 }
+                // Add boolean operator recommendations
+                if (patternAnalysis.booleanRecommendations.length > 0) {
+                    responseText += `\n\n🔍 BOOLEAN OPERATOR RECOMMENDATIONS:`;
+                    patternAnalysis.booleanRecommendations.forEach(rec => {
+                        responseText += `\n• ${rec}`;
+                    });
+                }
+                // Add context enrichment suggestions
+                if (patternAnalysis.contextEnrichment.length > 0) {
+                    responseText += `\n\n💡 CONTEXT ENRICHMENT SUGGESTIONS:`;
+                    patternAnalysis.contextEnrichment.forEach(context => {
+                        responseText += `\n• ${context}`;
+                    });
+                }
                 // Add critical warnings
                 if (patternAnalysis.warnings.length > 0) {
                     responseText += `\n\n⚠️ CRITICAL WARNINGS:`;
@@ -803,14 +1829,24 @@ function registerGitHubSearchCodeTool(server) {
                         responseText += `\n• ${warning}`;
                     });
                 }
-                // Add general best practices from testing
-                responseText += `\n\n📋 TESTING-VALIDATED BEST PRACTICES:`;
-                responseText += `\n• Boolean operators work: "useState OR useEffect", "error NOT test"`;
-                responseText += `\n• Path filters effective: "packages/react/src/__tests__" ✅`;
-                responseText += `\n• Extension filters reliable: .ts, .js, .jsx extensions ✅`;
-                responseText += `\n• Repository-specific targeting: owner/repo combinations ✅`;
+                // Enhanced best practices with GitHub API limitations
+                responseText += `\n\n📋 GITHUB API SEARCH BEST PRACTICES:`;
+                responseText += `\n• ✅ SUPPORTED: "useState OR useEffect", "function NOT test"`;
+                responseText += `\n• ❌ NOT SUPPORTED: "(useState OR useEffect) AND typescript" (parentheses)`;
+                responseText += `\n• ⚠️ COMPLEXITY LIMIT: Max 3-4 boolean operators per query`;
+                responseText += `\n• 🎯 PATTERN MATCHING: "async function" vs "function.*async"`;
+                responseText += `\n• 🚫 EXCLUDE NOISE: "auth NOT mock NOT test" for production code`;
+                responseText += `\n• 🔄 VARIATION COVERAGE: "login OR signin OR authenticate"`;
                 if (!args.owner && !args.repo) {
-                    responseText += `\n• Cross-repository search proven for "async function" patterns`;
+                    responseText += `\n• 🌐 GLOBAL SEARCH: Works well for common patterns across repositories`;
+                }
+                // Add alternative query suggestions
+                if (queryOptimization.fallbackQueries.length > 0 &&
+                    !usedFallbackQuery) {
+                    responseText += `\n\n🔄 ALTERNATIVE QUERY SUGGESTIONS:`;
+                    queryOptimization.fallbackQueries.forEach(query => {
+                        responseText += `\n• "${query}" - Simplified version for better compatibility`;
+                    });
                 }
                 return {
                     content: [
@@ -825,20 +1861,65 @@ function registerGitHubSearchCodeTool(server) {
             return result;
         }
         catch (error) {
-            // Enhanced error handling with testing insights
+            // Enhanced error handling with intelligent suggestions
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            const fallbackSuggestions = `
-🔄 TESTING-VALIDATED FALLBACK STRATEGIES:
-• Try simpler search terms - complex patterns may fail
-• Remove path filters if getting 0 results - many repos don't use 'src'
-• Use proven patterns: "export function", "useState OR useEffect"
-• Consider repository-specific search: owner + repo + simple terms
-• For React: use "packages" not "src" in path filters`;
+            // Detect specific error types
+            let errorType = 'general';
+            let specificSuggestions = '';
+            if (errorMessage.includes('JSON') || errorMessage.includes('parse')) {
+                errorType = 'json-parsing';
+                specificSuggestions = `
+🔧 JSON PARSING ERROR SOLUTIONS:
+• QUERY SIMPLIFICATION: Remove complex boolean logic
+• SYNTAX CHECK: Avoid parentheses () in queries  
+• RETRY STRATEGY: Try single keywords instead of complex queries`;
+            }
+            else if (errorMessage.includes('API') ||
+                errorMessage.includes('rate')) {
+                errorType = 'api-limit';
+                specificSuggestions = `
+🔧 API LIMIT SOLUTIONS:
+• REDUCE FREQUENCY: Wait before retrying
+• SIMPLIFY QUERIES: Use fewer boolean operators
+• SCOPE NARROWING: Add owner/repo parameters`;
+            }
+            else if (errorMessage.includes('syntax') ||
+                errorMessage.includes('invalid')) {
+                errorType = 'syntax-error';
+                specificSuggestions = `
+🔧 SYNTAX ERROR SOLUTIONS:
+• REMOVE PARENTHESES: GitHub API doesn't support () grouping
+• SIMPLIFY BOOLEAN: Use "term1 OR term2" not "(term1 OR term2)"
+• CHECK OPERATORS: Only AND, OR, NOT are supported`;
+            }
+            let fallbackSuggestions = `
+🔄 INTELLIGENT FALLBACK STRATEGIES:
+• PROGRESSIVE SIMPLIFICATION: Start with single terms, add complexity gradually
+• BOOLEAN BASICS: "term1 OR term2" works, "(term1 OR term2) AND term3" doesn't
+• EXCLUDE NOISE: Add "NOT test NOT spec NOT mock" to focus on production code
+• REMOVE FILTERS: Try without path/language filters first
+• REPOSITORY TARGETING: Use owner/repo for focused searches${specificSuggestions}`;
+            // Add pattern-specific fallback suggestions
+            const query = args.query.toLowerCase();
+            if (query.includes('react')) {
+                fallbackSuggestions += `\n• REACT SPECIFIC: Try "useState OR useEffect", avoid complex hook combinations`;
+            }
+            if (query.includes('auth')) {
+                fallbackSuggestions += `\n• AUTH SPECIFIC: Try "login OR authenticate OR signin NOT test"`;
+            }
+            if (query.includes('api')) {
+                fallbackSuggestions += `\n• API SPECIFIC: Try "fetch OR axios OR request NOT mock"`;
+            }
+            // Add the attempted queries for debugging
+            fallbackSuggestions += `\n\n🔍 DEBUGGING INFO:
+• Original Query: "${args.query}"
+• Error Type: ${errorType}
+• Error Message: ${errorMessage}`;
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `GitHub Code Search Failed: ${errorMessage}${fallbackSuggestions}`,
+                        text: `🚨 GitHub Code Search Failed: ${errorMessage}${fallbackSuggestions}`,
                     },
                 ],
                 isError: true,
@@ -859,31 +1940,127 @@ async function fetchGitHubFileContent(params) {
             const args = [apiPath, '--jq', '.content'];
             const result = await executeGitHubCommand('api', args, { cache: false });
             if (result.isError) {
-                return result;
+                // Parse the error message to provide better context
+                const errorMsg = result.content[0].text;
+                // Handle common GitHub API errors
+                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
+                    return createErrorResult$1(`File not found: ${params.filePath}`, new Error(`
+❌ FILE NOT FOUND: The file '${params.filePath}' does not exist in ${params.owner}/${params.repo}${params.branch ? ` on branch '${params.branch}'` : ''}.
+
+🔍 COMMON CAUSES:
+• File path is incorrect or has changed
+• Branch '${params.branch || 'default'}' doesn't contain this file
+• File may exist in a different directory
+
+💡 RECOMMENDED ACTIONS:
+1. Use 'github_get_contents' to explore repository structure first
+2. Use 'github_search_code' to find files by name or pattern
+3. Verify the branch contains the expected files
+
+📍 SEARCH ALTERNATIVES:
+• Search for filename: query="${params.filePath.split('/').pop()}"
+• Search in repository: repo:${params.owner}/${params.repo}
+• Explore repository structure starting from root`));
+                }
+                if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                    return createErrorResult$1(`Access denied to file: ${params.filePath}`, new Error(`
+🔒 ACCESS DENIED: You don't have permission to access '${params.filePath}' in ${params.owner}/${params.repo}.
+
+🔍 POSSIBLE CAUSES:
+• Repository is private and you lack access
+• File is in a protected branch
+• Organization restrictions apply
+
+💡 RECOMMENDED ACTIONS:
+1. Check if you're authenticated: gh auth status
+2. Request repository access from owner
+3. Use 'github_get_user_organizations' if this is your organization`));
+                }
+                // Handle rate limiting
+                if (errorMsg.includes('rate limit') || errorMsg.includes('429')) {
+                    return createErrorResult$1('GitHub API rate limit exceeded', new Error(`
+⏱️ RATE LIMIT: GitHub API rate limit has been exceeded.
+
+💡 RECOMMENDED ACTIONS:
+1. Wait a few minutes before trying again
+2. Use authentication to increase rate limits: gh auth login
+3. Try searching for content instead of direct file access`));
+                }
+                // Generic error fallback
+                return createErrorResult$1(`Failed to fetch file content: ${params.filePath}`, new Error(`GitHub API Error: ${errorMsg}
+
+🔧 TROUBLESHOOTING:
+• Verify repository exists: ${params.owner}/${params.repo}
+• Check file path: ${params.filePath}
+• Confirm branch: ${params.branch || 'default'}
+• Use repository exploration tools first`));
             }
             // Extract the actual content from the exec result
             const execResult = JSON.parse(result.content[0].text);
             const base64Content = execResult.result.trim().replace(/\n/g, '');
+            // Validate base64 content
+            if (!base64Content || base64Content === 'null') {
+                return createErrorResult$1(`Empty or invalid file content: ${params.filePath}`, new Error(`
+📄 EMPTY FILE: The file '${params.filePath}' exists but contains no content or returned invalid data.
+
+🔍 POSSIBLE CAUSES:
+• File is empty or binary
+• API returned null content
+• File is too large for API response
+
+💡 ALTERNATIVES:
+• Use 'github_search_code' to find content by pattern
+• Check file in GitHub web interface
+• Try accessing a different file in the same directory`));
+            }
             // Decode base64 content using Node.js Buffer
             let decodedContent;
             try {
                 decodedContent = Buffer.from(base64Content, 'base64').toString('utf-8');
             }
             catch (decodeError) {
-                throw new Error(`Failed to decode base64 content: ${decodeError.message}`);
+                return createErrorResult$1(`Failed to decode file content: ${params.filePath}`, new Error(`
+🔧 DECODE ERROR: Unable to decode base64 content from GitHub API.
+
+📋 DETAILS: ${decodeError.message}
+
+💡 POSSIBLE CAUSES:
+• File contains binary data
+• Corrupted response from API
+• Encoding mismatch
+
+🔍 ALTERNATIVES:
+• Use 'github_search_code' to find text-based content
+• Check if file is binary (images, executables, etc.)
+• Try accessing a different version of the file`));
             }
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: decodedContent,
-                    },
-                ],
-                isError: false,
-            };
+            return createSuccessResult$1({
+                filePath: params.filePath,
+                owner: params.owner,
+                repo: params.repo,
+                branch: params.branch,
+                content: decodedContent,
+                size: decodedContent.length,
+                encoding: 'utf-8',
+            });
         }
         catch (error) {
-            return createErrorResult$1('Failed to retrieve file content', error);
+            return createErrorResult$1(`Unexpected error fetching file content: ${params.filePath}`, new Error(`
+❌ UNEXPECTED ERROR: ${error.message}
+
+📍 FILE DETAILS:
+• Repository: ${params.owner}/${params.repo}
+• File: ${params.filePath}
+• Branch: ${params.branch || 'default'}
+
+🔧 TROUBLESHOOTING STEPS:
+1. Verify repository exists with 'github_get_repository'
+2. Explore structure with 'github_get_contents'
+3. Search for file with 'github_search_code'
+4. Check GitHub authentication: gh auth status
+
+💡 WORKFLOW RECOMMENDATION:
+github_get_repository → github_get_contents → github_search_code → github_get_file_content`));
         }
     });
 }
@@ -932,25 +2109,434 @@ async function viewGitHubRepositoryInfo(params) {
             const args = ['view', `${owner}/${params.repo}`];
             const result = await executeGitHubCommand('repo', args, { cache: false });
             if (result.isError) {
-                return result;
+                // Parse the error message to provide better context
+                const errorMsg = result.content[0].text;
+                // Handle repository not found
+                if (errorMsg.includes('404') ||
+                    errorMsg.includes('Not Found') ||
+                    errorMsg.includes('could not resolve to a Repository')) {
+                    return createErrorResult$1(`Repository not found: ${owner}/${params.repo}`, new Error(`
+❌ REPOSITORY NOT FOUND: The repository '${owner}/${params.repo}' does not exist or is not accessible.
+
+🔍 COMMON CAUSES:
+• Repository name is incorrect
+• Repository is private and you lack access
+• Owner/organization name is wrong
+• Repository has been deleted or moved
+
+🎯 RECOMMENDED DISCOVERY WORKFLOW (in this order):
+
+1️⃣ **NPM PACKAGE DISCOVERY** (if this is a package):
+   • Use 'npm_search_packages' with keywords: "${params.repo}"
+   • Then 'npm_get_package' to find the GitHub repository URL
+   • This automatically discovers the correct owner/repo
+
+2️⃣ **GITHUB TOPICS SEARCH** (for broader discovery):
+   • Use 'github_search_topics' with terms: "${params.repo}"
+   • Discover related repositories and ecosystems
+   • Find the correct repository among similar projects
+
+3️⃣ **REPOSITORY SEARCH** (last resort):
+   • Use 'github_search_repositories' with query: "${params.repo}"
+   • Add filters like language, stars, etc.
+   • Manual selection from search results
+
+💡 ORGANIZATION ACCESS:
+If this should be a private repository, try:
+• 'github_get_user_organizations' to see your available orgs
+• Use the correct organization name as owner
+
+🔧 VERIFICATION:
+• Check repository exists at: https://github.com/${owner}/${params.repo}
+• Verify spelling and case sensitivity`));
+                }
+                // Handle access denied
+                if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                    return createErrorResult$1(`Access denied to repository: ${owner}/${params.repo}`, new Error(`
+🔒 ACCESS DENIED: You don't have permission to access '${owner}/${params.repo}'.
+
+🔍 POSSIBLE CAUSES:
+• Repository is private
+• Organization restrictions
+• Invalid authentication
+
+💡 RECOMMENDED ACTIONS:
+1. Check authentication: gh auth status
+2. Request repository access from owner: ${owner}
+3. Use 'github_get_user_organizations' if this is your org
+4. Verify you're logged into the correct GitHub account
+
+🎯 ALTERNATIVE DISCOVERY:
+If you're looking for similar repositories, try:
+• 'npm_search_packages' for packages
+• 'github_search_topics' for general discovery
+• 'github_search_repositories' with broader terms`));
+                }
+                // Handle rate limiting
+                if (errorMsg.includes('rate limit') || errorMsg.includes('429')) {
+                    return createErrorResult$1('GitHub API rate limit exceeded', new Error(`
+⏱️ RATE LIMIT: GitHub API rate limit has been exceeded.
+
+💡 RECOMMENDED ACTIONS:
+1. Wait a few minutes before trying again
+2. Use authentication to increase rate limits: gh auth login
+3. Try discovery tools instead: npm_search_packages or github_search_topics`));
+                }
+                // Generic error fallback
+                return createErrorResult$1(`Failed to access repository: ${owner}/${params.repo}`, new Error(`GitHub CLI Error: ${errorMsg}
+
+🔧 TROUBLESHOOTING:
+• Verify repository exists: https://github.com/${owner}/${params.repo}
+• Check spelling and case sensitivity
+• Confirm authentication: gh auth status
+
+🎯 DISCOVERY WORKFLOW:
+1. npm_search_packages → npm_get_package
+2. github_search_topics  
+3. github_search_repositories
+4. github_get_repository (current step)`));
             }
             // Extract the actual content from the exec result
             const execResult = JSON.parse(result.content[0].text);
             const content = execResult.result;
+            // Parse repository info to extract key details
             const viewResult = {
                 owner,
                 repo: params.repo,
                 repositoryInfo: content,
                 rawOutput: content,
             };
-            return createSuccessResult$1(viewResult);
-        }
-        catch (error) {
-            return createErrorResult$1('Failed to view GitHub repository', error);
-        }
+            // Try to extract branch information from the output
+            let defaultBranch = 'main'; // fallback
+            try {
+                // The content is usually YAML-like output from gh repo view
+                const lines = content.split('\n');
+                for (const line of lines) {
+                    if (line.includes('default branch:') ||
+                        line.includes('Default branch:')) {
+                        const branchMatch = line.split(':')[1]?.trim();
+                        if (branchMatch) {
+                            defaultBranch = branchMatch;
+                            break;
+                        }
+                    }
+                }
+            }
+            catch (parseError) {
+                // If we can't parse the branch, keep the fallback
+            }
+            return createSuccessResult$1({
+                ...viewResult,
+                defaultBranch,
+                success: true,
+                message: `✅ Repository found: ${owner}/${params.repo}
+        
+📋 REPOSITORY DETAILS:
+• Default branch: ${defaultBranch}
+• Ready for file operations
+
+🔄 NEXT RECOMMENDED STEPS:
+1. Explore structure: github_get_contents
+2. Search for code: github_search_code  
+3. Fetch specific files: github_get_file_content
+
+⚠️ IMPORTANT: Use branch '${defaultBranch}' in subsequent file operations.`,
+            });
+        }
+        catch (error) {
+            return createErrorResult$1(`Unexpected error accessing repository: ${params.owner}/${params.repo}`, new Error(`
+❌ UNEXPECTED ERROR: ${error.message}
+
+📍 REPOSITORY DETAILS:
+• Owner: ${params.owner}
+• Repository: ${params.repo}
+
+🔧 TROUBLESHOOTING STEPS:
+1. Verify GitHub CLI is installed and authenticated
+2. Check network connectivity
+3. Try discovery workflow instead:
+
+🎯 DISCOVERY WORKFLOW:
+1. npm_search_packages "${params.repo}"
+2. github_search_topics "${params.repo}"  
+3. github_search_repositories query="${params.repo}" owner="${params.owner}"
+4. github_get_repository (retry after discovery)
+
+💡 This ensures you have the correct owner/repo before attempting direct access.`));
+        }
     });
 }
 
+// Cross-Tool Orchestration Chains
+const TOOL_FALLBACK_CHAINS = {
+    'package-discovery': [
+        { tool: TOOL_NAMES.NPM_SEARCH_PACKAGES, reason: 'Primary package search' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_TOPICS,
+            reason: 'Ecosystem terminology discovery',
+        },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_REPOS,
+            reason: 'Repository-based discovery',
+        },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+            reason: 'Code implementation search',
+        },
+    ],
+    'code-discovery': [
+        { tool: TOOL_NAMES.GITHUB_SEARCH_CODE, reason: 'Direct code search' },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_REPOS, reason: 'Project-level discovery' },
+        { tool: TOOL_NAMES.NPM_SEARCH_PACKAGES, reason: 'Package-based solutions' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+            reason: 'Problem discussion search',
+        },
+    ],
+    'repository-discovery': [
+        { tool: TOOL_NAMES.NPM_GET_REPOSITORY, reason: 'Package-to-repo mapping' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_REPOS,
+            reason: 'Direct repository search',
+        },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_TOPICS, reason: 'Topic-based discovery' },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_USERS, reason: 'Organization discovery' },
+    ],
+    'issue-discovery': [
+        { tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES, reason: 'Primary issue search' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
+            reason: 'Solution implementation search',
+        },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_CODE, reason: 'Code example search' },
+        {
+            tool: TOOL_NAMES.GITHUB_SEARCH_REPOS,
+            reason: 'Related project discovery',
+        },
+    ],
+    'user-discovery': [
+        { tool: TOOL_NAMES.GITHUB_SEARCH_USERS, reason: 'Primary user search' },
+        {
+            tool: TOOL_NAMES.GITHUB_GET_USER_ORGS,
+            reason: 'Organization membership discovery',
+        },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_REPOS, reason: 'User project discovery' },
+        { tool: TOOL_NAMES.GITHUB_SEARCH_CODE, reason: 'Contribution analysis' },
+    ],
+};
+// Query Simplification Utilities
+class QueryOptimizer {
+    static getProgressiveQueries(originalQuery) {
+        const queries = [];
+        // Original query
+        queries.push(originalQuery);
+        // Remove special characters and clean up
+        const cleaned = originalQuery.replace(/[^\w\s-]/g, ' ').trim();
+        if (cleaned !== originalQuery) {
+            queries.push(cleaned);
+        }
+        // Extract key terms (remove common words)
+        const stopWords = [
+            'the',
+            'a',
+            'an',
+            'and',
+            'or',
+            'but',
+            'in',
+            'on',
+            'at',
+            'to',
+            'for',
+            'of',
+            'with',
+            'by',
+        ];
+        const terms = cleaned
+            .split(/\s+/)
+            .filter(term => term.length > 2 && !stopWords.includes(term.toLowerCase()));
+        // Multiple key terms
+        if (terms.length >= 2) {
+            queries.push(terms.slice(0, 2).join(' '));
+        }
+        // Single most important term
+        if (terms.length >= 1) {
+            queries.push(terms[0]);
+        }
+        // Remove duplicates and return
+        return [...new Set(queries)];
+    }
+    static simplifyPackageName(packageName) {
+        const variations = [packageName];
+        // Remove scope if present
+        if (packageName.startsWith('@')) {
+            const withoutScope = packageName.split('/')[1];
+            if (withoutScope) {
+                variations.push(withoutScope);
+            }
+        }
+        // Remove common suffixes
+        const suffixes = ['-js', '-node', '-lib', '-tool', '-cli', '-api'];
+        suffixes.forEach(suffix => {
+            if (packageName.endsWith(suffix)) {
+                variations.push(packageName.slice(0, -suffix.length));
+            }
+        });
+        return [...new Set(variations)];
+    }
+}
+// Context Analysis
+class ContextAnalyzer {
+    static analyzeQuery(query) {
+        const lowerQuery = query.toLowerCase();
+        const keywords = query.split(/\s+/).filter(term => term.length > 2);
+        // Determine query type
+        let type = 'general';
+        if (lowerQuery.includes('npm') ||
+            lowerQuery.includes('package') ||
+            lowerQuery.includes('install')) {
+            type = 'package';
+        }
+        else if (lowerQuery.includes('function') ||
+            lowerQuery.includes('class') ||
+            lowerQuery.includes('import')) {
+            type = 'code';
+        }
+        else if (lowerQuery.includes('repo') ||
+            lowerQuery.includes('project') ||
+            lowerQuery.includes('github')) {
+            type = 'repository';
+        }
+        else if (lowerQuery.includes('bug') ||
+            lowerQuery.includes('issue') ||
+            lowerQuery.includes('problem')) {
+            type = 'issue';
+        }
+        else if (lowerQuery.includes('user') ||
+            lowerQuery.includes('developer') ||
+            lowerQuery.includes('maintainer')) {
+            type = 'user';
+        }
+        // Determine complexity
+        const complexity = keywords.length <= 1
+            ? 'simple'
+            : keywords.length <= 3
+                ? 'medium'
+                : 'complex';
+        // Generate suggestions
+        const suggestions = [];
+        if (complexity === 'complex') {
+            suggestions.push('Try breaking down into simpler terms');
+            suggestions.push('Use 1-2 key words instead of full phrases');
+        }
+        return { type, keywords, complexity, suggestions };
+    }
+    static getToolChain(queryType) {
+        const chainKey = `${queryType}-discovery`;
+        return (TOOL_FALLBACK_CHAINS[chainKey] ||
+            TOOL_FALLBACK_CHAINS['package-discovery']);
+    }
+}
+// Enhanced Error Recovery
+function generateSmartRecovery(options) {
+    const { tool, query, packageName, resultCount, error } = options;
+    const queryAnalysis = query ? ContextAnalyzer.analyzeQuery(query) : null;
+    const simplifiedQueries = query
+        ? QueryOptimizer.getProgressiveQueries(query)
+        : [];
+    const packageVariations = packageName
+        ? QueryOptimizer.simplifyPackageName(packageName)
+        : [];
+    // Determine appropriate tool chain
+    const toolChain = queryAnalysis
+        ? ContextAnalyzer.getToolChain(queryAnalysis.type)
+        : TOOL_FALLBACK_CHAINS['package-discovery'];
+    // Build comprehensive recovery message
+    let recoveryText = `${tool} failed: ${error.message}`;
+    // Context-specific analysis
+    if (queryAnalysis) {
+        recoveryText += `
+
+🔍 QUERY ANALYSIS:
+• Type: ${queryAnalysis.type.toUpperCase()} search
+• Complexity: ${queryAnalysis.complexity.toUpperCase()}
+• Keywords: ${queryAnalysis.keywords.join(', ')}`;
+        if (queryAnalysis.suggestions.length > 0) {
+            recoveryText += `
+• Suggestions: ${queryAnalysis.suggestions.join(', ')}`;
+        }
+    }
+    // Query simplification suggestions
+    if (simplifiedQueries.length > 1) {
+        recoveryText += `
+
+🔄 SIMPLIFIED QUERY OPTIONS:
+${simplifiedQueries
+            .slice(1)
+            .map((q, i) => `${i + 1}. "${q}"`)
+            .join('\n')}`;
+    }
+    // Package name variations
+    if (packageVariations.length > 1) {
+        recoveryText += `
+
+📦 PACKAGE NAME VARIATIONS:
+${packageVariations
+            .slice(1)
+            .map((v, i) => `${i + 1}. "${v}"`)
+            .join('\n')}`;
+    }
+    // Cross-tool recommendations
+    recoveryText += `
+
+🔗 ALTERNATIVE TOOL CHAIN:
+${toolChain.map((t, i) => `${i + 1}. ${t.tool} - ${t.reason}`).join('\n')}`;
+    // Specific error type handling
+    if (error.message.includes('404') || error.message.includes('not found')) {
+        recoveryText += `
+
+💡 NOT FOUND RECOVERY:
+• Check spelling and exact names
+• Try search tools instead of direct access
+• Use broader discovery methods first`;
+    }
+    if (error.message.includes('API') || error.message.includes('rate limit')) {
+        recoveryText += `
+
+⏱️ API LIMIT RECOVERY:
+• Wait a moment before retrying
+• Use simpler queries to reduce API usage
+• Try different tools that may use different API endpoints`;
+    }
+    // General best practices
+    recoveryText += `
+
+📋 PROVEN RECOVERY WORKFLOW:
+1. Start with search tools (npm_search_packages, github_search_repos)
+2. Use discovery results to guide specific tool usage
+3. Progressively simplify queries if needed
+4. Try alternative tool chains for different perspectives`;
+    // Context-specific recommendations
+    if (resultCount === 0) {
+        recoveryText += `
+
+🎯 ZERO RESULTS STRATEGY:
+• Broaden search terms
+• Remove restrictive filters
+• Try ecosystem discovery tools
+• Use single keywords instead of phrases`;
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: recoveryText,
+            },
+        ],
+        isError: true,
+    };
+}
+
 function registerViewRepositoryTool(server) {
     server.tool(TOOL_NAMES.GITHUB_GET_REPOSITORY, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_REPOSITORY], {
         owner: z
@@ -970,88 +2556,12 @@ function registerViewRepositoryTool(server) {
             return await viewGitHubRepositoryInfo(args);
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to view repository: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-}
-
-async function npmView(packageName) {
-    const cacheKey = generateCacheKey('npm-view', { packageName });
-    return withCache(cacheKey, async () => {
-        try {
-            const result = await executeNpmCommand('view', [packageName, '--json'], {
-                cache: true,
+            return generateSmartRecovery({
+                tool: 'GitHub Repository View',
+                owner: args.owner,
+                repo: args.repo,
+                error: error,
             });
-            if (result.isError) {
-                return result;
-            }
-            // Parse the result from the executed command
-            const commandOutput = JSON.parse(result.content[0].text);
-            const npmData = commandOutput.result;
-            let popularityData = '';
-            try {
-                // Get version count as popularity indicator
-                const versionsResult = await executeNpmCommand('view', [
-                    packageName,
-                    'time',
-                    '--json',
-                ]);
-                if (!versionsResult.isError) {
-                    const versionsOutput = JSON.parse(versionsResult.content[0].text);
-                    const timeData = versionsOutput.result;
-                    const versionCount = Object.keys(timeData).length - 2; // Subtract 'created' and 'modified'
-                    popularityData = `Package versions released: ${versionCount}`;
-                }
-            }
-            catch {
-                // Popularity data is optional
-            }
-            const enhancedResult = {
-                npmData: JSON.parse(JSON.stringify(npmData)),
-                popularityInfo: popularityData,
-                lastAnalyzed: new Date().toISOString(),
-            };
-            return createSuccessResult$1(enhancedResult);
-        }
-        catch (error) {
-            return createErrorResult$1('Failed to get npm repository information', error);
-        }
-    });
-}
-
-function registerNpmViewTool(server) {
-    server.tool(TOOL_NAMES.NPM_GET_PACKAGE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_PACKAGE], {
-        packageName: z
-            .string()
-            .describe("The name of the npm package to analyze (e.g., 'react', '@types/node', 'lodash')"),
-    }, {
-        title: 'View NPM Package',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    }, async (args) => {
-        try {
-            return await npmView(args.packageName);
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to get npm package info: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
         }
     });
 }
@@ -1184,8 +2694,8 @@ function buildGitHubReposSearchCommand(params) {
         args.push(`--include-forks=${params.includeForks}`);
     if (params.language)
         args.push(`--language=${params.language}`);
-    if (params.license)
-        args.push(`--license=${params.license}`);
+    if (params.license && params.license.length > 0)
+        args.push(`--license=${params.license.join(',')}`);
     if (params.limit)
         args.push(`--limit=${params.limit}`);
     if (params.match)
@@ -1196,15 +2706,15 @@ function buildGitHubReposSearchCommand(params) {
         args.push(`--order=${params.order}`);
     if (params.size)
         args.push(`--size="${params.size}"`);
-    // DEFAULT TO UPDATED SORTING for recency prioritization
-    const sortBy = params.sort || 'updated';
+    // Use best-match as default, only specify sort if different from default
+    const sortBy = params.sort || 'best-match';
     if (sortBy !== 'best-match') {
         args.push(`--sort=${sortBy}`);
     }
     if (params.stars !== undefined)
-        args.push(`--stars=${params.stars}`);
-    if (params.topic)
-        args.push(`--topic=${params.topic}`);
+        args.push(`--stars="${params.stars}"`);
+    if (params.topic && params.topic.length > 0)
+        args.push(`--topic=${params.topic.join(',')}`);
     if (params.updated)
         args.push(`--updated="${params.updated}"`);
     if (params.visibility)
@@ -1264,7 +2774,13 @@ function validateFilterCombinations(args) {
             suggestion: 'PROVEN: owner=facebook + query=react without language filter → React (236K⭐), React Native (119K⭐), Create React App',
         },
         {
-            condition: args.language && args.stars !== undefined && args.stars > 10000,
+            condition: args.language &&
+                args.stars &&
+                ((args.stars.includes('>') &&
+                    parseInt(args.stars.replace(/[><]/g, '')) > 10000) ||
+                    (!args.stars.includes('>') &&
+                        !args.stars.includes('<') &&
+                        parseInt(args.stars) > 10000)),
             warning: 'High star threshold with specific language may be too restrictive (TESTING-VALIDATED)',
             suggestion: 'PROVEN: Use >1000 stars for established projects, >100 for active ones. Language filters often miss major projects.',
         },
@@ -1298,8 +2814,8 @@ function validateFilterCombinations(args) {
     if (args.limit && (args.limit < 1 || args.limit > 100)) {
         warnings.push('Limit must be between 1 and 100');
     }
-    if (args.stars !== undefined && args.stars < 0) {
-        warnings.push('Stars filter must be non-negative');
+    if (args.stars && !/^[><]=?\d+$|^\d+$|^\d+\.\.\d+$/.test(args.stars)) {
+        warnings.push('Stars filter must be in format ">100", ">=500", "<1000", "<=200", "50..200" or a simple number');
     }
     if (args.forks !== undefined && args.forks < 0) {
         warnings.push('Forks filter must be non-negative');
@@ -1338,8 +2854,9 @@ function registerSearchGitHubReposTool(server) {
             .describe('Search query for repositories. PRODUCTION TIP: Single terms work best (e.g., "react", "typescript"). Multi-term queries will be auto-decomposed with suggestions.'),
         owner: z
             .string()
-            .min(1, 'Owner is required and cannot be empty')
-            .describe('Repository owner/organization - REQUIRED for scoped, reliable results'),
+            .min(1)
+            .optional()
+            .describe('Repository owner/organization (e.g., "facebook", "microsoft"). OPTIONAL: Leave empty for global searches across all of GitHub. Recommended for scoped, reliable results.'),
         archived: z.boolean().optional().describe('Filter archived state'),
         created: z
             .string()
@@ -1363,7 +2880,10 @@ function registerSearchGitHubReposTool(server) {
             .string()
             .optional()
             .describe('Filter by programming language - WARNING: Can cause empty results with restrictive combinations'),
-        license: z.string().optional().describe('Filter by license type'),
+        license: z
+            .array(z.string())
+            .optional()
+            .describe('Filter based on license type (e.g., ["mit", "apache-2.0"])'),
         limit: z
             .number()
             .optional()
@@ -1373,28 +2893,37 @@ function registerSearchGitHubReposTool(server) {
             .enum(['name', 'description', 'readme'])
             .optional()
             .describe('Search scope restriction'),
-        numberTopics: z.number().optional().describe('Filter by topics count'),
+        numberTopics: z
+            .number()
+            .optional()
+            .describe('Filter on number of topics'),
         order: z
             .enum(['asc', 'desc'])
             .optional()
             .default('desc')
             .describe('Result order (default: desc for newest first)'),
-        size: z.string().optional().describe('Filter by size in KB'),
+        size: z
+            .string()
+            .optional()
+            .describe('Filter on size range, in kilobytes (e.g., ">1000", "50..120")'),
         sort: z
             .enum(['forks', 'help-wanted-issues', 'stars', 'updated', 'best-match'])
             .optional()
-            .default('updated')
-            .describe('Sort criteria (default: updated for recent activity)'),
+            .default('best-match')
+            .describe('Sort fetched repositories (default: best-match)'),
         stars: z
-            .number()
+            .string()
+            .optional()
+            .describe('Filter by stars count (e.g., ">100", "<1000", ">=500", "50..200" for range queries) - TIP: Use >100 for established projects, >10 for active ones'),
+        topic: z
+            .array(z.string())
             .optional()
-            .describe('Filter by stars count - TIP: Use >100 for established projects, >10 for active ones'),
-        topic: z.string().optional().describe('Filter by topic/tag'),
+            .describe('Filter on topic (e.g., ["react", "javascript"])'),
         updated: z.string().optional().describe('Filter by last update date'),
         visibility: z
             .enum(['public', 'private', 'internal'])
             .optional()
-            .describe('Filter by visibility'),
+            .describe('Filter based on repository visibility'),
     }, {
         title: 'Search GitHub Repositories',
         readOnlyHint: true,
@@ -1420,8 +2949,26 @@ function registerSearchGitHubReposTool(server) {
             const result = await searchGitHubRepos(searchArgs);
             // Check if we got empty results and provide helpful guidance
             const resultText = result.content[0].text;
-            const parsedResults = JSON.parse(resultText);
-            const resultCount = JSON.parse(parsedResults.rawOutput).length;
+            // Handle non-JSON responses gracefully
+            let parsedResults;
+            let resultCount = 0;
+            try {
+                parsedResults = JSON.parse(resultText);
+                if (parsedResults.rawOutput) {
+                    const rawData = JSON.parse(parsedResults.rawOutput);
+                    resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                }
+            }
+            catch (parseError) {
+                // If parsing fails, it might be an error message from GitHub CLI
+                if (resultText.includes('Failed to') ||
+                    resultText.includes('Error:')) {
+                    throw new Error(`GitHub CLI error: ${resultText}`);
+                }
+                // For other parsing issues, set reasonable defaults
+                resultCount = 0;
+                parsedResults = { rawOutput: '[]' };
+            }
             let responseText = resultText;
             // Add guidance for multi-term queries
             if (queryAnalysis.shouldDecompose) {
@@ -1462,6 +3009,10 @@ function registerSearchGitHubReposTool(server) {
                     responseText += `\n• SCOPED SEARCH SUCCESS: owner + single term pattern proven effective`;
                     responseText += `\n• PROVEN EXAMPLES: microsoft+typescript→VSCode(173K⭐), facebook+react→React(236K⭐)`;
                 }
+                else if (!args.owner) {
+                    responseText += `\n• GLOBAL SEARCH: Searching across all GitHub repositories`;
+                    responseText += `\n• TIP: Add owner filter for more targeted results if you know specific organizations`;
+                }
                 // Add caching recommendations for testing-validated popular searches
                 const validatedPopularTerms = [
                     'react', // 236K⭐ confirmed
@@ -1494,11 +3045,12 @@ function registerSearchGitHubReposTool(server) {
 🔄 RECOMMENDED FALLBACK WORKFLOW:
 ${fallbacks.map(f => `• ${f}`).join('\n')}
 
-💡 PRODUCTION NOTE: This tool is a last resort. For reliable discovery:
+💡 PRODUCTION NOTE: For reliable discovery:
 1. Start with npm_search_packages for package-based discovery
 2. Use github_search_topics for ecosystem terminology  
 3. Use npm_get_package to extract repository URLs
-4. Only use repository search when NPM + Topics completely fail`;
+4. Use global repository search (without owner) for broad discovery
+5. Use scoped search (with owner) when you know specific organizations`;
             return {
                 content: [
                     {
@@ -1856,18 +3408,69 @@ function registerSearchGitHubPullRequestsTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubPullRequests(args);
+            const result = await searchGitHubPullRequests(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO RESULTS RECOVERY STRATEGY:
+• Try broader terms: "${args.query}" → "fix", "feature", "update"
+• Implementation search: github_search_code for actual code changes
+• Project discovery: github_search_repos for related projects
+• Issue tracking: github_search_issues for related problems
+
+💡 PR SEARCH OPTIMIZATION:
+• Focus on action words: "implement", "add", "fix", "update"
+• Try state filters: state=open vs state=closed
+• Use review filters: draft=false for completed PRs
+
+🔗 RECOMMENDED TOOL CHAIN:
+1. github_search_issues - Find problems that needed solutions
+2. github_search_code - See actual implementation patterns
+3. github_search_repos - Discover projects with similar features`;
+                }
+                else if (resultCount <= 5) {
+                    responseText += `
+
+💡 FEW RESULTS ENHANCEMENT:
+• Found ${resultCount} PRs - try removing restrictive filters
+• Alternative: github_search_code for implementation examples
+• Cross-reference: github_search_issues for related discussions`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub pull requests: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Pull Requests Search',
+                query: args.query,
+                owner: args.owner,
+                repo: args.repo,
+                error: error,
+            });
         }
     });
 }
@@ -1999,6 +3602,39 @@ async function npmSearch(args) {
     }
 }
 
+// Analyze NPM search patterns and suggest fallbacks
+function analyzeNpmSearchPattern(args) {
+    const suggestions = [];
+    const fallbackStrategy = [];
+    const organizationalHints = [];
+    let patternType = 'basic';
+    const query = args.query.toLowerCase();
+    // Detect organizational packages
+    if (query.includes('@') ||
+        query.includes('internal') ||
+        query.includes('private')) {
+        patternType = 'organizational';
+        organizationalHints.push('ORGANIZATIONAL PACKAGE DETECTED: Consider checking GitHub organizations first');
+        fallbackStrategy.push(`Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} to discover private package access`);
+    }
+    // Complex search patterns
+    if (query.split(' ').length > 2) {
+        patternType = 'complex-multi-term';
+        suggestions.push('PROVEN: Complex phrases often yield zero results - try single terms');
+        fallbackStrategy.push('Break down into primary term → secondary filters');
+    }
+    // Technology-specific patterns
+    if (query.includes('react') ||
+        query.includes('vue') ||
+        query.includes('angular')) {
+        patternType = 'framework-specific';
+        suggestions.push('FRAMEWORK DETECTED: Consider ecosystem-specific searches');
+        fallbackStrategy.push(`Use ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} for framework ecosystem discovery`);
+    }
+    // Generic fallback strategy for all patterns
+    fallbackStrategy.push(`1. ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} - Search ecosystem terms`, `2. ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Find repositories that might be packages`, `3. ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Search package.json files`, `4. ${TOOL_NAMES.GITHUB_SEARCH_COMMITS} - Search package development history`, `5. ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Search package mentions in PRs`, `6. ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} - Search package discussions`);
+    return { patternType, suggestions, fallbackStrategy, organizationalHints };
+}
 function registerNpmSearchTool(server) {
     server.tool(TOOL_NAMES.NPM_SEARCH_PACKAGES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_SEARCH_PACKAGES], {
         query: z
@@ -2022,14 +3658,106 @@ function registerNpmSearchTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await npmSearch(args);
+            // Analyze search pattern for insights and fallbacks
+            const patternAnalysis = analyzeNpmSearchPattern(args);
+            const result = await npmSearch(args);
+            // Check if we got poor results and enhance with fallback suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                // Parse result to check quality
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.results && Array.isArray(parsed.results)) {
+                        resultCount = parsed.results.length;
+                    }
+                }
+                catch {
+                    // If not JSON, try to estimate from text
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5); // Rough estimate
+                }
+                // Add organizational hints if detected
+                if (patternAnalysis.organizationalHints.length > 0) {
+                    responseText += `\n\n🏢 ORGANIZATIONAL PACKAGE INSIGHTS:`;
+                    patternAnalysis.organizationalHints.forEach(hint => {
+                        responseText += `\n• ${hint}`;
+                    });
+                }
+                // Add pattern-specific suggestions
+                if (patternAnalysis.suggestions.length > 0) {
+                    responseText += `\n\n💡 SEARCH PATTERN INSIGHTS (${patternAnalysis.patternType.toUpperCase()}):`;
+                    patternAnalysis.suggestions.forEach(suggestion => {
+                        responseText += `\n• ${suggestion}`;
+                    });
+                }
+                // Add fallback strategy if results are poor (< 5 results or specific patterns)
+                if (resultCount < 5 || patternAnalysis.patternType !== 'basic') {
+                    responseText += `\n\n🔄 NPM SEARCH FALLBACK STRATEGY:`;
+                    responseText += `\nIf NPM search yields insufficient results, try this validated workflow:`;
+                    patternAnalysis.fallbackStrategy.forEach((step, index) => {
+                        responseText += `\n${index + 1}. ${step}`;
+                    });
+                }
+                // Add general best practices
+                responseText += `\n\n📋 NPM SEARCH BEST PRACTICES:`;
+                responseText += `\n• Single terms work best: "react", "auth", "cli"`;
+                responseText += `\n• Combined terms: "react-hooks", "typescript-cli"`;
+                responseText += `\n• Avoid complex phrases: Break "react auth jwt library" → "react" + "auth"`;
+                responseText += `\n• Organizational packages: @company/ triggers private search workflow`;
+                responseText += `\n• 0 results → broader terms, 1-20 IDEAL, 100+ → more specific`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
+            // Enhanced error handling with fallback suggestions
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            const fallbackSuggestions = `
+🔄 NPM SEARCH FALLBACK WORKFLOW:
+When NPM registry search fails, try this proven sequence:
+
+1. ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} - Discover ecosystem terminology
+   • Use broader terms: "authentication" instead of "jwt-auth-library"
+   • Find related technologies and packages
+
+2. ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Find package repositories
+   • Search for repositories that might contain packages
+   • Look for package.json indicators
+
+3. ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Search package manifests
+   • Query: "package.json" + your terms
+   • Find actual package definitions
+
+4. ${TOOL_NAMES.GITHUB_SEARCH_COMMITS} - Development history
+   • Search commit messages for package development
+   • Find package creation/updates
+
+5. ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Package discussions
+   • Find PRs mentioning package development
+   • Discover package features and issues
+
+6. ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} - Community discussions
+   • Find issues discussing packages
+   • Discover alternatives and recommendations
+
+💡 PROVEN STRATEGIES:
+• Try simpler terms if complex search fails
+• Check organizational access for @company/ packages  
+• Use GitHub ecosystem discovery when NPM fails`;
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `Failed to search npm packages: ${error.message}`,
+                        text: `NPM Search Failed: ${errorMessage}${fallbackSuggestions}`,
                     },
                 ],
                 isError: true,
@@ -2291,8 +4019,9 @@ function registerSearchGitHubIssuesTool(server) {
             .describe("The search query to find issues (e.g., 'bug fix', 'feature request', 'documentation')"),
         owner: z
             .string()
-            .min(1, 'Owner is required and cannot be empty')
-            .describe("Filter by repository owner/organization (e.g., 'example-org')"),
+            .min(1)
+            .optional()
+            .describe("Filter by repository owner/organization (e.g., 'example-org'). OPTIONAL: Leave empty for global searches across all of GitHub."),
         repo: z
             .string()
             .optional()
@@ -2407,18 +4136,71 @@ function registerSearchGitHubIssuesTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubIssues(args);
+            const result = await searchGitHubIssues(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    // If parsing fails, estimate from text
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                // Add smart suggestions for empty or poor results
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO RESULTS RECOVERY STRATEGY:
+• Try broader terms: "${args.query}" → single keywords
+• Alternative discovery: github_search_repos for related projects
+• Problem context: github_search_code for implementation examples
+• Solution tracking: github_search_pull_requests for fixes
+
+💡 QUERY SIMPLIFICATION:
+• Remove quotes and special characters
+• Use single keywords: "bug", "error", "feature"
+• Try related terms: "issue" → "problem", "bug" → "error"
+
+🔗 RECOMMENDED TOOL CHAIN:
+1. github_search_repos - Find projects that might have similar issues
+2. github_search_code - Search for code patterns related to your problem
+3. npm_search_packages - Find packages that solve similar problems`;
+                }
+                else if (resultCount <= 5) {
+                    responseText += `
+
+💡 FEW RESULTS ENHANCEMENT:
+• Found ${resultCount} issues - try broader search terms
+• Alternative: github_search_repos for project-level discovery
+• Cross-reference: github_search_code for implementation patterns`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub issues: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Issues Search',
+                query: args.query,
+                owner: args.owner,
+                repo: args.repo,
+                error: error,
+            });
         }
     });
 }
@@ -2535,23 +4317,72 @@ function registerSearchGitHubTopicsTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubTopics(args);
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub topics: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-}
-
-async function searchGitHubUsers(params) {
+            const result = await searchGitHubTopics(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO TOPICS FOUND RECOVERY:
+• Try simpler terms: "${args.query}" → single technology keywords
+• Ecosystem discovery: npm_search_packages for related packages
+• Repository search: github_search_repos for projects using these topics
+• User community: github_search_users for topic experts
+
+💡 TOPIC SEARCH OPTIMIZATION:
+• Use popular technology terms: "react", "javascript", "python"
+• Try compound topics: "machine-learning", "web-development"
+• Focus on featured topics: featured=true
+
+🔗 RECOMMENDED DISCOVERY CHAIN:
+1. npm_search_packages - Find packages in this domain
+2. github_search_repos - Discover projects using these topics
+3. github_search_code - Find implementations using topic technologies`;
+                }
+                else if (resultCount <= 3) {
+                    responseText += `
+
+💡 LIMITED TOPICS ENHANCEMENT:
+• Found ${resultCount} topics - try broader or more popular terms
+• Ecosystem expansion: npm_search_packages for related technologies
+• Project discovery: github_search_repos for topic implementation`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            return generateSmartRecovery({
+                tool: 'GitHub Topics Search',
+                query: args.query,
+                error: error,
+            });
+        }
+    });
+}
+
+async function searchGitHubUsers(params) {
     const cacheKey = generateCacheKey('gh-users', params);
     return withCache(cacheKey, async () => {
         try {
@@ -2605,6 +4436,8 @@ function buildGitHubUsersAPICommand(params) {
     // Add pagination parameters
     const limit = params.limit || 30;
     queryParams.push(`per_page=${limit}`);
+    const page = params.page || 1;
+    queryParams.push(`page=${page}`);
     if (params.sort)
         queryParams.push(`sort=${params.sort}`);
     if (params.order)
@@ -2623,8 +4456,9 @@ function registerSearchGitHubUsersTool(server) {
             .describe("The search query to find users/organizations (e.g., 'react developer', 'python', 'machine learning')"),
         owner: z
             .string()
-            .min(1, 'Owner is required and cannot be empty')
-            .describe("Filter by repository owner/organization (e.g., 'example-org') obtained from the appropriate tool for fetching user organizations"),
+            .min(1)
+            .optional()
+            .describe("Filter by repository owner/organization (e.g., 'example-org'). OPTIONAL: Leave empty for global searches across all of GitHub."),
         type: z
             .enum(['user', 'org'])
             .optional()
@@ -2663,6 +4497,11 @@ function registerSearchGitHubUsersTool(server) {
             .optional()
             .default(50)
             .describe('Maximum number of users to return (default: 50)'),
+        page: z
+            .number()
+            .optional()
+            .default(1)
+            .describe('The page number of the results to fetch (default: 1)'),
     }, {
         title: 'Search GitHub Users',
         readOnlyHint: true,
@@ -2671,79 +4510,67 @@ function registerSearchGitHubUsersTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            return await searchGitHubUsers(args);
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to search GitHub users: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-}
-
-async function npmPackageStats(packageName) {
-    const cacheKey = generateCacheKey('npm-stats', { packageName });
-    return withCache(cacheKey, async () => {
-        try {
-            // Execute multiple commands in parallel using executeNpmCommand
-            const commands = [
-                executeNpmCommand('view', [packageName, 'time', '--json']),
-                executeNpmCommand('view', [packageName, 'versions', '--json']),
-                executeNpmCommand('view', [packageName, 'dist-tags', '--json']),
-            ];
-            const results = await Promise.allSettled(commands);
-            const stats = {
-                packageName,
-                releaseHistory: results[0].status === 'fulfilled' && !results[0].value.isError
-                    ? JSON.parse(results[0].value.content[0].text).result
-                    : null,
-                versions: results[1].status === 'fulfilled' && !results[1].value.isError
-                    ? JSON.parse(results[1].value.content[0].text).result
-                    : null,
-                distTags: results[2].status === 'fulfilled' && !results[2].value.isError
-                    ? JSON.parse(results[2].value.content[0].text).result
-                    : null,
-                analyzedAt: new Date().toISOString(),
-            };
-            return createSuccessResult$1(stats);
-        }
-        catch (error) {
-            return createErrorResult$1('Failed to get npm package statistics', error);
-        }
-    });
-}
+            const result = await searchGitHubUsers(args);
+            // Check for empty results and enhance with smart suggestions
+            if (result.content && result.content[0]) {
+                let responseText = result.content[0].text;
+                let resultCount = 0;
+                try {
+                    const parsed = JSON.parse(responseText);
+                    if (parsed.rawOutput) {
+                        const rawData = JSON.parse(parsed.rawOutput);
+                        resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                    }
+                }
+                catch {
+                    const lines = responseText.split('\n').filter(line => line.trim());
+                    resultCount = Math.max(0, lines.length - 5);
+                }
+                if (resultCount === 0) {
+                    responseText += `
+
+🔄 NO RESULTS RECOVERY STRATEGY:
+• Try simpler terms: "${args.query}" → technology keywords only
+• Organization discovery: github_get_user_organizations for company access
+• Project-based search: github_search_repos to find user projects
+• Code contribution search: github_search_code for user activity
+
+💡 USER SEARCH OPTIMIZATION:
+• Use technology terms: "react", "python", "javascript"
+• Try location filters: location="San Francisco", location="Remote"
+• Focus on active users: followers>10, repos>5
+
+🔗 RECOMMENDED TOOL CHAIN:
+1. github_search_repos - Find projects by technology/topic
+2. github_get_user_organizations - Discover organizations
+3. npm_search_packages - Find package maintainers`;
+                }
+                else if (resultCount <= 5) {
+                    responseText += `
 
-function registerNpmPackageStatsTool(server) {
-    server.tool(TOOL_NAMES.NPM_GET_PACKAGE_STATS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_PACKAGE_STATS], {
-        packageName: z
-            .string()
-            .describe("The name of the npm package to analyze (e.g., 'react', '@types/node', 'lodash')"),
-    }, {
-        title: 'NPM Package Statistics',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    }, async (args) => {
-        try {
-            return await npmPackageStats(args.packageName);
+💡 FEW RESULTS ENHANCEMENT:
+• Found ${resultCount} users - try broader location or technology terms
+• Alternative: github_search_repos for project discovery
+• Organization search: github_get_user_organizations`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                    isError: false,
+                };
+            }
+            return result;
         }
         catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to get npm package statistics: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
+            return generateSmartRecovery({
+                tool: 'GitHub Users Search',
+                query: args.query,
+                error: error,
+            });
         }
     });
 }
@@ -2874,214 +4701,1153 @@ function registerNpmDependencyAnalysisTool(server) {
     });
 }
 
-function registerUsageGuideResource(server) {
-    server.resource('usage-guide', 'help://usage', async (uri) => ({
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: 'text/markdown',
-                text: `# Octocode MCP Quick Start
-
-## Setup (Required)
-\`\`\`bash
-gh auth login  # GitHub CLI authentication
-\`\`\`
-
-## MANDATORY SEARCH STRATEGY
-1. **ALWAYS START**: \`search_github_topics\` - **NEVER SKIP** - Maps ecosystem terminology
-2. **PRIMARY DISCOVERY**: \`npm_search\` and \`npm_view\` - Minimizes GitHub API calls
-3. **TARGETED EXTRACTION**: \`search_github_code\` with owner/repo from NPM
-4. **LAST RESORT**: \`search_github_repos\` - Single terms only when NPM insufficient
-
-## Core Workflow
-1. **Check Auth**: Read \`github://auth-status\` and \`github://rate-limits\`
-2. **MANDATORY**: \`search_github_topics\` for ecosystem mapping
-3. **NPM Discovery**: \`npm_search\` → \`npm_view\` → extract repository URLs
-4. **Extract**: Get complete implementations from discovered repositories
-5. **Validate**: Cross-reference multiple NPM packages
-
-## Essential Tools (Priority Order)
-- **\`search_github_topics\`**: **MANDATORY FIRST STEP** - Find technology ecosystems
-- **\`npm_search\`**: **PRIMARY DISCOVERY** - Find packages by functionality
-- **\`npm_view\`**: **PRIMARY DISCOVERY** - Package metadata and repo links
-- **\`view_repository\`**: Get branch info (required before file operations!)
-- **\`search_github_code\`**: Find specific implementations in discovered repos
-- **\`fetch_github_file_content\`**: Extract complete code
-- **\`search_github_repos\`**: **LAST RESORT ONLY** - Single terms when NPM fails
-
-## Search Strategy Rules
-- **Topics First**: Every workflow starts with \`search_github_topics\`
-- **NPM Primary**: Use NPM tools before GitHub repo search
-- **Single Terms Only**: NEVER multi-term searches in \`search_github_repos\`
-- **API Conservation**: NPM discovery reduces GitHub API usage by 60%
-
-## Search Term Strategy
-- **✅ GOOD**: "react", "authentication", "typescript", "deployment"
-- **❌ BAD**: "react hooks", "full-stack app", "react angular auth"
-- **Decompose**: "react typescript auth" → ["react", "typescript", "authentication"]
-
-## Quick Examples
-- **Package research**: \`search_github_topics\` → \`npm_search\` → \`npm_view\` → \`view_repository\` → \`search_github_code\`
-- **Problem solving**: \`search_github_topics\` → \`npm_search\` → \`search_github_issues\` → \`search_github_code\`
-- **Technology discovery**: \`search_github_topics\` → \`npm_search\` → \`npm_view\` → \`view_repository\` → \`fetch_github_file_content\`
-
-## CRITICAL REMINDERS
-- **NEVER skip** \`search_github_topics\` - provides essential context
-- **NPM FIRST** - use NPM tools before GitHub repo search
-- **SINGLE TERMS** - never combine multiple concepts in repo searches
-- **REPOS LAST** - \`search_github_repos\` is lowest priority discovery tool
-
-Generated: ${new Date().toISOString()}`,
-            },
-        ],
-    }));
-}
-
-// GitHub Authentication Status Resource
-function registerGithubStatusResource(server) {
-    server.resource('github-auth-status', 'github://auth-status', async (uri) => {
-        try {
-            // For version, we'll use a workaround since --version is not a command
-            // We can use 'help' command which shows version info, or skip detailed version check
-            const ghVersion = 'Available (GitHub CLI detected)';
-            let isAuthenticated = false;
-            let authError = null;
-            try {
-                // Check auth status using safe command
-                const authResult = await executeGitHubCommand('auth', ['status'], {
-                    timeout: 5000,
-                    cache: false,
-                });
-                if (!authResult.isError) {
-                    const content = String(authResult.content[0]?.text || '');
-                    if (content) {
-                        try {
-                            const parsed = JSON.parse(content);
-                            const output = parsed.result || content;
-                            // Only check if authenticated, don't expose user details
-                            isAuthenticated =
-                                String(output).includes('✓ Logged in') ||
-                                    String(output).includes('Logged in');
-                        }
-                        catch {
-                            isAuthenticated =
-                                content.includes('✓ Logged in') ||
-                                    content.includes('Logged in');
-                        }
-                    }
-                }
-                else {
-                    // auth status command failed, check error content for auth info
-                    const errorContent = String(authResult.content[0]?.text || 'Authentication check failed');
-                    if (errorContent.includes('✓ Logged in') ||
-                        errorContent.includes('Logged in')) {
-                        isAuthenticated = true;
-                    }
-                    else {
-                        authError = 'Not authenticated';
-                    }
-                }
-            }
-            catch (error) {
-                authError = 'Unable to check authentication status';
+async function checkGitHubAuth() {
+    try {
+        const authResult = await executeGitHubCommand('auth', ['status'], {
+            timeout: 10000,
+            cache: false,
+        });
+        if (authResult.isError) {
+            const errorText = String(authResult.content[0]?.text || '');
+            if (errorText.includes('not logged into') ||
+                errorText.includes('not authenticated')) {
+                return {
+                    status: 'not_authenticated',
+                    message: 'Not logged into GitHub CLI. Please run: gh auth login',
+                };
             }
             return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        mimeType: 'application/json',
-                        text: JSON.stringify({
-                            status: 'GitHub Authentication Status - LIVE STATUS',
-                            description: 'GitHub CLI authentication status and version information',
-                            gh_version: ghVersion,
-                            authenticated: isAuthenticated,
-                            auth_error: authError,
-                            setup_instructions: {
-                                not_authenticated: [
-                                    'Run: gh auth login',
-                                    'Follow the interactive prompts to authenticate',
-                                    'Choose your preferred authentication method',
-                                ],
-                                verification: [
-                                    'Run: gh auth status',
-                                    'Should show "✓ Logged in" if successful',
-                                ],
-                            },
-                            timestamp: new Date().toISOString(),
-                        }, null, 2),
-                    },
-                ],
+                status: 'error',
+                message: `GitHub CLI error: ${errorText}`,
             };
         }
-        catch (error) {
+        const statusText = String(authResult.content[0]?.text || '');
+        // Extract username if present
+        const userMatch = statusText.match(/Logged in to github\.com as ([^\s]+)/);
+        const user = userMatch ? userMatch[1] : undefined;
+        if (statusText.includes('Logged in to github.com')) {
             return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        mimeType: 'application/json',
-                        text: JSON.stringify({
-                            status: 'GitHub Authentication Status - ERROR',
-                            error: error.message,
-                            message: 'GitHub CLI may not be installed or accessible',
-                            timestamp: new Date().toISOString(),
-                        }, null, 2),
-                    },
-                ],
+                status: 'authenticated',
+                user,
+                message: user ? `Authenticated as ${user}` : 'Authenticated to GitHub',
             };
         }
-    });
+        return {
+            status: 'not_authenticated',
+            message: 'GitHub CLI authentication status unclear. Please run: gh auth login',
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            message: `Failed to check GitHub auth: ${error.message}`,
+        };
+    }
 }
-
-function registerGithubRateLimitResource(server) {
-    server.resource('github-rate-limits', 'github://rate-limits', async (uri) => {
-        try {
-            // Use safe GitHub command execution for API calls
-            const rateLimitResult = await executeGitHubCommand('api', ['rate_limit'], {
-                timeout: 10000,
-                cache: false,
-            });
-            if (rateLimitResult.isError) {
-                const errorText = String(rateLimitResult.content[0]?.text || 'Failed to fetch rate limits');
-                throw new Error(errorText);
-            }
-            // Extract and parse the rate limit data
-            const content = String(rateLimitResult.content[0]?.text || '');
-            if (!content) {
-                throw new Error('No rate limit data received');
+async function checkNpmConnectivity() {
+    try {
+        const pingResult = await executeNpmCommand('ping', [], {
+            timeout: 10000,
+            cache: false,
+        });
+        if (pingResult.isError) {
+            const errorText = String(pingResult.content[0]?.text || '');
+            return {
+                status: 'disconnected',
+                message: `NPM registry unreachable: ${errorText}`,
+            };
+        }
+        const pingText = String(pingResult.content[0]?.text || '');
+        if (pingText.includes('npm ping ok') || pingText.includes('Ping success')) {
+            // Extract registry if present
+            const registryMatch = pingText.match(/registry: (.+)/);
+            const registry = registryMatch
+                ? registryMatch[1]
+                : 'https://registry.npmjs.org';
+            return {
+                status: 'connected',
+                registry,
+                message: `Connected to NPM registry: ${registry}`,
+            };
+        }
+        return {
+            status: 'error',
+            message: `NPM ping response unclear: ${pingText}`,
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            message: `Failed to ping NPM registry: ${error.message}`,
+        };
+    }
+}
+async function checkGitHubRateLimits() {
+    try {
+        const rateLimitResult = await executeGitHubCommand('api', ['rate_limit'], {
+            timeout: 10000,
+            cache: false,
+        });
+        if (rateLimitResult.isError) {
+            const errorText = String(rateLimitResult.content[0]?.text || '');
+            return {
+                status: 'error',
+                primary_api: {
+                    remaining: 0,
+                    limit: 0,
+                    reset_time: '',
+                    usage_percentage: 100,
+                },
+                search_api: {
+                    remaining: 0,
+                    limit: 0,
+                    reset_time: '',
+                    usage_percentage: 100,
+                },
+                code_search: {
+                    remaining: 0,
+                    limit: 0,
+                    reset_time: '',
+                    usage_percentage: 100,
+                },
+                message: `Failed to fetch rate limits: ${errorText}`,
+                recommendations: [
+                    'GitHub authentication may be required',
+                    'Run: gh auth login',
+                ],
+            };
+        }
+        const content = String(rateLimitResult.content[0]?.text || '');
+        if (!content) {
+            throw new Error('No rate limit data received');
+        }
+        let rateLimit;
+        try {
+            const parsed = JSON.parse(content);
+            rateLimit = parsed.result || parsed;
+        }
+        catch {
+            rateLimit = JSON.parse(content);
+        }
+        const formatResetTime = (reset) => new Date(reset * 1000).toISOString();
+        const calculateUsage = (used, limit) => Math.round((used / limit) * 100);
+        const core = rateLimit.resources.core;
+        const search = rateLimit.resources.search;
+        const codeSearch = rateLimit.resources.code_search;
+        const primaryApi = {
+            remaining: core.remaining,
+            limit: core.limit,
+            reset_time: formatResetTime(core.reset),
+            usage_percentage: calculateUsage(core.used, core.limit),
+        };
+        const searchApi = {
+            remaining: search.remaining,
+            limit: search.limit,
+            reset_time: formatResetTime(search.reset),
+            usage_percentage: calculateUsage(search.used, search.limit),
+        };
+        const codeSearchApi = {
+            remaining: codeSearch.remaining,
+            limit: codeSearch.limit,
+            reset_time: formatResetTime(codeSearch.reset),
+            usage_percentage: calculateUsage(codeSearch.used, codeSearch.limit),
+        };
+        // Determine overall status
+        const minRemaining = Math.min(core.remaining, search.remaining, codeSearch.remaining);
+        let status;
+        const recommendations = [];
+        if (minRemaining === 0) {
+            status = 'exhausted';
+            recommendations.push('🚨 API limits exhausted - wait for reset or use alternative approaches');
+            recommendations.push('Consider using cached data or reducing API calls');
+        }
+        else if (minRemaining < 10) {
+            status = 'limited';
+            recommendations.push('⚠️ API limits low - prioritize essential requests only');
+            recommendations.push('Avoid extensive searches or bulk operations');
+        }
+        else {
+            status = 'healthy';
+            recommendations.push('✅ All APIs ready for normal operation');
+        }
+        // Add specific API recommendations
+        if (codeSearch.remaining < 5) {
+            recommendations.push('🔍 Code search severely limited - use repository-specific searches');
+        }
+        if (search.remaining < 10) {
+            recommendations.push('🔎 Search API limited - reduce search complexity');
+        }
+        if (core.remaining < 100) {
+            recommendations.push('🏠 Core API limited - avoid bulk repository operations');
+        }
+        return {
+            status,
+            primary_api: primaryApi,
+            search_api: searchApi,
+            code_search: codeSearchApi,
+            message: `Rate limits checked - ${status}`,
+            recommendations,
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            primary_api: {
+                remaining: 0,
+                limit: 0,
+                reset_time: '',
+                usage_percentage: 100,
+            },
+            search_api: {
+                remaining: 0,
+                limit: 0,
+                reset_time: '',
+                usage_percentage: 100,
+            },
+            code_search: {
+                remaining: 0,
+                limit: 0,
+                reset_time: '',
+                usage_percentage: 100,
+            },
+            message: `Error checking rate limits: ${error.message}`,
+            recommendations: [
+                'Unable to determine API status',
+                'Check GitHub authentication',
+            ],
+        };
+    }
+}
+async function performApiStatusCheck() {
+    try {
+        console.log('🔍 Performing comprehensive API status check...');
+        // Perform all checks in parallel for efficiency
+        const [githubAuth, npmConnectivity, githubRateLimits] = await Promise.all([
+            checkGitHubAuth(),
+            checkNpmConnectivity(),
+            checkGitHubRateLimits(),
+        ]);
+        // Determine overall status
+        let overallStatus;
+        const researchRecommendations = [];
+        if (githubAuth.status !== 'authenticated') {
+            overallStatus = 'not_ready';
+            researchRecommendations.push('❌ GitHub authentication required before research');
+            researchRecommendations.push('Run: gh auth login');
+        }
+        else if (npmConnectivity.status !== 'connected') {
+            overallStatus = 'limited';
+            researchRecommendations.push('⚠️ NPM unavailable - GitHub research only');
+        }
+        else if (githubRateLimits.status === 'exhausted') {
+            overallStatus = 'not_ready';
+            researchRecommendations.push('❌ GitHub API exhausted - wait for reset');
+            researchRecommendations.push(`Next reset: ${githubRateLimits.code_search.reset_time}`);
+        }
+        else if (githubRateLimits.status === 'limited') {
+            overallStatus = 'limited';
+            researchRecommendations.push('⚠️ Limited API quota - reduce research scope');
+            researchRecommendations.push('Use targeted searches instead of broad exploration');
+        }
+        else {
+            overallStatus = 'ready';
+            researchRecommendations.push('✅ All systems ready for comprehensive research');
+            researchRecommendations.push('NPM package discovery and GitHub analysis available');
+        }
+        // Add research strategy recommendations based on API limits
+        if (githubRateLimits.code_search.remaining < 5) {
+            researchRecommendations.push('🔍 Code search critical - use repository browsing instead');
+        }
+        if (githubRateLimits.search_api.remaining < 20) {
+            researchRecommendations.push('🔎 Search API limited - focus on specific repositories');
+        }
+        if (githubRateLimits.primary_api.remaining < 200) {
+            researchRecommendations.push('🏠 Core API limited - minimize repository exploration');
+        }
+        const result = {
+            github_auth: githubAuth,
+            npm_connectivity: npmConnectivity,
+            github_rate_limits: githubRateLimits,
+            overall_status: overallStatus,
+            research_recommendations: researchRecommendations,
+            timestamp: new Date().toISOString(),
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `🚨 API Status Check Failed: ${error.message}
+
+🔧 Troubleshooting Steps:
+1. Check GitHub CLI installation: gh --version
+2. Check NPM installation: npm --version  
+3. Check network connectivity
+4. Try: gh auth login
+5. Try: npm ping
+
+💡 Manual Verification:
+- GitHub Auth: gh auth status
+- NPM Registry: npm ping
+- GitHub API: gh api rate_limit`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+function registerApiStatusCheckTool(server) {
+    server.tool(TOOL_NAMES.API_STATUS_CHECK, TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK], {
+    // No parameters needed for status check
+    }, {
+        title: 'API Status Check',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async () => {
+        return await performApiStatusCheck();
+    });
+}
+
+async function npmGetRepository(packageName) {
+    const cacheKey = generateCacheKey('npm-get-repository', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only repository-related data
+            const repositoryResult = {
+                packageName: npmData.name,
+                description: npmData.description,
+                repository: npmData.repository,
+                homepage: npmData.homepage,
+            };
+            return createSuccessResult$1(repositoryResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm repository information', error);
+        }
+    });
+}
+
+function registerNpmGetRepositoryTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_REPOSITORY, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_REPOSITORY], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get repository information for (e.g., 'react', 'express', 'lodash'). Returns minimal repository data: package name, description, repository URL, and homepage - optimized for token efficiency."),
+    }, {
+        title: 'NPM Repository Discovery - Extract GitHub Repository URL',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetRepository(args.packageName);
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            // Enhanced error handling for package not found
+            if (errorMessage.includes('404') ||
+                errorMessage.includes('not found')) {
+                return generateSmartRecovery({
+                    tool: 'NPM Get Repository',
+                    packageName: args.packageName,
+                    error: error,
+                });
+            }
+            // Generic enhanced error handling
+            return generateSmartRecovery({
+                tool: 'NPM Get Repository',
+                packageName: args.packageName,
+                error: error,
+            });
+        }
+    });
+}
+
+async function npmGetDependencies(packageName) {
+    const cacheKey = generateCacheKey('npm-get-dependencies', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only dependencies data
+            const dependenciesResult = {
+                packageName: npmData.name,
+                dependencies: npmData.dependencies || {},
+                devDependencies: npmData.devDependencies || {},
+                resolutions: npmData.resolutions || {},
+            };
+            return createSuccessResult$1(dependenciesResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm dependencies information', error);
+        }
+    });
+}
+
+function registerNpmGetDependenciesTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_DEPENDENCIES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_DEPENDENCIES], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to analyze dependencies for (e.g., 'react', 'express', 'lodash'). Returns focused dependency data: dependencies, devDependencies, and resolutions - optimized for token efficiency."),
+    }, {
+        title: 'NPM Dependency Analysis - Extract Package Dependencies',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetDependencies(args.packageName);
+        }
+        catch (error) {
+            return generateSmartRecovery({
+                tool: 'NPM Get Dependencies',
+                packageName: args.packageName,
+                error: error,
+            });
+        }
+    });
+}
+
+async function npmGetBugs(packageName) {
+    const cacheKey = generateCacheKey('npm-get-bugs', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only bugs data
+            const bugsResult = {
+                packageName: npmData.name,
+                bugs: npmData.bugs,
+            };
+            return createSuccessResult$1(bugsResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm bugs information', error);
+        }
+    });
+}
+
+function registerNpmGetBugsTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_BUGS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_BUGS], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get bug tracking information for (e.g., 'react', 'express', 'lodash'). Returns minimal bug data: package name and bugs URL - optimized for token efficiency."),
+    }, {
+        title: 'NPM Bug Tracking - Extract Issue Tracker URL',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetBugs(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm bugs info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetReadme(packageName) {
+    const cacheKey = generateCacheKey('npm-get-readme', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only readme data
+            const readmeResult = {
+                packageName: npmData.name,
+                readmeFilename: npmData.readmeFilename,
+            };
+            return createSuccessResult$1(readmeResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm readme information', error);
+        }
+    });
+}
+
+function registerNpmGetReadmeTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_README, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_README], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get README information for (e.g., 'react', 'express', 'lodash'). Returns minimal README data: package name and readme filename - optimized for token efficiency."),
+    }, {
+        title: 'NPM Documentation Access - Extract README Filename',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetReadme(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm readme info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetVersions(packageName) {
+    const cacheKey = generateCacheKey('npm-get-versions', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Filter versions to include only official semantic versions (major.minor.patch)
+            // Excludes pre-release versions like alpha, beta, rc, dev, experimental, etc.
+            const semanticVersionRegex = /^\d+\.\d+\.\d+$/;
+            const officialVersions = npmData.versions.filter(version => semanticVersionRegex.test(version));
+            // Extract only versions data with filtered official versions
+            const versionsResult = {
+                packageName: npmData.name,
+                versions: officialVersions,
+                latestVersion: npmData['dist-tags'].latest,
+                versionCount: officialVersions.length,
+            };
+            return createSuccessResult$1(versionsResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm versions information', error);
+        }
+    });
+}
+
+function registerNpmGetVersionsTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_VERSIONS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_VERSIONS], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get version information for (e.g., 'react', 'express', 'lodash'). Returns only official semantic versions (major.minor.patch format), excluding pre-release versions like alpha, beta, rc - optimized for production planning."),
+    }, {
+        title: 'NPM Version Tracking - Extract Package Versions',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetVersions(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm versions: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetAuthor(packageName) {
+    const cacheKey = generateCacheKey('npm-get-author', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only author data
+            const authorResult = {
+                packageName: npmData.name,
+                author: npmData.author,
+                maintainers: npmData.maintainers,
+            };
+            return createSuccessResult$1(authorResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm author information', error);
+        }
+    });
+}
+
+function registerNpmGetAuthorTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_AUTHOR, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_AUTHOR], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get author information for (e.g., 'react', 'express', 'lodash'). Returns focused author data: author and maintainers list - optimized for token efficiency."),
+    }, {
+        title: 'NPM Maintainer Information - Extract Author and Maintainers',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetAuthor(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm author info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetLicense(packageName) {
+    const cacheKey = generateCacheKey('npm-get-license', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only license data
+            const licenseResult = {
+                packageName: npmData.name,
+                license: npmData.license,
+            };
+            return createSuccessResult$1(licenseResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm license information', error);
+        }
+    });
+}
+
+function registerNpmGetLicenseTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_LICENSE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_LICENSE], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get license information for (e.g., 'react', 'express', 'lodash'). Returns minimal license data: package name and license - optimized for token efficiency."),
+    }, {
+        title: 'NPM License Compliance - Extract Package License',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetLicense(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm license info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetHomepage(packageName) {
+    const cacheKey = generateCacheKey('npm-get-homepage', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only homepage data
+            const homepageResult = {
+                packageName: npmData.name,
+                homepage: npmData.homepage,
+            };
+            return createSuccessResult$1(homepageResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm homepage information', error);
+        }
+    });
+}
+
+function registerNpmGetHomepageTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_HOMEPAGE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_HOMEPAGE], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get homepage information for (e.g., 'react', 'express', 'lodash'). Returns direct access to official documentation, interactive examples, and comprehensive project resources - optimized for token efficiency."),
+    }, {
+        title: 'NPM Homepage Discovery - Extract Project Website URL',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetHomepage(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm homepage info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetId(packageName) {
+    const cacheKey = generateCacheKey('npm-get-id', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only _id data (name@latestVersion format)
+            const idResult = {
+                packageName: npmData.name,
+                id: npmData._id,
+            };
+            return createSuccessResult$1(idResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm ID information', error);
+        }
+    });
+}
+
+function registerNpmGetIdTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_ID, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_ID], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get ID information for (e.g., 'react', 'express', 'lodash'). Returns precise version identifier for dependency management, lockfiles, and reproducible builds - optimized for token efficiency."),
+    }, {
+        title: 'NPM Package Identification - Extract Name@Version ID',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetId(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm ID info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetReleases(packageName) {
+    const cacheKey = generateCacheKey('npm-get-releases', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only version entries (exclude 'created' and 'modified')
+            const versionEntries = Object.entries(npmData.time).filter(([key]) => key !== 'created' && key !== 'modified');
+            // Sort by release date (most recent first) and take last 10
+            const sortedVersions = versionEntries
+                .sort(([, dateA], [, dateB]) => new Date(dateB).getTime() - new Date(dateA).getTime())
+                .slice(0, 10)
+                .map(([version, releaseDate]) => ({ version, releaseDate }));
+            // Create efficient result with only requested data
+            const timeResult = {
+                packageName: npmData.name,
+                lastModified: npmData.time.modified,
+                created: npmData.time.created,
+                versionCount: versionEntries.length,
+                last10Releases: sortedVersions,
+            };
+            return createSuccessResult$1(timeResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm time information', error);
+        }
+    });
+}
+
+function registerNpmGetReleasesTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_RELEASES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_RELEASES], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get release information for (e.g., 'react', 'express', 'lodash'). Returns focused release data: last modified, created date, version count, and last 10 releases - optimized for token efficiency."),
+    }, {
+        title: 'NPM Package Releases - Extract Recent Release Data',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetReleases(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm release info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetEngines(packageName) {
+    const cacheKey = generateCacheKey('npm-get-engines', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only engines data
+            const enginesResult = {
+                packageName: npmData.name,
+                engines: npmData.engines || {},
+            };
+            return createSuccessResult$1(enginesResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm engines information', error);
+        }
+    });
+}
+
+function registerNpmGetEnginesTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_ENGINES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_ENGINES], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get engines information for (e.g., 'react', 'express', 'lodash'). Returns environment compatibility requirements to prevent deployment failures and runtime conflicts - optimized for token efficiency."),
+    }, {
+        title: 'NPM Runtime Compatibility - Extract Engine Requirements',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetEngines(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm engines info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetExports(packageName) {
+    const cacheKey = generateCacheKey('npm-get-exports', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
             }
-            let rateLimit;
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only exports data
+            const exportsResult = {
+                packageName: npmData.name,
+                exports: npmData.exports || {},
+            };
+            return createSuccessResult$1(exportsResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm exports information', error);
+        }
+    });
+}
+
+function registerNpmGetExportsTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_EXPORTS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_EXPORTS], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get exports information for (e.g., 'react', 'express', 'lodash'). Returns import path intelligence: available modules, entry points, and tree-shakable exports for optimal code search - optimized for token efficiency."),
+    }, {
+        title: 'NPM Module Structure - Extract Package Export Mappings',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetExports(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm exports info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+function registerUsageGuideResource(server) {
+    server.resource('usage-guide', 'help://usage', async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: `# Octocode MCP Quick Start
+
+## Setup (Required)
+\`\`\`bash
+gh auth login  # GitHub CLI authentication
+\`\`\`
+
+## MANDATORY SEARCH STRATEGY
+1. **ALWAYS START**: \`search_github_topics\` - **NEVER SKIP** - Maps ecosystem terminology
+2. **PRIMARY DISCOVERY**: \`npm_search\` and \`npm_view\` - Minimizes GitHub API calls
+3. **TARGETED EXTRACTION**: \`search_github_code\` with owner/repo from NPM
+4. **LAST RESORT**: \`search_github_repos\` - Single terms only when NPM insufficient
+
+## Core Workflow
+1. **Check Auth**: Read \`github://auth-status\` and \`github://rate-limits\`
+2. **MANDATORY**: \`search_github_topics\` for ecosystem mapping
+3. **NPM Discovery**: \`npm_search\` → \`npm_view\` → extract repository URLs
+4. **Extract**: Get complete implementations from discovered repositories
+5. **Validate**: Cross-reference multiple NPM packages
+
+## Essential Tools (Priority Order)
+- **\`search_github_topics\`**: **MANDATORY FIRST STEP** - Find technology ecosystems
+- **\`npm_search\`**: **PRIMARY DISCOVERY** - Find packages by functionality
+- **\`npm_view\`**: **PRIMARY DISCOVERY** - Package metadata and repo links
+- **\`view_repository\`**: Get branch info (required before file operations!)
+- **\`search_github_code\`**: Find specific implementations in discovered repos
+- **\`fetch_github_file_content\`**: Extract complete code
+- **\`search_github_repos\`**: **LAST RESORT ONLY** - Single terms when NPM fails
+
+## Search Strategy Rules
+- **Topics First**: Every workflow starts with \`search_github_topics\`
+- **NPM Primary**: Use NPM tools before GitHub repo search
+- **Single Terms Only**: NEVER multi-term searches in \`search_github_repos\`
+- **API Conservation**: NPM discovery reduces GitHub API usage by 60%
+
+## Search Term Strategy
+- **✅ GOOD**: "react", "authentication", "typescript", "deployment"
+- **❌ BAD**: "react hooks", "full-stack app", "react angular auth"
+- **Decompose**: "react typescript auth" → ["react", "typescript", "authentication"]
+
+## Quick Examples
+- **Package research**: \`search_github_topics\` → \`npm_search\` → \`npm_view\` → \`view_repository\` → \`search_github_code\`
+- **Problem solving**: \`search_github_topics\` → \`npm_search\` → \`search_github_issues\` → \`search_github_code\`
+- **Technology discovery**: \`search_github_topics\` → \`npm_search\` → \`npm_view\` → \`view_repository\` → \`fetch_github_file_content\`
+
+## CRITICAL REMINDERS
+- **NEVER skip** \`search_github_topics\` - provides essential context
+- **NPM FIRST** - use NPM tools before GitHub repo search
+- **SINGLE TERMS** - never combine multiple concepts in repo searches
+- **REPOS LAST** - \`search_github_repos\` is lowest priority discovery tool
+
+Generated: ${new Date().toISOString()}`,
+            },
+        ],
+    }));
+}
+
+// GitHub Authentication Status Resource
+function registerGithubStatusResource(server) {
+    server.resource('github-auth-status', 'github://auth-status', async (uri) => {
+        try {
+            // For version, we'll use a workaround since --version is not a command
+            // We can use 'help' command which shows version info, or skip detailed version check
+            const ghVersion = 'Available (GitHub CLI detected)';
+            let isAuthenticated = false;
+            let authError = null;
             try {
-                const parsed = JSON.parse(content);
-                rateLimit = parsed.result || parsed;
+                // Check auth status using safe command
+                const authResult = await executeGitHubCommand('auth', ['status'], {
+                    timeout: 5000,
+                    cache: false,
+                });
+                if (!authResult.isError) {
+                    const content = String(authResult.content[0]?.text || '');
+                    if (content) {
+                        try {
+                            const parsed = JSON.parse(content);
+                            const output = parsed.result || content;
+                            // Only check if authenticated, don't expose user details
+                            isAuthenticated =
+                                String(output).includes('✓ Logged in') ||
+                                    String(output).includes('Logged in');
+                        }
+                        catch {
+                            isAuthenticated =
+                                content.includes('✓ Logged in') ||
+                                    content.includes('Logged in');
+                        }
+                    }
+                }
+                else {
+                    // auth status command failed, check error content for auth info
+                    const errorContent = String(authResult.content[0]?.text || 'Authentication check failed');
+                    if (errorContent.includes('✓ Logged in') ||
+                        errorContent.includes('Logged in')) {
+                        isAuthenticated = true;
+                    }
+                    else {
+                        authError = 'Not authenticated';
+                    }
+                }
             }
-            catch {
-                rateLimit = JSON.parse(content);
+            catch (error) {
+                authError = 'Unable to check authentication status';
             }
-            const rateLimitInfo = processRateLimit(rateLimit);
             return {
                 contents: [
                     {
                         uri: uri.href,
                         mimeType: 'application/json',
                         text: JSON.stringify({
-                            status: 'GitHub API Rate Limits - LIVE STATUS',
-                            description: 'Real-time GitHub API rate limit status for all endpoints',
-                            rate_limits: rateLimitInfo,
-                            usage_notes: {
-                                primary_api: 'Used for most GitHub operations (repos, issues, PRs, etc.)',
-                                search_api: 'Used for searching repositories, code, issues, users',
-                                code_search: 'Dedicated endpoint for code search operations (most restrictive)',
-                                graphql_api: 'Used for GraphQL queries',
-                                status_meanings: {
-                                    healthy: 'All APIs have sufficient remaining requests',
-                                    limited: 'Some APIs are running low on requests (< 10 remaining)',
-                                    exhausted: 'One or more APIs have no remaining requests',
-                                },
-                            },
-                            recommendations: {
-                                healthy: 'All APIs ready for use',
-                                limited: 'Consider prioritizing essential requests only',
-                                exhausted: 'Wait until reset time or use alternative approaches',
+                            status: 'GitHub Authentication Status - LIVE STATUS',
+                            description: 'GitHub CLI authentication status and version information',
+                            gh_version: ghVersion,
+                            authenticated: isAuthenticated,
+                            auth_error: authError,
+                            setup_instructions: {
+                                not_authenticated: [
+                                    'Run: gh auth login',
+                                    'Follow the interactive prompts to authenticate',
+                                    'Choose your preferred authentication method',
+                                ],
+                                verification: [
+                                    'Run: gh auth status',
+                                    'Should show "✓ Logged in" if successful',
+                                ],
                             },
                             timestamp: new Date().toISOString(),
                         }, null, 2),
@@ -3096,9 +5862,9 @@ function registerGithubRateLimitResource(server) {
                         uri: uri.href,
                         mimeType: 'application/json',
                         text: JSON.stringify({
-                            status: 'GitHub API Rate Limits - ERROR',
+                            status: 'GitHub Authentication Status - ERROR',
                             error: error.message,
-                            message: 'Unable to check rate limits - authentication may be required',
+                            message: 'GitHub CLI may not be installed or accessible',
                             timestamp: new Date().toISOString(),
                         }, null, 2),
                     },
@@ -3107,56 +5873,6 @@ function registerGithubRateLimitResource(server) {
         }
     });
 }
-function processRateLimit(rateLimit) {
-    const formatResetTime = (reset) => new Date(reset * 1000).toISOString();
-    const calculateUsage = (used, limit) => Math.round((used / limit) * 100);
-    const core = rateLimit.resources.core;
-    const search = rateLimit.resources.search;
-    const codeSearch = rateLimit.resources.code_search;
-    const graphql = rateLimit.resources.graphql;
-    // Determine overall status based on most restrictive API
-    const minRemaining = Math.min(core.remaining, search.remaining, codeSearch.remaining, graphql.remaining);
-    let status;
-    if (minRemaining === 0) {
-        status = 'exhausted';
-    }
-    else if (minRemaining < 10) {
-        status = 'limited';
-    }
-    else {
-        status = 'healthy';
-    }
-    // Find the earliest reset time
-    const nextReset = Math.min(core.reset, search.reset, codeSearch.reset, graphql.reset);
-    return {
-        primary_api: {
-            remaining: core.remaining,
-            limit: core.limit,
-            reset_time: formatResetTime(core.reset),
-            usage_percentage: calculateUsage(core.used, core.limit),
-        },
-        search_api: {
-            remaining: search.remaining,
-            limit: search.limit,
-            reset_time: formatResetTime(search.reset),
-            usage_percentage: calculateUsage(search.used, search.limit),
-        },
-        code_search: {
-            remaining: codeSearch.remaining,
-            limit: codeSearch.limit,
-            reset_time: formatResetTime(codeSearch.reset),
-            usage_percentage: calculateUsage(codeSearch.used, codeSearch.limit),
-        },
-        graphql_api: {
-            remaining: graphql.remaining,
-            limit: graphql.limit,
-            reset_time: formatResetTime(graphql.reset),
-            usage_percentage: calculateUsage(graphql.used, graphql.limit),
-        },
-        status,
-        next_reset: formatResetTime(nextReset),
-    };
-}
 
 // Sanitize output to remove potential tokens
 function sanitizeOutput(output) {
@@ -3598,10 +6314,12 @@ process.stdin.on('close', async () => {
 });
 // Register all tools
 function registerAllTools(server) {
+    // System & API Status - CRITICAL FIRST STEP
+    registerApiStatusCheckTool(server);
     registerGitHubSearchCodeTool(server);
     registerFetchGitHubFileContentTool(server);
     registerViewRepositoryTool(server);
-    registerNpmViewTool(server);
+    //Tools.registerNpmViewTool(server);
     registerSearchGitHubReposTool(server);
     registerSearchGitHubCommitsTool(server);
     registerSearchGitHubPullRequestsTool(server);
@@ -3609,18 +6327,27 @@ function registerAllTools(server) {
     registerNpmSearchTool(server);
     registerViewRepositoryStructureTool(server);
     registerSearchGitHubIssuesTool(server);
-    // TODO: add discussions tool after fixing API
-    //Tools.registerSearchGitHubDiscussionsTool(server);
     registerSearchGitHubTopicsTool(server);
     registerSearchGitHubUsersTool(server);
-    registerNpmPackageStatsTool(server);
+    // Focused NPM tools for minimal token usage
     registerNpmDependencyAnalysisTool(server);
+    registerNpmGetRepositoryTool(server);
+    registerNpmGetDependenciesTool(server);
+    registerNpmGetBugsTool(server);
+    registerNpmGetReadmeTool(server);
+    registerNpmGetVersionsTool(server);
+    registerNpmGetAuthorTool(server);
+    registerNpmGetLicenseTool(server);
+    registerNpmGetHomepageTool(server);
+    registerNpmGetIdTool(server);
+    registerNpmGetReleasesTool(server);
+    registerNpmGetEnginesTool(server);
+    registerNpmGetExportsTool(server);
 }
 // Register all resources
 function registerResources(server) {
     registerUsageGuideResource(server);
     registerGithubStatusResource(server);
-    registerGithubRateLimitResource(server);
     registerNpmStatusResource(server);
     registerRepositoryIntelligenceResource(server);
 }