octocode-mcp 2.3.1 → 2.3.2

package/build/index.js

@@ -7,86 +7,40 @@ import NodeCache from 'node-cache';
 import crypto from 'crypto';
 import z from 'zod';
 
-const TOOL_NAMES = {
-    // System & API Status
-    API_STATUS_CHECK: 'api_status_check',
-    // GitHub
-    GITHUB_SEARCH_CODE: 'github_search_code',
-    GITHUB_SEARCH_REPOS: 'github_search_repositories',
-    GITHUB_SEARCH_COMMITS: 'github_search_commits',
-    GITHUB_SEARCH_ISSUES: 'github_search_issues',
-    GITHUB_SEARCH_PULL_REQUESTS: 'github_search_pull_requests',
-    GITHUB_GET_CONTENTS: 'github_get_contents',
-    GITHUB_GET_FILE_CONTENT: 'github_get_file_content',
-    // NPM
-    NPM_PACKAGE_SEARCH: 'npm_package_search',
-    NPM_VIEW_PACKAGE: 'npm_view_package',
-};
-const PROMPT_SYSTEM_PROMPT = `You are a smart code research assistant with semantic search capabilities using gh and npm cli under the hood.
-You are able to search code, repositories, issues, pull requests, commits, and packages.
-Using Github: You are able to search code, repositories, issues, pull requests, commits
-Using NPM: You are able to search packages, view package metadata, and view package dependencies.
+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.
 
-- ALWAYS START with ${TOOL_NAMES.API_STATUS_CHECK} before evaluating any user query (check npm and GitHub authentication and use GitHub organizations)
-- Understand users query from semantic understanding and choose the right tools for the job.
+IMPORTANT: check users github organizations and use them in github search tools if needed
 
-TOOLS SEARCH STRATEGY:
-- ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - START SHALLOW & GO BROAD: Use topics for exploratory discovery, then narrow down
-- ${TOOL_NAMES.GITHUB_SEARCH_CODE} - Find implementation patterns with SMART BOOLEAN OPERATORS (AND, OR, NOT)
-- ${TOOL_NAMES.NPM_PACKAGE_SEARCH} - Package ecosystem discovery
-- ${TOOL_NAMES.NPM_VIEW_PACKAGE} - Complete package analysis with exports for file discovery
-- ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} + ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Understanding development patterns
-- ${TOOL_NAMES.GITHUB_GET_CONTENTS} → ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT} - ALWAYS verify file existence before fetching
+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)
 
-BEST PRACTICES:
-- Leverage smart boolean operators if possible in tools and advanced filters for smart research 
-- For repo discovery: START SHALLOW with topics, then go BROAD to explore ecosystems
-- For code search: Be focused and specific with boolean operators
-- Always check documentation and examples when available
-- Add referenced and high quality research data from docs and quality code
-- Be creative and smart and use tools efficiently to gather most data
-- If query is short (e.g. where is the git repo of X package) make simple query and use tools to gather data fast
-- For broad research make steps and think about the best way to gather data`;
-const TOOL_DESCRIPTIONS = {
-    [TOOL_NAMES.API_STATUS_CHECK]: `**MANDATORY FIRST STEP** - Check GitHub & NPM authentication status before any user query evaluation.
-  Returns connectivity status and discovers user organizations - CRITICAL for accessing private/organizational repositories.
-  **DO NOT PROCEED** with searches if both GitHub and NPM are disconnected.
-  **USE ORGANIZATIONS** returned in 'github.organizations' array for targeted owner/org parameters in all search tools.
-  Essential for enterprise code exploration and accessing company-specific repositories that require organizational membership.`,
-    [TOOL_NAMES.NPM_PACKAGE_SEARCH]: `Search NPM packages by keyword. Use for package ecosystem discovery.`,
-    [TOOL_NAMES.NPM_VIEW_PACKAGE]: `Get comprehensive package metadata essential for GitHub searches and code analysis. Returns complete package context:
-  • repositoryGitUrl - Direct GitHub repo link for accurate searches
-  • exports - Critical for discovering available files and import paths  
-  • dependencies/devDependencies - Full ecosystem understanding
-  • versions with dates - Historical evolution context
-  The exports field is invaluable for GitHub file discovery - shows exact paths before fetching. Always use when finding packages in code.`,
-    [TOOL_NAMES.GITHUB_SEARCH_CODE]: `SEMANTIC CODE DISCOVERY: Search code with SMART BOOLEAN OPERATORS (AND, OR, NOT). 
-  Prioritize intelligent boolean combinations: "logger AND debug NOT test", "config OR settings", "error handling AND typescript".
-  Format: "term AND term" language:js path:src. Filters: owner/org/user, repo, extension, filename, language, path, size, limit, match scope. 
-  Use for finding actual implementation patterns and code examples.
-  CRITICAL: When packages found in results or from user input, use ${TOOL_NAMES.NPM_VIEW_PACKAGE} for metadata/paths.`,
-    [TOOL_NAMES.GITHUB_SEARCH_REPOS]: `Search repositories by name/description. START SHALLOW AND GO BROAD (contrary to code search).
-  Use topics for EXPLORATORY discovery: topic:["cli","typescript","api"] to find ecosystem patterns.
-  PRIMARY FILTERS work alone: owner, language, stars, topic, forks. SECONDARY FILTERS require query/primary filter: license, created, archived, includeForks, updated, visibility, match.
-  
-  SMART REPOS SEARCH PATTERNS: Use topic:["cli","typescript"] for semantic discovery. Use stars:">100" for quality. Use owner:"microsoft" for organization repos. Query supports GitHub syntax: "language:Go OR language:Rust".
-  
-  CRITICAL: When finding packages, use ${TOOL_NAMES.NPM_VIEW_PACKAGE} for metadata and repository paths.`,
-    [TOOL_NAMES.GITHUB_GET_CONTENTS]: `Browse repository structure and verify file existence. ALWAYS use before github_get_file_content to confirm files exist and understand organization.`,
-    [TOOL_NAMES.GITHUB_GET_FILE_CONTENT]: `Read file content. REQUIRES exact path verification from github_get_contents first. If fetching fails, check file existence with github_get_contents.`,
-    [TOOL_NAMES.GITHUB_SEARCH_ISSUES]: `Find GitHub issues and problems with rich metadata (labels, reactions, comments, state). 
-  Discover pain points, feature requests, bug patterns, and community discussions. 
-  Filter by state, labels, assignee, or date ranges. Use for understanding project health and common user issues.`,
-    [TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS]: `Find pull requests and implementations with detailed metadata. 
-  Discover how features were implemented, code review patterns, and development workflows. 
-  Filter by state, author, reviewer, or merge status. Essential for understanding project development practices.`,
-    [TOOL_NAMES.GITHUB_SEARCH_COMMITS]: `Search commit history. Use for understanding code evolution and development patterns.`,
-};
+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
+
+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
+
+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`;
 
-// CONSOLIDATED ERROR & SUCCESS HANDLING
 function createResult(data, isError = false, suggestions) {
     const text = isError
-        ? `${data}${suggestions ? ` | Try: ${suggestions.join(', ')}` : ''}`
+        ? `${data}${''}`
         : JSON.stringify(data, null, 2);
     return {
         content: [{ type: 'text', text }],
@@ -110,56 +64,6 @@ function parseJsonResponse(responseText, fallback = null) {
         return { data: (fallback || responseText), parsed: false };
     }
 }
-/**
- * Generate fallback suggestions for no results - ensures no tool suggests itself
- */
-function getNoResultsSuggestions(currentTool) {
-    const suggestions = [];
-    // Tool-specific fallbacks
-    switch (currentTool) {
-        case TOOL_NAMES.GITHUB_SEARCH_REPOS:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_NAMES.NPM_PACKAGE_SEARCH);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_CODE:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_ISSUES);
-            break;
-        case TOOL_NAMES.NPM_PACKAGE_SEARCH:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_CODE);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_ISSUES:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_NAMES.GITHUB_SEARCH_REPOS);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_ISSUES, TOOL_NAMES.GITHUB_SEARCH_CODE);
-            break;
-        case TOOL_NAMES.GITHUB_SEARCH_COMMITS:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_NAMES.GITHUB_SEARCH_REPOS);
-            break;
-        case TOOL_NAMES.GITHUB_GET_CONTENTS:
-        case TOOL_NAMES.GITHUB_GET_FILE_CONTENT:
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_CODE);
-            break;
-        default:
-            // Fallback for any other tools
-            suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_NAMES.GITHUB_SEARCH_CODE);
-    }
-    return suggestions.slice(0, 3);
-}
-/**
- * Generate fallback suggestions for errors - ensures no tool suggests itself
- */
-function getErrorSuggestions(currentTool) {
-    const suggestions = [];
-    // Always suggest API status check first (unless it's the current tool)
-    if (currentTool !== TOOL_NAMES.API_STATUS_CHECK) {
-        suggestions.push(TOOL_NAMES.API_STATUS_CHECK);
-    }
-    // Add discovery alternatives
-    if (currentTool !== TOOL_NAMES.GITHUB_SEARCH_REPOS) {
-        suggestions.push(TOOL_NAMES.GITHUB_SEARCH_REPOS);
-    }
-    return suggestions.slice(0, 3);
-}
 /**
  * Determines if a string needs quoting for GitHub search
  */
@@ -238,8 +142,9 @@ 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`));
     }
