octocode-mcp 2.2.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.
 
 ---
 
 
 
-