octocode-mcp 2.3.2 → 2.3.4

package/README.md

@@ -5,7 +5,7 @@
 <div>
   <img src="./assets/logo.png">
   
-  [![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](./package.json)
+  [![Version](https://img.shields.io/badge/version-2.3.2-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/)
 </div>
@@ -55,7 +55,7 @@ It's the tool you reach for when you need to understand *"how does this work?"*
 
 ### 1. Install Prerequisites
 ```bash
-# Install Node.js 21+
+# Install Node.js 18.12+
 brew install node  # macOS
 # or download from https://nodejs.org/
 
@@ -93,35 +93,44 @@ npm login
 
 **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**.
 
-## Example Questions 💬
+![Installation Demo](assets/installation.gif)
 
-**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?"*
 
-**Architecture & Patterns:**
-- *"How is authentication handled in enterprise applications?"*
-- *"Show me microservices communication patterns"*
-- *"Find examples of event-driven architecture implementations"*
+## How Octocode Works 🔄
 
-**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"*
+**Smart Discovery Flow:**
+1. **🔍 Query Analysis** → AI determines the best search strategy based on your question
+2. **⚡ Multi-Tool Orchestration** → Combines GitHub + NPM searches intelligently
+3. **🔄 Smart Fallbacks** → Automatically retries with different approaches if initial search fails
+4. **🔗 Cross-Reference Discovery** → Links packages to repositories, finds related implementations
+5. **🎯 Context Synthesis** → Provides comprehensive understanding across multiple sources
 
-**Specific Code Analysis:**
-- *"How does lodash implement debouncing?"*
-- *"Show usage examples of this API: `createContext`"*
-- *"Find React hooks patterns for data fetching"*
+## Example Flows
+
+### Example 1: LangGraph Node.js Implementation Tutorial
+**Query:** "Show implementations of langgraph in node js. Make a tutorial for how to implement a simple agent using OpenAI API."
+
+![LangGraph Node.js Tutorial](assets/langchainTutorial.gif)
+
+### Example 2: Zustand React State Management
+**Query:** "Show me how to add zustand to react application. Show examples and best practices"
+
+![Zustand React State Management](assets/reactZustand.gif)
+
+### Example 3: React vs Vue.js Rendering Comparison
+**Query:** "How did React implement their concurrent rendering flows? How is it different from Vue.js rendering mechanism? Which is better?"
+
+![React vs Vue.js Rendering Comparison](assets/reactVSVueJS.gif)
 
 ## Core Features 🛠️
 
 ### 🧠 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
+- **Smart Fallback Strategies** - Automatically tries alternative approaches when searches fail with actionable suggestions
+- **Boolean Search Intelligence** - Automatic query optimization with smart boolean operators (3-5x performance improvement)
 - **Context-Aware Discovery** - Understands code relationships and suggests related implementations
 - **Multi-Strategy Search** - Combines semantic, syntactic, and dependency-based search methods
+- **Graceful Error Recovery** - Comprehensive error handling with intelligent retry mechanisms
 
 ### 🔗 Connection Intelligence
 - **Repository-Package Mapping** - Automatically links NPM packages to their GitHub repositories
@@ -148,6 +157,24 @@ npm login
 - **🔑 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
 
+### Command Execution Security 🔒
+
+**Robust protection against prompt injections and malicious command execution:**
+
+- **⚪ Allowlisted Commands Only** - Only pre-approved, safe NPM and GitHub CLI commands are executable
+  - NPM: `view`, `search`, `ping`, `config`, `whoami` 
+  - GitHub CLI: `search`, `api`, `auth`, `org`
+- **🛡️ Argument Sanitization** - All command arguments are properly escaped to prevent shell injection attacks
+- **✅ Pre-execution Validation** - Every command is validated against allowed lists before execution
+- **🔧 Controlled Environment** - Commands run in a secure, cross-platform shell environment with controlled variables
+  - **Cross-platform shells**: Uses `/bin/sh` on Unix/macOS, `cmd.exe` or `powershell.exe` on Windows - minimal, standard shells
+  - **PowerShell support**: Modern Windows environments can optionally use PowerShell with enhanced security
+  - **Why minimal shells are safe**: Avoids user's potentially customized shells with aliases, functions, plugins, or advanced features
+  - **Controlled variables**: Only essential environment variables (`PATH`, `SHELL`) are passed, preventing environment-based attacks
+  - **Platform-specific escaping**: Uses appropriate argument escaping for each platform (single quotes on Unix, double quotes for CMD, single quotes for PowerShell)
+- **🚫 No Arbitrary Execution** - System cannot execute arbitrary shell commands or scripts
+- **⏱️ Timeout Protection** - All commands have execution timeouts to prevent resource exhaustion
+
 ## Best Practices 💡
 
 **AI-Powered Search Tips:**
@@ -193,6 +220,12 @@ npm whoami
 - **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
 
+**💻 Windows PowerShell Support:**
+- **Modern shell support** - Optionally use PowerShell instead of cmd.exe on Windows
+- **Enhanced security** - PowerShell provides better argument escaping and modern features
+- **Automatic detection** - The system automatically detects Windows and applies appropriate shell configurations
+- **Zero configuration** - Works seamlessly with existing setups, no additional configuration needed
+
 **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

package/build/index.js

@@ -3,40 +3,44 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { platform } from 'os';
 import NodeCache from 'node-cache';
 import crypto from 'crypto';
 import z from 'zod';
 
-const PROMPT_SYSTEM_PROMPT = `You are an expert code research assistant for developers doing smart research in GitHub and NPM ecosystems (public/private).
-You leverage powerful semantic search using GitHub (gh) and NPM CLI for code discovery.
+const PROMPT_SYSTEM_PROMPT = `Expert code research assistant for GitHub/NPM ecosystems (public/private). Use powerful semantic search for efficient code discovery.
 
-IMPORTANT: check users github organizations and use them in github search tools if needed
+CORE TOOLS:
+ GitHub: Code, repos, issues, PRs, commits - supports boolean logic (AND/OR/NOT) and exact phrases
+ NPM: Package search (fuzzy only, no boolean) + metadata (repo URLs, exports, dependencies)
+ API Status: Check connectivity + user's GitHub organizations for private access
 
-TOOLS:
-- API status: Check npm/gh connectivity and find user's GitHub organizations (for private repo access)
-- GitHub: Search code, repositories, issues, pull requests, commits
-- NPM: Search packages, view metadata (git URL, exports, dependencies, versions with dates)
+SEARCH STRATEGIES:
+GitHub Code/Issues/PRs/Commits:
+ OR (broad): "useState OR setState" - finds alternatives  
+ AND (precise): "react AND hooks" - requires both terms
+ NOT (filter): "auth NOT test" - excludes noise
+ Quotes (exact): "useEffect cleanup" - literal phrases
+ Combine with filters: language, path, owner for focus
 
-APPROACH:
-- Once code/project path is found from tools use it and research it for more data
-- Understand queries semantically to choose optimal tools
-- Optimize tools calls data and be smart about it (e.g. is some tool get information don't use other tools to get the same information)
-- Prioritize efficient, targeted searches with smart fallbacks
-- Use strategic tool combinations for comprehensive results an
-- Balance speed vs throughness based on query type
+NPM Search:
+ Space-separated keywords only: "react state management"
+ No boolean operators supported
+ Use npm_view_package for direct package metadata → GitHub repo URL
 
-GITHUB SEARCH STRATEGY:
-- OR: Explore alternatives ("useState OR setState OR setData")
-- AND: Precise requirements ("react AND testing AND hooks")  
-- NOT: Filter noise ("auth NOT test NOT mock")
-- Quotes: Exact phrases ("import React", "useEffect cleanup")
-- Mix with filters: language, path, repo for laser focus
+OPTIMIZATION:
+ Check user's GitHub orgs for private repo access
+ npm_view_package gives repo URL instantly - avoid GitHub repo search
+ Use targeted searches, avoid redundant tool calls
+ Combine tools strategically: NPM → GitHub file content
+ Discovery: comprehensive multi-tool approach
+ Direct queries: quick targeted approach
 
-GUIDELINES:
-- Discovery queries ("How X works?"): Be comprehensive, use multiple tools strategically
-- Direct queries ("Where is X package repo?"): Use quick, targeted approach
-- Always provide referenced code snippets and documentation
-- Search docs (README.md) for quality information about code flow and architecture`;
+ CLI Help using CLI (use when needed to check failures)
+ gh <command>  --help
+ npm <command> --help
+
+Always provide code snippets and documentation references.`;
 
 function createResult(data, isError = false, suggestions) {
     const text = isError
@@ -133,6 +137,86 @@ function isValidNpmCommand(command) {
 function isValidGhCommand(command) {
     return ALLOWED_GH_COMMANDS.includes(command);
 }
+/**
+ * Get platform-specific shell configuration with PowerShell support
+ */
+function getShellConfig(preferredWindowsShell) {
+    const isWindows = platform() === 'win32';
+    if (!isWindows) {
+        return {
+            shell: '/bin/sh',
+            shellEnv: '/bin/sh',
+            type: 'unix',
+        };
+    }
+    // Windows shell selection
+    const usesPowerShell = preferredWindowsShell === 'powershell';
+    if (usesPowerShell) {
+        return {
+            shell: 'powershell.exe',
+            shellEnv: 'powershell.exe',
+            type: 'powershell',
+        };
+    }
+    return {
+        shell: 'cmd.exe',
+        shellEnv: 'cmd.exe',
+        type: 'cmd',
+    };
+}
+/**
+ * Escape shell arguments to prevent shell injection and handle special characters
+ * Cross-platform compatible escaping for Windows CMD, PowerShell, and Unix shells
+ */
+function escapeShellArg(arg, shellType) {
+    // Auto-detect shell type if not provided
+    if (!shellType) {
+        const isWindows = platform() === 'win32';
+        shellType = isWindows ? 'cmd' : 'unix';
+    }
+    switch (shellType) {
+        case 'powershell':
+            return escapePowerShellArg(arg);
+        case 'cmd':
+            return escapeWindowsCmdArg(arg);
+        case 'unix':
+        default:
+            return escapeUnixShellArg(arg);
+    }
+}
+/**
+ * Escape arguments for PowerShell
+ * PowerShell uses single quotes for literal strings and has special escaping rules
+ */
+function escapePowerShellArg(arg) {
+    // PowerShell special characters that need escaping
+    if (/[\s&<>|;`$@"'()[\]{}]/.test(arg)) {
+        // Use single quotes for literal strings in PowerShell
+        // Escape single quotes by doubling them
+        return `'${arg.replace(/'/g, "''")}'`;
+    }
+    return arg;
+}
+/**
+ * Escape arguments for Windows CMD
+ */
+function escapeWindowsCmdArg(arg) {
+    // Windows CMD escaping
+    if (/[\s&<>|^"]/.test(arg)) {
+        return `"${arg.replace(/"/g, '""')}"`;
+    }
+    return arg;
+}
+/**
+ * Escape arguments for Unix shells (/bin/sh, bash, etc.)
+ */
+function escapeUnixShellArg(arg) {
+    // Unix shell escaping
+    if (/[^\w\-._/:=@]/.test(arg)) {
+        return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+    }
+    return arg;
+}
 /**
  * Execute NPM commands safely by validating against allowed commands
  * Security: Only executes commands that start with "npm {ALLOWED_COMMAND}"
@@ -142,27 +226,22 @@ async function executeNpmCommand(command, args = [], options = {}) {
     if (!isValidNpmCommand(command)) {
         return createErrorResult('Command not registered', new Error(`NPM command '${command}' is not in the allowed list`));
     }
+    // Get shell configuration
+    const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    const escapedArgs = args.map(escapeShellArg);
+    const escapedArgs = args.map(arg => escapeShellArg(arg, shellConfig.type));
     const fullCommand = `npm ${command} ${escapedArgs.join(' ')}`;
-    const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options);
+    const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options, shellConfig);
     if (options.cache) {
-        const cacheKey = generateCacheKey('npm-exec', { command, args });
+        const cacheKey = generateCacheKey('npm-exec', {
+            command,
+            args,
+            shell: shellConfig.type,
+        });
         return withCache(cacheKey, executeNpmCommand);
     }
     return executeNpmCommand();
 }
-/**
- * Escape shell arguments to prevent shell injection and handle special characters
- */
-function escapeShellArg(arg) {
-    // If the argument contains special characters, wrap it in single quotes
-    // and escape any single quotes within the argument
-    if (/[^\w\-._/:=@]/.test(arg)) {
-        return `'${arg.replace(/'/g, "'\"'\"'")}'`;
-    }
-    return arg;
-}
 /**
  * Execute GitHub CLI commands safely by validating against allowed commands
  * Security: Only executes commands that start with "gh {ALLOWED_COMMAND}"
@@ -172,12 +251,18 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     if (!isValidGhCommand(command)) {
         return createErrorResult('Command not registered', new Error(`GitHub command '${command}' is not in the allowed list`));
     }
+    // Get shell configuration
+    const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    const escapedArgs = args.map(escapeShellArg);
+    const escapedArgs = args.map(arg => escapeShellArg(arg, shellConfig.type));
     const fullCommand = `gh ${command} ${escapedArgs.join(' ')}`;
-    const executeGhCommand = () => executeCommand(fullCommand, 'github', options);
+    const executeGhCommand = () => executeCommand(fullCommand, 'github', options, shellConfig);
     if (options.cache) {
-        const cacheKey = generateCacheKey('gh-exec', { command, args });
+        const cacheKey = generateCacheKey('gh-exec', {
+            command,
+            args,
+            shell: shellConfig.type,
+        });
         return withCache(cacheKey, executeGhCommand);
     }
     return executeGhCommand();
@@ -186,21 +271,23 @@ async function executeGitHubCommand(command, args = [], options = {}) {
  * Execute shell commands with timeout and error handling
  * Security: Should only be called with pre-validated command prefixes
  */
-async function executeCommand(fullCommand, type, options = {}) {
+async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     try {
         const defaultTimeout = type === 'npm' ? 30000 : 60000;
+        const config = shellConfig || getShellConfig(options.windowsShell);
         const execOptions = {
             timeout: options.timeout || defaultTimeout,
+            maxBuffer: 5 * 1024 * 1024, // 5MB buffer limit (increased from default 1MB)
             cwd: options.cwd,
             env: {
                 ...process.env,
                 ...options.env,
-                // Ensure clean shell environment
-                SHELL: '/bin/sh',
+                // Ensure clean shell environment - cross-platform compatible
+                SHELL: config.shellEnv,
                 PATH: process.env.PATH,
             },
             encoding: 'utf-8',
-            shell: '/bin/sh', // Use sh instead of default shell
+            shell: config.shell, // Use platform-appropriate shell
         };
         const { stdout, stderr } = await safeExecAsync(fullCommand, execOptions);
         // Handle different warning patterns for npm vs gh
@@ -220,6 +307,9 @@ async function executeCommand(fullCommand, type, options = {}) {
             result: stdout,
             timestamp: new Date().toISOString(),
             type,
+            platform: platform(),
+            shell: config.shell,
+            shellType: config.type,
             ...(stderr && { warning: stderr }), // Include warnings but don't treat as error
         });
     }
@@ -359,32 +449,16 @@ function registerApiStatusCheckTool(server) {
 }
 
 const TOOL_NAME$8 = 'github_search_code';
-const DESCRIPTION$8 = `Search code across GitHub repositories using strategic boolean operators and filters usign "gh code search" command.
-
-STRATEGIC SEARCH PATTERNS:
-
- OR LOGIC (Exploratory Discovery):
-• Auto-applied to multi-word queries: "useState hook" → "useState OR hook"
-• Best for: Learning, finding alternatives, casting wide nets
-• Scope: BROADEST - finds files with ANY of the terms
-
-AND LOGIC (Precise Intersection):
-• Explicit requirement: "react AND hooks" requires BOTH terms present
-• Best for: Finding specific combinations, technology intersections
-• Scope: RESTRICTIVE - only files containing ALL terms
-
-EXACT PHRASE (Laser Targeting):
-• Escaped quotes: "useState hook" finds literal "useState hook" sequence
-• Best for: Documentation titles, specific API calls, exact implementations
-• Scope: MOST PRECISE - only exact sequence matches
-
-NOT LOGIC (Noise Filtering):
-• Exclude unwanted results: "authentication NOT test NOT mock"
-• Best for: Removing examples, tests, deprecated code
+const DESCRIPTION$8 = `Search code across GitHub repositories using strategic boolean operators and filters with "gh code search" command.
 
-RESTRICTIVENESS SCALE: OR < AND < Exact Phrase (Broadest → Most Precise)
+SEARCH PATTERNS:
+ OR (broad): "useState hook" → "useState OR hook" (auto-default for multi-word)
+ AND (precise): "react AND hooks" (both terms required)
+ NOT (filter): "auth NOT test" (exclude unwanted)
+ Exact phrases: "useState hook" (quoted for literal match)
+ Combine with filters: language, owner, path for laser focus
 
-COMBINE FILTERS: Mix query with language, owner, path filters for laser-focused results.`;
+RESTRICTIVENESS: OR (broadest) < AND < Exact Phrase (most precise)`;
 function registerGitHubSearchCodeTool(server) {
     server.tool(TOOL_NAME$8, DESCRIPTION$8, {
         query: z
@@ -444,8 +518,10 @@ function registerGitHubSearchCodeTool(server) {
         openWorldHint: true,
     }, async (args) => {
         try {
-            if (args.repo && !args.owner) {
-                return createResult('Repository search requires owner parameter - specify owner when searching specific repositories', true);
+            // Validate parameter combinations
+            const validationError = validateSearchParameters(args);
+            if (validationError) {
+                return createResult(validationError, true);
             }
             const result = await searchGitHubCode(args);
             if (result.isError) {
@@ -469,7 +545,12 @@ function registerGitHubSearchCodeTool(server) {
             });
         }
         catch (error) {
-            return createErrorResult$1('GitHub code search failed - check repository access or simplify query', error);
+            const errorMessage = error.message || '';
+            // Handle JSON parsing errors
+            if (errorMessage.includes('JSON')) {
+                return createErrorResult$1('GitHub CLI returned invalid response - check if GitHub CLI is up to date with "gh version" and try again', error);
+            }
+            return createErrorResult$1('GitHub code search failed - verify parameters and try with simpler query or specific filters (language, owner, path)', error);
         }
     });
 }
@@ -489,10 +570,12 @@ function parseSearchQuery(query, filters) {
         exactPhrases.push(match);
         processedQuery = processedQuery.replace(match, placeholder);
     });
-    // Step 3: Smart boolean logic - default to OR between terms if no explicit operators
+    // Step 3: Check complexity BEFORE adding auto-OR logic
+    const originalHasComplexLogic = hasComplexBooleanLogic(processedQuery);
+    // Step 4: Smart boolean logic - default to OR between terms if no explicit operators
     let searchQuery = processedQuery;
     // Check if query already has explicit boolean operators
-    if (!hasComplexBooleanLogic(processedQuery)) {
+    if (!originalHasComplexLogic) {
         // Split by whitespace and join with OR for better search results
         const terms = processedQuery
             .trim()
@@ -502,21 +585,22 @@ function parseSearchQuery(query, filters) {
             searchQuery = terms.join(' OR ');
         }
     }
-    // Step 4: Add GitHub-specific filters that go in the query string
+    // Step 5: Handle filters differently based on ORIGINAL query complexity
     const githubFilters = [];
+    // Always add path and visibility to query string (they don't have CLI equivalents)
     if (filters.path) {
         githubFilters.push(`path:${filters.path}`);
     }
     if (filters.visibility) {
         githubFilters.push(`visibility:${filters.visibility}`);
     }
-    // For complex boolean queries, add language/extension/filename/size to query string
-    const hasComplexLogic = hasComplexBooleanLogic(searchQuery);
-    if (hasComplexLogic) {
+    // For complex boolean queries, add ALL filters to query string to avoid CLI conflicts
+    if (originalHasComplexLogic) {
         if (filters.language) {
             githubFilters.push(`language:${filters.language}`);
         }
-        if (filters.extension) {
+        // For complex queries with both language and extension, prioritize language
+        if (filters.extension && !filters.language) {
             githubFilters.push(`extension:${filters.extension}`);
         }
         if (filters.filename) {
@@ -526,11 +610,11 @@ function parseSearchQuery(query, filters) {
             githubFilters.push(`size:${filters.size}`);
         }
     }
-    // Step 5: Combine query with GitHub filters
+    // Step 6: Combine query with GitHub filters using proper spacing
     if (githubFilters.length > 0) {
         searchQuery = `${searchQuery} ${githubFilters.join(' ')}`;
     }
-    // Step 6: Restore exact phrases
+    // Step 7: Restore exact phrases
     exactPhrases.forEach((phrase, index) => {
         const placeholder = `__EXACT_PHRASE_${index}__`;
         searchQuery = searchQuery.replace(placeholder, phrase);
@@ -545,19 +629,17 @@ function hasComplexBooleanLogic(query) {
     return booleanOperators.test(query);
 }
 /**
- * Build command line arguments for GitHub CLI
+ * Build command line arguments for GitHub CLI with improved parameter handling
  */
 function buildGitHubCliArgs(params) {
     const args = ['code'];
     // Parse and add the main search query
     const searchQuery = parseSearchQuery(params.query, params);
     args.push(searchQuery);
-    // Add CLI flags - Always add basic flags, but be careful with complex boolean queries
-    const hasComplexLogic = hasComplexBooleanLogic(searchQuery);
-    // For complex boolean queries, add filters to the query string instead of CLI flags
-    if (hasComplexLogic) ;
-    else {
-        // Simple queries: use CLI flags for better performance
+    // Determine strategy based on ORIGINAL query complexity, not processed query
+    const hasComplexLogic = hasComplexBooleanLogic(params.query);
+    // For simple queries, use CLI flags for better performance and validation
+    if (!hasComplexLogic) {
         if (params.language) {
             args.push(`--language=${params.language}`);
         }
@@ -571,15 +653,16 @@ function buildGitHubCliArgs(params) {
             args.push(`--size=${params.size}`);
         }
     }
+    // For complex queries, filters are already in the query string (handled by parseSearchQuery)
+    // Always add limit
     if (params.limit) {
         args.push(`--limit=${params.limit}`);
     }
-    // Handle match parameter - can be string or array
+    // Handle match parameter with conflict resolution
     if (params.match) {
         const matchValues = Array.isArray(params.match)
             ? params.match
             : [params.match];
-        // GitHub API limitation: can't use both in:file and in:path in same query
         // Use the first match type when multiple are provided
         const matchValue = matchValues[0];
         args.push(`--match=${matchValue}`);
@@ -591,7 +674,7 @@ function buildGitHubCliArgs(params) {
             : [params.owner];
         ownerValues.forEach(owner => args.push(`--owner=${owner}`));
     }
-    // Handle repository filters
+    // Handle repository filters with improved validation
     if (params.owner && params.repo) {
         const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
         const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
@@ -623,10 +706,65 @@ async function searchGitHubCode(params) {
             return result;
         }
         catch (error) {
-            return createErrorResult$1('Code search command failed - verify GitHub CLI is authenticated', error);
+            const errorMessage = error.message || '';
+            // Parse specific GitHub CLI error types
+            if (errorMessage.includes('authentication')) {
+                return createErrorResult$1('GitHub CLI authentication required - run the api_status_check tool to verify authentication and available organizations', error);
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createErrorResult$1('GitHub API rate limit exceeded - wait a few minutes before searching again or use more specific filters to reduce results', error);
+            }
+            if (errorMessage.includes('validation failed') ||
+                errorMessage.includes('Invalid query')) {
+                return createErrorResult$1('Invalid search query syntax - check boolean operators (AND/OR/NOT), quotes for exact phrases, and filter formats. Try simplifying your query', error);
+            }
+            if (errorMessage.includes('repository not found') ||
+                errorMessage.includes('owner not found')) {
+                return createErrorResult$1('Repository or owner not found - run api_status_check tool to verify available organizations and access permissions', error);
+            }
+            if (errorMessage.includes('timeout')) {
+                return createErrorResult$1('Search timeout - query too broad or complex. Try adding filters like language, owner, or path to narrow results', error);
+            }
+            // Generic fallback with helpful guidance
+            return createErrorResult$1('GitHub code search failed - run api_status_check tool to verify authentication and permissions, or try simplifying your query', error);
         }
     });
 }
+/**
+ * Validate parameter combinations to prevent conflicts
+ */
+function validateSearchParameters(params) {
+    // Query validation
+    if (!params.query.trim()) {
+        return 'Empty search query - provide a search term like "useState", "function init", or "api AND endpoint"';
+    }
+    if (params.query.length > 1000) {
+        return 'Search query too long - limit to 1000 characters. Try breaking into smaller, focused searches';
+    }
+    // Repository validation
+    if (params.repo && !params.owner) {
+        return 'Missing owner parameter - when searching specific repositories, format as owner/repo (e.g., "microsoft/vscode") or provide both owner and repo parameters';
+    }
+    // Invalid characters in query
+    if (params.query.includes('\\') && !params.query.includes('\\"')) {
+        return 'Invalid escape characters in query - use quotes for exact phrases: "exact phrase" instead of escaping';
+    }
+    // Boolean operator validation
+    const invalidBooleans = params.query.match(/\b(and|or|not)\b/g);
+    if (invalidBooleans) {
+        return `Boolean operators must be uppercase - use ${invalidBooleans.map(op => op.toUpperCase()).join(', ')} instead of ${invalidBooleans.join(', ')}`;
+    }
+    // Unmatched quotes
+    const quoteCount = (params.query.match(/"/g) || []).length;
+    if (quoteCount % 2 !== 0) {
+        return 'Unmatched quotes in query - ensure all quotes are properly paired for exact phrase matching';
+    }
+    // Size parameter validation
+    if (params.size && !/^[<>]=?\d+$|^\d+\.\.\d+$|^\d+$/.test(params.size)) {
+        return 'Invalid size format - use ">100", "<50", "10..100", or "100" for file size filtering';
+    }
+    return null; // No validation errors
+}
 
 const TOOL_NAME$7 = 'github_get_file_content';
 const DESCRIPTION$7 = `Read file content. This tool REQUIRES exact path verification from github_get_contents or package view exports. If fetching fails, re-check file existence with github_get_contents or branch name.`;
@@ -729,6 +867,13 @@ async function fetchGitHubFileContent(params) {
                 else if (errorMsg.includes('403')) {
                     return createErrorResult$1('Access denied - repository may be private or require authentication', new Error(`${owner}/${repo}`));
                 }
+                else if (errorMsg.includes('maxBuffer') ||
+                    errorMsg.includes('stdout maxBuffer length exceeded')) {
+                    return createErrorResult$1(` File too large to fetch (buffer limit exceeded)\n\n` +
+                        `This usually happens with files >300KB. Consider:\n` +
+                        `    Use github_search_code to find specific patterns\n` +
+                        `    Browse directory structure with github_get_contents`, new Error(`Buffer overflow: ${filePath}`));
+                }
                 else {
                     return createErrorResult$1('Fetch failed - check repository and file path', new Error(errorMsg));
                 }
@@ -736,6 +881,15 @@ async function fetchGitHubFileContent(params) {
             return await processFileContent(result, owner, repo, branch, filePath);
         }
         catch (error) {
+            const errorMessage = error.message;
+            // Handle maxBuffer errors that escape the main try-catch
+            if (errorMessage.includes('maxBuffer') ||
+                errorMessage.includes('stdout maxBuffer length exceeded')) {
+                return createErrorResult$1(` File too large to fetch (buffer limit exceeded)\n\n` +
+                    `This usually happens with files >300KB. Consider:\n` +
+                    `    Use github_search_code to find specific patterns instead of fetching the whole file\n` +
+                    `    Browse directory structure with github_get_contents`, error);
+            }
             return createErrorResult$1('Unexpected error during file fetch - check connection and permissions', error);
         }
     });
@@ -749,10 +903,15 @@ async function processFileContent(result, owner, repo, branch, filePath) {
         return createErrorResult$1('Path is directory - use github_get_contents to browse directory structure', new Error(filePath));
     }
     const fileSize = fileData.size || 0;
-    const MAX_FILE_SIZE = 500 * 1024; // 500KB limit for simplicity
-    // Check file size
+    const MAX_FILE_SIZE = 300 * 1024; // 300KB limit for better performance and reliability
+    // Check file size with helpful message
     if (fileSize > MAX_FILE_SIZE) {
-        return createErrorResult$1('File too large - files over 500KB cannot be fetched', new Error(`${Math.round(fileSize / 1024)}KB > 500KB`));
+        const fileSizeKB = Math.round(fileSize / 1024);
+        const maxSizeKB = Math.round(MAX_FILE_SIZE / 1024);
+        return createErrorResult$1(` File too large to display (${fileSizeKB}KB > ${maxSizeKB}KB limit)\n\n` +
+            `For large files like this, consider:\n` +
+            `    Use github_get_contents to browse directory structure\n` +
+            `    Search specific code patterns with github_search_code`, new Error(`File: ${filePath} (${fileSizeKB}KB)`));
     }
     // Get and decode content
     const base64Content = fileData.content?.replace(/\s/g, ''); // Remove all whitespace
@@ -1011,44 +1170,16 @@ async function searchGitHubRepos(params) {
 function buildGitHubReposSearchCommand(params) {
     // Build query following GitHub CLI patterns
     const query = params.query?.trim() || '';
-    // Handle complex queries (with qualifiers, operators, or --) differently
-    const hasComplexSyntax = query.includes('--') ||
-        query.includes(':') ||
-        query.includes('OR') ||
-        query.includes('AND') ||
-        query.includes('(') ||
-        query.includes(')') ||
-        query.startsWith('-');
     const args = ['repos'];
-    // Only add query if it exists
+    // Only add query if it exists and handle it properly
     if (query) {
-        if (hasComplexSyntax) {
-            // For complex queries with special syntax, we need to be more careful
-            // Split by spaces but preserve quoted strings and handle special characters
-            const queryParts = query.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
-            queryParts.forEach(part => {
-                // If part contains shell special characters, quote it
-                if (/[><=&|$`(){}[\];\\]/.test(part) && !part.includes('"')) {
-                    args.push(`"${part}"`);
-                }
-                else {
-                    args.push(part);
-                }
-            });
+        // For repository search, treat multi-word queries as a single quoted string
+        // This matches GitHub CLI expected behavior for repo searches
+        if (query.includes(' ')) {
+            args.push(query); // Let GitHub CLI handle the quoting
         }
         else {
-            // For simple queries, split by spaces to match GitHub CLI examples
-            // "cli shell" becomes separate args: cli shell
-            const queryParts = query.split(/\s+/).filter(part => part.length > 0);
-            queryParts.forEach(part => {
-                // Only quote if the part contains special characters
-                if (needsQuoting(part)) {
-                    args.push(`"${part}"`);
-                }
-                else {
-                    args.push(part);
-                }
-            });
+            args.push(query);
         }
     }
     // Add JSON output with specific fields for structured data parsing
@@ -1077,14 +1208,15 @@ function buildGitHubReposSearchCommand(params) {
         const starsValue = params.stars.trim();
         const isValidStars = /^(\d+|>\d+|<\d+|\d+\.\.\d+|>=\d+|<=\d+)$/.test(starsValue);
         if (isValidStars) {
-            args.push(`--stars=${params.stars}`);
+            // Don't add quotes around the stars value - GitHub CLI handles this internally
+            args.push(`--stars=${starsValue}`);
         }
     }
     // SECONDARY FILTERS - only add if we have primary filters
     if (params.archived !== undefined)
         args.push(`--archived=${params.archived}`);
     if (params.created)
-        args.push(`--created="${params.created}"`);
+        args.push(`--created=${params.created}`);
     if (params.includeForks)
         args.push(`--include-forks=${params.includeForks}`);
     if (params.license && params.license.length > 0)
@@ -1092,7 +1224,7 @@ function buildGitHubReposSearchCommand(params) {
     if (params.match)
         args.push(`--match=${params.match}`);
     if (params.updated)
-        args.push(`--updated="${params.updated}"`);
+        args.push(`--updated=${params.updated}`);
     if (params.visibility)
         args.push(`--visibility=${params.visibility}`);
     if (params.goodFirstIssues)
@@ -1391,15 +1523,13 @@ function buildGitHubCommitsSearchCommand(params) {
 
 // TODO: add PR commeents. e.g, gh pr view <PR_NUMBER_OR_URL_OR_BRANCH> --comments
 const TOOL_NAME$4 = 'github_search_pull_requests';
-const DESCRIPTION$4 = `Find pull requests and implementations with detailed metadata. Discover how features were implemented, code review patterns, and development workflows.
+const DESCRIPTION$4 = `Find pull requests and implementations with detailed metadata. Discover feature implementations, code review patterns, and development workflows.
 
-SEARCH PATTERNS SUPPORTED:
-• BOOLEAN OPERATORS: "fix AND bug" (both required), "refactor OR cleanup" (either term), "feature NOT draft" (excludes draft)
-• EXACT PHRASES: "initial commit" (precise phrase matching)
-• GITHUB QUALIFIERS: Built-in support for "is:merged", "review:approved", "base:main", etc.
-• COMBINABLE: Mix search terms with filters for targeted PR discovery
-
-Filter by state, author, reviewer, or merge status for comprehensive development workflow analysis.`;
+SEARCH PATTERNS:
+ Boolean: "fix AND bug", "refactor OR cleanup", "feature NOT draft"
+ Exact phrases: "initial commit" (quoted)
+ GitHub qualifiers: "is:merged review:approved base:main"
+ Combine with filters for targeted PR discovery`;
 function registerSearchGitHubPullRequestsTool(server) {
     server.tool(TOOL_NAME$4, DESCRIPTION$4, {
         query: z
@@ -1600,9 +1730,9 @@ const TOOL_NAME$3 = 'npm_package_search';
 const DESCRIPTION$3 = `Search npm packages by keywords using fuzzy matching. 
 
 IMPORTANT LIMITATIONS:
-• NO BOOLEAN OPERATORS: NPM search does NOT support AND/OR/NOT - use space-separated keywords for broader search
-• FUZZY MATCHING ONLY: No exact phrase matching - searches are approximate keyword matching
-• KEYWORD-BASED: Best results with simple, space-separated terms like "react hooks" or "cli typescript"
+ NO BOOLEAN OPERATORS: NPM search does NOT support AND/OR/NOT - use space-separated keywords for broader search
+ FUZZY MATCHING ONLY: No exact phrase matching - searches are approximate keyword matching
+ KEYWORD-BASED: Best results with simple, space-separated terms like "react hooks" or "cli typescript"
 
 Required when package name is unknown. If you have the exact package name, use npm_view_package directly. This reduces the need to use GitHub search when packages are found.`;
 const MAX_DESCRIPTION_LENGTH = 100;
@@ -1930,15 +2060,13 @@ async function getSmartBranchFallback(owner, repo, requestedBranch) {
 }
 
 const TOOL_NAME$1 = 'github_search_issues';
-const DESCRIPTION$1 = `Find GitHub issues and problems with rich metadata (labels, reactions, comments, state). Discover pain points, feature requests, bug patterns, and community discussions.
-
-SEARCH PATTERNS SUPPORTED:
-• BOOLEAN OPERATORS: "bug AND crash" (both required), "feature OR enhancement" (either term), "error NOT test" (excludes test)
-• EXACT PHRASES: "memory leak" (precise phrase matching)
-• GITHUB QUALIFIERS: Built-in support for "is:open", "label:bug", "author:username", etc.
-• COMBINABLE: Mix search terms with filters for surgical precision
+const DESCRIPTION$1 = `Find GitHub issues with rich metadata (labels, reactions, comments, state). Discover pain points, feature requests, and bug patterns with boolean logic and GitHub qualifiers.
 
-Filter by state, labels, assignee, or date ranges for comprehensive issue discovery.`;
+SEARCH PATTERNS:
+ Boolean: "bug AND crash", "feature OR enhancement", "error NOT test"
+ Exact phrases: "memory leak" (quoted)
+ GitHub qualifiers: "is:open label:bug author:username"
+ Combine with filters for precision`;
 function registerSearchGitHubIssuesTool(server) {
     server.tool(TOOL_NAME$1, DESCRIPTION$1, {
         query: z
@@ -2150,10 +2278,7 @@ function buildGitHubIssuesAPICommand(params) {
 }
 
 const TOOL_NAME = 'npm_view_package';
-const DESCRIPTION = `use npm view to get package metadata. You can get the package
-name from search results or user input. This tool is effieicnt since it gets important package metadata
-on a package fast to optimize tools calls. get package git repository path easily without need to search it (using repo/code search tools),
-exported files of a package are there, along with dependencies and version history.`;
+const DESCRIPTION = `Get comprehensive NPM package metadata efficiently. Returns repository URL, exports, dependencies, and version history without needing GitHub searches. Essential for finding package source code and understanding project structure.`;
 function registerNpmViewPackageTool(server) {
     server.tool(TOOL_NAME, DESCRIPTION, {
         packageName: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-mcp",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "Model Context Protocol (MCP) server for advanced GitHub repository analysis, code discovery, and npm package exploration. Provides AI assistants with powerful tools to search, analyze, and understand codebases across GitHub and npm ecosystems.",
   "author": "Guy Bary <guybary@gmail.com>",
   "homepage": "https://github.com/bgauryy/octocode-mcp#readme",