-    // Build command with validated prefix - no sanitization needed since we control the prefix
-    const fullCommand = `npm ${command} ${args.join(' ')}`;
+    // Build command with validated prefix and properly escaped arguments
+    const escapedArgs = args.map(escapeShellArg);
+    const fullCommand = `npm ${command} ${escapedArgs.join(' ')}`;
     const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options);
     if (options.cache) {
         const cacheKey = generateCacheKey('npm-exec', { command, args });
@@ -247,6 +152,17 @@ async function executeNpmCommand(command, args = [], options = {}) {
     }
     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}"
@@ -256,8 +172,9 @@ 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`));
     }
-    // Build command with validated prefix - no sanitization needed since we control the prefix
-    const fullCommand = `gh ${command} ${args.join(' ')}`;
+    // Build command with validated prefix and properly escaped arguments
+    const escapedArgs = args.map(escapeShellArg);
+    const fullCommand = `gh ${command} ${escapedArgs.join(' ')}`;
     const executeGhCommand = () => executeCommand(fullCommand, 'github', options);
     if (options.cache) {
         const cacheKey = generateCacheKey('gh-exec', { command, args });
@@ -314,10 +231,13 @@ async function executeCommand(fullCommand, type, options = {}) {
     }
 }
 
+const TOOL_NAME$9 = 'api_status_check';
+const DESCRIPTION$9 = `Gets the list of user github  organizations (in case the tool needs to use them in "owner" fields in github search) and checks users gh cli and npm cli login status.
+Use when user asks on specific implementaon in his organization (e.g. - I work at Wix, or search Wix code about X) or when cli is failing.`;
 function registerApiStatusCheckTool(server) {
-    server.tool(TOOL_NAMES.API_STATUS_CHECK, TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK], {}, {
-        title: TOOL_NAMES.API_STATUS_CHECK,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.API_STATUS_CHECK],
+    server.tool(TOOL_NAME$9, DESCRIPTION$9, {}, {
+        title: 'Check API Connections and Github Organizations',
+        description: DESCRIPTION$9,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -433,64 +353,72 @@ function registerApiStatusCheckTool(server) {
             });
         }
         catch (error) {
-            return createResult(`API status check failed: ${error.message}`, true);
+            return createResult('API status check failed - verify GitHub CLI and NPM are installed and accessible', true);
         }
     });
 }
 
-/**
- * Registers the GitHub Code Search tool with the MCP server.
- *
- * This tool provides semantic code search across GitHub repositories using the GitHub CLI.
- * It supports advanced search features like boolean operators, qualifiers, and filters.
- *
- * Key features:
- * - Boolean operator support (AND, OR, NOT) in queries
- * - GitHub qualifier support (language:, path:, etc.)
- * - Repository, owner, and organization filtering
- * - File type, size, and visibility filtering
- * - Multiple match scopes and filtering options
- */
+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
+
+RESTRICTIVENESS SCALE: OR < AND < Exact Phrase (Broadest → Most Precise)
+
+COMBINE FILTERS: Mix query with language, owner, path filters for laser-focused results.`;
 function registerGitHubSearchCodeTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE], {
+    server.tool(TOOL_NAME$8, DESCRIPTION$8, {
         query: z
             .string()
             .min(1)
-            .describe('Search query with boolean operators (AND, OR, NOT) and qualifiers. ' +
-            'Examples: "react lifecycle", "error handling", "logger AND debug", "config OR settings", "main NOT test". ' +
-            'Use quotes for exact phrases. Supports GitHub search syntax.'),
+            .describe('Search query with strategic boolean operators. SEARCH PATTERNS: OR (auto-default): "useState hook" → "useState OR hook" for BROADEST discovery. AND (explicit): "react AND hooks" requires BOTH terms for RESTRICTIVE intersection. EXACT PHRASE (escaped quotes): "useState hook" finds literal sequence for MOST PRECISE targeting. NOT (filtering): "auth NOT test" excludes unwanted results. USAGE GUIDE: Use OR for exploration/alternatives, AND for specific combinations, exact phrases for documentation/APIs, NOT for removing noise. RESTRICTIVENESS: OR < AND < Exact Phrase. No parentheses - simple boolean logic only.'),
         owner: z
             .union([z.string(), z.array(z.string())])
             .optional()
-            .describe('Repository owner/organization(s). Single string or array for multiple owners. Leave empty for global search.'),
+            .describe('Repository owner/organization filter. Examples: "microsoft", "google". Combines with other filters for targeted search. get from user orgamizations in case of private repositories search (e.g. for employees of organizations)'),
         repo: z
             .union([z.string(), z.array(z.string())])
             .optional()
-            .describe('Specific repositories in "owner/repo" format. Can be a single repository string or array of repository strings. Requires owner parameter to be set.'),
+            .describe('Specific repositories in "owner/repo" format. Examples: "facebook/react", "microsoft/vscode". Requires owner parameter.'),
         language: z
             .string()
             .optional()
-            .describe('Programming language filter (e.g., "javascript", "python", "go").'),
+            .describe('Programming language filter. Examples: "javascript", "python", "typescript", "go". Highly effective for targeted searches.'),
         extension: z
             .string()
             .optional()
-            .describe('File extension filter without dot (e.g., "js", "py", "md").'),
+            .describe('File extension filter without dot. Examples: "js", "ts", "py", "md", "json". Precise file type targeting.'),
         filename: z
             .string()
             .optional()
-            .describe('Exact filename filter (e.g., "package.json", "Dockerfile", "README.md").'),
+            .describe('Exact filename filter. Examples: "package.json", "Dockerfile", "README.md", "index.js". Perfect for config files.'),
         path: z
             .string()
             .optional()
-            .describe('Directory path filter with wildcards (e.g., "src/", "*/tests/*", "docs/**").'),
+            .describe('Directory path filter. Examples: "src/", "test/", "docs/", "components/". Focus search on specific directories.'),
         size: z
             .string()
             .optional()
             .describe('File size filter in KB with operators (e.g., ">100", "<50", "10..100").'),
-        visibility: z
-            .enum(['public', 'private', 'internal'])
-            .optional()
-            .describe('Repository visibility filter. "public" for public repos, "private" for private repos you have access to.'),
         limit: z
             .number()
             .int()
@@ -502,10 +430,14 @@ function registerGitHubSearchCodeTool(server) {
         match: z
             .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
             .optional()
-            .describe('Search scope: "file" for content search, "path" for filename/path search. If array provided, only first value is used due to GitHub API limitations.'),
+            .describe('Search scope: "file" searches code content, "path" searches filenames/paths. Use "path" to find files by name.'),
+        visibility: z
+            .enum(['public', 'private', 'internal'])
+            .optional()
+            .describe('Repository visibility filter: "public", "private", or "internal". Defaults to accessible repositories.'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_CODE,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE],
+        title: TOOL_NAME$8,
+        description: DESCRIPTION$8,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -513,7 +445,7 @@ function registerGitHubSearchCodeTool(server) {
     }, async (args) => {
         try {
             if (args.repo && !args.owner) {
-                return createResult('Repository search requires owner parameter', true);
+                return createResult('Repository search requires owner parameter - specify owner when searching specific repositories', true);
             }
             const result = await searchGitHubCode(args);
             if (result.isError) {
@@ -525,113 +457,206 @@ function registerGitHubSearchCodeTool(server) {
             const items = Array.isArray(codeResults) ? codeResults : [];
             return createSuccessResult$1({
                 query: args.query,
+                processed_query: parseSearchQuery(args.query, args),
                 total_count: items.length,
                 items: items,
+                cli_command: execResult.command,
+                debug_info: {
+                    has_complex_boolean_logic: hasComplexBooleanLogic(args.query),
+                    escaped_args: buildGitHubCliArgs(args),
+                    original_query: args.query,
+                },
             });
         }
         catch (error) {
-            return createErrorResult$1('Code search failed', error);
+            return createErrorResult$1('GitHub code search failed - check repository access or simplify query', error);
         }
     });
 }
+/**
+ * Enhanced query parser that handles exact strings, boolean operators, and filters
+ */
+function parseSearchQuery(query, filters) {
+    // Step 1: Handle quoted strings more intelligently
+    // Convert escaped quotes to simple quotes to avoid shell escaping issues
+    let processedQuery = query.replace(/\\"/g, '"');
+    // Step 2: Preserve exact phrases (quoted strings)
+    const exactPhrases = [];
+    // Extract quoted strings and replace with placeholders
+    const quotedMatches = processedQuery.match(/"[^"]+"/g) || [];
+    quotedMatches.forEach((match, index) => {
+        const placeholder = `__EXACT_PHRASE_${index}__`;
+        exactPhrases.push(match);
+        processedQuery = processedQuery.replace(match, placeholder);
+    });
+    // Step 3: 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)) {
+        // Split by whitespace and join with OR for better search results
+        const terms = processedQuery
+            .trim()
+            .split(/\s+/)
+            .filter(term => term.length > 0);
+        if (terms.length > 1) {
+            searchQuery = terms.join(' OR ');
+        }
+    }
+    // Step 4: Add GitHub-specific filters that go in the query string
+    const githubFilters = [];
+    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) {
+        if (filters.language) {
+            githubFilters.push(`language:${filters.language}`);
+        }
+        if (filters.extension) {
+            githubFilters.push(`extension:${filters.extension}`);
+        }
+        if (filters.filename) {
+            githubFilters.push(`filename:${filters.filename}`);
+        }
+        if (filters.size) {
+            githubFilters.push(`size:${filters.size}`);
+        }
+    }
+    // Step 5: Combine query with GitHub filters
+    if (githubFilters.length > 0) {
+        searchQuery = `${searchQuery} ${githubFilters.join(' ')}`;
+    }
+    // Step 6: Restore exact phrases
+    exactPhrases.forEach((phrase, index) => {
+        const placeholder = `__EXACT_PHRASE_${index}__`;
+        searchQuery = searchQuery.replace(placeholder, phrase);
+    });
+    return searchQuery.trim();
+}
+/**
+ * Check if query contains complex boolean logic that might conflict with CLI flags
+ */
+function hasComplexBooleanLogic(query) {
+    const booleanOperators = /\b(AND|OR|NOT)\b/i;
+    return booleanOperators.test(query);
+}
+/**
+ * Build command line arguments for GitHub CLI
+ */
+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
+        if (params.language) {
+            args.push(`--language=${params.language}`);
+        }
+        if (params.extension) {
+            args.push(`--extension=${params.extension}`);
+        }
+        if (params.filename) {
+            args.push(`--filename=${params.filename}`);
+        }
+        if (params.size) {
+            args.push(`--size=${params.size}`);
+        }
+    }
+    if (params.limit) {
+        args.push(`--limit=${params.limit}`);
+    }
+    // Handle match parameter - can be string or array
+    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}`);
+    }
+    // Handle owner parameter - can be string or array
+    if (params.owner && !params.repo) {
+        const ownerValues = Array.isArray(params.owner)
+            ? params.owner
+            : [params.owner];
+        ownerValues.forEach(owner => args.push(`--owner=${owner}`));
+    }
+    // Handle repository filters
+    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];
+        // Create repo filters for each owner/repo combination
+        owners.forEach(owner => {
+            repos.forEach(repo => {
+                // Handle both "owner/repo" format and just "repo" format
+                if (repo.includes('/')) {
+                    args.push(`--repo=${repo}`);
+                }
+                else {
+                    args.push(`--repo=${owner}/${repo}`);
+                }
+            });
+        });
+    }
+    // JSON output with all available fields
+    args.push('--json=repository,path,textMatches,sha,url');
+    return args;
+}
 async function searchGitHubCode(params) {
     const cacheKey = generateCacheKey('gh-code', params);
     return withCache(cacheKey, async () => {
         try {
-            const args = ['code'];
-            // Build the main query - preserve boolean operators and GitHub syntax
-            let query = params.query;
-            // Add path filter to query if provided (GitHub search syntax)
-            if (params.path) {
-                query = `${query} path:${params.path}`;
-            }
-            // Add visibility filter to query if provided
-            if (params.visibility) {
-                query = `${query} visibility:${params.visibility}`;
-            }
-            args.push(query);
-            // Add command-line filters
-            if (params.language)
-                args.push(`--language=${params.language}`);
-            if (params.extension)
-                args.push(`--extension=${params.extension}`);
-            if (params.filename)
-                args.push(`--filename=${params.filename}`);
-            if (params.size)
-                args.push(`--size=${params.size}`);
-            if (params.limit)
-                args.push(`--limit=${params.limit}`);
-            // Handle match parameter - can be string or array
-            // Note: GitHub search API doesn't support multiple match types in a single query
-            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}`);
-            }
-            // Handle owner parameter - can be string or array
-            if (params.owner && !params.repo) {
-                const ownerValues = Array.isArray(params.owner)
-                    ? params.owner
-                    : [params.owner];
-                ownerValues.forEach(owner => args.push(`--owner=${owner}`));
-            }
-            // Handle repository filters
-            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];
-                // Create repo filters for each owner/repo combination
-                owners.forEach(owner => {
-                    repos.forEach(repo => {
-                        // Handle both "owner/repo" format and just "repo" format
-                        if (repo.includes('/')) {
-                            args.push(`--repo=${repo}`);
-                        }
-                        else {
-                            args.push(`--repo=${owner}/${repo}`);
-                        }
-                    });
-                });
-            }
-            // JSON output with all available fields
-            args.push('--json=repository,path,textMatches,sha,url');
+            const args = buildGitHubCliArgs(params);
             const result = await executeGitHubCommand('search', args, {
                 cache: false,
             });
             return result;
         }
         catch (error) {
-            return createErrorResult$1('Failed to execute search command', error);
+            return createErrorResult$1('Code search command failed - verify GitHub CLI is authenticated', error);
         }
     });
 }
 
