octocode-mcp 2.3.0 → 2.3.1

package/README.md

@@ -1,6 +1,6 @@
 # Octocode MCP
 
-**AI-Powered GitHub Research Assistant for Code Discovery**
+**The Perfect AI Code Assistant - Advanced Search & Discovery Across GitHub & NPM**
 
 <div>
   <img src="./assets/logo.png">
@@ -10,590 +10,208 @@
   [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
 </div>
 
-## 📋 Table of Contents
-
-- [✨ Overview](#-overview)
-  - [A New Take on Code Discovery MCP](#a-new-take-on-code-discovery-mcp)
-  - [🧠 AI-First Architecture](#-ai-first-architecture)
-  - [🔄 Intelligent Tool Chaining](#-intelligent-tool-chaining)
-  - [🎯 Smart Discovery Features](#-smart-discovery-features)
-- [💡 Background & Motivation](#-background--motivation)
-  - [🔄 A Tool That Built Itself](#-a-tool-that-built-itself)
-  - [🎯 Innovation: NPM-Driven Repository Discovery](#-innovation-npm-driven-repository-discovery)
-- [🌟 Example Use Cases](#-example-use-cases)
-- [🎯 Features](#-features)
-  - [For Developers](#for-developers)
-  - [For Engineering Managers](#for-engineering-managers)
-- [🛠 Available Tools](#-available-tools)
-  - [🔍 GitHub Code & Repository Search](#-github-code--repository-search)
-  - [📦 NPM & Package Ecosystem](#-npm--package-ecosystem)
-  - [📋 Development History & Collaboration](#-development-history--collaboration)
-  - [👥 User & Organization Management](#-user--organization-management)
-  - [🎯 Smart Features](#-smart-features)
-- [📚 Usage Examples](#-usage-examples)
-  - [Basic Code Discovery](#basic-code-discovery)
-  - [Advanced Research](#advanced-research)
-  - [Learning & Documentation](#learning--documentation)
-  - [Historical Analysis](#historical-analysis)
-  - [Code Review & Improvement](#code-review--improvement)
-- [💡 Tips for Effective Usage](#-tips-for-effective-usage)
-  - [🎯 Search Strategy Tips](#-search-strategy-tips)
-  - [📚 Documentation & Knowledge Management](#-documentation--knowledge-management)
-  - [⚡ Performance & Limitations](#-performance--limitations)
-  - [🔗 Cross-Repository Analysis](#-cross-repository-analysis)
-  - [🎨 Advanced Use Cases](#-advanced-use-cases)
-  - [🚀 Pro Tips](#-pro-tips)
-- [🛠 Installation & Setup](#-installation--setup)
-  - [🚀 Works Out Of The Box (OOTB) - Any Environment!](#-works-out-of-the-box-ootb---any-environment)
-  - [Step 1: Install Prerequisites](#step-1-install-prerequisites)
-  - [Step 2: Authentication Setup](#step-2-authentication-setup)
-  - [Step 3: MCP Configuration](#step-3-mcp-configuration)
-  - [🎉 That's It! Ready To Use](#-thats-it-ready-to-use)
-  - [🌟 Alternative Installation Options](#-alternative-installation-options)
-- [🔒 Privacy & Local Operation](#-privacy--local-operation)
-- [🔒 Why Different Than Static PAT](#-why-different-than-static-pat)
-- [License](#license)
-- [⚙️ Advanced Configuration](#️-advanced-configuration)
-  - [Rate Limiting & Performance](#rate-limiting--performance)
-  - [Authentication Management](#authentication-management)
-  - [NPM Configuration](#npm-configuration)
-- [🎯 Best Practices](#-best-practices)
-  - [Search Strategy](#search-strategy)
-  - [Performance Optimization](#performance-optimization)
-  - [Tool Chaining Best Practices](#tool-chaining-best-practices)
-- [🐛 Troubleshooting](#-troubleshooting)
-  - [Authentication Issues](#authentication-issues)
-  - [Common Issues](#common-issues)
-  - [NPM Configuration Issues](#npm-configuration-issues)
-  - [Misconfigured .npmrc File](#misconfigured-npmrc-file)
-  - [Development Setup](#development-setup)
-- [Disclaimer](#disclaimer)
-
-## ✨ Overview
-
-### A New Take on Code Discovery MCP
-
-**Differences Between Traditional GitHub MCPs and Octocode MCP:**
-- **Octocode MCP** = AI-Powered Research Assistant for Code Discovery
-- **Traditional GitHub MCPs** = Traditional API Wrapper for CRUD Operations
-
-### 🧠 **AI-First Architecture**
-- **Chain-of-Thought Reasoning Framework**: 6-step reasoning methodology built into prompts
-- **Teaching Methodology Integration**: AI education built into tool descriptions  
-- **Context-aware Search Optimization**: Quality validation pipelines for code discovery
-- **Automatic Query Optimization**: Single-word prioritization strategy ("RAG" -> "Ranking" not "RAG Ranking")
-
-### 🔄 **Intelligent Tool Chaining**
-- **Automatic Organization Detection**: Smart tool chaining based on context
-- **Package-to-Repository Mapping**: NPM mentions trigger automatic repository discovery
-- **Cross-validation Workflows**: Multi-step research flows with tool interconnection
-- **Progressive Search Refinement**: Phase-based search refinement (Broad -> Pattern -> Precise)
-
-### 🎯 **Smart Discovery Features**
-- **Semantic Landscape Mapping**: `search_github_topics` for ecosystem understanding
-- **Community Knowledge Discovery**: `search_github_discussions` for Q&A and tutorials
-- **Evolution Tracking**: `search_github_commits` for code history analysis
-- **Private Repository Discovery**: `get_user_organizations` for enterprise access
-- **Package Ecosystem Discovery**: `npm_search` and `npm_view` integration
-
-## 💡 Background & Motivation
-
-
-This project was born from a personal need while working at **Wix** - navigating and understanding large-scale repositories and codebases became increasingly challenging as projects grew in complexity. Traditional GitHub search and documentation often fell short when trying to:
-
-- **Understand architectural decisions** across multiple repositories
-- **Find real implementation examples** rather than just documentation
-- **Track the evolution** of complex features and systems
-- **Discover internal patterns** and best practices across teams
-
-Beyond repository navigation, this tool has become essential for **keeping pace with the vast landscape of technology changes**. In today's rapidly evolving development ecosystem, staying current with new frameworks, libraries, and patterns is crucial for maintaining high development velocity.
-
-What started as a side project to solve my own daily challenges evolved into a comprehensive AI-powered research assistant. The goal was simple: **make repository exploration and code discovery as intelligent and intuitive as having a senior developer guide you through any codebase.**
-
-### 🔄 A Tool That Built Itself
-
-In a fascinating turn of meta-development, **Octocode MCP actually helped create itself**. During development, I used the tool to:
-
-- **Understand MCP APIs correctly** by analyzing existing MCP implementations and documentation
-- **Compare features with other MCPs** to identify gaps and opportunities  
-- **Research best practices** from successful GitHub integrations
-- **Study code patterns** from high-quality open source projects
-
-This self-referential development process validated the tool's core value proposition: **enabling developers to learn from and build upon the collective intelligence of the entire GitHub ecosystem.**
-
-### 🎯 Innovation: NPM-Driven Repository Discovery
-
-One approach that emerged from my own search challenges: **using the NPM registry as a quality filter for repository discovery**. When searching through the vast GitHub landscape, finding high-quality, production-ready code was challenging.
-
-The approach:
-- **NPM as Quality Signal**: Published packages indicate battle-tested, production-ready code
-- **Package-to-Repository Mapping**: Automatically link NPM packages to their GitHub repositories
-- **Quality Amplification**: Focus on repositories that maintain published packages, ensuring real-world usage
-- **Ecosystem Context**: Understand dependencies and relationships through package management
-
-This methodology improved search result quality by leveraging the NPM ecosystem's inherent curation - if someone published it as a package, it's likely production-ready and well-maintained.
-
-*Note: This is a personal side project and not an official Wix product.*
-
-## 🌟 Example Use Cases
-
-**AI agents can now ask questions like:**
-
-- *"Show the langchain code examples from my organization"*
-- *"From code and PRs, how did React implement concurrent rendering?"*
-- *"Show examples of usage of this API: `import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';` Look at my code and suggest how I can improve it"*
-- *"Best ways from code examples to use routing in Next.js"*
-- *"Make docs of lodash"*
-- *"Show progress of React project in the recent 5 years"*
-- *"How is Vue rendering architecture different than React? Check from code"*
-- *"Create development docs and guides about how wix ai gateway works"*
-- *"How does SOME_REPOSITORY work?"*
-- *"Summarise the main PRs on project X"*
-- *"How do Vue and React render components? Which approach is more optimized?"*
-
-## 🎯 Features
-
-### For Developers
-- **🔍 Intelligent Code Discovery**: Find implementations, patterns, and examples with AI-guided search
-- **🔗 Cross-Repository Investigation**: Trace code patterns, dependencies, and implementations across multiple repositories
-- **🏢 Cross-Organization Dependencies**: Understand dependencies and relationships across different organizations and teams
-- **📚 Library & API Understanding**: Deep dive into libraries and APIs with examples from both internal and external repositories
-- **🔎 Specific Code Usage Search**: Find exact code patterns, function implementations, and usage examples
-- **🏷️ Topic Understanding**: Explore and understand technology topics, trends, and ecosystems
-- **🏗️ Big Project Analysis**: Comprehensive analysis of large-scale projects and their architecture
-  - *"Create development docs and guides about how wix ai gateway works"*
-  - *"How does SOME_REPOSITORY work?"*
-- **📈 Project Progress Analysis**: Track and summarize project evolution and key changes
-  - *"Summarise the main PRs on project X"*
-- **🔬 Cross-Repository Analysis**: Compare approaches and implementations across different projects
-  - *"How do Vue and React render components? Which approach is more optimized?"*
-- **📦 Smart Dependency Analysis**: Understand package relationships and find alternative libraries with automatic NPM integration
-- **🐛 Advanced Bug Investigation**: Track issues, commits, and pull requests with multi-repository correlation
-- **📚 Learning & Reference**: Access community discussions, documentation, and best practices with context-aware recommendations
-- **🏗️ Architecture Understanding**: Explore repository structures and analyze codebases with intelligent navigation
-- **📈 Historical Code Analysis**: Understand code evolution through commit history and PR reviews
-- **💡 Code Insights**: Extract insights from code patterns, repository structures, and development practices
-
-### For Engineering Managers
-- **📊 Repository Health Assessment**: Assess the current status and health of repositories with comprehensive metrics
-- **⚖️ Technology Assessment**: Evaluate libraries, frameworks, and tools adoption with trend analysis
-- **🤝 Cross-Team Collaboration Analysis**: Track contributions, knowledge sharing, and code reuse patterns
-- **💡 Knowledge Management**: Discover internal resources, documentation, and established patterns
-- **📈 Competitive Analysis**: Research similar projects and industry trends with automated discovery
-- **🛡️ Risk & Compliance Management**: Identify security vulnerabilities, licensing issues, and maintenance gaps
-- **📋 Strategic Planning**: Analyze technology trends, migration patterns, and adoption metrics
-
-## 🛠 Available Tools
-
-### 🔍 **GitHub Code & Repository Search**
-- **`search_github_code`**: Find specific implementations, functions, and patterns with semantic search
-- **`search_github_repos`**: Progressive repository discovery with intelligent filtering  
-- **`fetch_github_file_content`**: Extract complete working code with full context
-- **`view_repository_structure`**: Strategic repository exploration for code analysis
-- **`view_repository`**: Discover default branch information (mandatory first step)
-
-### 📦 **NPM & Package Ecosystem**
-- **`npm_view`**: Transform package names into GitHub repositories for code analysis
-- **`npm_search`**: Search NPM registry for packages by keywords with intelligent optimization
-- **Package-to-Repository Mapping**: Automatic linking from NPM packages to their GitHub repositories
-
-### 📋 **Development History & Collaboration**
-- **`search_github_commits`**: Advanced GitHub commits search for development history analysis
-- **`search_github_pull_requests`**: Code review and feature analysis with quality focus
-- **`search_github_issues`**: Problem discovery and solution research with pattern analysis
-- **`search_github_discussions`**: Community knowledge discovery for Q&A and tutorials
-
-### 👥 **User & Organization Management**
-- **`search_github_users`**: Advanced developer and organization discovery
-- **`get_user_organizations`**: Automatic private repository discovery for enterprise environments
-- **`search_github_topics`**: Vital foundation tool for effective GitHub discovery
-
-### 🎯 **Smart Features**
-- **Automatic Query Optimization**: Built-in search strategy optimization
-- **Chain-of-Thought Reasoning**: 6-step reasoning methodology for complex queries
-- **Teaching Methodology Integration**: AI education built into tool descriptions
-- **Progressive Search Refinement**: Phase-based search from broad to precise
-- **Cross-validation Workflows**: Multi-step research flows with tool interconnection
-
-## 📚 Usage Examples
-
-### Basic Code Discovery
-```bash
-# Find React hooks implementations
-"Show me examples of custom React hooks for data fetching"
-
-# Explore API patterns
-"How do popular libraries implement rate limiting? Show code examples"
-```
-
-### Advanced Research
-```bash
-# Deep architectural analysis
-"From code and PRs, how did React implement concurrent rendering?"
-
-# Cross-repository investigation
-"Show the langchain code examples from my organization"
-```
-
-### Learning & Documentation
-```bash
-# Best practices discovery
-"Best ways from code examples to use routing in Next.js"
-
-# Documentation generation
-"Make docs of lodash based on actual implementation"
-```
-
-### Historical Analysis
-```bash
-# Project evolution tracking
-"Show progress of React project in the recent 5 years"
-
-# Comparative analysis
-"How is Vue rendering architecture different than React? Check from code"
-```
-
-### Code Review & Improvement
-```bash
-# Code analysis and suggestions
-"Show examples of usage of this API: import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; Look at my code and suggest how I can improve it"
-```
-
-## 💡 Tips for Effective Usage
+## What is Octocode? 🐙
 
-### 🎯 **Search Strategy Tips**
-- **🔍 Be Specific**: Use specific library names, repository URLs, or exact function names for better results
-  - Good: *"Show me how the `useEffect` hook works in React"*
-  - Better: *"Show me `useEffect` cleanup patterns in facebook/react repository"*
+**The perfect code assistant that can help understand anything.** Octocode was built to understand connections between repositories and NPM packages under any privilege level you have. With **AI-powered advanced search**, heuristic discovery, and smart fallbacks, it makes GitHub's vast repository of knowledge truly searchable and analyzable.
 
-- **🎭 Deep Analysis Requires Multiple Prompts**: Most comprehensive analysis will require more than one prompt
-  - Start broad, then drill down into specific areas of interest
-  - Use follow-up questions to explore different aspects
+Instead of manually browsing repositories, you can ask questions like:
 
-### 📚 **Documentation & Knowledge Management**
-- **📝 Create Documentation**: Create documentation of topics important to you and reference it from Cursor or chat sessions
-  - *"Create a comprehensive guide about Next.js routing based on real examples"*
-  - Then use that documentation as reference for future development
+- *"How did React implement concurrent rendering?"*
+- *"Show me authentication patterns in Next.js applications"*
+- *"Find examples of how to use this specific API"*
+- *"What's the architecture of this library?"*
+- *"How do I use this MCP tool effectively?"*
 
-- **🔄 Iterative Learning**: Use the tool to build knowledge progressively
-  - Session 1: "What is server-side rendering?"
-  - Session 2: "Show me SSR implementations in Next.js"
-  - Session 3: "Compare SSR vs SSG in production applications"
+## Recommended Use Cases
 
-### ⚡ **Performance & Limitations**
-- **🚦 Rate Limiting Awareness**: GitHub has API rate limits for file fetching
-  - This tool has optimizations to manage rate limits efficiently
-  - **Not designed for bulk operations** like *"show all files in my org using XYZ"*
-  - Focus on targeted analysis rather than exhaustive scans
+**Use Octocode when you need to:**
 
-- **🎯 Quality Over Quantity**: Better to get precise, high-quality results than overwhelming amounts of data
-  - Use filters and specific queries to narrow down results
-  - Combine multiple focused searches rather than one broad search
+- **🔍 Understand implementations** - See how features work across different repositories
+- **📚 Find real code examples** - Discover patterns and best practices from production code  
+- **🏗️ Analyze architecture** - Explore how systems are designed and structured
+- **🔬 Research approaches** - Compare different implementation strategies
+- **💡 Learn from code** - Deep-dive into technical details and understand "how does this work?"
 
-### 🔗 **Cross-Repository Analysis**
-- **🏢 Organization Context**: Mention your organization or company for internal repository access
-  - *"Show authentication patterns used in our team's repositories"*
-  - The tool will automatically detect and use your organization access
+## Unique Value Proposition
 
-- **📦 Package-Based Discovery**: Mention specific packages to trigger automatic repository discovery
-  - *"How does the lodash library implement debouncing?"* -> Automatically finds and analyzes lodash repository
+**The most advanced AI-powered code assistant for understanding connections across the entire GitHub & NPM ecosystem.** While other GitHub MCPs focus on project management or basic operations, Octocode provides unparalleled depth for code discovery and technical research.
 
-### 🎨 **Advanced Use Cases**
-- **🔬 Comparative Analysis**: Compare different approaches across repositories
-  - *"How do GraphQL implementations differ between Apollo and Relay?"*
+**🚀 Out-of-the-Box Advanced Search (Powered by AI):**
+- **🧠 Heuristic Search** - Intelligent pattern recognition that finds relevant code even with vague queries
+- **🔄 Smart Fallbacks** - Automatic retry with alternative search strategies when initial searches fail
+- **🎯 Smart Discovery** - AI-guided exploration that uncovers hidden connections and patterns
+- **🔗 Connection Intelligence** - Understands relationships between repositories, packages, and dependencies
+- **📊 Multi-dimensional Analysis** - Combines code, commits, issues, discussions, and package data
 
-- **📈 Evolution Tracking**: Understand how projects evolved over time
-  - *"Show the major architectural changes in React over the past 2 years"*
+**Key Differentiators:**
+- **🧠 Advanced AI Search** - Heuristic algorithms that understand code context and connections
+- **🔐 Secure & Simple** - No personal access tokens needed, uses [GitHub CLI](https://cli.github.com/) authentication
+- **🔗 Connected Discovery** - Maps NPM packages to repositories, traces dependencies, finds related code
+- **🌐 Cross-Ecosystem Understanding** - Works across any privilege level you have (public, private, organization)
 
-- **🛠️ Implementation Patterns**: Find real-world usage patterns
-  - *"Show me production examples of microservices communication patterns"*
+It's the tool you reach for when you need to understand *"how does this work?"* rather than *"how do I manage this project?"*
 
-### 🚀 **Pro Tips**
-- **🔧 Combine Tools**: Use multiple MCP tools together for comprehensive analysis
-- **📊 Context Building**: Build context over multiple interactions for deeper insights
-- **🎯 Focus Areas**: Target specific areas of interest rather than general exploration
-- **📱 Real Examples**: Always ask for real code examples rather than theoretical explanations
+## Quick Start 🚀
 
-## 🛠 Installation & Setup
-
-### 🚀 **Works Out Of The Box (OOTB) - Any Environment!**
-
-**Octocode MCP works instantly on any environment** - no complex setup, no configuration files, no environment variables. Just install prerequisites and configure MCP client. **That's it!**
-
-### Step 1: Install Prerequisites
-
-#### Install Node.js (21+)
+### 1. Install Prerequisites
 ```bash
-# macOS with Homebrew
-brew install node
-
-# Or download from https://nodejs.org/
-# Verify installation
-node --version  # Should be 21+
-```
-
-#### Install GitHub CLI
-```bash
-# macOS
-brew install gh
-
-# Windows (with Chocolatey)
-choco install gh
+# Install Node.js 21+
+brew install node  # macOS
+# or download from https://nodejs.org/
 
-# Windows (with Scoop)
-scoop install gh
-
-# Linux (Debian/Ubuntu)
-sudo apt update && sudo apt install gh
-
-# Other platforms: https://github.com/cli/cli#installation
+# Install GitHub CLI
+brew install gh    # macOS
+# or see: https://github.com/cli/cli#installation
 ```
 
-#### Install NPM (usually comes with Node.js)
+### 2. Authenticate
 ```bash
-# Verify NPM installation
-npm --version
-```
-
-### Step 2: Authentication Setup
-
-#### GitHub CLI Authentication
-```bash
-# Login to GitHub (opens web browser)
+# Login to GitHub (opens browser)
 gh auth login
 
-# Select options:
-# 1. GitHub.com (for public repos) or GitHub Enterprise Server
-# 2. HTTPS (recommended)
-# 3. Login with a web browser (easier and more secure)
-
-# Verify authentication
-gh auth status
-# Should show: ✓ Logged in to github.com as [your-username]
-```
-
-#### NPM Authentication (for private packages)
-```bash
-# For npm registry
+# Login to NPM (for package research)
 npm login
-
-# For private registries, check your .npmrc
-npm config list
-npm whoami  # Verify authentication
 ```
 
-### Step 3: MCP Configuration
+**🔐 GitHub Authentication via CLI:**
+- ✅ **No personal access tokens needed** - Uses [GitHub CLI](https://cli.github.com/) behind the scenes
+- ✅ **Secure OAuth flow** - Browser-based authentication, no tokens to store
+- ✅ **Enterprise ready** - Works with SSO, 2FA, and organization access
+- ✅ **Private repository access** - Automatically detects your organizations and accesses private repos
+- ✅ **Zero configuration** - Uses your existing `gh` CLI permissions
 
-**This is the only configuration you need!** Add this to your MCP client configuration:
 
+### 3. Add to MCP Configuration
 ```json
 {
   "octocode-mcp": {
     "command": "npx",
-    "args": [
-      "octocode-mcp"
-    ]
+    "args": ["octocode-mcp"]
   }
 }
 ```
 
-### 🎉 **That's It! Ready To Use**
+**That's it!** No personal access tokens, no config files, no complex setup. Octocode leverages [GitHub CLI](https://cli.github.com/) authentication behind the scenes and **automatically works with your organization's private repositories**.
 
-**No installation needed** - `npx` will automatically download and run the latest version
-**No environment variables** - Uses your existing GitHub CLI authentication  
-**No configuration files** - Works with your current permissions
-**No tokens to manage** - Secure authentication handled automatically
-**Works everywhere** - Any OS, any environment, any setup
+## Example Questions 💬
 
-## 🔒 Privacy & Local Operation
+**Learning & Research:**
+- *"How do popular libraries implement rate limiting?"*
+- *"Show me Server Actions patterns in Next.js applications"*
+- *"What are the differences between Vue and React rendering?"*
 
-**🏠 100% Local Execution** - Octocode MCP runs entirely on your machine. No remote servers, no cloud processing, no data transmission to third parties.
+**Architecture & Patterns:**
+- *"How is authentication handled in enterprise applications?"*
+- *"Show me microservices communication patterns"*
+- *"Find examples of event-driven architecture implementations"*
 
-**🚫 Zero Data Collection** - We don't collect, store, or transmit any of your data, search queries, or repository information. Everything stays on your machine.
+**Organization & Private Repositories:**
+- *"Show me authentication patterns used in our team's repositories"*
+- *"Find internal libraries and how they're implemented in our org"*
+- *"Analyze our company's coding standards and patterns"*
 
-**🔑 Your Credentials, Your Control** - All API calls use your existing CLI configurations:
-- **GitHub**: Uses your `gh` CLI authentication and permissions
-- **NPM**: Uses your local `.npmrc` and `npm` CLI configuration
-- **No Token Sharing**: Your authentication tokens never leave your machine
+**Specific Code Analysis:**
+- *"How does lodash implement debouncing?"*
+- *"Show usage examples of this API: `createContext`"*
+- *"Find React hooks patterns for data fetching"*
 
-**🛡️ Privacy by Design** - The tool operates as a local proxy using your own credentials, ensuring you maintain full control over what repositories and data you can access based on your existing permissions.
+## Core Features 🛠️
 
-### Optional: Verify Setup
-```bash
-# Check all components
-node --version    # Should be 21+
-gh --version      # Should show version
-gh auth status    # Should show authenticated
-npm --version     # Should show version
-
-# Test NPX execution (optional)
-npx octocode-mcp --help
-```
+### 🧠 AI-Powered Advanced Search
+- **Heuristic Pattern Recognition** - Finds relevant code even with vague or incomplete queries
+- **Smart Fallback Strategies** - Automatically tries alternative approaches when searches fail
+- **Context-Aware Discovery** - Understands code relationships and suggests related implementations
+- **Multi-Strategy Search** - Combines semantic, syntactic, and dependency-based search methods
 
-### 🌟 **Alternative Installation Options**
+### 🔗 Connection Intelligence
+- **Repository-Package Mapping** - Automatically links NPM packages to their GitHub repositories
+- **Dependency Tracing** - Follows dependency chains across the entire ecosystem
+- **Cross-Reference Analysis** - Finds how different projects implement similar patterns
+- **Ecosystem Understanding** - Maps relationships between libraries, frameworks, and tools
 
-#### Option A: Global Installation (if you prefer)
-```bash
-# Install globally
-yarn global add octocode-mcp
-# or
-npm install -g octocode-mcp
+### 🌐 Universal Access & Discovery
+- **Cross-Privilege Search** - Works with any access level you have (public, private, organization)
+- **Organization-Aware** - Automatically detects and uses your GitHub organization memberships
+- **Smart Repository Discovery** - Finds relevant repositories even when you don't know they exist
+- **Progressive Refinement** - AI-guided search that gets more precise with each iteration
 
-# Then use this MCP configuration:
-{
-  "octocode-mcp": {
-    "command": "octocode-mcp"
-  }
-}
-```
+### 📊 Multi-Dimensional Analysis
+- **Code + Context** - Combines source code with commits, issues, discussions, and documentation
+- **Historical Understanding** - Tracks how implementations evolved over time
+- **Community Insights** - Discovers patterns from real-world usage and discussions
+- **Quality Signals** - Uses NPM publication and GitHub activity as quality indicators
 
-#### Option B: NPX (Recommended - Always Latest)
-```bash
-# No installation needed - NPX handles everything
-# Just use the MCP configuration above! ⬆️
-```
+## Privacy & Security 🛡️
 
-## 🔒 Why Different Than Static PAT
+- **🏠 100% Local** - Runs entirely on your machine
+- **🚫 Zero Data Collection** - No telemetry, logging, or data transmission
+- **🔑 No Token Management** - Uses [GitHub CLI](https://cli.github.com/) authentication, no personal access tokens needed
+- **🛡️ Privacy by Design** - All API calls use your existing `gh` CLI permissions directly
 
-### Traditional GitHub MCPs Challenges:
-❌ **Manual PAT Management**: Create, store, rotate personal access tokens manually  
-❌ **Security Risks**: Tokens in config files, potential exposure  
-❌ **Limited Scope**: Fixed permissions, hard to manage different access levels  
-❌ **Expiration Issues**: Tokens expire, breaking workflows  
-❌ **No SSO Integration**: Doesn't work with enterprise SSO/SAML  
+## Best Practices 💡
 
-### Octocode MCP Approach:
-✅ **Zero Configuration**: Uses existing GitHub CLI authentication  
-✅ **Automatic Security**: Leverages GitHub's secure OAuth flow  
-✅ **Dynamic Permissions**: Uses your actual GitHub permissions  
-✅ **SSO Compatible**: Works seamlessly with enterprise authentication  
-✅ **No Token Management**: GitHub CLI handles all authentication automatically  
-✅ **Better Security**: No tokens stored in files or transmitted  
+**AI-Powered Search Tips:**
+- **Let AI guide you** - Start with natural language questions, the heuristic search will find relevant code
+- **Trust the smart fallbacks** - If initial search doesn't work, AI automatically tries alternative strategies
+- **Explore connections** - Ask about relationships between packages, libraries, and implementations
+- **Use any privilege level** - Works seamlessly across public repos, private repos, and organization repositories
+- **Keep research along the MCP** - Build upon previous searches and maintain context across multiple queries for deeper exploration
 
-## License
-
-MIT License - See [LICENSE](./LICENSE.md) for details.
+**Effective Questions:**
+- **Vague is OK** - "How does authentication work?" → AI finds relevant patterns across repositories
+- **Ask for connections** - "What libraries use this pattern?" → Discovers related implementations
+- **Cross-ecosystem queries** - "NPM packages that implement X" → Links packages to their repositories
+- **Evolution questions** - "How has this approach changed?" → Traces implementation history
 
-## ⚙️ Advanced Configuration
+**Advanced Search Features:**
+- **Automatic fallbacks** - No need to retry failed searches, AI handles it automatically
+- **Smart discovery** - Finds repositories and packages you didn't know existed
+- **Connection mapping** - Understands relationships between different codebases
+- **Context preservation** - Maintains search context across multiple queries
 
-### Rate Limiting & Performance
-- **Built-in Rate Limiting**: Prevents API quota exhaustion with smart request management
-- **Intelligent Caching**: Result caching with configurable timeouts
-- **Progressive Search**: Adaptive search strategies from broad to specific
-- **Configurable Results**: Optimized result limits for different use cases
+## Troubleshooting 🔧
 
-### Authentication Management
-- **Seamless GitHub CLI Integration**: Zero-configuration authentication
-- **NPM Registry Support**: Private package access with existing credentials
-- **Organization-aware Access**: Automatic detection and private repository access
-- **Local Execution**: All operations run locally using your existing permissions
-
-### NPM Configuration
-```bash
-# Check your NPM configuration
-npm config list
-npm whoami  # Verify authentication for private registries
-
-# Configure for private registries if needed
-echo "@your-org:registry=https://npm.your-company.com/" >> ~/.npmrc
-```
-
-## 🎯 Best Practices
-
-### Search Strategy
-- **Start Broad**: Begin with general terms, then narrow down based on findings
-- **Use Progressive Discovery**: Combine multiple tools for comprehensive understanding
-- **Leverage Organizations**: Use your team's GitHub org for internal discovery
-- **Cross-Reference Sources**: Combine code, issues, and discussions for complete context
-
-### Performance Optimization
-- **Use Specific Repository Filters**: When you know the target repository
-- **Combine Related Searches**: In single sessions for efficiency
-- **Monitor API Rate Limits**: Built-in management prevents quota exhaustion
-- **Cache Frequently Accessed Information**: Automatic intelligent caching
-
-### Tool Chaining Best Practices
-- **Start with Topics**: Use `search_github_topics` for proper terminology discovery
-- **Repository Discovery**: Use discovered topic names in `search_github_repos`
-- **Organization Context**: Let automatic detection handle private repository access
-- **Package Research**: Mention packages to trigger automatic NPM-to-repository mapping
-
-## 🐛 Troubleshooting
-
-### Authentication Issues
+**Authentication Issues:**
 ```bash
 # Check GitHub CLI status
 gh auth status
-# Should show: ✓ Logged in to github.com as [username]
 
 # Re-authenticate if needed
-gh auth logout
-gh auth login
+gh auth logout && gh auth login
 
-# Check NPM authentication
+# Check NPM access
 npm whoami
 ```
 
-### Common Issues
-- **No Results Found**: Try broader search terms or check organization filters
-- **Rate Limiting**: Built-in management should prevent this, but reduce frequency if needed
-- **Private Repository Access**: Ensure proper organization membership via `gh auth status`
-- **NPX Cache Issues**: Clear cache with `rm -rf ~/.npm/_npx` (Unix) or delete via File Explorer (Windows)
-
-### NPM Configuration Issues
-```bash
-# View current configuration
-npm config list
-
-# Check for common issues:
-# - Registry URL correctness
-# - Authentication tokens validity
-# - Proxy settings (if behind firewall)
-# - Syntax errors in .npmrc
-
-# Reset NPM configuration if needed
-rm ~/.npmrc
-npm login
-```
-
-### Misconfigured .npmrc File
-1. **Locate .npmrc files**: Project-level (./), User-level (~/.npmrc), Global-level
-2. **Check for common issues**: Registry URL, auth tokens, proxy settings, syntax errors
-3. **View configuration**: `npm config list`
-4. **Test after changes**: `yarn install` or `npm install`
+**Common Solutions:**
+- No results? Try broader search terms
+- Private repos not found? Check organization membership with `gh auth status`
+- NPX issues? Clear cache: `rm -rf ~/.npm/_npx`
 
-### Development Setup
-```bash
-# Clone repository
-git clone https://github.com/your-org/octocode-mcp.git
-cd octocode-mcp
+**🏢 Organization & Private Repository Access:**
+- **Automatic detection** - Octocode automatically discovers your GitHub organizations
+- **No additional setup** - If you have access to private repos through your organization, they work immediately
+- **Verify access** - Run `gh auth status` to see your organization memberships
 
-# Install dependencies
-yarn install
+**Why GitHub CLI Authentication?**
+- ✅ **No token creation** - GitHub CLI handles OAuth flow automatically
+- ✅ **Enterprise compatible** - Works with SSO, SAML, and 2FA out of the box
+- ✅ **Organization auto-detection** - Automatically discovers your GitHub organizations and private repo access
+- ✅ **Works out of the box** - If you work for an organization, private repositories are immediately accessible
+- ❌ **vs Personal Access Tokens** - No manual creation, rotation, or security risks
 
-# Run development server
-yarn build
+## Background 💭
 
-// Configuration local MCP
-// "octocode-mcp-local": {
-//   "command": "node",
-//   "args": [
-//     "PATH_TO_OCTOCODE_MCP/octocode-mcp/dist/index.js"
-//   ]
-// }
+This project started as a personal tool while working at Wix, born from the challenge of navigating large codebases and keeping up with rapidly evolving technology landscapes. What began as a side project to solve daily development challenges evolved into **the perfect code assistant that can help understand anything**.
 
-```
+The goal was simple: **make code exploration as intelligent as having a senior developer guide you through any codebase.** Built specifically to understand connections between many repositories and NPM packages under any privilege the user has, with AI-powered heuristic search, smart fallbacks, and intelligent discovery.
 
-## Disclaimer
 
-**This is a personal side project** developed to solve real-world code discovery challenges. While functional and useful, please keep in mind:
+## License 📄
 
-- **🚧 Work in Progress**: Some improvements and optimizations are still needed
-- **🎯 Intentionally Lean**: Designed to be simple and lightweight - no unnecessary overhead or complexity
-- **🔬 Experimental**: As with any side project, expect occasional rough edges and areas for improvement
+MIT License - See [LICENSE](./LICENSE.md) for details.
 
 ---
 
 
 
-

package/build/index.js

@@ -22,33 +22,37 @@ const TOOL_NAMES = {
     NPM_PACKAGE_SEARCH: 'npm_package_search',
     NPM_VIEW_PACKAGE: 'npm_view_package',
 };
-const PROMPT_SYSTEM_PROMPT = `Smart code research assistant with semantic search capabilities.
+const PROMPT_SYSTEM_PROMPT = `You are a smart code research assistant with semantic search capabilities using gh and npm cli under the hood.
+You are able to search code, repositories, issues, pull requests, commits, and packages.
+Using Github: You are able to search code, repositories, issues, pull requests, commits
+Using NPM: You are able to search packages, view package metadata, and view package dependencies.
 
-APPROACH:
-- Start with ${TOOL_NAMES.API_STATUS_CHECK} to check authentication
-- Use ${TOOL_NAMES.GITHUB_SEARCH_REPOS} for smart repository and topic discovery
-- Run searches in parallel when possible for efficiency
-- Dive deeper with specific tools for detailed analysis
+- ALWAYS START with ${TOOL_NAMES.API_STATUS_CHECK} before evaluating any user query (check npm and GitHub authentication and use GitHub organizations)
+- Understand users query from semantic understanding and choose the right tools for the job.
 
-SEARCH STRATEGY:
-- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Smart semantic search combining repositories and topics
-- ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Find implementation patterns and examples  
+TOOLS SEARCH STRATEGY:
+- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - START SHALLOW & GO BROAD: Use topics for exploratory discovery, then narrow down
+- ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Find implementation patterns with SMART BOOLEAN OPERATORS (AND, OR, NOT)
 - ${TOOL_NAMES.NPM_PACKAGE_SEARCH} - Package ecosystem discovery
 - ${TOOL_NAMES.NPM_VIEW_PACKAGE} - Complete package analysis with exports for file discovery
 - ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} + ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Understanding development patterns
 - ${TOOL_NAMES.GITHUB_GET_CONTENTS} → ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT} - ALWAYS verify file existence before fetching
 
 BEST PRACTICES:
-- Use natural language queries - the tools are semantic and adaptive
-- Leverage quality filters like stars:>100 for established projects
-- Run parallel searches for comprehensive results
-- ALWAYS verify file existence with ${TOOL_NAMES.GITHUB_GET_CONTENTS} before using ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
-- Use ${TOOL_NAMES.NPM_VIEW_PACKAGE} exports field to discover available files in packages
-- Always check documentation and examples when available`;
+- Leverage smart boolean operators if possible in tools and advanced filters for smart research 
+- For repo discovery: START SHALLOW with topics, then go BROAD to explore ecosystems
+- For code search: Be focused and specific with boolean operators
+- Always check documentation and examples when available
+- Add referenced and high quality research data from docs and quality code
+- Be creative and smart and use tools efficiently to gather most data
+- If query is short (e.g. where is the git repo of X package) make simple query and use tools to gather data fast
+- For broad research make steps and think about the best way to gather data`;
 const TOOL_DESCRIPTIONS = {
-    [TOOL_NAMES.API_STATUS_CHECK]: `Check GitHub & NPM authentication status and discover user organizations.
-  Essential first step that enables access to private/organizational repositories by identifying available organizations for the 'owner' parameter in search tools.
-  Critical for enterprise code exploration and accessing company-specific repositories that require organizational membership.`,
+    [TOOL_NAMES.API_STATUS_CHECK]: `**MANDATORY FIRST STEP** - Check GitHub & NPM authentication status before any user query evaluation.
+  Returns connectivity status and discovers user organizations - CRITICAL for accessing private/organizational repositories.
+  **DO NOT PROCEED** with searches if both GitHub and NPM are disconnected.
+  **USE ORGANIZATIONS** returned in 'github.organizations' array for targeted owner/org parameters in all search tools.
+  Essential for enterprise code exploration and accessing company-specific repositories that require organizational membership.`,
     [TOOL_NAMES.NPM_PACKAGE_SEARCH]: `Search NPM packages by keyword. Use for package ecosystem discovery.`,
     [TOOL_NAMES.NPM_VIEW_PACKAGE]: `Get comprehensive package metadata essential for GitHub searches and code analysis. Returns complete package context:
   • repositoryGitUrl - Direct GitHub repo link for accurate searches
@@ -56,13 +60,16 @@ const TOOL_DESCRIPTIONS = {
   • dependencies/devDependencies - Full ecosystem understanding
   • versions with dates - Historical evolution context
   The exports field is invaluable for GitHub file discovery - shows exact paths before fetching. Always use when finding packages in code.`,
-    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `SEMANTIC CODE DISCOVERY: Search code with boolean logic (AND, OR, NOT). 
+    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `SEMANTIC CODE DISCOVERY: Search code with SMART BOOLEAN OPERATORS (AND, OR, NOT). 
+  Prioritize intelligent boolean combinations: "logger AND debug NOT test", "config OR settings", "error handling AND typescript".
   Format: "term AND term" language:js path:src. Filters: owner/org/user, repo, extension, filename, language, path, size, limit, match scope. 
   Use for finding actual implementation patterns and code examples.
   CRITICAL: When packages found in results or from user input, use ${TOOL_NAMES.NPM_VIEW_PACKAGE} for metadata/paths.`,
-    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `Search repositories by name/description. PRIMARY FILTERS work alone: owner, language, stars, topic, forks. SECONDARY FILTERS require query/primary filter: license, created, archived, includeForks, updated, visibility, match.
+    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `Search repositories by name/description. START SHALLOW AND GO BROAD (contrary to code search).
+  Use topics for EXPLORATORY discovery: topic:["cli","typescript","api"] to find ecosystem patterns.
+  PRIMARY FILTERS work alone: owner, language, stars, topic, forks. SECONDARY FILTERS require query/primary filter: license, created, archived, includeForks, updated, visibility, match.
   
-  PATTERNS: Use topic:["cli","typescript"] for semantic discovery. Use stars:">100" for quality. Use owner:"microsoft" for organization repos. Query supports GitHub syntax: "language:Go OR language:Rust".
+  SMART REPOS SEARCH PATTERNS: Use topic:["cli","typescript"] for semantic discovery. Use stars:">100" for quality. Use owner:"microsoft" for organization repos. Query supports GitHub syntax: "language:Go OR language:Rust".
   
   CRITICAL: When finding packages, use ${TOOL_NAMES.NPM_VIEW_PACKAGE} for metadata and repository paths.`,
     [TOOL_NAMES.GITHUB_GET_CONTENTS]: `Browse repository structure and verify file existence. ALWAYS use before github_get_file_content to confirm files exist and understand organization.`,
@@ -309,7 +316,7 @@ async function executeCommand(fullCommand, type, options = {}) {
 
 function registerApiStatusCheckTool(server) {
     server.tool(TOOL_NAMES.API_STATUS_CHECK, TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK], {}, {
-        title: 'Verify Tools Readiness and Authentication',
+        title: TOOL_NAMES.API_STATUS_CHECK,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK],
         readOnlyHint: true,
         destructiveHint: false,
@@ -457,9 +464,9 @@ function registerGitHubSearchCodeTool(server) {
             .optional()
             .describe('Repository owner/organization(s). Single string or array for multiple owners. Leave empty for global search.'),
         repo: z
-            .array(z.string())
+            .union([z.string(), z.array(z.string())])
             .optional()
-            .describe('Specific repositories in "owner/repo" format. Requires owner parameter to be set.'),
+            .describe('Specific repositories in "owner/repo" format. Can be a single repository string or array of repository strings. Requires owner parameter to be set.'),
         language: z
             .string()
             .optional()
@@ -497,9 +504,8 @@ function registerGitHubSearchCodeTool(server) {
             .optional()
             .describe('Search scope: "file" for content search, "path" for filename/path search. If array provided, only first value is used due to GitHub API limitations.'),
     }, {
-        title: 'Search Code in GitHub Repositories',
-        description: 'Search code across GitHub with boolean operators (AND, OR, NOT), qualifiers, and filters. ' +
-            'Supports language, file type, owner, repository, path, and visibility filtering.',
+        title: TOOL_NAMES.GITHUB_SEARCH_CODE,
+        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE],
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -578,7 +584,7 @@ async function searchGitHubCode(params) {
                 const owners = Array.isArray(params.owner)
                     ? params.owner
                     : [params.owner];
-                const repos = params.repo;
+                const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
                 // Create repo filters for each owner/repo combination
                 owners.forEach(owner => {
                     repos.forEach(repo => {
@@ -624,9 +630,8 @@ function registerFetchGitHubFileContentTool(server) {
             .min(1)
             .describe(`File path from repository root (e.g., 'README.md', 'src/index.js'). Use github_get_contents to explore structure.`),
     }, {
-        title: 'Read File Content from GitHub Repositories',
-        description: `Fetches complete file content from GitHub repositories. ` +
-            `Handles text files up to 500KB, detects binary files, supports branch fallback.`,
+        title: TOOL_NAMES.GITHUB_GET_FILE_CONTENT,
+        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_FILE_CONTENT],
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -852,7 +857,7 @@ function registerSearchGitHubReposTool(server) {
             .default(25)
             .describe('Maximum results (default: 25, max: 50)'),
     }, {
-        title: 'GitHub Repository Search',
+        title: TOOL_NAMES.GITHUB_SEARCH_REPOS,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_REPOS],
         readOnlyHint: true,
         destructiveHint: false,
@@ -1132,7 +1137,7 @@ function registerSearchGitHubCommitsTool(server) {
             .default(25)
             .describe('Maximum results (default: 25)'),
     }, {
-        title: 'GitHub Commit Search',
+        title: TOOL_NAMES.GITHUB_SEARCH_COMMITS,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_COMMITS],
         readOnlyHint: true,
         destructiveHint: false,
@@ -1407,7 +1412,7 @@ function registerSearchGitHubPullRequestsTool(server) {
             .default('desc')
             .describe('Order (default: desc)'),
     }, {
-        title: 'Search Pull Requests for Implementation Analysis',
+        title: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS],
         readOnlyHint: true,
         destructiveHint: false,
@@ -1544,7 +1549,7 @@ function registerNpmSearchTool(server) {
             .default(20)
             .describe('Max results per query (default: 20)'),
     }, {
-        title: 'Search NPM Packages by Name/Keyword',
+        title: TOOL_NAMES.NPM_PACKAGE_SEARCH,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_PACKAGE_SEARCH],
         readOnlyHint: true,
         destructiveHint: false,
@@ -1663,7 +1668,7 @@ function registerViewRepositoryStructureTool(server) {
             .describe('Directory path within repository (e.g., "src/components", "packages/core"). ' +
             'Leave empty for root. Use previous results to navigate deeper.'),
     }, {
-        title: 'Browse Repository Structure and Browse Directories',
+        title: TOOL_NAMES.GITHUB_GET_CONTENTS,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_CONTENTS],
         readOnlyHint: true,
         destructiveHint: false,
@@ -1995,7 +2000,7 @@ function registerSearchGitHubIssuesTool(server) {
             .default(25)
             .describe('Maximum results (default: 25)'),
     }, {
-        title: 'Search Issues for Problem Discovery and Solutions',
+        title: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_ISSUES],
         readOnlyHint: true,
         destructiveHint: false,
@@ -2112,7 +2117,7 @@ function registerNpmViewPackageTool(server) {
             .min(1, 'Package name is required')
             .describe('NPM package name to analyze. Returns complete package context including exports (critical for GitHub file discovery), repository URL, dependencies, and version history.'),
     }, {
-        title: 'Get NPM Package Metadata',
+        title: TOOL_NAMES.NPM_VIEW_PACKAGE,
         description: TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_VIEW_PACKAGE],
         readOnlyHint: true,
         destructiveHint: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-mcp",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Model Context Protocol (MCP) server for advanced GitHub repository analysis, code discovery, and npm package exploration. Provides AI assistants with powerful tools to search, analyze, and understand codebases across GitHub and npm ecosystems.",
   "keywords": [
     "mcp",