Octocode MCP

The Perfect AI Code Assistant - Advanced Search & Discovery Across GitHub & NPM

🌐 For More Details - 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.

Instead of manually browsing repositories, ask questions like:

• "How did React implement concurrent rendering?"
• "Show me authentication patterns in Next.js applications"
• "Find examples of how to use this specific API"
• "What's the architecture of this library?"
• "How do I use this MCP tool effectively?"

Unique Value Proposition

The most advanced AI-powered code assistant for understanding connections across the entire GitHub & NPM ecosystem. While other GitHub MCPs focus on project management or basic operations, Octocode provides unparalleled depth for code discovery and technical research.

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

Quick Start 🚀

1. Install Prerequisites

macOS/Linux:

# Install Node.js 18.12+
brew install node

# Install GitHub CLI
brew install gh

Windows:

# Install using WinGet (recommended)
winget install Microsoft.PowerShell  # PowerShell 7+ for better security
winget install GitHub.cli
winget install OpenJS.NodeJS

# Or using Chocolatey
choco install powershell-core nodejs github-cli

# Or using Scoop
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

# Login to GitHub (opens browser)
gh auth login

# Login to NPM (for package research)
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 MCP Configuration

{
  "octocode-mcp": {
    "command": "npx",
    "args": ["octocode-mcp"]
  }
}

That's it! Octocode automatically works with your organization's private repositories.

4. Windows PowerShell Support (v2.3.24+)

🚀 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

Custom Path Configuration:

# Set custom GitHub CLI path
$env:GH_PATH = "C:\custom\path\gh.exe"

# Set custom NPM path  
$env:NPM_PATH = "C:\custom\path\npm.cmd"

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

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:

# Install dependencies
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

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:

# 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

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?"

Pro Tips:

• Let AI guide discovery - vague queries work great
• Trust smart fallbacks - automatic retry with alternatives
• Build on previous searches - maintain context for deeper exploration
• Works everywhere - public, private, and organization repositories

Troubleshooting 🔧

Cross-Platform Commands:

# Check GitHub CLI status
gh auth status

# Re-authenticate if needed
gh auth logout && gh auth login

# Check NPM access
npm whoami

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:

# 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
• Permission errors? Check executable permissions and PATH configuration

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.

The goal: make code exploration as intelligent as having a senior developer guide you through any codebase.

License 📄

MIT License - See LICENSE for details.