+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.`;
 function registerFetchGitHubFileContentTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_GET_FILE_CONTENT, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_FILE_CONTENT], {
+    server.tool(TOOL_NAME$7, DESCRIPTION$7, {
         owner: z
             .string()
             .min(1)
+            .max(100)
+            .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
             .describe(`Repository owner/organization (e.g., 'microsoft', 'facebook')`),
         repo: z
             .string()
             .min(1)
+            .max(100)
+            .regex(/^[a-zA-Z0-9._-]+$/)
             .describe(`Repository name (e.g., 'vscode', 'react'). Case-sensitive.`),
         branch: z
             .string()
             .min(1)
+            .max(255)
+            .regex(/^[^\s]+$/)
             .describe(`Branch name (e.g., 'main', 'master'). Auto-fallback to common branches if not found.`),
         filePath: z
             .string()
             .min(1)
             .describe(`File path from repository root (e.g., 'README.md', 'src/index.js'). Use github_get_contents to explore structure.`),
     }, {
-        title: TOOL_NAMES.GITHUB_GET_FILE_CONTENT,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_FILE_CONTENT],
+        title: TOOL_NAME$7,
+        description: DESCRIPTION$7,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -666,26 +691,7 @@ function registerFetchGitHubFileContentTool(server) {
             return result;
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            let suggestions = [];
-            if (errorMessage.includes('404') ||
-                errorMessage.includes('Not Found')) {
-                suggestions = [
-                    TOOL_NAMES.GITHUB_GET_CONTENTS,
-                    TOOL_NAMES.GITHUB_SEARCH_CODE,
-                ];
-            }
-            else if (errorMessage.includes('403') ||
-                errorMessage.includes('Forbidden')) {
-                suggestions = [TOOL_NAMES.API_STATUS_CHECK];
-            }
-            else if (errorMessage.includes('branch')) {
-                suggestions = [TOOL_NAMES.GITHUB_GET_CONTENTS];
-            }
-            else {
-                suggestions = getErrorSuggestions(TOOL_NAMES.GITHUB_GET_FILE_CONTENT);
-            }
-            return createResult(`Failed to fetch file content: ${errorMessage}. Context: ${args.owner}/${args.repo}/${args.filePath} on ${args.branch}`, true, suggestions);
+            return createResult('File fetch failed - verify file path exists or try github_get_contents first', true);
         }
     });
 }
@@ -718,19 +724,19 @@ async function fetchGitHubFileContent(params) {
                 }
                 // Handle common errors
                 if (errorMsg.includes('404')) {
-                    return createErrorResult$1(`File not found: ${filePath}`, new Error(`File does not exist in ${owner}/${repo} on branch ${branch}`));
+                    return createErrorResult$1('File not found - verify path with github_get_contents first', new Error(filePath));
                 }
                 else if (errorMsg.includes('403')) {
-                    return createErrorResult$1(`Access denied: ${filePath}`, new Error(`Permission denied for ${owner}/${repo}`));
+                    return createErrorResult$1('Access denied - repository may be private or require authentication', new Error(`${owner}/${repo}`));
                 }
                 else {
-                    return createErrorResult$1(`Failed to fetch file: ${filePath}`, new Error(errorMsg));
+                    return createErrorResult$1('Fetch failed - check repository and file path', new Error(errorMsg));
                 }
             }
             return await processFileContent(result, owner, repo, branch, filePath);
         }
         catch (error) {
-            return createErrorResult$1(`Unexpected error fetching file: ${filePath}`, error);
+            return createErrorResult$1('Unexpected error during file fetch - check connection and permissions', error);
         }
     });
 }
@@ -740,30 +746,30 @@ async function processFileContent(result, owner, repo, branch, filePath) {
     const fileData = JSON.parse(execResult.result);
     // Check if it's a directory
     if (Array.isArray(fileData)) {
-        return createErrorResult$1(`Path is a directory: ${filePath}`, new Error(`"${filePath}" is a directory, not a file`));
+        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
     if (fileSize > MAX_FILE_SIZE) {
-        return createErrorResult$1(`File too large: ${filePath}`, new Error(`File size (${Math.round(fileSize / 1024)}KB) exceeds limit (500KB)`));
+        return createErrorResult$1('File too large - files over 500KB cannot be fetched', new Error(`${Math.round(fileSize / 1024)}KB > 500KB`));
     }
     // Get and decode content
     const base64Content = fileData.content?.replace(/\s/g, ''); // Remove all whitespace
     if (!base64Content) {
-        return createErrorResult$1(`Empty file: ${filePath}`, new Error(`File appears to be empty`));
+        return createErrorResult$1('Empty file - file has no content to display', new Error(filePath));
     }
     let decodedContent;
     try {
         const buffer = Buffer.from(base64Content, 'base64');
         // Simple binary check - look for null bytes
         if (buffer.indexOf(0) !== -1) {
-            return createErrorResult$1(`Binary file detected: ${filePath}`, new Error(`Binary files cannot be displayed as text`));
+            return createErrorResult$1('Binary file detected - cannot display binary content as text', new Error(filePath));
         }
         decodedContent = buffer.toString('utf-8');
     }
     catch (decodeError) {
-        return createErrorResult$1(`Failed to decode file: ${filePath}`, new Error(`Unable to decode file as UTF-8`));
+        return createErrorResult$1('Decode failed - file encoding not supported or corrupted', new Error(filePath));
     }
     // Return simplified response
     const response = {
@@ -781,8 +787,17 @@ async function processFileContent(result, owner, repo, branch, filePath) {
     return createSuccessResult$1(response);
 }
 
+const TOOL_NAME$6 = 'github_search_repositories';
+const DESCRIPTION$6 = `Search repositories by name/description. Start shallow and go broad: use topics for exploratory discovery (e.g., topic:["cli","typescript","api"]) to find ecosystem patterns.
+  PRIMARY FILTERS work alone: owner, language, stars, topic, forks. SECONDARY FILTERS require a query or primary filter: license, created, archived, includeForks, updated, visibility, match.
+  SMART REPOS SEARCH PATTERNS: Use topic:["cli","typescript"] for semantic discovery; stars:">100" for quality; owner:"microsoft" for organization repos. Query supports GitHub syntax: "language:Go OR language:Rust".
+  
+  EFFICIENCY NOTE: If you have a package name, use npm_view_package FIRST to get repositoryGitUrl - this tool becomes UNNECESSARY
+  
+  SMART INTEGRATION: When finding packages → npm_view_package + npm_package_search provide direct repo access
+  AVOID: Searching for "react" repos when npm_view_package("react") gives you the exact repository instantly`;
 function registerSearchGitHubReposTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_REPOS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_REPOS], {
+    server.tool(TOOL_NAME$6, DESCRIPTION$6, {
         query: z
             .string()
             .optional()
@@ -791,52 +806,66 @@ function registerSearchGitHubReposTool(server) {
         owner: z
             .string()
             .optional()
-            .describe('Repository owner/organization. PRIMARY FILTER - works alone.'),
+            .describe('Repository owner/organization (e.g., "microsoft", "facebook").'),
         language: z
             .string()
             .optional()
-            .describe('Programming language. PRIMARY FILTER - works alone.'),
+            .describe('Programming language (e.g., "javascript", "python", "go").'),
         stars: z
             .string()
             .optional()
-            .describe('Stars count with ranges: "100", ">500", "<50", "10..100", ">=1000". PRIMARY FILTER - works alone. Use >100 for quality projects.'),
+            .describe('Stars count with ranges: "100", ">500", "<50", "10..100", ">=1000". Use >100 for quality projects.'),
         topic: z
             .array(z.string())
             .optional()
-            .describe('Filter by topics. PRIMARY FILTER - works alone.'),
-        forks: z
+            .describe('Filter by topics (e.g., ["cli", "typescript", "api"]).'),
+        forks: z.number().optional().describe('Exact forks count.'),
+        numberOfTopics: z
             .number()
             .optional()
-            .describe('Exact forks count. PRIMARY FILTER - works alone.'),
+            .describe('Filter on number of topics.'),
         // SECONDARY FILTERS (require query or primary filter)
         license: z
             .array(z.string())
             .optional()
-            .describe('License types. REQUIRES query or primary filter.'),
+            .describe('License types (e.g., ["mit", "apache-2.0"]).'),
         match: z
             .enum(['name', 'description', 'readme'])
             .optional()
-            .describe('Search scope. REQUIRES query.'),
+            .describe('Search scope: "name", "description", or "readme".'),
         visibility: z
             .enum(['public', 'private', 'internal'])
             .optional()
-            .describe('Repository visibility. REQUIRES query or primary filter.'),
+            .describe('Repository visibility filter.'),
         created: z
             .string()
             .optional()
-            .describe('Created date filter: ">2020-01-01", "<2023-12-31". REQUIRES query or primary filter.'),
+            .describe('Created date filter: ">2020-01-01", "<2023-12-31", "2022-01-01..2023-12-31".'),
         updated: z
             .string()
             .optional()
-            .describe('Updated date filter. REQUIRES query or primary filter.'),
-        archived: z
-            .boolean()
-            .optional()
-            .describe('Archived state. REQUIRES query or primary filter.'),
+            .describe('Updated date filter (same format as created).'),
+        archived: z.boolean().optional().describe('Filter by archived state.'),
         includeForks: z
             .enum(['false', 'true', 'only'])
             .optional()
-            .describe('Include forks. REQUIRES query or primary filter.'),
+            .describe('Include forks: "false" (default), "true", or "only".'),
+        goodFirstIssues: z
+            .string()
+            .optional()
+            .describe('Filter by good first issues count (e.g., ">=10", ">5").'),
+        helpWantedIssues: z
+            .string()
+            .optional()
+            .describe('Filter by help wanted issues count (e.g., ">=5", ">10").'),
+        followers: z
+            .number()
+            .optional()
+            .describe('Filter by number of followers.'),
+        size: z
+            .string()
+            .optional()
+            .describe('Repository size filter in KB (e.g., ">100", "<50", "10..100").'),
         // Sorting and limits
         sort: z
             .enum(['forks', 'help-wanted-issues', 'stars', 'updated', 'best-match'])
@@ -857,8 +886,8 @@ function registerSearchGitHubReposTool(server) {
             .default(25)
             .describe('Maximum results (default: 25, max: 50)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_REPOS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_REPOS],
+        title: TOOL_NAME$6,
+        description: DESCRIPTION$6,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -880,7 +909,7 @@ function registerSearchGitHubReposTool(server) {
             return result;
         }
         catch (error) {
-            return createResult(`Search failed: ${error.message}`, true, getErrorSuggestions(TOOL_NAMES.GITHUB_SEARCH_REPOS));
+            return createResult('Repository search failed - check query syntax, filters, or try broader terms', true);
         }
     });
 }
@@ -947,7 +976,7 @@ async function searchGitHubRepos(params) {
                     isPrivate: repo.isPrivate || false,
                     isArchived: repo.isArchived || false,
                     isFork: repo.isFork || false,
-                    topics: [], // Topics not available via CLI JSON output
+                    topics: [], // GitHub CLI search repos doesn't provide topics in JSON output
                     license: repo.license?.name || null,
                     hasIssues: repo.hasIssues || false,
                     openIssuesCount: repo.openIssuesCount || 0,
@@ -971,17 +1000,11 @@ async function searchGitHubRepos(params) {
                     }
                     : {
                         repositories: [],
-                        suggestions: [
-                            `${TOOL_NAMES.NPM_PACKAGE_SEARCH} "${params.query || 'package'}"`,
-                            `${TOOL_NAMES.GITHUB_SEARCH_CODE} "${params.query || 'code'}"`,
-                            'Try broader search terms',
-                            'Check spelling and try synonyms',
-                        ],
                     }),
             });
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub repositories', error);
+            return createErrorResult$1('GitHub repository search failed - verify connection or try simpler query', error);
         }
     });
 }
@@ -1014,12 +1037,22 @@ function buildGitHubReposSearchCommand(params) {
             });
         }
         else {
-            // For simple queries, use quoting logic
-            const queryString = needsQuoting(query) ? `"${query}"` : query;
-            args.push(queryString);
+            // 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);
+                }
+            });
         }
     }
     // Add JSON output with specific fields for structured data parsing
+    // Note: 'topics' field is not available in GitHub CLI search repos JSON output
     args.push('--json', 'name,fullName,description,language,stargazersCount,forksCount,updatedAt,createdAt,url,owner,isPrivate,license,hasIssues,openIssuesCount,isArchived,isFork,visibility');
     // PRIMARY FILTERS - Handle owner as single string (BaseSearchParams) or array
     if (params.owner) {
@@ -1034,6 +1067,8 @@ function buildGitHubReposSearchCommand(params) {
         args.push(`--forks=${params.forks}`);
     if (params.topic && params.topic.length > 0)
         args.push(`--topic=${params.topic.join(',')}`);
+    if (params.numberOfTopics !== undefined)
+        args.push(`--number-topics=${params.numberOfTopics}`);
     // Only add stars filter if it's a valid numeric value or range
     if (params.stars !== undefined &&
         params.stars !== '*' &&
@@ -1042,7 +1077,7 @@ 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}"`);
+            args.push(`--stars=${params.stars}`);
         }
     }
     // SECONDARY FILTERS - only add if we have primary filters
