octocode-mcp 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +530 -190
  2. package/build/index.js +3418 -1367
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,259 +1,599 @@
1
1
  # Octocode MCP
2
2
 
3
- **Octocode MCP** is a robust Model Context Protocol (MCP) server designed for comprehensive code discovery and analysis across various platforms. It offers advanced search functionalities, enabling efficient exploration of both internal/public codebases and the expansive GitHub ecosystem using NPM capabilities for more insights.
4
-
5
- <div >
6
- <img src="./assets/logo.png" width="500" height="700">
3
+ **AI-Powered GitHub Research Assistant for Code Discovery**
7
4
 
5
+ <div>
6
+ <img src="./assets/logo.png">
7
+
8
8
  [![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](./package.json)
9
- [![License](https://img.shields.io/badge/license-MIT-green.svg)](./package.json)
10
- [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
9
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](./package.json)
10
+ [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
11
11
  </div>
12
12
 
13
- ## Features
13
+ ## 📋 Table of Contents
14
+
15
+ - [✨ Overview](#-overview)
16
+ - [A New Take on Code Discovery MCP](#a-new-take-on-code-discovery-mcp)
17
+ - [🧠 AI-First Architecture](#-ai-first-architecture)
18
+ - [🔄 Intelligent Tool Chaining](#-intelligent-tool-chaining)
19
+ - [🎯 Smart Discovery Features](#-smart-discovery-features)
20
+ - [💡 Background & Motivation](#-background--motivation)
21
+ - [🔄 A Tool That Built Itself](#-a-tool-that-built-itself)
22
+ - [🎯 Innovation: NPM-Driven Repository Discovery](#-innovation-npm-driven-repository-discovery)
23
+ - [🌟 Example Use Cases](#-example-use-cases)
24
+ - [🎯 Features](#-features)
25
+ - [For Developers](#for-developers)
26
+ - [For Engineering Managers](#for-engineering-managers)
27
+ - [🛠 Available Tools](#-available-tools)
28
+ - [🔍 GitHub Code & Repository Search](#-github-code--repository-search)
29
+ - [📦 NPM & Package Ecosystem](#-npm--package-ecosystem)
30
+ - [📋 Development History & Collaboration](#-development-history--collaboration)
31
+ - [👥 User & Organization Management](#-user--organization-management)
32
+ - [🎯 Smart Features](#-smart-features)
33
+ - [📚 Usage Examples](#-usage-examples)
34
+ - [Basic Code Discovery](#basic-code-discovery)
35
+ - [Advanced Research](#advanced-research)
36
+ - [Learning & Documentation](#learning--documentation)
37
+ - [Historical Analysis](#historical-analysis)
38
+ - [Code Review & Improvement](#code-review--improvement)
39
+ - [💡 Tips for Effective Usage](#-tips-for-effective-usage)
40
+ - [🎯 Search Strategy Tips](#-search-strategy-tips)
41
+ - [📚 Documentation & Knowledge Management](#-documentation--knowledge-management)
42
+ - [⚡ Performance & Limitations](#-performance--limitations)
43
+ - [🔗 Cross-Repository Analysis](#-cross-repository-analysis)
44
+ - [🎨 Advanced Use Cases](#-advanced-use-cases)
45
+ - [🚀 Pro Tips](#-pro-tips)
46
+ - [🛠 Installation & Setup](#-installation--setup)
47
+ - [🚀 Works Out Of The Box (OOTB) - Any Environment!](#-works-out-of-the-box-ootb---any-environment)
48
+ - [Step 1: Install Prerequisites](#step-1-install-prerequisites)
49
+ - [Step 2: Authentication Setup](#step-2-authentication-setup)
50
+ - [Step 3: MCP Configuration](#step-3-mcp-configuration)
51
+ - [🎉 That's It! Ready To Use](#-thats-it-ready-to-use)
52
+ - [🌟 Alternative Installation Options](#-alternative-installation-options)
53
+ - [🔒 Privacy & Local Operation](#-privacy--local-operation)
54
+ - [🔒 Why Different Than Static PAT](#-why-different-than-static-pat)
55
+ - [License](#license)
56
+ - [⚙️ Advanced Configuration](#️-advanced-configuration)
57
+ - [Rate Limiting & Performance](#rate-limiting--performance)
58
+ - [Authentication Management](#authentication-management)
59
+ - [NPM Configuration](#npm-configuration)
60
+ - [🎯 Best Practices](#-best-practices)
61
+ - [Search Strategy](#search-strategy)
62
+ - [Performance Optimization](#performance-optimization)
63
+ - [Tool Chaining Best Practices](#tool-chaining-best-practices)
64
+ - [🐛 Troubleshooting](#-troubleshooting)
65
+ - [Authentication Issues](#authentication-issues)
66
+ - [Common Issues](#common-issues)
67
+ - [NPM Configuration Issues](#npm-configuration-issues)
68
+ - [Misconfigured .npmrc File](#misconfigured-npmrc-file)
69
+ - [Development Setup](#development-setup)
70
+ - [Disclaimer](#disclaimer)
71
+
72
+ ## ✨ Overview
73
+
74
+ ### A New Take on Code Discovery MCP
75
+
76
+ **Differences Between Traditional GitHub MCPs and Octocode MCP:**
77
+ - **Octocode MCP** = AI-Powered Research Assistant for Code Discovery
78
+ - **Traditional GitHub MCPs** = Traditional API Wrapper for CRUD Operations
79
+
80
+ ### 🧠 **AI-First Architecture**
81
+ - **Chain-of-Thought Reasoning Framework**: 6-step reasoning methodology built into prompts
82
+ - **Teaching Methodology Integration**: AI education built into tool descriptions
83
+ - **Context-aware Search Optimization**: Quality validation pipelines for code discovery
84
+ - **Automatic Query Optimization**: Single-word prioritization strategy ("RAG" -> "Ranking" not "RAG Ranking")
85
+
86
+ ### 🔄 **Intelligent Tool Chaining**
87
+ - **Automatic Organization Detection**: Smart tool chaining based on context
88
+ - **Package-to-Repository Mapping**: NPM mentions trigger automatic repository discovery
89
+ - **Cross-validation Workflows**: Multi-step research flows with tool interconnection
90
+ - **Progressive Search Refinement**: Phase-based search refinement (Broad -> Pattern -> Precise)
91
+
92
+ ### 🎯 **Smart Discovery Features**
93
+ - **Semantic Landscape Mapping**: `search_github_topics` for ecosystem understanding
94
+ - **Community Knowledge Discovery**: `search_github_discussions` for Q&A and tutorials
95
+ - **Evolution Tracking**: `search_github_commits` for code history analysis
96
+ - **Private Repository Discovery**: `get_user_organizations` for enterprise access
97
+ - **Package Ecosystem Discovery**: `npm_search` and `npm_view` integration
98
+
99
+ ## 💡 Background & Motivation
100
+
101
+
102
+ 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:
103
+
104
+ - **Understand architectural decisions** across multiple repositories
105
+ - **Find real implementation examples** rather than just documentation
106
+ - **Track the evolution** of complex features and systems
107
+ - **Discover internal patterns** and best practices across teams
108
+
109
+ 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.
110
+
111
+ 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.**
112
+
113
+ ### 🔄 A Tool That Built Itself
114
+
115
+ In a fascinating turn of meta-development, **Octocode MCP actually helped create itself**. During development, I used the tool to:
116
+
117
+ - **Understand MCP APIs correctly** by analyzing existing MCP implementations and documentation
118
+ - **Compare features with other MCPs** to identify gaps and opportunities
119
+ - **Research best practices** from successful GitHub integrations
120
+ - **Study code patterns** from high-quality open source projects
121
+
122
+ 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.**
123
+
124
+ ### 🎯 Innovation: NPM-Driven Repository Discovery
125
+
126
+ 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.
127
+
128
+ The approach:
129
+ - **NPM as Quality Signal**: Published packages indicate battle-tested, production-ready code
130
+ - **Package-to-Repository Mapping**: Automatically link NPM packages to their GitHub repositories
131
+ - **Quality Amplification**: Focus on repositories that maintain published packages, ensuring real-world usage
132
+ - **Ecosystem Context**: Understand dependencies and relationships through package management
133
+
134
+ 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.
135
+
136
+ *Note: This is a personal side project and not an official Wix product.*
137
+
138
+ ## 🌟 Example Use Cases
139
+
140
+ **AI agents can now ask questions like:**
141
+
142
+ - *"Show the langchain code examples from my organization"*
143
+ - *"From code and PRs, how did React implement concurrent rendering?"*
144
+ - *"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"*
145
+ - *"Best ways from code examples to use routing in Next.js"*
146
+ - *"Make docs of lodash"*
147
+ - *"Show progress of React project in the recent 5 years"*
148
+ - *"How is Vue rendering architecture different than React? Check from code"*
149
+ - *"Create development docs and guides about how wix ai gateway works"*
150
+ - *"How does SOME_REPOSITORY work?"*
151
+ - *"Summarise the main PRs on project X"*
152
+ - *"How do Vue and React render components? Which approach is more optimized?"*
153
+
154
+ ## 🎯 Features
14
155
 
15
156
  ### For Developers
16
- - **Code Discovery**: Find implementations, patterns, and examples across repositories
17
- - **Cross-Repository Investigation**: Trace code patterns, dependencies, and implementations across multiple repositories
18
- - **Dependency Analysis**: Understand package relationships and find alternative libraries
19
- - **Deep Dependency Insights**: Map transitive dependencies, version conflicts, and security vulnerabilities
20
- - **Bug Investigation**: Track issues, commits, and pull requests related to specific problems
21
- - **Advanced Bug Hunting**: Correlate bugs across repositories, find recurring patterns, and trace root causes
22
- - **Learning & Reference**: Access community discussions, documentation, and best practices
23
- - **Architecture Understanding**: Explore repository structures and analyze codebases
24
- - **Historical Code Analysis**: Understand code evolution through commit history and PR reviews
157
+ - **🔍 Intelligent Code Discovery**: Find implementations, patterns, and examples with AI-guided search
158
+ - **🔗 Cross-Repository Investigation**: Trace code patterns, dependencies, and implementations across multiple repositories
159
+ - **🏢 Cross-Organization Dependencies**: Understand dependencies and relationships across different organizations and teams
160
+ - **📚 Library & API Understanding**: Deep dive into libraries and APIs with examples from both internal and external repositories
161
+ - **🔎 Specific Code Usage Search**: Find exact code patterns, function implementations, and usage examples
162
+ - **🏷️ Topic Understanding**: Explore and understand technology topics, trends, and ecosystems
163
+ - **🏗️ Big Project Analysis**: Comprehensive analysis of large-scale projects and their architecture
164
+ - *"Create development docs and guides about how wix ai gateway works"*
165
+ - *"How does SOME_REPOSITORY work?"*
166
+ - **📈 Project Progress Analysis**: Track and summarize project evolution and key changes
167
+ - *"Summarise the main PRs on project X"*
168
+ - **🔬 Cross-Repository Analysis**: Compare approaches and implementations across different projects
169
+ - *"How do Vue and React render components? Which approach is more optimized?"*
170
+ - **📦 Smart Dependency Analysis**: Understand package relationships and find alternative libraries with automatic NPM integration
171
+ - **🐛 Advanced Bug Investigation**: Track issues, commits, and pull requests with multi-repository correlation
172
+ - **📚 Learning & Reference**: Access community discussions, documentation, and best practices with context-aware recommendations
173
+ - **🏗️ Architecture Understanding**: Explore repository structures and analyze codebases with intelligent navigation
174
+ - **📈 Historical Code Analysis**: Understand code evolution through commit history and PR reviews
175
+ - **💡 Code Insights**: Extract insights from code patterns, repository structures, and development practices
25
176
 
26
177
  ### For Engineering Managers
27
- - **Repository Status Evaluation**: Assess the current status and health of repositories
28
- - **Technology Assessment**: Evaluate libraries, frameworks, and tools adoption
29
- - **Cross-Team Collaboration Analysis**: Track contributions, knowledge sharing, and code reuse patterns
30
- - **Knowledge Management**: Discover internal resources, documentation, and established patterns
31
- - **Competitive Analysis**: Research similar projects and industry trends
32
- - **Risk & Compliance Management**: Identify security vulnerabilities, licensing issues, and maintenance gaps
33
- - **Strategic Planning**: Analyze technology trends, migration patterns, and adoption metrics
34
-
35
- ## What it Does
36
-
37
- ### 🔍 **Comprehensive Code Discovery & Analysis**
38
- - **GitHub Code Search**: Find specific implementations, functions, and patterns across repositories
39
- - **Repository Exploration**: Navigate project structures, fetch complete source files, and understand architectures
40
- - **Cross-Repository Investigation**: Trace code patterns, dependencies, and implementations across multiple repositories
41
- - **Branch Intelligence**: Automatic branch detection (main/master/develop/trunk) with fallback mechanisms
178
+ - **📊 Repository Health Assessment**: Assess the current status and health of repositories with comprehensive metrics
179
+ - **⚖️ Technology Assessment**: Evaluate libraries, frameworks, and tools adoption with trend analysis
180
+ - **🤝 Cross-Team Collaboration Analysis**: Track contributions, knowledge sharing, and code reuse patterns
181
+ - **💡 Knowledge Management**: Discover internal resources, documentation, and established patterns
182
+ - **📈 Competitive Analysis**: Research similar projects and industry trends with automated discovery
183
+ - **🛡️ Risk & Compliance Management**: Identify security vulnerabilities, licensing issues, and maintenance gaps
184
+ - **📋 Strategic Planning**: Analyze technology trends, migration patterns, and adoption metrics
185
+
186
+ ## 🛠 Available Tools
187
+
188
+ ### 🔍 **GitHub Code & Repository Search**
189
+ - **`search_github_code`**: Find specific implementations, functions, and patterns with semantic search
190
+ - **`search_github_repos`**: Progressive repository discovery with intelligent filtering
191
+ - **`fetch_github_file_content`**: Extract complete working code with full context
192
+ - **`view_repository_structure`**: Strategic repository exploration for code analysis
193
+ - **`view_repository`**: Discover default branch information (mandatory first step)
42
194
 
43
195
  ### 📦 **NPM & Package Ecosystem**
44
- - **NPM Package Analysis**: Get detailed package information, dependencies, and metadata
45
- - **NPM Registry Search**: Discover packages by functionality and keywords
196
+ - **`npm_view`**: Transform package names into GitHub repositories for code analysis
197
+ - **`npm_search`**: Search NPM registry for packages by keywords with intelligent optimization
46
198
  - **Package-to-Repository Mapping**: Automatic linking from NPM packages to their GitHub repositories
47
- - **Dependency Graph Analysis**: Understand package relationships and find alternatives
48
-
49
- ### 🔎 **GitHub Ecosystem Search**
50
- - **Repository Discovery**: Find relevant projects by keywords, language, topics, stars, and activity
51
- - **Development History**: Track code evolution through commits, pull requests, and releases
52
- - **Issue & Bug Tracking**: Discover bugs, feature requests, and community-driven solutions
53
- - **Pull Request Analysis**: Review implementation approaches, code quality, and merge patterns
54
-
55
- ### 👥 **Community & Collaboration**
56
- - **GitHub Discussions**: Access Q&A, tutorials, and community wisdom
57
- - **User & Organization Discovery**: Find experts, contributors, and active developers
58
- - **Team Collaboration Analysis**: Track contributions, knowledge sharing, and code reuse patterns
59
- - **Organization Intelligence**: Automatic detection and access to private repositories
60
-
61
- ### 🏷️ **Technology & Topic Exploration**
62
- - **Topic Discovery**: Explore trending technologies and ecosystems with community validation
63
- - **Technology Assessment**: Evaluate libraries, frameworks, and tools adoption
64
- - **Featured Content**: Access GitHub-curated and community-maintained topics
65
-
66
- ### 🔐 **Security & Access Management**
67
- - **Secure Authentication**: Integrated GitHub CLI and NPM authentication
68
- - **Private Repository Access**: Organization-aware access control for enterprise environments
69
- - **Local Execution**: All operations run locally using your existing permissions
70
- - **No Data Sharing**: Ensures privacy and security of your code and credentials
71
199
 
72
- ### ⚡ **Performance & Intelligence**
73
- - **Built-in Caching**: Intelligent result caching with configurable timeouts
74
- - **Rate Limiting**: Prevents API quota exhaustion with smart request management
75
- - **Progressive Search**: Adaptive search strategies from broad to specific
76
- - **Configurable Results**: Optimized result limits for different use cases
200
+ ### 📋 **Development History & Collaboration**
201
+ - **`search_github_commits`**: Advanced GitHub commits search for development history analysis
202
+ - **`search_github_pull_requests`**: Code review and feature analysis with quality focus
203
+ - **`search_github_issues`**: Problem discovery and solution research with pattern analysis
204
+ - **`search_github_discussions`**: Community knowledge discovery for Q&A and tutorials
77
205
 
78
- ### 🐞 **Advanced Bug Analysis**
79
- - **Multi-Repository Bug Understanding**: Correlate issues across related repositories
80
- - **Historical Bug Analysis**: Track bug patterns and resolution strategies
81
- - **Security Vulnerability Tracking**: Identify and analyze security-related issues
82
- - **Root Cause Analysis**: Trace bugs through commit history and discussions
83
-
84
- ### 🌐 **Remote Code Analysis**
85
- - **Cross-Platform Analysis**: Analyze code from any accessible repository
86
- - **Architecture Understanding**: Explore and document system architectures
87
- - **Code Quality Assessment**: Evaluate code patterns and implementation quality
88
- - **Documentation Generation**: Create comprehensive documentation from any source
89
-
90
- ### 📊 **Enterprise & Management Features**
91
- - **Repository Health Assessment**: Evaluate maintenance status and activity levels
92
- - **Compliance & Licensing**: Audit licenses and compliance across repositories
93
- - **Developer Productivity Insights**: Analyze contribution patterns and team efficiency
94
- - **Strategic Technology Planning**: Research adoption trends and migration patterns
95
-
96
- ## How It Works
97
-
98
- This tool utilizes the `gh` CLI along with the `yarn` CLI and strong prompts to collect information based on the user's permissions. All operations are executed locally, ensuring that no data is shared externally with the tool. This method takes advantage of the user's existing access rights and configurations to deliver insights and analysis without compromising security or privacy.
99
-
100
- ## Table of Contents
101
-
102
- - [Installation & Setup](#installation--setup)
103
- - [Authentication](#authentication)
104
- - [Features](#features)
105
- - [Available Tools](#available-tools)
106
- - [Usage Examples](#usage-examples)
107
- - [Advanced Configuration](#advanced-configuration)
108
- - [Best Practices](#best-practices)
109
- - [Troubleshooting](#troubleshooting)
110
- - [Contributing](#contributing)
111
- - [License](#license)
206
+ ### 👥 **User & Organization Management**
207
+ - **`search_github_users`**: Advanced developer and organization discovery
208
+ - **`get_user_organizations`**: Automatic private repository discovery for enterprise environments
209
+ - **`search_github_topics`**: Vital foundation tool for effective GitHub discovery
210
+
211
+ ### 🎯 **Smart Features**
212
+ - **Automatic Query Optimization**: Built-in search strategy optimization
213
+ - **Chain-of-Thought Reasoning**: 6-step reasoning methodology for complex queries
214
+ - **Teaching Methodology Integration**: AI education built into tool descriptions
215
+ - **Progressive Search Refinement**: Phase-based search from broad to precise
216
+ - **Cross-validation Workflows**: Multi-step research flows with tool interconnection
217
+
218
+ ## 📚 Usage Examples
112
219
 
113
- ## Installation & Setup
220
+ ### Basic Code Discovery
221
+ ```bash
222
+ # Find React hooks implementations
223
+ "Show me examples of custom React hooks for data fetching"
114
224
 
115
- ### Prerequisites
225
+ # Explore API patterns
226
+ "How do popular libraries implement rate limiting? Show code examples"
227
+ ```
116
228
 
117
- #### Required Software
118
- - **Node.js**: Version 21 or higher
119
- - **GitHub CLI**: For GitHub authentication and API access
120
- - **NPM**: For package management and analysis
229
+ ### Advanced Research
230
+ ```bash
231
+ # Deep architectural analysis
232
+ "From code and PRs, how did React implement concurrent rendering?"
121
233
 
234
+ # Cross-repository investigation
235
+ "Show the langchain code examples from my organization"
236
+ ```
122
237
 
123
- #### Install GitHub CLI & Login
238
+ ### Learning & Documentation
239
+ ```bash
240
+ # Best practices discovery
241
+ "Best ways from code examples to use routing in Next.js"
124
242
 
243
+ # Documentation generation
244
+ "Make docs of lodash based on actual implementation"
245
+ ```
246
+
247
+ ### Historical Analysis
248
+ ```bash
249
+ # Project evolution tracking
250
+ "Show progress of React project in the recent 5 years"
251
+
252
+ # Comparative analysis
253
+ "How is Vue rendering architecture different than React? Check from code"
254
+ ```
255
+
256
+ ### Code Review & Improvement
257
+ ```bash
258
+ # Code analysis and suggestions
259
+ "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"
260
+ ```
261
+
262
+ ## 💡 Tips for Effective Usage
263
+
264
+ ### 🎯 **Search Strategy Tips**
265
+ - **🔍 Be Specific**: Use specific library names, repository URLs, or exact function names for better results
266
+ - Good: *"Show me how the `useEffect` hook works in React"*
267
+ - Better: *"Show me `useEffect` cleanup patterns in facebook/react repository"*
268
+
269
+ - **🎭 Deep Analysis Requires Multiple Prompts**: Most comprehensive analysis will require more than one prompt
270
+ - Start broad, then drill down into specific areas of interest
271
+ - Use follow-up questions to explore different aspects
272
+
273
+ ### 📚 **Documentation & Knowledge Management**
274
+ - **📝 Create Documentation**: Create documentation of topics important to you and reference it from Cursor or chat sessions
275
+ - *"Create a comprehensive guide about Next.js routing based on real examples"*
276
+ - Then use that documentation as reference for future development
277
+
278
+ - **🔄 Iterative Learning**: Use the tool to build knowledge progressively
279
+ - Session 1: "What is server-side rendering?"
280
+ - Session 2: "Show me SSR implementations in Next.js"
281
+ - Session 3: "Compare SSR vs SSG in production applications"
282
+
283
+ ### ⚡ **Performance & Limitations**
284
+ - **🚦 Rate Limiting Awareness**: GitHub has API rate limits for file fetching
285
+ - This tool has optimizations to manage rate limits efficiently
286
+ - **Not designed for bulk operations** like *"show all files in my org using XYZ"*
287
+ - Focus on targeted analysis rather than exhaustive scans
288
+
289
+ - **🎯 Quality Over Quantity**: Better to get precise, high-quality results than overwhelming amounts of data
290
+ - Use filters and specific queries to narrow down results
291
+ - Combine multiple focused searches rather than one broad search
292
+
293
+ ### 🔗 **Cross-Repository Analysis**
294
+ - **🏢 Organization Context**: Mention your organization or company for internal repository access
295
+ - *"Show authentication patterns used in our team's repositories"*
296
+ - The tool will automatically detect and use your organization access
297
+
298
+ - **📦 Package-Based Discovery**: Mention specific packages to trigger automatic repository discovery
299
+ - *"How does the lodash library implement debouncing?"* -> Automatically finds and analyzes lodash repository
300
+
301
+ ### 🎨 **Advanced Use Cases**
302
+ - **🔬 Comparative Analysis**: Compare different approaches across repositories
303
+ - *"How do GraphQL implementations differ between Apollo and Relay?"*
304
+
305
+ - **📈 Evolution Tracking**: Understand how projects evolved over time
306
+ - *"Show the major architectural changes in React over the past 2 years"*
307
+
308
+ - **🛠️ Implementation Patterns**: Find real-world usage patterns
309
+ - *"Show me production examples of microservices communication patterns"*
310
+
311
+ ### 🚀 **Pro Tips**
312
+ - **🔧 Combine Tools**: Use multiple MCP tools together for comprehensive analysis
313
+ - **📊 Context Building**: Build context over multiple interactions for deeper insights
314
+ - **🎯 Focus Areas**: Target specific areas of interest rather than general exploration
315
+ - **📱 Real Examples**: Always ask for real code examples rather than theoretical explanations
316
+
317
+ ## 🛠 Installation & Setup
318
+
319
+ ### 🚀 **Works Out Of The Box (OOTB) - Any Environment!**
320
+
321
+ **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!**
322
+
323
+ ### Step 1: Install Prerequisites
324
+
325
+ #### Install Node.js (21+)
326
+ ```bash
327
+ # macOS with Homebrew
328
+ brew install node
329
+
330
+ # Or download from https://nodejs.org/
331
+ # Verify installation
332
+ node --version # Should be 21+
333
+ ```
334
+
335
+ #### Install GitHub CLI
125
336
  ```bash
126
337
  # macOS
127
338
  brew install gh
128
- gh auth login
339
+
340
+ # Windows (with Chocolatey)
341
+ choco install gh
342
+
343
+ # Windows (with Scoop)
344
+ scoop install gh
345
+
346
+ # Linux (Debian/Ubuntu)
347
+ sudo apt update && sudo apt install gh
129
348
 
130
349
  # Other platforms: https://github.com/cli/cli#installation
131
- # Open authentication in web browser and complete login flow
132
350
  ```
133
351
 
134
- #### Verify setup
135
- ```bash
136
- # Check versions
137
- node --version # Should be 21+
138
- gh --version
139
- gh auth status # Should show authenticated
140
- ```
352
+ #### Install NPM (usually comes with Node.js)
353
+ ```bash
354
+ # Verify NPM installation
355
+ npm --version
356
+ ```
141
357
 
142
- #### Configure MCP Client:
358
+ ### Step 2: Authentication Setup
143
359
 
144
- ```json
145
- {
146
- "name": "octocode-mcp",
147
- "command": "npx",
148
- "args": ["octocode-mcp"]
149
- }
150
- ```
360
+ #### GitHub CLI Authentication
361
+ ```bash
362
+ # Login to GitHub (opens web browser)
363
+ gh auth login
151
364
 
152
- ### NPM Configuration
153
- Ensure your `.npmrc` files are properly configured
365
+ # Select options:
366
+ # 1. GitHub.com (for public repos) or GitHub Enterprise Server
367
+ # 2. HTTPS (recommended)
368
+ # 3. Login with a web browser (easier and more secure)
369
+
370
+ # Verify authentication
371
+ gh auth status
372
+ # Should show: ✓ Logged in to github.com as [your-username]
373
+ ```
374
+
375
+ #### NPM Authentication (for private packages)
154
376
  ```bash
155
- # Check NPM configuration
377
+ # For npm registry
378
+ npm login
379
+
380
+ # For private registries, check your .npmrc
156
381
  npm config list
157
- npm whoami # Verify authentication for private registries
382
+ npm whoami # Verify authentication
158
383
  ```
159
384
 
160
- ## Available Tools
385
+ ### Step 3: MCP Configuration
161
386
 
162
- ### Code & Repository Search
163
- - **Search GitHub Code**: Find specific implementations, functions, and patterns
164
- - **Repository Discovery**: Locate relevant projects and libraries by keywords
165
- - **File Content Analysis**: Fetch complete source files with dependency tracking
166
- - **Repository Structure**: Explore project organization and architecture
387
+ **This is the only configuration you need!** Add this to your MCP client configuration:
167
388
 
168
- ### Package & Dependency Management
169
- - **NPM Package Analysis**: Get detailed package information and metadata
170
- - **NPM Registry Search**: Discover packages by functionality and keywords
171
- - **Dependency Mapping**: Understand package relationships and alternatives
389
+ ```json
390
+ {
391
+ "octocode-mcp": {
392
+ "command": "npx",
393
+ "args": [
394
+ "octocode-mcp"
395
+ ]
396
+ }
397
+ }
398
+ ```
172
399
 
173
- ### Development History & Collaboration
174
- - **Commit History**: Track code evolution and find specific changes
175
- - **Pull Request Analysis**: Review implementation approaches and code quality
176
- - **Issue Tracking**: Find bugs, feature requests, and community discussions
177
- - **User & Organization Discovery**: Identify experts and active contributors
400
+ ### 🎉 **That's It! Ready To Use**
401
+
402
+ **No installation needed** - `npx` will automatically download and run the latest version
403
+ **No environment variables** - Uses your existing GitHub CLI authentication
404
+ **No configuration files** - Works with your current permissions
405
+ **No tokens to manage** - Secure authentication handled automatically
406
+ **Works everywhere** - Any OS, any environment, any setup
407
+
408
+ ## 🔒 Privacy & Local Operation
409
+
410
+ **🏠 100% Local Execution** - Octocode MCP runs entirely on your machine. No remote servers, no cloud processing, no data transmission to third parties.
411
+
412
+ **🚫 Zero Data Collection** - We don't collect, store, or transmit any of your data, search queries, or repository information. Everything stays on your machine.
413
+
414
+ **🔑 Your Credentials, Your Control** - All API calls use your existing CLI configurations:
415
+ - **GitHub**: Uses your `gh` CLI authentication and permissions
416
+ - **NPM**: Uses your local `.npmrc` and `npm` CLI configuration
417
+ - **No Token Sharing**: Your authentication tokens never leave your machine
418
+
419
+ **🛡️ 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.
420
+
421
+ ### Optional: Verify Setup
422
+ ```bash
423
+ # Check all components
424
+ node --version # Should be 21+
425
+ gh --version # Should show version
426
+ gh auth status # Should show authenticated
427
+ npm --version # Should show version
428
+
429
+ # Test NPX execution (optional)
430
+ npx octocode-mcp --help
431
+ ```
432
+
433
+ ### 🌟 **Alternative Installation Options**
434
+
435
+ #### Option A: Global Installation (if you prefer)
436
+ ```bash
437
+ # Install globally
438
+ yarn global add octocode-mcp
439
+ # or
440
+ npm install -g octocode-mcp
441
+
442
+ # Then use this MCP configuration:
443
+ {
444
+ "octocode-mcp": {
445
+ "command": "octocode-mcp"
446
+ }
447
+ }
448
+ ```
449
+
450
+ #### Option B: NPX (Recommended - Always Latest)
451
+ ```bash
452
+ # No installation needed - NPX handles everything
453
+ # Just use the MCP configuration above! ⬆️
454
+ ```
178
455
 
179
- ### Community & Knowledge
180
- - **GitHub Discussions**: Access Q&A, tutorials, and community wisdom
181
- - **Topic Exploration**: Discover trending technologies and ecosystems
182
- - **Documentation Access**: Find READMEs, guides, and best practices
456
+ ## 🔒 Why Different Than Static PAT
183
457
 
184
- ## Advanced Configuration
458
+ ### Traditional GitHub MCPs Challenges:
459
+ ❌ **Manual PAT Management**: Create, store, rotate personal access tokens manually
460
+ ❌ **Security Risks**: Tokens in config files, potential exposure
461
+ ❌ **Limited Scope**: Fixed permissions, hard to manage different access levels
462
+ ❌ **Expiration Issues**: Tokens expire, breaking workflows
463
+ ❌ **No SSO Integration**: Doesn't work with enterprise SSO/SAML
464
+
465
+ ### Octocode MCP Approach:
466
+ ✅ **Zero Configuration**: Uses existing GitHub CLI authentication
467
+ ✅ **Automatic Security**: Leverages GitHub's secure OAuth flow
468
+ ✅ **Dynamic Permissions**: Uses your actual GitHub permissions
469
+ ✅ **SSO Compatible**: Works seamlessly with enterprise authentication
470
+ ✅ **No Token Management**: GitHub CLI handles all authentication automatically
471
+ ✅ **Better Security**: No tokens stored in files or transmitted
472
+
473
+ ## License
474
+
475
+ MIT License - See [LICENSE](./LICENSE.md) for details.
476
+
477
+ ## ⚙️ Advanced Configuration
185
478
 
186
479
  ### Rate Limiting & Performance
187
- - Built-in rate limiting prevents API quota exhaustion
188
- - Configurable result limits for optimal performance
189
- - Intelligent caching reduces redundant requests
480
+ - **Built-in Rate Limiting**: Prevents API quota exhaustion with smart request management
481
+ - **Intelligent Caching**: Result caching with configurable timeouts
482
+ - **Progressive Search**: Adaptive search strategies from broad to specific
483
+ - **Configurable Results**: Optimized result limits for different use cases
190
484
 
191
485
  ### Authentication Management
192
- - Seamless GitHub CLI integration
193
- - NPM registry authentication support
194
- - Organization-aware access control
486
+ - **Seamless GitHub CLI Integration**: Zero-configuration authentication
487
+ - **NPM Registry Support**: Private package access with existing credentials
488
+ - **Organization-aware Access**: Automatic detection and private repository access
489
+ - **Local Execution**: All operations run locally using your existing permissions
195
490
 
196
- ## Best Practices
491
+ ### NPM Configuration
492
+ ```bash
493
+ # Check your NPM configuration
494
+ npm config list
495
+ npm whoami # Verify authentication for private registries
496
+
497
+ # Configure for private registries if needed
498
+ echo "@your-org:registry=https://npm.your-company.com/" >> ~/.npmrc
499
+ ```
500
+
501
+ ## 🎯 Best Practices
197
502
 
198
503
  ### Search Strategy
199
- - **Start Broad**: Begin with general terms, then narrow down
504
+ - **Start Broad**: Begin with general terms, then narrow down based on findings
200
505
  - **Use Progressive Discovery**: Combine multiple tools for comprehensive understanding
201
506
  - **Leverage Organizations**: Use your team's GitHub org for internal discovery
202
507
  - **Cross-Reference Sources**: Combine code, issues, and discussions for complete context
203
508
 
204
509
  ### Performance Optimization
205
- - Use specific repository filters when possible
206
- - Combine related searches in single sessions
207
- - Cache frequently accessed information
208
- - Monitor API rate limits
510
+ - **Use Specific Repository Filters**: When you know the target repository
511
+ - **Combine Related Searches**: In single sessions for efficiency
512
+ - **Monitor API Rate Limits**: Built-in management prevents quota exhaustion
513
+ - **Cache Frequently Accessed Information**: Automatic intelligent caching
514
+
515
+ ### Tool Chaining Best Practices
516
+ - **Start with Topics**: Use `search_github_topics` for proper terminology discovery
517
+ - **Repository Discovery**: Use discovered topic names in `search_github_repos`
518
+ - **Organization Context**: Let automatic detection handle private repository access
519
+ - **Package Research**: Mention packages to trigger automatic NPM-to-repository mapping
209
520
 
210
- ## Troubleshooting
521
+ ## 🐛 Troubleshooting
522
+
523
+ ### Authentication Issues
524
+ ```bash
525
+ # Check GitHub CLI status
526
+ gh auth status
527
+ # Should show: ✓ Logged in to github.com as [username]
528
+
529
+ # Re-authenticate if needed
530
+ gh auth logout
531
+ gh auth login
532
+
533
+ # Check NPM authentication
534
+ npm whoami
535
+ ```
211
536
 
212
537
  ### Common Issues
213
- - **Authentication Errors**: Verify `gh auth status` and NPM login
214
- - **No Results**: Try broader search terms or different organizations
215
- - **Rate Limiting**: Reduce search frequency or use more specific filters
216
- - **Private Repository Access**: Ensure proper organization membership
217
- - **NPX cache**: To reset the npx cache, you can manually delete the cache directory. The location of the npx cache can vary based on your operating system. Typically, it is located in the `.npm/_npx` directory within your home folder. You can remove this directory using a command like `rm -rf ~/.npm/_npx` on Unix-based systems or by deleting it through File Explorer on Windows.
538
+ - **No Results Found**: Try broader search terms or check organization filters
539
+ - **Rate Limiting**: Built-in management should prevent this, but reduce frequency if needed
540
+ - **Private Repository Access**: Ensure proper organization membership via `gh auth status`
541
+ - **NPX Cache Issues**: Clear cache with `rm -rf ~/.npm/_npx` (Unix) or delete via File Explorer (Windows)
542
+
543
+ ### NPM Configuration Issues
544
+ ```bash
545
+ # View current configuration
546
+ npm config list
547
+
548
+ # Check for common issues:
549
+ # - Registry URL correctness
550
+ # - Authentication tokens validity
551
+ # - Proxy settings (if behind firewall)
552
+ # - Syntax errors in .npmrc
553
+
554
+ # Reset NPM configuration if needed
555
+ rm ~/.npmrc
556
+ npm login
557
+ ```
558
+
218
559
  ### Misconfigured .npmrc File
560
+ 1. **Locate .npmrc files**: Project-level (./), User-level (~/.npmrc), Global-level
561
+ 2. **Check for common issues**: Registry URL, auth tokens, proxy settings, syntax errors
562
+ 3. **View configuration**: `npm config list`
563
+ 4. **Test after changes**: `yarn install` or `npm install`
219
564
 
220
- A misconfigured `.npmrc` file can lead to various issues, such as authentication errors, incorrect registry settings, or unexpected behavior during package installations. Here's how you can check and troubleshoot your `.npmrc` file:
565
+ ### Development Setup
566
+ ```bash
567
+ # Clone repository
568
+ git clone https://github.com/your-org/octocode-mcp.git
569
+ cd octocode-mcp
221
570
 
222
- 1. **Locate the .npmrc File**:
223
- - The `.npmrc` file can exist in multiple locations, affecting different scopes:
224
- - **Project-level**: Located in the root of your project directory.
225
- - **User-level**: Located in your home directory (`~/.npmrc`).
226
- - **Global-level**: Located in the global npm configuration directory.
571
+ # Install dependencies
572
+ yarn install
227
573
 
228
- 2. **Check for Common Issues**:
229
- - **Registry URL**: Ensure the registry URL is correct. For example, it should be `https://registry.yarnpkg.com/` if using Yarn.
230
- - **Authentication Tokens**: Verify that authentication tokens are correctly set and not expired.
231
- - **Proxy Settings**: If you're behind a proxy, ensure proxy settings are correctly configured.
232
- - **Syntax Errors**: Check for any syntax errors or invalid entries.
574
+ # Run development server
575
+ yarn build
233
576
 
234
- 3. **View Current Configuration**:
235
- - Use the following command to view the current npm configuration, including settings from all `.npmrc` files:
236
- ```bash
237
- npm config list
238
- ```
577
+ // Configuration local MCP
578
+ // "octocode-mcp-local": {
579
+ // "command": "node",
580
+ // "args": [
581
+ // "PATH_TO_OCTOCODE_MCP/octocode-mcp/dist/index.js"
582
+ // ]
583
+ // }
239
584
 
240
- 4. **Edit the .npmrc File**:
241
- - Open the `.npmrc` file in a text editor to make necessary corrections. Ensure that sensitive information, like tokens, is not exposed in version control.
585
+ ```
242
586
 
243
- 5. **Test Configuration**:
244
- - After making changes, test the configuration by running a simple npm command, such as:
245
- ```bash
246
- yarn install
247
- ```
248
- - Ensure that the command executes without errors.
587
+ ## Disclaimer
249
588
 
250
- By following these steps, you can identify and resolve issues related to a misconfigured `.npmrc` file, ensuring smooth package management operations.
589
+ **This is a personal side project** developed to solve real-world code discovery challenges. While functional and useful, please keep in mind:
251
590
 
252
- ### Prefered models
591
+ - **🚧 Work in Progress**: Some improvements and optimizations are still needed
592
+ - **🎯 Intentionally Lean**: Designed to be simple and lightweight - no unnecessary overhead or complexity
593
+ - **🔬 Experimental**: As with any side project, expect occasional rough edges and areas for improvement
253
594
 
254
- ## License
595
+ ---
255
596
 
256
- MIT License - See [LICENSE](./LICENSE) for details.
257
597
 
258
598
 
259
599