Content
# Octocode Ecosystem
**The Complete AI-Powered Code Analysis and Research Platform**
<div align="center">
<a href="https://github.com/modelcontextprotocol/servers">
<img src="https://avatars.githubusercontent.com/u/182288589?s=48&v=4" width="20" height="20" alt="MCP Logo" style="vertical-align: middle; margin-right: 6px;">
<img src="https://img.shields.io/badge/Model_Context_Protocol-Official_Community_Server-blue?style=flat-square" alt="MCP Community Server" style="vertical-align: middle;">
</a>
</div>
<div align="center">
<img src="./assets/logo.png" width="300px" alt="Octocode Logo">
</div>
<div style="height: 20px;"></div>
<div align="center">
[](https://octocode.ai)
[](https://deepwiki.com/bgauryy/octocode-mcp)
[](https://x.com/guy_bary)
[](https://archestra.ai/mcp-catalog/bgauryy__octocode-mcp)
</div>
<div align="center">
<a href="https://github.com/bgauryy/octocode-mcp/tree/main/packages/octocode-mcp" style="font-size: 1.8em; font-weight: bold; text-decoration: none; padding: 8px 16px; background-color: #f0f8ff; border-radius: 6px; color: #0066cc;">
🚀 Go to Octocode MCP →
</a>
</div>
<br/>
## 🌟 What is Octocode?
**Octocode** is a revolutionary AI-powered code analysis and research platform that transforms how developers, teams, and organizations understand, explore, and work with codebases. Built on the **Model Context Protocol (MCP)**, Octocode provides AI assistants with unprecedented capabilities to analyze GitHub repositories, search code semantically, and extract actionable insights from millions of open-source and private repositories.
### 🎯 The Vision
While most code context and research MCPs rely on documentation from a single repository, Octocode focuses on actual code analysis and documentation from real repositories at runtime, understanding complex flows anywhere in the GitHub ecosystem.
**For Organizations:** Unlock institutional knowledge trapped in private repositories, understand complex multi-service architectures, and maintain coding standards across teams through intelligent pattern recognition and cross-repository analysis.
**For Public Search:** Discover proven implementations from millions of open-source repositories, learn from the best practices of top developers, and find battle-tested solutions to any coding challenge through semantic code discovery.
Octocode can research and analyze any flow and complexity through smart research, leveraging real data and intelligent LLM communication.
In the age of AI-assisted development, the bottleneck isn't writing code—it's understanding existing codebases, discovering proven patterns, and extracting institutional knowledge. Octocode bridges this gap by making any codebase instantly accessible and comprehensible to AI assistants, enabling:
- **🧠 Instant Code Intelligence** - Transform any repository into structured knowledge
- **🧩 Smart Context Generation** - Instantly create rich, actionable context from any repository for AI applications
- **🔍 Semantic Code Discovery** - Find implementations by describing what you need
- **🏢 Enterprise Knowledge Mining** - Extract patterns and practices from organizational codebases
- **⚡ AI-Native Research** - Purpose-built for modern AI-assisted development workflows
- **🌐 Ecosystem Analysis** - Navigate complex relationships between repositories and dependencies
- **📊 Implementation-First Approach** - Focus on actual code rather than just documentation
## 🎯 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.
### For Beginners & Advanced Vibe Coders
- **Beginners**: Take code from anywhere and understand it deeply. Learn from production codebases, discover proven patterns, and build confidence by seeing how experienced developers solve problems.
- **Advanced Vibe Coders**: Leverage quality context for superior code generation. Use comprehensive understanding from issues, PRs, and documentation to generate production-ready code that follows established patterns.
## 🌟 Featured On
### Official MCP Server
[](https://github.com/modelcontextprotocol/servers) **modelcontextprotocol/servers**
### Community Collections
- [](https://github.com/punkpeye/awesome-mcp-servers) **punkpeye/awesome-mcp-servers**
- [](https://github.com/appcypher/awesome-mcp-servers) **appcypher/awesome-mcp-servers**
- [](https://github.com/Puliczek/awesome-mcp-security) **Puliczek/awesome-mcp-security**
### MCP Directories & Tools
- [](https://glama.ai/mcp/servers/@bgauryy/octocode-mcp)
- [](https://mcp.so/server/octocode/bgauryy)
- [](https://www.pulsemcp.com/servers/bgauryy-octocode)
- [](https://devtool.io/tool/octocode-mcp)
- [](https://www.mcpserverfinder.com/servers/bgauryy/octocode-mcp)
- [](https://mcp-container.com/en/mcp/137e872e-ef4f-4bdb-a697-d1e628200215)
<a href="https://glama.ai/mcp/servers/@bgauryy/octocode-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@bgauryy/octocode-mcp/badge" />
## 🏗️ The Octocode Ecosystem
The Octocode platform consists of specialized packages, each serving a critical role in the AI-powered code analysis pipeline:
### 📦 Core Packages
<table>
<tr>
<td width="50%">
#### 🔧 [Octocode MCP](https://github.com/bgauryy/octocode-mcp/tree/main/packages/octocode-mcp) - The Main Engine
**The heart of the Octocode platform** - A comprehensive MCP server that provides AI assistants with 8 specialized tools for GitHub repository analysis, code discovery, and package exploration.
**Key Capabilities:**
- **Advanced Code Search** - Semantic search across millions of repositories
- **Repository Intelligence** - Deep structural analysis and exploration
- **Commit & PR Analysis** - Understanding code evolution and development patterns
- **Package Discovery** - NPM and Python package research with repository connections
- **Enterprise Integration** - Private repository access with organizational intelligence
**Perfect For:** AI assistants that need comprehensive code research capabilities
[**📚 Read the Complete MCP Documentation →**](./packages/octocode-mcp/README.md)
</td>
<td width="50%">
#### 🛠️ [Octocode Utils](https://github.com/bgauryy/octocode-mcp/tree/main/packages/octocode-utils) - The Foundation
**Shared utilities powering the entire ecosystem** - Essential tools for content processing, AI optimization, and data transformation used across all Octocode packages.
**Core Features:**
- **🧠 AI-Optimized Content Processing** - Transform any content for optimal AI consumption
- **⚡ Advanced Minification** - Multi-strategy compression for 50+ file types
- **🔄 JSON-to-Natural Language** - Convert structured data to human-readable format
- **🛡️ Production Ready** - Comprehensive error handling and fallback mechanisms
**Perfect For:** Developers building MCP applications or AI content processing tools
[**📚 Read the Complete Utils Documentation →**](./packages/octocode-utils/README.md)
</td>
</tr>
</table>
### 🔗 Package Relationships
```mermaid
graph TB
A[🔧 Octocode MCP<br/>Main Engine] --> C[🛠️ Octocode Utils<br/>Foundation]
A --> D[GitHub API]
A --> E[NPM Registry]
A --> F[MCP Protocol]
G[AI Assistant] --> F
F --> A
C --> H[Content Minification]
C --> I[JSON Processing]
C --> J[AI Optimization]
style A fill:#e1f5fe
style C fill:#f3e5f5
style G fill:#e8f5e8
style F fill:#fff3e0
```
## 🤖 Understanding MCP (Model Context Protocol)
**Model Context Protocol (MCP)** is a revolutionary standard that enables AI assistants to connect with external tools and data sources securely and efficiently. Think of it as the "API standard" for AI applications.
### Why MCP Matters
Traditional AI assistants are limited to their training data and can't access real-time information or perform actions in external systems. MCP solves this by providing:
- **🔌 Standardized Integration** - Universal protocol for AI-tool communication
- **🛡️ Secure Architecture** - Built-in security and permission management
- **⚡ Real-Time Capabilities** - Access live data and perform actions
- **🔄 Bidirectional Communication** - Tools can provide context and receive commands
### MCP in the Octocode Context
Octocode leverages MCP to transform AI assistants into powerful code researchers:
```
AI Assistant ←→ MCP Protocol ←→ Octocode Tools ←→ GitHub/NPM APIs
↑ ↓
Natural Structured
Language Data
Queries & Actions
```
**The Flow:**
1. **Developer asks** AI assistant about code patterns or repositories
2. **AI assistant** communicates with Octocode via MCP protocol
3. **Octocode tools** execute advanced searches and analysis
4. **Results flow back** through MCP as structured, AI-optimized data
5. **AI assistant** provides intelligent insights based on real code
## 🚀 Quick Start
### Setup
Get Octocode running in your AI assistant in just a few steps:
#### 1. **Install with Claude Desktop** (Recommended)
```bash
claude mcp add octocode npx 'octocode-mcp@latest'
```
#### 2. **Authenticate with GitHub**
```bash
# Option A: GitHub CLI (easiest)
gh auth login
# Option B: Set environment variable
export GITHUB_TOKEN="your_github_token"
# Option C: Authorization header format
export Authorization="Bearer your_github_token"
```
#### 3. **Start Using**
Ask your AI assistant: *"Use Octocode to find React authentication patterns"*
### Alternative Installation Methods
<table>
<tr>
<th>🎯 Main Package</th>
<th>🔧 Individual Packages</th>
</tr>
<tr>
<td>
**For AI-powered code research:**
```bash
# NPM global install
npm install -g octocode-mcp
# Yarn global install
yarn global add octocode-mcp
```
</td>
<td>
**For custom development:**
```bash
# MCP Server
npm install octocode-mcp
# Utilities
npm install octocode-utils
```
</td>
</tr>
</table>
### Authentication Setup
Configure GitHub access for enhanced capabilities:
**Option 1: Environment Variable (Recommended)**
```json
{
"octocode": {
"command": "npx",
"args": ["octocode-mcp"],
"env": {
"GITHUB_TOKEN": "your_github_token"
}
}
}
```
**Option 1b: Authorization Header Format**
```json
{
"octocode": {
"command": "npx",
"args": ["octocode-mcp"],
"env": {
"Authorization": "Bearer your_github_token"
}
}
}
```
**Option 2: GitHub CLI (Automatic)**
Using [GitHub CLI](https://cli.github.com/) provides seamless authentication after running `gh auth login`:
```json
{
"octocode": {
"command": "npx",
"args": ["octocode-mcp"]
}
}
```
### Authentication Fallback Chain
Octocode uses a smart authentication fallback system that tries multiple methods in order:
1. **`GITHUB_TOKEN`** - Direct GitHub token environment variable
2. **`GH_TOKEN`** - Alternative GitHub token environment variable
3. **GitHub CLI** - Automatically detected from `gh auth login`
4. **`Authorization`** - Bearer token from Authorization header format (`Bearer {{token}}`)
## 🎯 Use Cases & Applications
<table>
<tr>
<td width="33%">
### 🏢 Enterprise Teams
**Organizational Intelligence**
- Map coding standards across teams
- Extract institutional knowledge
- Analyze architectural patterns
- Discover internal libraries
**Security & Compliance**
- Scan for vulnerabilities
- Audit compliance
- Analyze access controls
- Track security patterns
</td>
<td width="33%">
### 👨💻 Individual Developers
**Learning & Discovery**
- Learn from production codebases
- Discover proven patterns
- Understand complex architectures
- Generate documentation
**Development Acceleration**
- Find existing solutions
- Understand dependencies
- Generate boilerplate code
- Research best practices
</td>
<td width="33%">
### 🔬 Researchers & Analysts
**Code Analysis**
- Large-scale pattern analysis
- Study coding evolution
- Analyze technology adoption
- Research vulnerabilities
**Ecosystem Understanding**
- Map package relationships
- Understand adoption trends
- Analyze project health
- Study collaboration patterns
</td>
</tr>
</table>
## 🏗️ Architecture & Technical Excellence
For detailed technical architecture, implementation details, and advanced features, see our comprehensive [Technical Architecture Documentation](./packages/octocode-mcp/docs/SUMMARY.md).
## 📚 Documentation & Resources
### 📖 Package Documentation
- **[🔧 Octocode MCP](./packages/octocode-mcp/README.md)** - Complete MCP server documentation with 8 specialized tools
- **[🛠️ Octocode Utils](./packages/octocode-utils/README.md)** - Utilities and shared components for AI optimization
- **[📊 Technical Architecture](./packages/octocode-mcp/docs/SUMMARY.md)** - Deep technical implementation details
### 🌐 External Resources
- **[Official Website](https://octocode.ai)** - Product information and updates
- **[GitHub Repository](https://github.com/bgauryy/octocode-mcp)** - Source code and issues
- **[MCP Documentation](https://modelcontextprotocol.io/)** - Official MCP protocol documentation
- **[Community Discussions](https://github.com/bgauryy/octocode-mcp/discussions)** - User community and support
### 💬 Support & Community
- **[GitHub Issues](https://github.com/bgauryy/octocode-mcp/issues)** - Bug reports and feature requests
- **[X/Twitter](https://x.com/guy_bary)** - Updates and announcements
- **[Email Support](mailto:bgauryy@octocodeai.com)** - Direct developer contact
## 🎉 Join the Revolution
Octocode represents the future of AI-assisted development where artificial intelligence meets human creativity to unlock the full potential of the world's code. Whether you're a solo developer looking to learn from the best, an enterprise team seeking to leverage institutional knowledge, or a researcher analyzing code at scale, Octocode provides the tools and insights you need.
**Start your journey today:**
1. **🚀 Install Octocode MCP** → [5-Minute Setup Guide](#-quick-start)
2. **🔍 Explore real examples** → [Usage Guide](./packages/octocode-mcp/docs/USAGE_GUIDE.md)
3. **⚡ Master the tools** → [Tool Schemas](./packages/octocode-mcp/docs/TOOL_SCHEMAS.md)
4. **🤝 Join the community** → [GitHub Discussions](https://github.com/bgauryy/octocode-mcp/discussions)
---
### 🏆 Why Choose Octocode?
<table>
<tr>
<td align="center" width="25%">
<h4>🎯 Purpose-Built</h4>
Designed specifically for AI-assisted code research and analysis
</td>
<td align="center" width="25%">
<h4>🔒 Enterprise-Ready</h4>
Security-first architecture with comprehensive validation and sanitization
</td>
<td align="center" width="25%">
<h4>⚡ High Performance</h4>
Token-optimized responses with intelligent caching and bulk operations
</td>
<td align="center" width="25%">
<h4>🌍 Open Source</h4>
MIT licensed with active community development and support
</td>
</tr>
</table>
---
## 📄 License
MIT License - See [LICENSE](https://github.com/bgauryy/octocode-mcp/blob/main/packages/octocode-mcp/LICENSE.md) for details.
---
<div align="center">
<strong>Built with ❤️ by the Octocode team</strong><br>
<em>Transforming code research, one repository at a time</em>
<br><br>
<a href="https://octocode.ai">🌐 Website</a> •
<a href="https://x.com/guy_bary">🐦 Twitter</a> •
<a href="https://github.com/bgauryy/octocode-mcp">⭐ GitHub</a> •
<a href="mailto:bgauryy@octocodeai.com">📧 Contact</a> •
<a href="https://buymeacoffee.com/bgauryy">☕ Buy Me a Coffee</a>
</div>