@@ -1060,6 +1095,14 @@ function buildGitHubReposSearchCommand(params) {
         args.push(`--updated="${params.updated}"`);
     if (params.visibility)
         args.push(`--visibility=${params.visibility}`);
+    if (params.goodFirstIssues)
+        args.push(`--good-first-issues=${params.goodFirstIssues}`);
+    if (params.helpWantedIssues)
+        args.push(`--help-wanted-issues=${params.helpWantedIssues}`);
+    if (params.followers !== undefined)
+        args.push(`--followers=${params.followers}`);
+    if (params.size)
+        args.push(`--size=${params.size}`);
     // SORTING AND LIMITS
     if (params.limit)
         args.push(`--limit=${params.limit}`);
@@ -1073,12 +1116,14 @@ function buildGitHubReposSearchCommand(params) {
     return { command: 'search', args };
 }
 
+const TOOL_NAME$5 = 'github_search_commits';
+const DESCRIPTION$5 = `Search commit history with powerful boolean logic and exact phrase matching. Use advanced GitHub search syntax including AND/OR operators for precise commit discovery. Understand code evolution patterns, track bug fixes, and analyze development workflows over time. Filter by author, date ranges, commit content, and repository metadata with surgical precision.`;
 function registerSearchGitHubCommitsTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_COMMITS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_COMMITS], {
+    server.tool(TOOL_NAME$5, DESCRIPTION$5, {
         query: z
             .string()
             .optional()
-            .describe('Search query with full GitHub syntax support: "readme typo" (AND), "bug fix" (phrase), "author:john OR committer:jane" (OR), "-- -author:botuser" (exclude). Optional - can search with just filters.'),
+            .describe('Search query with POWERFUL boolean logic and exact phrase matching. BOOLEAN OPERATORS: "fix AND bug" (both required), "fix OR update" (either term), "readme typo" (implicit AND). EXACT PHRASES: "initial commit" (precise phrase matching). ADVANCED SYNTAX: "author:john OR committer:jane" (user qualifiers), "-- -author:botuser" (exclusions). STRENGTH: Surgical precision for commit discovery across millions of repositories. Optional - can search with just filters.'),
         // Basic filters
         owner: z
             .string()
@@ -1135,10 +1180,10 @@ function registerSearchGitHubCommitsTool(server) {
             .max(50)
             .optional()
             .default(25)
-            .describe('Maximum results (default: 25)'),
+            .describe('Maximum results (default: 25, max: 50)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_COMMITS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_COMMITS],
+        title: TOOL_NAME$5,
+        description: DESCRIPTION$5,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -1157,7 +1202,7 @@ function registerSearchGitHubCommitsTool(server) {
             return result;
         }
         catch (error) {
-            return createResult(`Search failed: ${error.message}`, true, getErrorSuggestions(TOOL_NAMES.GITHUB_SEARCH_COMMITS));
+            return createResult('Commit search failed - check query syntax, filters, or repository access', true);
         }
     });
 }
@@ -1252,17 +1297,10 @@ async function searchGitHubCommits(params) {
                 query: params.query,
                 total: 0,
                 commits: [],
-                suggestions: [
-                    `${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} "${params.query || 'pr'}"`,
-                    `${TOOL_NAMES.GITHUB_SEARCH_ISSUES} "${params.query || 'issue'}"`,
-                    `${TOOL_NAMES.GITHUB_SEARCH_CODE} "${params.query || 'code'}"`,
-                    'Try broader search terms',
-                    'Check spelling and try synonyms',
-                ],
             });
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub commits', error);
+            return createErrorResult$1('GitHub commit search failed - verify repository exists or try different filters', error);
         }
     });
 }
