octocode-mcp 2.3.24 → 2.3.26

package/README.md

@@ -1,22 +1,21 @@
 # Octocode MCP
 
-**The Perfect AI Code Assistant - Advanced Search & Discovery Across GitHub & NPM**
+**The Perfect AI Code Assistant - Advanced Search & Discovery Across GitHub**
 
 <div>
   <img src="./assets/logo.png" width="400px">
   
-  [![Version](https://img.shields.io/badge/version-2.3.24-blue.svg)](./package.json)
+  [![Version](https://img.shields.io/badge/version-2.3.25-blue.svg)](./package.json)
   [![License](https://img.shields.io/badge/license-MIT-green.svg)](./package.json)
   [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
     [![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-☕-orange.svg)](https://buymeacoffee.com/bgauryy)
 
 </div>
 
+## 🌐 For More Details - [octocode.ai](https://octocode.ai)
+## 📚 For Technical Details - [Technical Summary](./docs/summary.md)
 
-## 🌐 For More Details -  [octocode.ai](https://octocode.ai)
-
-
-**The perfect code assistant that can help understand anything.** Octocode provides AI-powered advanced search with heuristic discovery and smart fallbacks to understand connections between repositories and NPM packages across any privilege level you have.
+**The perfect code assistant that can help understand anything.** Transform your AI assistant into an expert code researcher with instant access to millions of repositories and packages across GitHub and npm ecosystems.
 
 Instead of manually browsing repositories, ask questions like:
 - *"How did React implement concurrent rendering?"*
@@ -25,17 +24,45 @@ Instead of manually browsing repositories, ask questions like:
 - *"What's the architecture of this library?"*
 - *"How do I use this MCP tool effectively?"*
 
-## Unique Value Proposition
+## 🌟 Featured On
+
+### modelcontextprotocol - Official Community MCP Server 
+[![MCP Servers](https://img.shields.io/badge/Official-MCP%20Servers-purple.svg?logo=github)](https://github.com/modelcontextprotocol/servers)
+
+### Community Collections
+[![Awesome MCP Servers](https://img.shields.io/badge/Awesome-MCP%20Servers-orange.svg?logo=awesome-lists)](https://github.com/punkpeye/awesome-mcp-servers) 
+[![Awesome MCP Servers](https://img.shields.io/badge/Awesome-MCP%20Collection-blue.svg?logo=awesome-lists)](https://github.com/appcypher/awesome-mcp-servers)
+
+### MCP Directories & Tools
+[![MCP.so](https://img.shields.io/badge/MCP.so-Server%20Directory-green.svg?logo=web)](https://mcp.so/server/octocode/bgauryy)
+[![PulseMCP](https://img.shields.io/badge/PulseMCP-Server%20Registry-red.svg?logo=pulse)](https://www.pulsemcp.com/servers/bgauryy-octocode)
+[![DevTool.io](https://img.shields.io/badge/DevTool.io-Development%20Tool-teal.svg?logo=tools)](https://devtool.io/tool/octocode-mcp)
+
+## 🎯 Who Is This For?
+
+### For Developers
+Navigate complex multi-repo architectures, understand organizational issues at scale, and generate custom documentation on-demand from real code examples. Create contextual documentation directly in your IDE, or ask OctoCode to learn from any repository and implement similar patterns in your current project.
+
+### For Product & Engineering Managers
+Gain unprecedented visibility into application behavior through semantic code search, track development progress across teams, and understand the real implementation behind product features.
+
+### For Security Researchers
+Discover security patterns, vulnerabilities, and compliance issues across both public and private repositories with advanced pattern matching and cross-codebase analysis.
+
+### For Large Organizations
+Dramatically increase development velocity by enabling teams to instantly learn from existing codebases, understand cross-team implementations, and replicate proven patterns—transforming institutional knowledge into actionable development acceleration.
+
+## 🚀 Key Benefits
+
+**Zero-Configuration Setup** - Works with existing GitHub CLI authentication, no personal access tokens needed
+
+**Enterprise-Ready Security** - Respects organizational permissions with content sanitization
 
-**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.
+**AI Token Optimization** - Reduces AI costs by through intelligent content processing
 
-**Key Differentiators:**
-- **🧠 AI-Powered Search** - Multi-modal search strategies with progressive complexity reduction and context-aware suggestions
-- **🔐 Zero-Config Security** - Uses GitHub CLI authentication with organization discovery - no personal access tokens needed
-- **🔗 Connection Intelligence** - Maps NPM packages to repositories with commit SHA integration and cross-tool data sharing
-- **🌐 Universal Access** - Works seamlessly with public, private, and organization repositories using GitHub CLI permissions
-- **⚡ LLM Optimized** - Advanced content minification, intelligent caching, and parallel processing reduces token usage by 80-90%
-- **🖥️ Cross-Platform Excellence** - Native Windows PowerShell support with automatic path detection and custom installation paths
+**Cross-Platform Excellence** - Native Windows PowerShell support with automatic path detection
+
+**Universal Access** - Works seamlessly with public, private, and organization repositories
 
 ## Quick Start 🚀
 
@@ -64,11 +91,6 @@ choco install powershell-core nodejs github-cli
 scoop install gh nodejs
 ```
 
-**Manual Installation:**
-- Node.js: https://nodejs.org/
-- GitHub CLI: https://github.com/cli/cli#installation
-- PowerShell 7+: https://github.com/PowerShell/PowerShell#installation
-
 ### 2. Authenticate
 ```bash
 # Login to GitHub (opens browser)
@@ -78,13 +100,13 @@ gh auth login
 npm login
 ```
 
-**🔐 Authentication Benefits:**
-- ✅ **No personal access tokens** - Uses GitHub CLI OAuth flow
-- ✅ **Enterprise ready** - Works with SSO, 2FA, and organization access
-- ✅ **Automatic organization detection** - Instantly accesses your private repositories
-- ✅ **Zero configuration** - Uses existing `gh` CLI permissions
+### 3. Add to Claude Desktop
+```bash
+# For Claude Desktop users
+claude mcp add octocode npx 'octocode-mcp@latest'
+```
 
-### 3. Add to MCP Configuration
+### Or Add to MCP Configuration Manually
 ```json
 {
   "octocode-mcp": {
@@ -96,36 +118,38 @@ npm login
 
 **That's it!** Octocode automatically works with your organization's private repositories.
 
-### 4. Windows PowerShell Support (v2.3.24+)
+## 🛠️ What You Can Do
 
-**🚀 Enhanced Windows Support:**
-- **PowerShell Core Priority**: Automatically uses PowerShell 7+ for better security
-- **Automatic Path Detection**: Detects installations from WinGet, Scoop, Chocolatey, MSI
-- **Custom Path Support**: Use environment variables for custom installations
-- **Cross-Platform Security**: Implements GitHub CLI's security best practices
+### Deep Project Research & Analysis
+- **Issue Search & Analysis**: Understand project challenges, feature requests, and bug patterns
+- **Commit History Research**: Trace feature implementations and bug fixes across time
+- **Pull Request & Code Review Analysis**: Access actual code diffs and understand development workflows
+- **Project Progress Tracking**: Monitor development velocity and team collaboration patterns
 
-**Custom Path Configuration:**
-```powershell
-# Set custom GitHub CLI path
-$env:GH_PATH = "C:\custom\path\gh.exe"
+### Core GitHub Research
+- **Repository Discovery**: Find repositories by topic, language, and activity
+- **Code Search**: Find exact patterns and implementations across millions of repositories
+- **Cross-Repository Flow Understanding**: Connect related changes across multiple repositories
+- **Repository Architecture**: Navigate and understand project structures
 
-# Set custom NPM path  
-$env:NPM_PATH = "C:\custom\path\npm.cmd"
-```
+### Package Ecosystem Tools
+- **NPM Package Discovery**: Analyze Node.js packages with comprehensive metadata
+- **Python Package Integration**: Explore PyPI packages with cross-ecosystem comparison
+- **Package Analysis**: Deep-dive into versions, dependencies, and repository connections
+
+### Advanced Research Capabilities
+- **Code Pattern Discovery**: Identify implementation patterns and best practices
+- **Security & Compliance Research**: Search for security patterns across codebases
+- **Team Collaboration Analysis**: Understand code review processes and team dynamics
+- **Real-time Documentation**: Generate custom docs from live code for any topic
 
-**Supported Installation Methods:**
-- **WinGet**: `%LOCALAPPDATA%\Microsoft\WindowsApps\gh.exe`
-- **Scoop**: `%USERPROFILE%\scoop\apps\gh\current\bin\gh.exe`
-- **Chocolatey**: `%PROGRAMDATA%\chocolatey\bin\gh.exe`
-- **MSI**: `%PROGRAMFILES%\GitHub CLI\gh.exe`
+> **📚 For detailed technical architecture, tool specifications, and implementation details, see [Technical Summary](./docs/summary.md)**
 
 ## DXT Extension 📦
 
 This project is available as a **Desktop Extension (DXT)** for easy installation in AI applications like Claude Desktop.
 
-### For Developers
-
-**Building the DXT Package:**
+### Quick DXT Setup
 
 ```bash
 # Install dependencies
@@ -133,146 +157,26 @@ yarn install
 
 # Build the DXT package
 yarn dxt:pack
-
-# Validate the manifest
-yarn dxt:validate
-
-# View package information
-yarn dxt:info
-
-# Sign the package (optional)
-yarn dxt:sign
 ```
 
+The generated `octocode-mcp.dxt` file can be installed in Claude Desktop by simply clicking on it.
+
 **DXT Scripts:**
 - `yarn dxt:validate` - Validate the manifest.json file
-- `yarn dxt:pack` - Build and package the extension as a .dxt file
-- `yarn dxt:info` - Show information about the packaged extension
-- `yarn dxt:sign` - Sign the package with a self-signed certificate
-- `yarn dxt:verify` - Verify the signature of a signed package
-
-**The DXT package includes:**
-- Compiled MCP server (`dist/index.js`)
-- Extension manifest (`manifest.json`)
-- Package metadata (`package.json`)
-- Logo and assets (`assets/logo.png`)
-- Documentation (`README.md`)
-
-**Building DXT from Source:**
-To build the DXT package locally from this repository:
-```bash
-# Clone the repository
-git clone https://github.com/bgauryy/octocode-mcp.git
-cd octocode-mcp
-
-# Install dependencies and build
-yarn install
-yarn build
-yarn dxt:pack
-```
-
-The generated `octocode-mcp.dxt` file can then be installed in Claude Desktop (just click on it and it will open claude desktop with the extension)
-
-## Core Features 🛠️
-
-### 🧠 **AI-Powered Intelligence**
-- **Advanced Search Strategies** - Multi-modal search with exact/term modes and progressive complexity reduction
-- **Connection Mapping** - Automatically links NPM packages to GitHub repositories with URL extraction
-- **Cross-Reference Analysis** - Discovers implementation patterns across projects with commit SHA integration
-- **Progressive Refinement** - AI-guided search with contextual suggestions and smart fallback chains
-- **Context-Aware Discovery** - Understands relationships between repositories, packages, commits, and issues
-
-### 🔗 **Commit SHA Integration** 
-- **Time Travel Code Viewing** - View files from specific commits and pull requests using SHA references
-- **PR Code Analysis** - Fetch commit data with file changes for precise code comparison
-- **Historical Implementation** - Compare code evolution across versions with diff analysis
-- **Cross-Tool Integration** - Commit SHAs work seamlessly across search, fetch, and analysis tools
-
-### ⚡ **Performance Optimization**
-- **Smart Content Selection** - Extracts targeted line ranges with configurable context
-- **Advanced Minification** - Language-aware compression preserving structure and meaning
-- **Intelligent Caching** - Generated cache keys with automatic invalidation
-- **Parallel Processing** - Concurrent API calls for enhanced content fetching
-- **Token Efficiency** - 80-90% reduction in LLM token usage through optimization
-
-## Available Tools
-
-**10 specialized tools** working together intelligently:
-
-### 🔍 **Discovery & Navigation**
-- **Repository Search** - Multi-modal search with quality filters, URL extraction, and private repository support
-- **Package Search** - NPM ecosystem discovery with deduplication and framework detection
-- **Repository Structure** - Smart branch detection with path validation and enhanced fallbacks
-
-### 💻 **Code Analysis**
-- **Code Search** - Advanced search with exact/term modes, progressive strategies, and text match optimization
-- **File Content Fetching** - Intelligent retrieval with partial access, minification, and smart branch fallbacks
-- **Package Analysis** - Detailed NPM package inspection with export structure and GitHub integration
-
-### 📊 **Development Activity**
-- **Commit Search** - Multi-modal search with content fetching and SHA integration for file viewing
-- **Pull Request Search** - Dual search modes with commit data and cross-tool SHA integration
-- **Issue Search** - Rich filtering with parallel content fetching and advanced metrics
-
-### 🛠️ **System Integration**
-- **API Status Check** - Central authentication validation with organization discovery and smart error handling
-
-### 🚀 **Latest Features**
-- **Windows PowerShell Support (v2.3.24)** - Native PowerShell Core integration with automatic path detection
-- **Custom Path Support (v2.3.24)** - Environment variables for custom GitHub CLI and NPM installations
-- **Enhanced Security Architecture (v2.3.24)** - Implements GitHub CLI's security best practices with safe path resolution
-- **Commit SHA Integration** - View files from specific commits and pull requests
-- **Progressive Search Strategies** - AI-guided complexity reduction with contextual suggestions
-- **Cross-Tool Data Sharing** - Seamless integration with shared data formats and relationship mapping
-- **Advanced Error Recovery** - Context-aware suggestions and smart fallback chains
-- **Performance Optimization** - Token efficiency, intelligent caching, and parallel processing
-
-## Security & Privacy 🛡️
-
-### Local-First Architecture
-- **🏠 100% Local** - Runs entirely on your machine
-- **🚫 Zero Data Collection** - No telemetry or data transmission
-- **🔑 Safe Token Usage** - Uses GitHub CLI authentication, no personal access tokens needed
-
-### Multi-Layer Security Protection
-- **🛡️ Input Sanitization** - Comprehensive validation of all user inputs with Zod schemas
-- **🔐 Content Sanitization** - Automatic detection and redaction of 1100+ secret patterns
-- **⚡ Prompt Injection Defense** - Advanced pattern detection prevents malicious prompt manipulation
-- **🚨 Malicious Content Detection** - Real-time scanning for suspicious patterns and code
-- **🔒 Output Sanitization** - All responses are filtered and sanitized before delivery
-
-### Command Execution Security
-- **⚪ Allowlisted Commands Only** - Pre-approved safe commands (GitHub CLI & NPM only)
-- **🛡️ Argument Sanitization** - Prevents shell injection attacks with proper escaping
-- **✅ Pre-execution Validation** - Every command is validated before execution
-- **🔧 Controlled Environment** - Cross-platform secure shell execution
-- **⏱️ Timeout Protection** - Prevents resource exhaustion with configurable timeouts
-
-### Windows Security Enhancements (v2.3.24+)
-- **🔒 PowerShell Core Priority** - Uses PowerShell 7+ for enhanced security over Windows PowerShell
-- **🛡️ Safe Path Resolution** - Prevents Windows security vulnerability where current directory is searched
-- **🔐 Custom Path Validation** - Validates custom executable paths to prevent injection attacks
-- **✅ Absolute Path Requirements** - Custom paths must be absolute for security compliance
-- **🚨 Executable Validation** - Verifies file existence and accessibility before execution
-- **🔧 Platform-Specific Escaping** - Dedicated argument escaping for PowerShell, CMD, and Unix shells
-
-### Secret & Credential Protection
-- **🔍 Comprehensive Detection** - Detects API keys, tokens, private keys, and credentials
-- **🎭 Smart Masking** - Preserves readability while redacting sensitive information
-- **🏢 Enterprise Ready** - Handles AWS, Google Cloud, Azure, and 100+ service patterns
-- **🔄 Real-time Processing** - Secrets are detected and masked in real-time during content processing
+- `yarn dxt:pack` - Build and package the extension
+- `yarn dxt:release` - Full release pipeline (build → pack → sign → verify)
 
 ## Best Practices 💡
 
-**Effective Questions:**
-- Start with natural language - "How does authentication work?"
-- Ask for connections - "What libraries use this pattern?"
-- Cross-ecosystem queries - "NPM packages that implement X"
-- Evolution questions - "How has this approach changed?"
+**Ask Natural Questions:**
+- "How does authentication work in this project?"
+- "What libraries implement this pattern?"
+- "Show me NPM packages that solve X problem"
+- "How has this approach evolved over time?"
 
-**Pro Tips:**
-- Let AI guide discovery - vague queries work great
-- Trust smart fallbacks - automatic retry with alternatives
+**Let AI Guide Discovery:**
+- Start with broad queries - the system will intelligently narrow down
+- Trust the smart fallbacks - automatic retry with alternatives
 - Build on previous searches - maintain context for deeper exploration
 - Works everywhere - public, private, and organization repositories
 
@@ -290,40 +194,36 @@ gh auth logout && gh auth login
 npm whoami
 ```
 
-**Windows-Specific (PowerShell):**
+**Windows-Specific:**
 ```powershell
 # Check PowerShell version (7+ recommended)
 $PSVersionTable.PSVersion
 
-# Verify custom paths
-Write-Host "GH_PATH: $env:GH_PATH"
-Write-Host "NPM_PATH: $env:NPM_PATH"
-
 # Test executable detection
 where.exe gh
 where.exe npm
-
-# Clear NPX cache
-Remove-Item -Recurse -Force "$env:APPDATA\npm\_npx" -ErrorAction SilentlyContinue
-```
-
-**macOS/Linux:**
-```bash
-# Clear NPX cache
-rm -rf ~/.npm/_npx
-
-# Check installation paths
-which gh
-which npm
 ```
 
 **Common Solutions:**
 - No results? Try broader search terms
 - Private repos not found? Check `gh auth status` for organization membership
-- Windows PowerShell issues? Install PowerShell 7+ for better security
-- Custom paths not working? Ensure absolute paths and file existence
+- Windows issues? Install PowerShell 7+ for better security
 - Permission errors? Check executable permissions and PATH configuration
 
+## Security & Privacy 🛡️
+
+### Local-First Architecture
+- **🏠 100% Local** - Runs entirely on your machine
+- **🚫 Zero Data Collection** - No telemetry or data transmission
+- **🔑 Safe Authentication** - Uses GitHub CLI OAuth, no personal tokens needed
+
+### Enterprise Security
+- **🛡️ Content Protection** - Input validation and content sanitization
+- **🔐 Secret Detection** - Automatic detection and redaction of sensitive data patterns
+- **⚪ Safe Commands Only** - Pre-approved GitHub CLI and NPM commands only
+
+> **📚 For comprehensive security architecture details, see [Technical Summary](./docs/summary.md)**
+
 ## Background 💭
 
 This project started as a personal tool while working at Wix, born from the challenge of navigating large codebases and keeping up with rapidly evolving technology landscapes. What began as a side project evolved into **the perfect code assistant that can help understand anything**.