@@ -1352,12 +1390,22 @@ 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.
+
+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.`;
 function registerSearchGitHubPullRequestsTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS], {
+    server.tool(TOOL_NAME$4, DESCRIPTION$4, {
         query: z
             .string()
             .min(1, 'Search query is required and cannot be empty')
-            .describe('Search query to find pull requests'),
+            .describe('Search query with GITHUB SEARCH SYNTAX support. BOOLEAN OPERATORS: "fix AND bug" (both required), "refactor OR cleanup" (either term), "feature NOT draft" (excludes). EXACT PHRASES: "initial commit" (precise matching). GITHUB QUALIFIERS: "is:merged review:approved base:main" (native GitHub syntax). COMBINED: Mix boolean logic with qualifiers for precise PR discovery.'),
         owner: z.string().optional().describe('Repository owner/organization'),
         repo: z.string().optional().describe('Repository name'),
         author: z.string().optional().describe('Filter by pull request author'),
@@ -1382,6 +1430,15 @@ function registerSearchGitHubPullRequestsTool(server) {
         mergedAt: z.string().optional().describe('Filter by merged date'),
         closed: z.string().optional().describe('Filter by closed date'),
         draft: z.boolean().optional().describe('Filter by draft state'),
+        checks: z
+            .enum(['pending', 'success', 'failure'])
+            .optional()
+            .describe('Filter based on status of the checks'),
+        merged: z.boolean().optional().describe('Filter based on merged state'),
+        review: z
+            .enum(['none', 'required', 'approved', 'changes_requested'])
+            .optional()
+            .describe('Filter based on review status'),
         limit: z
             .number()
             .int()
@@ -1389,7 +1446,7 @@ function registerSearchGitHubPullRequestsTool(server) {
             .max(50)
             .optional()
             .default(25)
-            .describe('Maximum results (default: 25)'),
+            .describe('Maximum results (default: 25, max: 50)'),
         sort: z
             .enum([
             'comments',
@@ -1412,24 +1469,24 @@ function registerSearchGitHubPullRequestsTool(server) {
             .default('desc')
             .describe('Order (default: desc)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS],
+        title: TOOL_NAME$4,
+        description: DESCRIPTION$4,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true,
     }, async (args) => {
         if (!args.query?.trim()) {
-            return createErrorResult$1('Search query is required and cannot be empty', new Error('Invalid query'));
+            return createErrorResult$1('Search query is required and cannot be empty - provide keywords to search for pull requests', new Error('Invalid query'));
         }
         if (args.query.length > 256) {
-            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less.', new Error('Query too long'));
+            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less - simplify your search terms', new Error('Query too long'));
         }
         try {
             return await searchGitHubPullRequests(args);
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub pull requests', error);
+            return createErrorResult$1('GitHub pull requests search failed - verify repository access and query syntax', error);
         }
     });
 }
@@ -1521,6 +1578,12 @@ function buildGitHubPullRequestsAPICommand(params) {
         queryParts.push(`merged:${params.mergedAt}`);
     if (params.draft !== undefined)
         queryParts.push(`draft:${params.draft}`);
+    if (params.checks)
+        queryParts.push(`status:${params.checks}`);
+    if (params.merged !== undefined)
+        queryParts.push(`is:${params.merged ? 'merged' : 'unmerged'}`);
+    if (params.review)
+        queryParts.push(`review:${params.review}`);
     // Add type qualifier to search only pull requests
     queryParts.push('type:pr');
     const query = queryParts.filter(Boolean).join(' ');
@@ -1533,13 +1596,22 @@ function buildGitHubPullRequestsAPICommand(params) {
     return { command: 'api', args: [apiPath] };
 }
 
+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"
+
+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;
 const MAX_KEYWORDS = 10;
 function registerNpmSearchTool(server) {
-    server.tool(TOOL_NAMES.NPM_PACKAGE_SEARCH, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_PACKAGE_SEARCH], {
+    server.tool(TOOL_NAME$3, DESCRIPTION$3, {
         queries: z
             .union([z.string(), z.array(z.string())])
-            .describe('Package names or keywords to search for'),
+            .describe('Package names or keywords to search for. NOTE: No boolean operators (AND/OR/NOT) supported - use simple space-separated keywords like "react hooks" or "typescript cli" for fuzzy matching.'),
         searchlimit: z
             .number()
             .int()
@@ -1547,10 +1619,10 @@ function registerNpmSearchTool(server) {
             .max(50)
             .optional()
             .default(20)
-            .describe('Max results per query (default: 20)'),
+            .describe('Max results per query (default: 20, max: 50)'),
     }, {
-        title: TOOL_NAMES.NPM_PACKAGE_SEARCH,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_PACKAGE_SEARCH],
+        title: TOOL_NAME$3,
+        description: DESCRIPTION$3,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -1580,12 +1652,10 @@ function registerNpmSearchTool(server) {
                     results: deduplicatedPackages,
                 });
             }
-            const suggestions = getNoResultsSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH);
-            return createResult('No packages found', true, suggestions);
+            return createResult('No packages found', true);
         }
         catch (error) {
-            const suggestions = getErrorSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH);
-            return createResult(`Search failed: ${error.message}`, true, suggestions);
+            return createResult('NPM package search failed - check search terms or try different keywords', true);
         }
     });
 }
@@ -1637,8 +1707,10 @@ function parseNpmSearchOutput(output) {
     }
 }
 
+const TOOL_NAME$2 = 'github_get_contents';
+const DESCRIPTION$2 = `Browse repository structure and verify file existence. Use before github_get_file_content to confirm files exist and understand organization, especially when the path is uncertain.`;
 function registerViewRepositoryStructureTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_GET_CONTENTS, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_CONTENTS], {
+    server.tool(TOOL_NAME$2, DESCRIPTION$2, {
         owner: z
             .string()
             .min(1)
@@ -1668,8 +1740,8 @@ function registerViewRepositoryStructureTool(server) {
             .describe('Directory path within repository (e.g., "src/components", "packages/core"). ' +
             'Leave empty for root. Use previous results to navigate deeper.'),
     }, {
-        title: TOOL_NAMES.GITHUB_GET_CONTENTS,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_GET_CONTENTS],
+        title: TOOL_NAME$2,
+        description: DESCRIPTION$2,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -1699,48 +1771,7 @@ function registerViewRepositoryStructureTool(server) {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            // Enhanced context-aware error suggestions
-            let suggestions = [];
-            const context = `${args.owner}/${args.repo}`;
-            if (errorMessage.includes('404') ||
-                errorMessage.includes('Not Found')) {
-                if (args.path) {
-                    suggestions = [
-                        `Try exploring root first: github_get_contents(owner: "${args.owner}", repo: "${args.repo}", branch: "${args.branch}", path: "")`,
-                        `Search for similar paths: github_search_code with path filters`,
-                    ];
-                }
-                else {
-                    suggestions = [
-                        `Search for repository: github_search_repositories(query: "${args.repo}")`,
-                        `Verify owner exists: github_search_repositories(owner: "${args.owner}")`,
-                    ];
-                }
-            }
-            else if (errorMessage.includes('403') ||
-                errorMessage.includes('Forbidden')) {
-                suggestions = [
-                    `Check authentication status: api_status_check`,
-                    `Try public repositories first to verify access`,
-                ];
-            }
-            else if (errorMessage.includes('rate limit')) {
-                suggestions = [
-                    `Check rate limit status: api_status_check`,
-                    `Wait before retrying or use authenticated requests`,
-                ];
-            }
-            else if (errorMessage.includes('invalid') ||
-                errorMessage.includes('branch')) {
-                suggestions = [
-                    `Find valid branches: github_search_repositories(query: "${context}")`,
-                    `Try common branches: main, master, develop`,
-                ];
-            }
-            else {
-                suggestions = getErrorSuggestions(TOOL_NAMES.GITHUB_GET_CONTENTS);
-            }
-            return createResult(`Repository exploration failed: ${errorMessage}. Context: ${context} on ${args.branch}${args.path ? ` at ${args.path}` : ''}`, true, suggestions);
+            return createResult(`Repository exploration failed: ${errorMessage} - verify repository exists and is accessible`, true);
         }
     });
 }
@@ -1751,7 +1782,7 @@ function registerViewRepositoryStructureTool(server) {
  * - Smart branch detection: fetches repository default branch automatically
  * - Intelligent fallback: tries requested -> default -> common branches
  * - Input validation: prevents path traversal and validates GitHub naming
- * - Enhanced error context: provides actionable suggestions for recovery
+ * - Clear error context: provides descriptive error messages
  * - Efficient caching: avoids redundant API calls
  */
 async function viewRepositoryStructure(params) {
@@ -1794,19 +1825,17 @@ async function viewRepositoryStructure(params) {
                 const errorMsg = lastError?.message || 'Unknown error';
                 if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
                     if (path) {
-                        throw new Error(`Path "${path}" not found in repository ${owner}/${repo}. ` +
-                            `Use github_get_contents with empty path first to discover the repository structure.`);
+                        throw new Error(`Path "${path}" not found - verify path exists or use github_search_code to find files`);
                     }
                     else {
-                        throw new Error(`Repository ${owner}/${repo} not found or no accessible branches. ` +
-                            `Tried branches: ${branchesToTry.join(', ')}`);
+                        throw new Error(`Repository not found: ${owner}/${repo} - verify owner/repo names or use github_search_repositories`);
                     }
                 }
                 else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
-                    throw new Error(`Access denied to repository ${owner}/${repo}`);
+                    throw new Error(`Access denied to repository ${owner}/${repo} - repository may be private or require authentication`);
                 }
                 else {
-                    throw new Error(`Repository ${owner}/${repo} not found or path "${path}" doesn't exist`);
+                    throw new Error(`Access failed: ${owner}/${repo} - check connection or repository permissions`);
                 }
             }
             // Limit total items to 100 for efficiency
@@ -1864,7 +1893,7 @@ async function viewRepositoryStructure(params) {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            return createErrorResult$1(`Repository access failed: ${owner}/${repo}${path ? ` at ${path}` : ''}`, new Error(errorMessage));
+            return createErrorResult$1('Repository access failed - verify repository exists and check authentication', new Error(errorMessage));
         }
     });
 }
@@ -1900,12 +1929,22 @@ async function getSmartBranchFallback(owner, repo, requestedBranch) {
     return branches;
 }
 
+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
+
+Filter by state, labels, assignee, or date ranges for comprehensive issue discovery.`;
 function registerSearchGitHubIssuesTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_ISSUES, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_ISSUES], {
+    server.tool(TOOL_NAME$1, DESCRIPTION$1, {
         query: z
             .string()
             .min(1, 'Search query is required and cannot be empty')
-            .describe('Search query to find issues'),
+            .describe('Search query with GITHUB SEARCH SYNTAX support. BOOLEAN OPERATORS: "bug AND crash" (both required), "feature OR enhancement" (either term), "error NOT test" (excludes). EXACT PHRASES: "memory leak" (precise matching). GITHUB QUALIFIERS: "is:open label:bug author:username" (native GitHub syntax). COMBINED: Mix boolean logic with qualifiers for precise issue discovery.'),
         owner: z
             .string()
             .min(1)
@@ -1998,26 +2037,26 @@ function registerSearchGitHubIssuesTool(server) {
             .max(50)
             .optional()
             .default(25)
-            .describe('Maximum results (default: 25)'),
+            .describe('Maximum results (default: 25, max: 50)'),
     }, {
-        title: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_ISSUES],
+        title: TOOL_NAME$1,
+        description: DESCRIPTION$1,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true,
     }, async (args) => {
         if (!args.query?.trim()) {
-            return createErrorResult$1('Search query is required and cannot be empty', new Error('Invalid query'));
+            return createErrorResult$1('Search query is required and cannot be empty - provide keywords to search for issues', new Error('Invalid query'));
         }
         if (args.query.length > 256) {
-            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less.', new Error('Query too long'));
+            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less - simplify your search terms', new Error('Query too long'));
         }
         try {
             return await searchGitHubIssues(args);
         }
         catch (error) {
-            return createErrorResult$1('Failed to search GitHub issues', error);
+            return createErrorResult$1('GitHub issues search failed - check repository exists and query is valid', error);
         }
     });
 }
@@ -2110,15 +2149,20 @@ function buildGitHubIssuesAPICommand(params) {
     return { command: 'api', args: [apiPath] };
 }
 
+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.`;
 function registerNpmViewPackageTool(server) {
-    server.tool(TOOL_NAMES.NPM_VIEW_PACKAGE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_VIEW_PACKAGE], {
+    server.tool(TOOL_NAME, DESCRIPTION, {
         packageName: z
             .string()
             .min(1, 'Package name is required')
             .describe('NPM package name to analyze. Returns complete package context including exports (critical for GitHub file discovery), repository URL, dependencies, and version history.'),
     }, {
-        title: TOOL_NAMES.NPM_VIEW_PACKAGE,
-        description: TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_VIEW_PACKAGE],
+        title: TOOL_NAME,
+        description: DESCRIPTION,
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
@@ -2126,17 +2170,17 @@ function registerNpmViewPackageTool(server) {
     }, async (args) => {
         try {
             if (!args.packageName || args.packageName.trim() === '') {
-                return createResult('Package name is required', true);
+                return createResult('Package name is required - provide a valid NPM package name', true);
             }
             // Basic package name validation
             if (!/^[a-z0-9@._/-]+$/.test(args.packageName)) {
-                return createResult('Invalid package name format', true);
+                return createResult('Invalid package name format - use standard NPM naming (e.g., "package-name" or "@scope/package")', true);
             }
             const result = await npmViewPackage(args.packageName);
             return result;
         }
         catch (error) {
-            return createResult(`Failed to get package metadata: ${error.message}`, true);
+            return createResult('Failed to get package metadata - verify package exists on NPM registry', true);
         }
     });
 }
@@ -2194,7 +2238,7 @@ async function npmViewPackage(packageName) {
             return createSuccessResult$1(viewResult);
         }
         catch (error) {
-            return createErrorResult$1('Failed to get npm package metadata', error);
+            return createErrorResult$1('Failed to get npm package metadata - package may not exist or registry unavailable', error);
         }
     });
 }