octocode-mcp 2.3.5 → 2.3.6

package/build/index.js

@@ -8,44 +8,12 @@ import NodeCache from 'node-cache';
 import crypto from 'crypto';
 import z from 'zod';
 
-const PROMPT_SYSTEM_PROMPT = `Expert code research assistant for GitHub/NPM ecosystems (public/private). Use powerful semantic search for efficient code discovery.
-
-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
-
-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
-
-NPM Search:
- Space-separated keywords only: "react state management"
- No boolean operators supported
- Use npm_view_package for direct package metadata → GitHub repo URL
-
-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
-
- CLI Help using CLI (use when needed to check failures)
- gh <command>  --help
- npm <command> --help
-
-Always provide code snippets and documentation references.`;
-
 const VERSION = 'v1';
 const cache = new NodeCache({
     stdTTL: 86400, // 24 hour cache
     checkperiod: 3600, // Check for expired keys every 1 hour
+    maxKeys: 1000, // Limit cache to 1000 entries to prevent unbounded growth
+    deleteOnExpire: true, // Automatically delete expired keys
 });
 function generateCacheKey(prefix, params) {
     const paramString = JSON.stringify(params, Object.keys(params).sort());
@@ -66,6 +34,9 @@ async function withCache(cacheKey, operation) {
     }
     return result;
 }
+function clearAllCache() {
+    cache.flushAll();
+}
 
 const safeExecAsync = promisify(exec);
 // Allowed command prefixes - this prevents shell injection by restricting to safe commands
@@ -85,10 +56,9 @@ function createSuccessResult(data) {
     };
 }
 function createErrorResult(message, error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
     return {
-        content: [
-            { type: 'text', text: `${message}: ${error.message}` },
-        ],
+        content: [{ type: 'text', text: `${message}: ${errorMessage}` }],
         isError: true,
     };
 }
@@ -128,23 +98,31 @@ function getShellConfig(preferredWindowsShell) {
     };
 }
 /**
- * Checks if a query contains GitHub search boolean operators
+ * Escape shell arguments with improved GitHub CLI query handling
  */
-function hasGitHubBooleanOperators(query) {
-    // Check for GitHub boolean operators (must be uppercase)
-    return (/\b(AND|OR|NOT)\b/.test(query) ||
-        /\s+(AND|OR|NOT)\s+/.test(query) ||
-        /"[^"]*\s+(AND|OR|NOT)\s+[^"]*"/.test(query));
-}
-/**
- * Escape shell arguments with improved GitHub CLI boolean query handling
- */
-function escapeShellArg(arg, shellType, isGitHubQuery) {
+function escapeShellArg(arg, shellType, isGitHubQuery // Flag to indicate if this is the main GitHub search query argument
+) {
     // Auto-detect shell type if not provided
     if (!shellType) {
         const isWindows = platform() === 'win32';
         shellType = isWindows ? 'cmd' : 'unix';
     }
+    // Special handling for GitHub search queries
+    if (isGitHubQuery) {
+        // If the argument already contains quotes, preserve them
+        if (arg.includes('"')) {
+            // For Unix-like shells, wrap the entire argument in single quotes
+            if (shellType === 'unix') {
+                return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+            }
+            // For Windows CMD
+            if (shellType === 'cmd') {
+                return `"${arg.replace(/"/g, '""')}"`;
+            }
+            // For PowerShell
+            return `'${arg.replace(/'/g, "''")}'`;
+        }
+    }
     switch (shellType) {
         case 'powershell':
             return escapePowerShellArg(arg);
@@ -182,25 +160,17 @@ function escapeWindowsCmdArg(arg) {
  * Escape arguments for Unix shells with special handling for GitHub CLI queries
  */
 function escapeUnixShellArg(arg, isGitHubQuery) {
-    // Special handling for GitHub CLI search queries to preserve boolean logic
-    if (isGitHubQuery && hasGitHubBooleanOperators(arg)) {
-        // For boolean queries with OR/AND/NOT, use double quotes to preserve operators
-        // GitHub CLI handles boolean logic properly when quoted
-        return `"${arg.replace(/"/g, '\\"')}"`;
-    }
-    // For GitHub queries with spaces but no boolean operators, quote them
-    if (isGitHubQuery &&
-        /\s/.test(arg) &&
-        !arg.startsWith('"') &&
-        !arg.endsWith('"')) {
-        return `"${arg.replace(/"/g, '\\"')}"`;
-    }
-    // For already quoted GitHub queries, pass through with escaped internal quotes
-    if (isGitHubQuery && arg.startsWith('"') && arg.endsWith('"')) {
-        return arg.replace(/\\"/g, '\\\\"'); // Escape already escaped quotes
+    // If it's a GitHub search query with special characters or spaces
+    if (isGitHubQuery && (arg.includes(' ') || /[:"']/g.test(arg))) {
+        // Preserve existing quotes if present
+        if (arg.includes('"')) {
+            return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+        }
+        // Add double quotes for terms that need them
+        return `"${arg}"`;
     }
     // Standard Unix shell escaping for other arguments
-    if (/[^\w\-._/:=@]/.test(arg)) {
+    if (/[^a-zA-Z0-9\-_./=@:]/.test(arg)) {
         return `'${arg.replace(/'/g, "'\"'\"'")}'`;
     }
     return arg;
@@ -241,12 +211,21 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     // Get shell configuration
     const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    // First argument is typically the search query for GitHub CLI search commands
+    // For GitHub search commands, qualifiers like "language:typescript" should not be escaped
+    // Only the main query term (if it contains spaces) needs escaping
     const escapedArgs = args.map((arg, index) => {
-        const isFirstArg = index === 0;
-        // Detect if this is a search query (first non-subcommand argument)
-        const isSearchQuery = command === 'search' && isFirstArg && !arg.startsWith('--');
-        return escapeShellArg(arg, shellConfig.type, isSearchQuery);
+        const isMainQueryArgument = command === 'search' && index === 1;
+        const isGitHubQualifier = command === 'search' &&
+            index > 1 &&
+            (arg.includes(':') || arg.startsWith('(')) &&
+            !arg.startsWith('--');
+        // Don't escape GitHub search qualifiers - they need to be passed as-is
+        // This includes qualifiers like "language:typescript", "user:microsoft", "org:microsoft"
+        // and complex expressions like "(user:microsoft OR org:microsoft)"
+        if (isGitHubQualifier) {
+            return arg;
+        }
+        return escapeShellArg(arg, shellConfig.type, isMainQueryArgument);
     });
     const fullCommand = `gh ${command} ${escapedArgs.join(' ')}`;
     const executeGhCommand = () => executeCommand(fullCommand, 'github', options, shellConfig);
@@ -307,9 +286,17 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
             const errorType = type === 'npm' ? 'NPM command error' : 'GitHub CLI command error';
             return createErrorResult(errorType, new Error(stderr));
         }
+        // Try to parse stdout as JSON, fallback to string if not possible
+        let parsedResult = stdout;
+        try {
+            parsedResult = JSON.parse(stdout);
+        }
+        catch {
+            // Not JSON, keep as string
+        }
         return createSuccessResult({
             command: fullCommand,
-            result: stdout,
+            result: parsedResult,
             timestamp: new Date().toISOString(),
             type,
             platform: platform(),
@@ -326,37 +313,91 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     }
 }
 
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["ERROR"] = "ERROR";
+    LogLevel["WARN"] = "WARN";
+    LogLevel["INFO"] = "INFO";
+    LogLevel["DEBUG"] = "DEBUG";
+})(LogLevel || (LogLevel = {}));
+class Logger {
+    appName;
+    timestamp;
+    constructor(appName = 'octocode-mcp', timestamp = true) {
+        this.appName = appName;
+        this.timestamp = timestamp;
+    }
+    formatMessage(level, message, ...args) {
+        const timestamp = this.timestamp ? `[${new Date().toISOString()}] ` : '';
+        const prefix = `${timestamp}[${this.appName}] [${level}]`;
+        const formattedArgs = args.length > 0
+            ? ' ' +
+                args
+                    .map(arg => {
+                    if (arg instanceof Error) {
+                        return `${arg.message}\n${arg.stack}`;
+                    }
+                    return typeof arg === 'object'
+                        ? JSON.stringify(arg, null, 2)
+                        : String(arg);
+                })
+                    .join(' ')
+            : '';
+        return `${prefix} ${message}${formattedArgs}`;
+    }
+    error(message, ...args) {
+        // eslint-disable-next-line no-console
+        console.error(this.formatMessage(LogLevel.ERROR, message, ...args));
+    }
+    warn(message, ...args) {
+        // eslint-disable-next-line no-console
+        console.warn(this.formatMessage(LogLevel.WARN, message, ...args));
+    }
+    info(message, ...args) {
+        // eslint-disable-next-line no-console
+        console.log(this.formatMessage(LogLevel.INFO, message, ...args));
+    }
+    debug(message, ...args) {
+        if (process.env.DEBUG === 'true' ||
+            process.env.NODE_ENV === 'development') {
+            // eslint-disable-next-line no-console
+            console.log(this.formatMessage(LogLevel.DEBUG, message, ...args));
+        }
+    }
+}
+// Singleton instance
+const logger = new Logger();
+
 function createResult(options) {
-    const { data, error, suggestions, cli_command } = options;
+    const { data, error } = options;
     if (error) {
         const errorMessage = typeof error === 'string'
             ? error
             : error.message || 'Unknown error';
-        // Build error response with optional CLI command
-        const errorResponse = { error: errorMessage };
-        if (suggestions) {
-            errorResponse.suggestions = suggestions;
-        }
-        if (cli_command) {
-            errorResponse.cli_command = cli_command;
-        }
+        const errorResponse = errorMessage;
         return {
-            content: [{ type: 'text', text: JSON.stringify(errorResponse, null, 2) }],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
-    // For successful responses, include cli_command if provided (for debugging)
-    if (cli_command && data && typeof data === 'object') {
-        const dataWithCli = { ...data, cli_command };
+    try {
         return {
-            content: [{ type: 'text', text: JSON.stringify(dataWithCli, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
             isError: false,
         };
     }
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-        isError: false,
-    };
+    catch (jsonError) {
+        logger.error('JSON serialization failed:', jsonError);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `JSON serialization failed: ${jsonError instanceof Error ? jsonError.message : 'Unknown error'}`,
+                },
+            ],
+            isError: true,
+        };
+    }
 }
 /**
  * Convert ISO timestamp to DDMMYYYY format
@@ -417,10 +458,149 @@ function optimizeTextMatch(fragment, maxLength = 100) {
     return truncated + '…';
 }
 
-const TOOL_NAME$9 = 'api_status_check';
-const DESCRIPTION$9 = `Get GitHub organizations list and check CLI authentication status. Use when searching private repos or when CLI tools fail.`;
+/**
+ * Constants for error messages and suggestions across MCP tools
+ * Centralized management of error handling for better consistency
+ */
+const ERROR_MESSAGES = {
+    // Authentication errors
+    AUTHENTICATION_REQUIRED: 'GitHub authentication required - run api_status_check tool',
+    // Rate limit errors
+    RATE_LIMIT_EXCEEDED: 'Rate limit exceeded - use specific filters (owner, language) or wait',
+    RATE_LIMIT_SIMPLE: 'Rate limit exceeded - wait or add filters',
+    // No results errors
+    NO_RESULTS_FOUND: 'No results found - try simpler query or different filters',
+    NO_REPOSITORIES_FOUND: 'No repositories found - try simpler query or different filters',
+    NO_COMMITS_FOUND: 'No commits found - try simpler query or different filters',
+    NO_ISSUES_FOUND: 'No issues found - try simpler query or different filters',
+    NO_PULL_REQUESTS_FOUND: 'No pull requests found - try simpler query or different filters',
+    NO_PACKAGES_FOUND: 'No packages found',
+    // Connection/network errors
+    SEARCH_FAILED: 'Search failed - check connection or simplify query',
+    REPOSITORY_SEARCH_FAILED: 'Repository search failed - check connection or query',
+    COMMIT_SEARCH_FAILED: 'Commit search failed',
+    ISSUE_SEARCH_FAILED: 'Issue search failed - check auth or simplify query',
+    PR_SEARCH_FAILED: 'PR search failed - check access and query syntax',
+    PACKAGE_SEARCH_FAILED: 'Package search failed - try different keywords',
+    // GitHub CLI errors
+    CLI_INVALID_RESPONSE: 'GitHub CLI invalid response - check "gh version" and update',
+    // Timeout errors
+    SEARCH_TIMEOUT: 'Search timed out - add filters (language, owner) or use specific terms',
+    // Query validation errors
+    QUERY_TOO_LONG: 'Query too long (max 256 chars) - simplify search terms',
+    QUERY_REQUIRED: 'Query required - provide search keywords',
+    EMPTY_QUERY: 'Empty query - try "useState", "authentication", or language:python',
+    QUERY_TOO_LONG_1000: 'Query too long (max 1000 chars) - use key terms like "error handling"',
+    REPO_OR_OWNER_NOT_FOUND: 'Repository/owner not found - check spelling, visibility, and permissions',
+    // Query syntax errors
+    INVALID_QUERY_SYNTAX: 'Invalid syntax - Boolean operators not supported, use quotes for phrases',
+    // Size/format validation errors
+    INVALID_SIZE_FORMAT: 'Invalid size format - use >N, <N, or N..M without quotes',
+    INVALID_SEARCH_SCOPE: 'Invalid scope - use "file" for content, "path" for filenames',
+    // API Status check errors
+    API_STATUS_CHECK_FAILED: 'API Status Check Failed',
+};
+const SUGGESTIONS = {
+    // Code search suggestions
+    CODE_SEARCH_NO_RESULTS: `No results found. Try this progression:
+1. Remove ALL filters and search with just one keyword
+2. Break into several queries with minimal query and filters
+3. Use api_status_check to verify access to private repos`,
+    // Repository search suggestions
+    REPO_SEARCH_PRIMARY_FILTER: 'Start with simple query (1-2 words), then add filters based on results',
+    // General search suggestions
+    SIMPLIFY_QUERY: `Try this search progression:
+1. Single keyword with NO filters
+2. Add ONE filter at a time
+3. Try synonyms and related terms
+4. Search broader categories`,
+    // Issue/PR search suggestions
+    PROVIDE_KEYWORDS: 'Start with simple keywords, then refine based on results',
+    PROVIDE_PR_KEYWORDS: 'Begin with basic terms, analyze results, then add filters',
+    // Package search suggestions
+    DIFFERENT_KEYWORDS: `Try multiple approaches:
+1. Single functional terms: "auth", "react"
+2. Break compound words: "authlib" → "auth"
+3. Search by use case: "user login" vs "authentication"
+4. Try category terms: "framework", "tool", "library"`,
+};
+// Helper function to get error message with context-specific suggestions
+function getErrorWithSuggestion(options) {
+    const { baseError, suggestion } = options;
+    const errors = Array.isArray(baseError) ? baseError : [baseError];
+    const suggestions = Array.isArray(suggestion)
+        ? suggestion
+        : suggestion
+            ? [suggestion]
+            : [];
+    let result = errors.join('\n');
+    if (suggestions.length > 0) {
+        result += '\n\nSuggestion: ' + suggestions.join('\n');
+    }
+    return result;
+}
+// Common error handling patterns
+function createAuthenticationError() {
+    return ERROR_MESSAGES.AUTHENTICATION_REQUIRED;
+}
+function createRateLimitError(detailed = true) {
+    return detailed
+        ? ERROR_MESSAGES.RATE_LIMIT_EXCEEDED
+        : ERROR_MESSAGES.RATE_LIMIT_SIMPLE;
+}
+function createNoResultsError(type = 'code') {
+    switch (type) {
+        case 'repositories':
+            return ERROR_MESSAGES.NO_REPOSITORIES_FOUND;
+        case 'commits':
+            return ERROR_MESSAGES.NO_COMMITS_FOUND;
+        case 'issues':
+            return ERROR_MESSAGES.NO_ISSUES_FOUND;
+        case 'pull_requests':
+            return ERROR_MESSAGES.NO_PULL_REQUESTS_FOUND;
+        case 'packages':
+            return ERROR_MESSAGES.NO_PACKAGES_FOUND;
+        default:
+            return ERROR_MESSAGES.NO_RESULTS_FOUND;
+    }
+}
+function createSearchFailedError(type = 'code') {
+    switch (type) {
+        case 'repositories':
+            return ERROR_MESSAGES.REPOSITORY_SEARCH_FAILED;
+        case 'commits':
+            return ERROR_MESSAGES.COMMIT_SEARCH_FAILED;
+        case 'issues':
+            return ERROR_MESSAGES.ISSUE_SEARCH_FAILED;
+        case 'pull_requests':
+            return ERROR_MESSAGES.PR_SEARCH_FAILED;
+        case 'packages':
+            return ERROR_MESSAGES.PACKAGE_SEARCH_FAILED;
+        default:
+            return ERROR_MESSAGES.SEARCH_FAILED;
+    }
+}
+
+const API_STATUS_CHECK_TOOL_NAME = 'apiStatusCheck';
+const DESCRIPTION$9 = `Check GitHub and NPM authentication status. Returns connected status and GitHub organizations for accessing private repositories. No parameters required.`;
+// Helper function to parse execution results with proper typing
+function parseExecResult(result) {
+    if (!result.isError && result.content?.[0]?.text) {
+        try {
+            const textContent = result.content[0].text;
+            if (typeof textContent === 'string') {
+                const parsed = JSON.parse(textContent);
+                return typeof parsed === 'object' && parsed !== null ? parsed : null;
+            }
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    return null;
+}
 function registerApiStatusCheckTool(server) {
-    server.registerTool(TOOL_NAME$9, {
+    server.registerTool(API_STATUS_CHECK_TOOL_NAME, {
         description: DESCRIPTION$9,
         inputSchema: {},
         annotations: {
@@ -440,32 +620,22 @@ function registerApiStatusCheckTool(server) {
             try {
                 const authResult = await executeGitHubCommand('auth', ['status']);
                 if (!authResult.isError) {
-                    let authData;
-                    try {
-                        authData = JSON.parse(authResult.content[0].text);
-                    }
-                    catch (parseError) {
-                        // JSON parsing error - this is unexpected, propagate it
-                        throw new Error(`GitHub auth response JSON parsing failed: ${parseError.message}`);
-                    }
-                    const isAuthenticated = authData.result?.includes('Logged in') ||
-                        authData.result?.includes('github.com');
+                    const execResult = parseExecResult(authResult);
+                    const isAuthenticated = typeof execResult?.result === 'string'
+                        ? execResult.result.includes('Logged in') ||
+                            execResult.result.includes('github.com')
+                        : false;
                     if (isAuthenticated) {
                         githubConnected = true;
                         // Get user organizations using direct GitHub CLI command
                         try {
                             const orgsResult = await executeGitHubCommand('org', ['list', '--limit=50'], { cache: false });
-                            if (!orgsResult.isError) {
-                                let execResult;
-                                try {
-                                    execResult = JSON.parse(orgsResult.content[0].text);
-                                }
-                                catch (parseError) {
-                                    // JSON parsing error for organizations - treat as no orgs available
-                                    execResult = { result: '' };
-                                }
-                                const output = execResult.result;
-                                // Parse organizations into clean array
+                            const orgsExecResult = parseExecResult(orgsResult);
+                            const output = typeof orgsExecResult?.result === 'string'
+                                ? orgsExecResult.result
+                                : '';
+                            // Parse organizations into clean array
+                            if (typeof output === 'string') {
                                 organizations = output
                                     .split('\n')
                                     .map((org) => org.trim())
@@ -500,23 +670,12 @@ function registerApiStatusCheckTool(server) {
                 if (!npmResult.isError) {
                     npmConnected = true;
                     // Get registry info
-                    try {
-                        const registryResult = await executeNpmCommand('config', ['get', 'registry'], { timeout: 3000 });
-                        if (!registryResult.isError) {
-                            let registryData;
-                            try {
-                                registryData = JSON.parse(registryResult.content[0].text);
-                            }
-                            catch (parseError) {
-                                // JSON parsing error for registry - use default
-                                registryData = { result: 'https://registry.npmjs.org/' };
-                            }
-                            registry = registryData.result.trim();
-                        }
-                    }
-                    catch {
-                        registry = 'https://registry.npmjs.org/'; // default fallback
-                    }
+                    const registryResult = await executeNpmCommand('config', ['get', 'registry'], { timeout: 3000 });
+                    const registryExecResult = parseExecResult(registryResult);
+                    registry =
+                        typeof registryExecResult?.result === 'string'
+                            ? registryExecResult.result.trim()
+                            : 'https://registry.npmjs.org/'; // default fallback
                 }
             }
             catch (error) {
@@ -529,120 +688,66 @@ function registerApiStatusCheckTool(server) {
                 }
                 npmConnected = false;
             }
-            // Build structured response object
-            const loginStatus = {
-                login: {
-                    github: {
-                        connected: githubConnected,
-                        user_organizations: organizations,
-                    },
-                    npm: {
-                        connected: npmConnected,
-                        registry: registry || 'https://registry.npmjs.org/',
+            return createResult({
+                data: {
+                    login: {
+                        github: {
+                            connected: githubConnected,
+                            user_organizations: organizations,
+                        },
+                        npm: {
+                            connected: npmConnected,
+                            registry: registry || 'https://registry.npmjs.org/',
+                        },
+                        hints: [
+                            'Use user organizations to search private repositories when requested - verify access by checking query and repository structure',
+                        ],
                     },
-                    hints: [
-                        'use user organizations: to search on private repositories in case the user asked about private repo - check by query nd structure',
-                    ],
                 },
-            };
-            return createResult({ data: loginStatus });
+            });
         }
         catch (error) {
             return createResult({
-                error: `API Status Check Failed\nError: ${error instanceof Error ? error.message : 'Unknown error'}\n\nThis usually indicates a system configuration issue. Please verify GitHub CLI and NPM are properly installed.`,
+                error: `${ERROR_MESSAGES.API_STATUS_CHECK_FAILED}\nError: ${error instanceof Error ? error.message : 'Unknown error'}\n\nThis usually indicates a system configuration issue. Please verify GitHub CLI and NPM are properly installed.`,
             });
         }
     });
 }
 
-const TOOL_NAME$8 = 'github_search_code';
-const DESCRIPTION$8 = `Search code across GitHub repositories with powerful GitHub search syntax and advanced filtering.
-
-BOOLEAN LOGIC (MOST POWERFUL):
-- "useState OR useEffect" - Find either hook
-- "useState AND useEffect" - Find both hooks together
-- "authentication AND (jwt OR oauth)" - Complex logic combinations
-- "NOT deprecated" - Exclude deprecated code
-
-EMBEDDED QUALIFIERS:
-- "useState language:javascript filename:*.jsx" - Hook in React files
-- "authentication language:python path:*/security/*" - Security code in Python
-- "docker OR kubernetes language:yaml extension:yml" - Container configs
-
-TRADITIONAL FILTERS (ALSO SUPPORTED):
-- language: "javascript", owner: "microsoft", filename: "package.json"
-
-PROVEN PATTERNS: "authentication" → +language → +owner → +filename
-KEY TIPS: language filter = 90% speed boost, boolean operators work perfectly with filters`;
-function registerGitHubSearchCodeTool(server) {
-    server.registerTool(TOOL_NAME$8, {
+const GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME = 'githubViewRepoStructure';
+const DESCRIPTION$8 = `Explore repository structure and navigate directories. Auto-detects branches and provides file/folder listings with size information. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), path (optional).`;
+function registerViewRepositoryStructureTool(server) {
+    server.registerTool(GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME, {
         description: DESCRIPTION$8,
         inputSchema: {
-            query: z
-                .string()
-                .min(1)
-                .describe(`Search query with GitHub syntax. BOOLEAN LOGIC: "useState OR useEffect", "authentication AND jwt", "NOT deprecated". EMBEDDED QUALIFIERS: "useState language:javascript", "docker path:*/config/*". EXACT PHRASES: "error handling".
-
-POWERFUL EXAMPLES: "useState OR useEffect language:javascript", "authentication AND (jwt OR oauth)", "docker OR kubernetes language:yaml", "NOT deprecated language:python"
-RULES: Boolean operators MUST be uppercase (AND, OR, NOT). Combines perfectly with traditional filters.`),
-            language: z
-                .string()
-                .optional()
-                .describe(`MOST EFFECTIVE FILTER - 90% speed boost! Essential for popular languages.
-
-POPULAR: javascript, typescript, python, java, go, rust, php, ruby, swift, kotlin, dart
-SYSTEMS: c, cpp, assembly, shell, dockerfile, yaml`),
             owner: z
-                .union([z.string(), z.array(z.string())])
-                .optional()
-                .describe(`HIGH IMPACT - Reduces search space by 95%+
-
-EXAMPLES: "microsoft", "google", "facebook" or ["microsoft", "google"]
-POPULAR: microsoft, google, facebook, amazon, apache, hashicorp, kubernetes`),
-            filename: z
                 .string()
-                .optional()
-                .describe(`SURGICAL PRECISION for configs and special files
-
-TARGETS: "package.json", "Dockerfile", "webpack.config.js", ".eslintrc", "README.md"
-STRATEGY: filename:package.json + "react typescript"`),
+                .min(1)
+                .max(100)
+                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, 'Invalid GitHub username/org format')
+                .describe(`Repository owner/org name (e.g., 'microsoft', 'google', NOT 'microsoft/vscode')`),
             repo: z
-                .union([z.string(), z.array(z.string())])
-                .optional()
-                .describe(`PRECISE TARGETING for specific repositories
-
-FORMAT: "facebook/react", "microsoft/vscode" or ["facebook/react", "vuejs/vue"]
-USE: Deep dive analysis of specific projects`),
-            extension: z
-                .string()
-                .optional()
-                .describe(`FILE TYPE PRECISION - More specific than language filter
-
-POPULAR: js, ts, jsx, tsx, py, java, go, rs, rb, php, cs, sh, yml, json, md
-USE: extension:tsx (React TypeScript only), extension:dockerfile`),
-            match: z
-                .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
-                .optional()
-                .describe(`SEARCH SCOPE: "file" (content), "path" (filenames), ["file", "path"] (both)
-
-EXAMPLES: match:"path" + "test" (find test files), match:"file" + "useState"`),
-            size: z
                 .string()
-                .optional()
-                .describe(`FILE SIZE FILTER: ">100" (>100KB), "<50" (<50KB), "10..100" (range)
-
-STRATEGY: "<200" (avoid huge files), ">20" (substantial code), "<10" (configs)`),
-            limit: z
-                .number()
-                .int()
                 .min(1)
                 .max(100)
+                .regex(/^[a-zA-Z0-9._-]+$/, 'Invalid repository name format')
+                .describe('Repository name (case-sensitive)'),
+            branch: z
+                .string()
+                .min(1)
+                .max(255)
+                .regex(/^[^\s]+$/, 'Branch name cannot contain spaces')
+                .describe('Branch name. Falls back to default branch if not found'),
+            path: z
+                .string()
                 .optional()
-                .default(30)
-                .describe(`RESULTS: 10-20 (quick), 30 (default), 50-100 (comprehensive). Use filters over high limits.`),
+                .default('')
+                .refine(path => !path.includes('..'), 'Path traversal not allowed')
+                .refine(path => path.length <= 500, 'Path too long')
+                .describe('Directory path within repository. Leave empty for root.'),
         },
         annotations: {
-            title: 'GitHub Code Search - Smart & Efficient',
+            title: 'GitHub Repository Explorer',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -650,604 +755,170 @@ STRATEGY: "<200" (avoid huge files), ">20" (substantial code), "<10" (configs)`)
         },
     }, async (args) => {
         try {
-            // Validate parameter combinations
-            const validationError = validateSearchParameters(args);
-            if (validationError) {
-                return createResult({ error: validationError });
-            }
-            const result = await searchGitHubCode(args);
-            if (result.isError) {
-                return result;
-            }
-            const execResult = JSON.parse(result.content[0].text);
-            const codeResults = JSON.parse(execResult.result);
-            // GitHub CLI returns a direct array, not an object with total_count and items
-            const items = Array.isArray(codeResults) ? codeResults : [];
-            // Smart handling for no results - provide actionable suggestions
-            if (items.length === 0) {
-                return handleNoResults(args, execResult.command);
-            }
-            // Transform to optimized format
-            const optimizedResult = transformToOptimizedFormat$1(items, args);
-            return createResult({ data: optimizedResult });
+            const result = await viewRepositoryStructure(args);
+            return result;
         }
         catch (error) {
-            const errorMessage = error.message || '';
-            // Handle JSON parsing errors
-            if (errorMessage.includes('JSON')) {
-                return createResult({
-                    error: 'GitHub CLI returned invalid response - check if GitHub CLI is up to date with "gh version" and try again',
-                });
-            }
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
             return createResult({
-                error: 'GitHub code search failed',
-                suggestions: [
-                    'Try simpler queries without NOT operators',
-                    'Use filters (language, owner, filename) instead of complex boolean',
-                    'Check authentication with api_status_check',
-                ],
+                error: `Failed to explore repository. ${errorMessage}. Verify repository exists and is accessible`,
             });
         }
     });
 }
 /**
- * Smart handler for no results - provides actionable suggestions
+ * Views the structure of a GitHub repository at a specific path.
+ * Optimized for code analysis workflows with smart defaults and clear errors.
  */
-function handleNoResults(params, cliCommand) {
-    const suggestions = generateSmartSuggestions(params);
-    const fallbackQueries = generateFallbackQueries(params);
-    return createResult({
-        data: {
-            items: [],
-            total_count: 0,
-            smart_suggestions: {
-                message: "No results found. Here are smart strategies to find what you're looking for:",
-                suggestions,
-                fallback_queries: fallbackQueries,
-                next_steps: [
-                    'Try one of the fallback queries above',
-                    'Remove some filters to broaden the search',
-                    'Use different keywords or synonyms',
-                    'Check spelling and try variations',
-                ],
-            },
-            metadata: {
-                has_filters: !!(params.language ||
-                    params.owner ||
-                    params.filename ||
-                    params.extension),
-                search_scope: params.match
-                    ? Array.isArray(params.match)
-                        ? params.match.join(',')
-                        : params.match
-                    : 'file',
-            },
-            cli_command: cliCommand,
-        },
+async function viewRepositoryStructure(params) {
+    const cacheKey = generateCacheKey('gh-repo-structure', params);
+    return withCache(cacheKey, async () => {
+        const { owner, repo, branch, path = '' } = params;
+        try {
+            // Clean up path
+            const cleanPath = path.startsWith('/') ? path.substring(1) : path;
+            // Try the requested branch first, then fallback to main/master
+            const branchesToTry = await getSmartBranchFallback(owner, repo, branch);
+            let items = [];
+            let usedBranch = branch;
+            let lastError = null;
+            let attemptCount = 0;
+            const maxAttempts = 3; // Prevent infinite loops
+            for (const tryBranch of branchesToTry) {
+                if (attemptCount >= maxAttempts)
+                    break;
+                attemptCount++;
+                try {
+                    const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
+                    const result = await executeGitHubCommand('api', [apiPath], {
+                        cache: false,
+                    });
+                    if (!result.isError) {
+                        const execResult = JSON.parse(result.content[0].text);
+                        const apiItems = execResult.result;
+                        items = Array.isArray(apiItems) ? apiItems : [apiItems];
+                        usedBranch = tryBranch;
+                        break;
+                    }
+                    else {
+                        lastError = new Error(result.content[0].text);
+                    }
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    // Try next branch
+                    continue;
+                }
+            }
+            if (items.length === 0) {
+                // Use the most descriptive error message
+                const errorMsg = lastError?.message || 'Unknown error';
+                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
+                    if (path) {
+                        return createResult({
+                            error: `Path "${path}" not found. Verify the path or use github_search_code to find files`,
+                        });
+                    }
+                    else {
+                        return createResult({
+                            error: `Repository not found: ${owner}/${repo}. Check spelling and case sensitivity`,
+                        });
+                    }
+                }
+                else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                    return createResult({
+                        error: `Access denied to ${owner}/${repo}. Repository may be private - use api_status_check`,
+                    });
+                }
+                else {
+                    return createResult({
+                        error: `Failed to access ${owner}/${repo}. Check network connection`,
+                    });
+                }
+            }
+            // Limit total items to 100 for efficiency
+            const limitedItems = items.slice(0, 100);
+            // Sort: directories first, then alphabetically
+            limitedItems.sort((a, b) => {
+                if (a.type !== b.type) {
+                    return a.type === 'dir' ? -1 : 1;
+                }
+                return a.name.localeCompare(b.name);
+            });
+            // Create simplified, token-efficient structure
+            const files = limitedItems
+                .filter(item => item.type === 'file')
+                .map(item => ({
+                name: item.name,
+                size: item.size,
+                url: item.path, // Use path for fetching
+            }));
+            const folders = limitedItems
+                .filter(item => item.type === 'dir')
+                .map(item => ({
+                name: item.name,
+                url: item.path, // Use path for browsing
+            }));
+            return createResult({
+                data: {
+                    repository: `${owner}/${repo}`,
+                    branch: usedBranch,
+                    path: cleanPath || '/',
+                    githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
+                    files: {
+                        count: files.length,
+                        files: files,
+                    },
+                    folders: {
+                        count: folders.length,
+                        folders: folders,
+                    },
+                },
+            });
+        }
+        catch (error) {
+            return createResult({
+                error: `Failed to access repository. ${error}. Verify repository name and authentication`,
+            });
+        }
     });
 }
 /**
- * Generate smart suggestions based on current search parameters
+ * Smart branch detection with automatic fallback to common branch names.
  */
-function generateSmartSuggestions(params) {
-    const suggestions = [];
-    // Query-specific suggestions
-    if (params.query.includes('"')) {
-        suggestions.push('Remove quotes to search for individual terms instead of exact phrase');
-    }
-    if (params.query.includes(' AND ') || params.query.includes(' OR ')) {
-        suggestions.push('Try simpler queries without boolean operators');
-    }
-    if (params.query.length > 50) {
-        suggestions.push('Simplify query - shorter terms often work better');
-    }
-    // Filter-specific suggestions
-    if (!params.language) {
-        suggestions.push('Add language filter - this improves results by 90%');
-    }
-    if (params.language && !params.owner && !params.filename) {
-        suggestions.push('Add owner filter to target specific organizations');
-    }
-    if (params.owner && params.repo) {
-        suggestions.push('Remove repo filter and search across all repos in the organization');
-    }
-    if (params.filename) {
-        suggestions.push('Remove filename filter to search all file types');
-    }
-    if (params.extension && params.language) {
-        suggestions.push('Try removing extension filter (language filter might be sufficient)');
-    }
-    // Always provide generic fallbacks
-    if (suggestions.length === 0) {
-        suggestions.push('Try a broader search with fewer filters');
-        suggestions.push('Use more common/general terms');
-        suggestions.push('Check for typos in query or filter values');
-    }
-    return suggestions.slice(0, 5); // Limit to top 5 suggestions
-}
-/**
- * Generate fallback queries that are likely to succeed
- */
-function generateFallbackQueries(params) {
-    const fallbacks = [];
-    // Extract key terms from original query
-    const keyTerms = extractKeyTerms(params.query);
-    // Fallback 1: Simplify query, keep language if present
-    if (keyTerms.length > 1) {
-        const simplifiedQuery = keyTerms[0];
-        fallbacks.push({
-            query: simplifiedQuery,
-            description: `Search for just "${simplifiedQuery}"${params.language ? ` in ${params.language}` : ''}`,
-            rationale: 'Single term searches often yield better results',
-        });
-    }
-    // Fallback 2: Remove filters but keep core query
-    if (params.language || params.owner || params.filename || params.extension) {
-        fallbacks.push({
-            query: keyTerms.join(' '),
-            description: `Search "${keyTerms.join(' ')}" without filters`,
-            rationale: 'Removes restrictive filters for broader results',
-        });
-    }
-    // Fallback 3: Language-specific popular search
-    if (params.language) {
-        const popularTerms = getPopularTermsForLanguage(params.language);
-        if (popularTerms.length > 0) {
-            fallbacks.push({
-                query: popularTerms[0],
-                description: `Popular ${params.language} pattern: "${popularTerms[0]}"`,
-                rationale: `Common patterns in ${params.language} development`,
-            });
-        }
-    }
-    // Fallback 4: Broader category search
-    const category = inferCategory(params.query);
-    if (category) {
-        fallbacks.push({
-            query: category,
-            description: `Broader search: "${category}"`,
-            rationale: 'Searches the general category for related patterns',
+async function getSmartBranchFallback(owner, repo, requestedBranch) {
+    const branches = [requestedBranch];
+    try {
+        // Try to get repository info to find default branch
+        const repoInfoResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+            cache: false,
         });
-    }
-    return fallbacks.slice(0, 4);
-}
-/**
- * Extract key terms from search query
- */
-function extractKeyTerms(query) {
-    // Remove quotes, boolean operators, and special characters
-    const cleaned = query
-        .replace(/["']/g, '')
-        .replace(/\b(AND|OR|NOT)\b/gi, '')
-        .replace(/[^\w\s]/g, ' ')
-        .replace(/\s+/g, ' ')
-        .trim();
-    return cleaned.split(' ').filter(term => term.length > 2);
-}
-/**
- * Get popular search terms for specific programming languages
- */
-function getPopularTermsForLanguage(language) {
-    const popularTerms = {
-        javascript: [
-            'useState',
-            'async await',
-            'fetch api',
-            'event listener',
-            'promise',
-        ],
-        typescript: [
-            'interface',
-            'generic type',
-            'type guard',
-            'enum',
-            'namespace',
-        ],
-        python: ['def function', 'import', 'class method', 'lambda', 'decorator'],
-        java: [
-            'public class',
-            'static method',
-            'interface',
-            'annotation',
-            'spring',
-        ],
-        go: ['func main', 'interface', 'goroutine', 'channel', 'struct'],
-        rust: ['fn main', 'impl', 'trait', 'enum', 'match'],
-        cpp: ['class', 'template', 'namespace', 'virtual', 'std::'],
-        c: ['int main', 'struct', 'malloc', 'pointer', 'header'],
-        php: ['function', 'class', 'namespace', 'interface', 'trait'],
-        ruby: ['def', 'class', 'module', 'block', 'gem'],
-        swift: ['func', 'class', 'protocol', 'extension', 'guard'],
-        kotlin: ['fun', 'class', 'interface', 'data class', 'coroutine'],
-        dart: ['class', 'function', 'widget', 'async', 'future'],
-        shell: ['function', 'if then', 'for loop', 'variable', 'script'],
-        yaml: ['version', 'name', 'build', 'deploy', 'config'],
-        dockerfile: ['FROM', 'RUN', 'COPY', 'EXPOSE', 'CMD'],
-    };
-    return popularTerms[language.toLowerCase()] || [];
-}
-/**
- * Infer search category from query terms
- */
-function inferCategory(query) {
-    const categories = {
-        authentication: [
-            'auth',
-            'login',
-            'oauth',
-            'jwt',
-            'token',
-            'passport',
-            'session',
-        ],
-        database: ['db', 'sql', 'query', 'model', 'schema', 'migration', 'orm'],
-        api: ['rest', 'graphql', 'endpoint', 'route', 'request', 'response'],
-        testing: ['test', 'spec', 'mock', 'assert', 'unit', 'integration'],
-        config: ['config', 'setting', 'env', 'environment', 'setup'],
-        ui: ['component', 'button', 'form', 'modal', 'layout', 'style'],
-        error: ['error', 'exception', 'try', 'catch', 'throw', 'handle'],
-        performance: ['cache', 'optimization', 'memory', 'speed', 'performance'],
-        security: ['security', 'encrypt', 'hash', 'validate', 'sanitize'],
-    };
-    const queryLower = query.toLowerCase();
-    for (const [category, keywords] of Object.entries(categories)) {
-        if (keywords.some(keyword => queryLower.includes(keyword))) {
-            return category;
-        }
-    }
-    return null;
-}
-/**
- * Transform GitHub CLI response to optimized format with enhanced metadata
- */
-function transformToOptimizedFormat$1(items, params) {
-    const searchEfficiency = calculateSearchEfficiency(params);
-    // Extract repository info if single repo search
-    const singleRepo = extractSingleRepository$1(items);
-    const optimizedItems = items.map(item => ({
-        path: item.path,
-        matches: item.textMatches.map(match => ({
-            context: optimizeTextMatch(match.fragment, 120), // Increased context for better understanding
-            positions: match.matches.map(m => m.indices),
-        })),
-        url: singleRepo ? item.path : simplifyGitHubUrl(item.url),
-    }));
-    const result = {
-        items: optimizedItems,
-        total_count: items.length,
-    };
-    // Add repository info if single repo
-    if (singleRepo) {
-        result.repository = {
-            name: singleRepo.nameWithOwner,
-            url: simplifyRepoUrl(singleRepo.url),
-        };
-    }
-    // Enhanced metadata with search efficiency and tips
-    result.metadata = {
-        has_filters: !!(params.language ||
-            params.owner ||
-            params.filename ||
-            params.extension),
-        search_scope: params.match
-            ? Array.isArray(params.match)
-                ? params.match.join(',')
-                : params.match
-            : 'file',
-        search_efficiency: searchEfficiency,
-    };
-    // Add performance tips for low-efficiency searches
-    if (searchEfficiency.score < 7) {
-        result.metadata.performance_tips = generatePerformanceTips(params);
-    }
-    return result;
-}
-/**
- * Calculate search efficiency score and provide insights
- */
-function calculateSearchEfficiency(params) {
-    let score = 5; // Base score
-    const factors = [];
-    const recommendations = [];
-    // Language filter is huge efficiency boost
-    if (params.language) {
-        score += 3;
-        factors.push('Language filter (+3)');
-    }
-    else {
-        recommendations.push('Add language filter for 90% performance boost');
-    }
-    // Owner filter provides good targeting
-    if (params.owner) {
-        score += 2;
-        factors.push('Owner filter (+2)');
-    }
-    // Filename filter is very efficient
-    if (params.filename) {
-        score += 2;
-        factors.push('Filename filter (+2)');
-    }
-    // Extension filter adds precision
-    if (params.extension) {
-        score += 1;
-        factors.push('Extension filter (+1)');
-    }
-    // Repository filter is highly targeted
-    if (params.repo) {
-        score += 2;
-        factors.push('Repository filter (+2)');
-    }
-    // Size filter helps avoid huge files
-    if (params.size) {
-        score += 1;
-        factors.push('Size filter (+1)');
-    }
-    // Boolean operators are now properly supported
-    if (params.query.includes(' OR ')) {
-        // OR is powerful when used correctly
-        if (params.language || params.owner) {
-            score += 1;
-            factors.push('OR with filters (+1)');
-        }
-        else {
-            factors.push('OR operator (neutral)');
-            recommendations.push('Add language or owner filter with OR for better targeting');
-        }
-    }
-    if (params.query.includes(' AND ')) {
-        score += 1;
-        factors.push('AND operator (+1)');
-    }
-    if (params.query.includes(' NOT ')) {
-        // NOT can be useful but less efficient
-        factors.push('NOT operator (neutral)');
-        recommendations.push('Consider positive filters alongside NOT for better results');
-    }
-    if (params.query.length > 100) {
-        score -= 1;
-        factors.push('Long query (-1)');
-        recommendations.push('Simplify query for better results');
-    }
-    return {
-        score: Math.max(1, Math.min(10, score)),
-        factors,
-        recommendations,
-    };
-}
-/**
- * Generate performance tips for inefficient searches
- */
-function generatePerformanceTips(params) {
-    const tips = [];
-    if (!params.language) {
-        tips.push('Add language filter - single biggest performance boost');
-    }
-    if (!params.owner && !params.repo) {
-        tips.push('Add owner filter to target specific organizations');
-    }
-    if (params.query.includes(' OR ') && !params.language && !params.owner) {
-        tips.push('Add language or owner filter with OR for better targeting');
-    }
-    if (params.query.includes(' NOT ')) {
-        tips.push('Combine NOT with positive filters (language, filename, etc.) for best results');
-    }
-    if (!params.filename && !params.extension) {
-        tips.push('Add filename or extension filter for file-type precision');
-    }
-    return tips.slice(0, 3);
-}
-/**
- * Extract single repository if all results are from same repo
- */
-function extractSingleRepository$1(items) {
-    if (items.length === 0)
-        return null;
-    const firstRepo = items[0].repository;
-    const allSameRepo = items.every(item => item.repository.nameWithOwner === firstRepo.nameWithOwner);
-    return allSameRepo ? firstRepo : null;
-}
-/**
- * Build command line arguments for GitHub CLI with improved parameter handling
- * Ensures exact string search capability with proper quote and escape handling
- */
-function buildGitHubCliArgs(params) {
-    const args = ['code'];
-    // Handle exact string search - preserve quotes and special characters
-    const searchQuery = params.query;
-    // For exact string searches (quoted strings), preserve the quotes
-    // For special characters and escape sequences, pass them through
-    // GitHub CLI will handle the proper escaping to the GitHub API
-    if (searchQuery.includes('"') || searchQuery.includes("'")) {
-        // Already has quotes - exact string search
-        args.push(searchQuery);
-    }
-    else if (searchQuery.includes('\\') ||
-        /[<>{}[\]()&|;$`!*?~]/.test(searchQuery)) {
-        // Contains special characters that might need exact matching
-        // Let GitHub CLI handle the escaping - don't double-escape
-        args.push(searchQuery);
-    }
-    else {
-        // Regular search query
-        args.push(searchQuery);
-    }
-    // Add filters in order of effectiveness for better CLI performance
-    if (params.language) {
-        args.push(`--language=${params.language}`);
-    }
-    if (params.filename) {
-        args.push(`--filename=${params.filename}`);
-    }
-    if (params.extension) {
-        args.push(`--extension=${params.extension}`);
-    }
-    if (params.size) {
-        args.push(`--size=${params.size}`);
-    }
-    // Always add limit
-    if (params.limit) {
-        args.push(`--limit=${params.limit}`);
-    }
-    // Handle match parameter
-    if (params.match) {
-        const matchValues = Array.isArray(params.match)
-            ? params.match
-            : [params.match];
-        // 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 with improved validation
-    if (params.repo) {
-        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
-        if (params.owner) {
-            const owners = Array.isArray(params.owner)
-                ? params.owner
-                : [params.owner];
-            // 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}`);
-                    }
-                });
-            });
-        }
-        else {
-            // Handle repo without owner (must be in owner/repo format)
-            repos.forEach(repo => {
-                args.push(`--repo=${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 = buildGitHubCliArgs(params);
-            const result = await executeGitHubCommand('search', args, {
-                cache: false,
-            });
-            return result;
-        }
-        catch (error) {
-            const errorMessage = error.message || '';
-            // Parse specific GitHub CLI error types
-            if (errorMessage.includes('authentication')) {
-                return createResult({
-                    error: 'GitHub authentication required - run api_status_check tool',
-                });
-            }
-            if (errorMessage.includes('rate limit')) {
-                return createResult({
-                    error: 'GitHub rate limit exceeded - use more specific filters or wait',
-                    suggestions: [
-                        'Add language filter to reduce search scope',
-                        'Use owner filter to target specific organizations',
-                        'Add filename filter for precision targeting',
-                        'Wait a few minutes and try again',
-                    ],
-                });
-            }
-            if (errorMessage.includes('validation failed') ||
-                errorMessage.includes('Invalid query')) {
-                return createResult({
-                    error: 'Invalid query syntax. GitHub legacy search has limitations.',
-                    suggestions: [
-                        'Remove NOT operators (use positive filters instead)',
-                        'Simplify OR logic to separate searches',
-                        'Use quotes for exact phrases: "error handling"',
-                        'Try: language:python + "function definition" instead of complex boolean',
-                    ],
-                });
-            }
-            if (errorMessage.includes('repository not found') ||
-                errorMessage.includes('owner not found')) {
-                return createResult({
-                    error: 'Repository or owner not found',
-                    suggestions: [
-                        'Verify exact owner/repository names (case-sensitive)',
-                        'Check if repository is private and you have access',
-                        'Remove repo filter to search across all repositories',
-                        'Use owner filter instead of specific repo for broader search',
-                    ],
-                });
-            }
-            if (errorMessage.includes('timeout')) {
-                return createResult({
-                    error: 'Search timeout - query too broad',
-                    suggestions: [
-                        'Add language filter to narrow scope',
-                        'Use owner or repo filters for targeting',
-                        'Simplify query terms',
-                        'Add filename filter for specific file types',
-                    ],
-                });
+        if (!repoInfoResult.isError) {
+            const execResult = JSON.parse(repoInfoResult.content[0].text);
+            const repoData = execResult.result;
+            const defaultBranch = repoData.default_branch;
+            if (defaultBranch && !branches.includes(defaultBranch)) {
+                branches.push(defaultBranch);
             }
-            // Generic fallback with helpful guidance
-            return createResult({
-                error: 'Code search failed',
-                suggestions: [
-                    'Check GitHub CLI authentication with: gh auth status',
-                    'Simplify query and add language filter',
-                    'Try owner filter for targeted search',
-                    'Use api_status_check tool to verify setup',
-                ],
-            });
         }
-    });
-}
-/**
- * Enhanced validation with helpful suggestions
- * Supports exact string search with quotes and special characters
- */
-function validateSearchParameters(params) {
-    // Query validation
-    if (!params.query.trim()) {
-        return 'Empty query. Try: "useState", "authentication", "docker setup", or use filters like language:python';
     }
-    if (params.query.length > 1000) {
-        return 'Query too long (max 1000 chars). Simplify to key terms like "error handling" instead of full sentences.';
+    catch {
+        // If we can't get repo info, proceed with standard fallbacks
     }
-    // Repository validation - allow owner/repo format in repo field
-    if (params.repo && !params.owner) {
-        const repoValues = Array.isArray(params.repo) ? params.repo : [params.repo];
-        const hasOwnerFormat = repoValues.every(repo => repo.includes('/'));
-        if (!hasOwnerFormat) {
-            return 'Repository format error. Use "owner/repo" format like "facebook/react" or provide both owner and repo parameters.';
+    // Add common branch names if not already included
+    const commonBranches = ['main', 'master', 'develop', 'dev'];
+    commonBranches.forEach(branch => {
+        if (!branches.includes(branch)) {
+            branches.push(branch);
         }
-    }
-    // Support exact string searches with quotes and special characters
-    // Remove overly restrictive validation for escape characters
-    // GitHub CLI and API can handle special characters properly
-    // Boolean operator validation with suggestions
-    const invalidBooleans = params.query.match(/\b(and|or|not)\b/g);
-    if (invalidBooleans) {
-        const corrected = invalidBooleans.map(op => op.toUpperCase()).join(', ');
-        return `Boolean operators must be uppercase: ${corrected}. Example: "react OR vue" not "react or vue"`;
-    }
-    return null; // No validation errors
+    });
+    return branches;
 }
 
-const TOOL_NAME$7 = 'github_get_file_content';
-const DESCRIPTION$7 = `Read file content with exact path verification. Smart branch fallbacks and size limits. Use github_get_contents first to verify file existence.`;
+const GITHUB_GET_FILE_CONTENT_TOOL_NAME = 'githubGetFileContent';
+const DESCRIPTION$7 = `Fetch file content from GitHub repositories. Use ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} first to explore repository structure and find exact file paths. Supports automatic branch fallback (main/master) and handles files up to 300KB. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), filePath (required).`;
 function registerFetchGitHubFileContentTool(server) {
-    server.registerTool(TOOL_NAME$7, {
+    server.registerTool(GITHUB_GET_FILE_CONTENT_TOOL_NAME, {
         description: DESCRIPTION$7,
         inputSchema: {
             owner: z
@@ -1255,26 +926,26 @@ function registerFetchGitHubFileContentTool(server) {
                 .min(1)
                 .max(100)
                 .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
-                .describe(`Repository owner/organization`),
+                .describe(`Repository owner/org name (e.g., 'microsoft', 'google', NOT 'microsoft/vscode')`),
             repo: z
                 .string()
                 .min(1)
                 .max(100)
                 .regex(/^[a-zA-Z0-9._-]+$/)
-                .describe(`Repository name. Case-sensitive.`),
+                .describe(`Repository name only (e.g., 'vscode', 'react', NOT 'microsoft/vscode')`),
             branch: z
                 .string()
                 .min(1)
                 .max(255)
                 .regex(/^[^\s]+$/)
-                .describe(`Branch name. Auto-fallback to common branches if not found.`),
+                .describe(`Branch name. Falls back to main/master if not found`),
             filePath: z
                 .string()
                 .min(1)
-                .describe(`File path from repository root. Use github_get_contents to explore structure.`),
+                .describe(`Exact file path from repo root (e.g., src/index.js, README.md)`),
         },
         annotations: {
-            title: 'GitHub File Content Reader',
+            title: 'GitHub File Content - Direct Access',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -1287,7 +958,7 @@ function registerFetchGitHubFileContentTool(server) {
         }
         catch (error) {
             return createResult({
-                error: 'File fetch failed - verify path or try github_get_contents first',
+                error: 'Failed to fetch file. Verify path with github_get_contents first',
             });
         }
     });
@@ -1322,27 +993,23 @@ async function fetchGitHubFileContent(params) {
                 // Handle common errors
                 if (errorMsg.includes('404')) {
                     return createResult({
-                        error: 'File not found - verify path with github_get_contents',
-                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                        error: 'File not found. Use github_view_repo_structure to explore repository structure',
                     });
                 }
                 else if (errorMsg.includes('403')) {
                     return createResult({
-                        error: 'Access denied - repository may be private',
-                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                        error: 'Access denied. Repository may be private - use apiStatusCheck to verify',
                     });
                 }
                 else if (errorMsg.includes('maxBuffer') ||
                     errorMsg.includes('stdout maxBuffer length exceeded')) {
                     return createResult({
-                        error: 'File too large (>300KB) - use github_search_code for patterns instead',
-                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                        error: 'File too large (>300KB). Use githubSearchCode to search for patterns within the file',
                     });
                 }
                 else {
                     return createResult({
-                        error: 'Fetch failed - check repository and file path',
-                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                        error: 'Failed to fetch file. Verify repository name and file path',
                     });
                 }
             }
@@ -1354,11 +1021,11 @@ async function fetchGitHubFileContent(params) {
             if (errorMessage.includes('maxBuffer') ||
                 errorMessage.includes('stdout maxBuffer length exceeded')) {
                 return createResult({
-                    error: 'File too large (>300KB) - use github_search_code for patterns instead',
+                    error: 'File too large (>300KB). Use github_search_code to search for patterns within the file',
                 });
             }
             return createResult({
-                error: 'Unexpected error during file fetch - check connection',
+                error: 'Unexpected error. Check network connection and try again',
             });
         }
     });
@@ -1366,28 +1033,33 @@ async function fetchGitHubFileContent(params) {
 async function processFileContent(result, owner, repo, branch, filePath) {
     // Extract the actual content from the exec result
     const execResult = JSON.parse(result.content[0].text);
-    const fileData = JSON.parse(execResult.result);
+    const fileData = execResult.result;
     // Check if it's a directory
     if (Array.isArray(fileData)) {
         return createResult({
-            error: 'Path is directory - use github_get_contents instead',
+            error: 'Path is a directory. Use github_view_repo_structure to list directory contents',
         });
     }
-    const fileSize = fileData.size || 0;
+    const fileSize = typeof fileData.size === 'number' ? fileData.size : 0;
     const MAX_FILE_SIZE = 300 * 1024; // 300KB limit for better performance and reliability
     // Check file size with helpful message
     if (fileSize > MAX_FILE_SIZE) {
         const fileSizeKB = Math.round(fileSize / 1024);
         const maxSizeKB = Math.round(MAX_FILE_SIZE / 1024);
         return createResult({
-            error: `File too large (${fileSizeKB}KB > ${maxSizeKB}KB) - use github_search_code for patterns`,
+            error: `File too large (${fileSizeKB}KB > ${maxSizeKB}KB). Use githubSearchCode to search within the file`,
+        });
+    }
+    // Get and decode content with validation
+    if (!fileData.content) {
+        return createResult({
+            error: 'File is empty - no content to display',
         });
     }
-    // Get and decode content
-    const base64Content = fileData.content?.replace(/\s/g, ''); // Remove all whitespace
+    const base64Content = fileData.content.replace(/\s/g, ''); // Remove all whitespace
     if (!base64Content) {
         return createResult({
-            error: 'Empty file - no content to display',
+            error: 'File is empty - no content to display',
         });
     }
     let decodedContent;
@@ -1396,215 +1068,61 @@ async function processFileContent(result, owner, repo, branch, filePath) {
         // Simple binary check - look for null bytes
         if (buffer.indexOf(0) !== -1) {
             return createResult({
-                error: 'Binary file detected - cannot display as text',
+                error: 'Binary file detected. Cannot display as text - download directly from GitHub',
             });
         }
         decodedContent = buffer.toString('utf-8');
     }
     catch (decodeError) {
         return createResult({
-            error: 'Decode failed - file encoding not supported',
+            error: 'Failed to decode file. Encoding may not be supported (expected UTF-8)',
         });
     }
-    // Return simplified response
-    const response = {
-        filePath,
-        owner,
-        repo,
-        branch,
-        content: decodedContent,
-        metadata: {
-            size: fileSize,
-            lines: decodedContent.split('\n').length,
-            encoding: 'utf-8',
+    return createResult({
+        data: {
+            filePath,
+            owner,
+            repo,
+            branch,
+            content: decodedContent,
         },
-    };
-    return createResult({ data: response });
+    });
 }
 
-/**
- * GitHub Repository Search Tool
- *
- * MOST EFFECTIVE PATTERNS (based on testing):
- *
- * 1. Quality Discovery:
- *    { topic: ["react", "typescript"], stars: "1000..5000", limit: 10 }
- *
- * 2. Organization Research:
- *    { owner: ["microsoft", "google"], language: "python", limit: 10 }
- *
- * 3. Beginner Projects:
- *    { goodFirstIssues: ">=5", stars: "100..5000", limit: 10 }
- *
- * 4. Recent Quality:
- *    { stars: ">1000", created: ">2023-01-01", limit: 10 }
- *
- * AVOID: OR queries + language filter, 5+ filters, multi-word OR
- * TIP: Use limit parameter instead of adding more filters
- */
-const TOOL_NAME$6 = 'github_search_repositories';
-const DESCRIPTION$6 = `Search GitHub repositories with powerful GitHub search syntax and advanced filtering.
-
-EMBEDDED QUALIFIERS (MOST POWERFUL):
-- "vue OR react stars:>1000 language:javascript" - OR logic with constraints
-- "typescript AND framework stars:100..5000" - AND logic with star range  
-- "repo:facebook/react OR repo:vuejs/vue" - Multiple specific repositories
-- "org:microsoft OR org:google language:typescript" - Multiple organizations
-- "topic:react topic:typescript stars:>500" - Multiple topics with quality filter
-
-TRADITIONAL FILTERS (ALSO SUPPORTED):
-- owner: ["microsoft", "google"] - Multiple owners as array
-- topic: ["react", "typescript"] - Multiple topics as array
-- stars: "1000..5000" - Range or threshold filtering
-
-BEST PRACTICES:
-- Use embedded qualifiers for complex queries with OR/AND logic
-- Use traditional filters for simple, clean parameter-based searches
-- Combine both approaches: "vue OR react" + language:"javascript" + stars:">1000"`;
-/**
- * Extract owner/repo information from various query formats
- */
-function extractOwnerRepoFromQuery(query) {
-    let cleanedQuery = query;
-    let extractedOwner;
-    let extractedRepo;
-    // Pattern 1: GitHub URLs (https://github.com/owner/repo)
-    const githubUrlMatch = query.match(/github\.com\/([^\\s]+)\/([^\\s]+)/i);
-    if (githubUrlMatch) {
-        extractedOwner = githubUrlMatch[1];
-        extractedRepo = githubUrlMatch[2];
-        cleanedQuery = query
-            .replace(/https?:\/\/github\.com\/[^\\s]+\/[^\\s]+/gi, '')
-            .trim();
-    }
-    // Pattern 2: owner/repo format in query
-    const ownerRepoMatch = query.match(/\b([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\/([a-zA-Z0-9][a-zA-Z0-9\-.]*[a-zA-Z0-9])\b/);
-    if (ownerRepoMatch && !extractedOwner) {
-        extractedOwner = ownerRepoMatch[1];
-        extractedRepo = ownerRepoMatch[2];
-        cleanedQuery = query.replace(ownerRepoMatch[0], '').trim();
-    }
-    // Pattern 3: NPM package-like references (@scope/package)
-    const scopedPackageMatch = query.match(/@([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\/([a-zA-Z0-9][a-zA-Z0-9\-.]*[a-zA-Z0-9])/);
-    if (scopedPackageMatch && !extractedOwner) {
-        extractedOwner = scopedPackageMatch[1];
-        extractedRepo = scopedPackageMatch[2];
-        cleanedQuery = query.replace(scopedPackageMatch[0], '').trim();
-    }
-    return {
-        extractedOwner,
-        extractedRepo,
-        cleanedQuery: cleanedQuery || query,
-    };
-}
-function registerSearchGitHubReposTool(server) {
-    server.registerTool(TOOL_NAME$6, {
+const GITHUB_SEARCH_CODE_TOOL_NAME = 'githubSearchCode';
+const DESCRIPTION$6 = `Search code across GitHub repositories. Start with simple 1-2 word queries, then refine with filters like language, owner, or filename. Supports exact phrase matching with quotes. Parameters: query (required), language (optional), owner (optional - GitHub username/org, NOT owner/repo), filename (optional), extension (optional), match (optional), size (optional), limit (optional).`;
+function registerGitHubSearchCodeTool(server) {
+    server.registerTool(GITHUB_SEARCH_CODE_TOOL_NAME, {
         description: DESCRIPTION$6,
         inputSchema: {
             query: z
                 .string()
-                .optional()
-                .describe('Search query with GitHub search syntax. POWERFUL EXAMPLES: "vue OR react stars:>1000", "typescript AND framework stars:100..5000", "repo:facebook/react OR repo:vuejs/vue", "org:microsoft language:typescript", "topic:react topic:typescript stars:>500". SUPPORTS: OR/AND logic, embedded qualifiers (stars:, language:, org:, repo:, topic:, etc.), exact repository targeting. COMBINES with traditional filters for maximum flexibility.'),
-            // CORE FILTERS (GitHub CLI flags)
-            owner: z
-                .union([z.string(), z.array(z.string())])
-                .optional()
-                .describe('Repository owner/organization. HIGHLY EFFECTIVE as array ["microsoft", "google"]. FIXED: Now supports multiple owners with comma separation. Best for targeted research.'),
+                .min(1)
+                .describe('Search terms. START SIMPLE: Use 1-2 words first (e.g., "useState", "auth"). Add more terms only after seeing initial results.'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter. CAUTION: Restrictive with other filters. Use alone or with stars/owner only.'),
-            stars: z
-                .union([
-                z.number().int().min(0),
-                z
-                    .string()
-                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid stars format. Use: number, ">100", ">=50", "<200", "<=100", or "10..100"'),
-            ])
-                .optional()
-                .describe('Stars filter. MOST EFFECTIVE: ranges "1000..5000", thresholds ">1000". Excellent for quality filtering.'),
-            topic: z
-                .union([z.string(), z.array(z.string())])
-                .optional()
-                .describe('Topics filter. BEST PATTERN: arrays ["react", "typescript"]. FIXED: Now supports comma-separated topics. Preferred over OR queries. Combines well with stars.'),
-            forks: z.number().optional().describe('Number of forks filter.'),
-            // UPDATED: Match CLI parameter name exactly
-            numberOfTopics: z
-                .number()
-                .optional()
-                .describe('Filter by number of topics (indicates documentation quality).'),
-            // QUALITY & STATE FILTERS
-            license: z
+                .describe('Language filter (javascript, python, etc). Use only when needed.'),
+            owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('License filter. Works well as array ["mit", "apache-2.0"].'),
-            archived: z
-                .boolean()
+                .describe('Repository owner/org (for organization-specific searches). Format: username or org-name only, NOT owner/repo. Use this to search within a specific organization.'),
+            filename: z
+                .string()
                 .optional()
-                .describe('Filter archived repositories (true/false).'),
-            includeForks: z
-                .enum(['false', 'true', 'only'])
+                .describe('Specific filename to search. Use for targeted searches.'),
+            extension: z
+                .string()
                 .optional()
-                .describe('Include forks: false (exclude), true (include), only (forks only).'),
-            visibility: z
-                .enum(['public', 'private', 'internal'])
+                .describe('File extension (.js, .py, etc). Alternative to language filter.'),
+            match: z
+                .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
                 .optional()
-                .describe('Repository visibility filter.'),
-            // DATE & SIZE FILTERS
-            created: z
+                .describe('Search scope: "file" for content, "path" for filenames. Default: file content.'),
+            size: z
                 .string()
                 .optional()
-                .describe('Created date filter. Format: ">2020-01-01", "<2023-12-31".'),
-            updated: z
-                .string()
-                .optional()
-                .describe('Updated date filter. Good for finding active projects.'),
-            size: z
-                .string()
-                .optional()
-                .describe('Repository size filter in KB. Format: ">1000", "<500".'),
-            // COMMUNITY FILTERS - Match CLI parameter names exactly
-            goodFirstIssues: z
-                .union([
-                z.number().int().min(0),
-                z
-                    .string()
-                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
-            ])
-                .optional()
-                .describe('Good first issues count. WORKING: Filter for beginner-friendly projects. EXCELLENT when combined with stars "100..5000" for quality beginner projects.'),
-            helpWantedIssues: z
-                .union([
-                z.number().int().min(0),
-                z
-                    .string()
-                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
-            ])
-                .optional()
-                .describe('Help wanted issues count. Good for finding projects needing contributors.'),
-            followers: z.number().optional().describe('Followers count filter.'),
-            // SEARCH SCOPE
-            match: z
-                .enum(['name', 'description', 'readme'])
-                .optional()
-                .describe('Search scope: name, description, or readme content.'),
-            // SORTING & LIMITS - Match CLI defaults exactly
-            sort: z
-                .enum([
-                'forks',
-                'help-wanted-issues',
-                'stars',
-                'updated',
-                'best-match',
-            ])
-                .optional()
-                .default('best-match')
-                .describe('Sort by: stars, updated, forks, help-wanted-issues, best-match.'),
-            order: z
-                .enum(['asc', 'desc'])
-                .optional()
-                .default('desc')
-                .describe('Sort order: asc or desc.'),
+                .describe('File size in KB. Format: >10, <100, or 10..50'),
             limit: z
                 .number()
                 .int()
@@ -1612,10 +1130,10 @@ function registerSearchGitHubReposTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Results limit (1-100). PREFER increasing limit over adding filters.'),
+                .describe('Results limit (1-100). Default: 30'),
         },
         annotations: {
-            title: 'GitHub Repository Search',
+            title: 'GitHub Code Search - Smart & Efficient',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -1623,325 +1141,307 @@ function registerSearchGitHubReposTool(server) {
         },
     }, async (args) => {
         try {
-            // Extract owner/repo from query if present
-            const queryInfo = args.query
-                ? extractOwnerRepoFromQuery(args.query)
-                : {
-                    cleanedQuery: '',
-                    extractedOwner: undefined,
-                    extractedRepo: undefined,
-                };
-            // Merge extracted owner with explicit owner parameter
-            let finalOwner = args.owner;
-            if (queryInfo.extractedOwner && !finalOwner) {
-                finalOwner = queryInfo.extractedOwner;
+            // Validate parameter combinations
+            const validationError = validateSearchParameters(args);
+            if (validationError) {
+                return createResult({ error: validationError });
             }
-            // Update parameters with extracted information
-            const enhancedArgs = {
-                ...args,
-                query: queryInfo.cleanedQuery || args.query,
-                owner: finalOwner,
-            };
-            // Enhanced validation logic for primary filters
-            const hasPrimaryFilter = enhancedArgs.query?.trim() ||
-                enhancedArgs.owner ||
-                enhancedArgs.language ||
-                enhancedArgs.topic ||
-                enhancedArgs.stars ||
-                enhancedArgs.forks;
-            if (!hasPrimaryFilter) {
-                return createResult({
-                    error: 'Requires query or primary filter (owner, language, stars, topic, forks). You can also use owner/repo format like "microsoft/vscode" in the query.',
-                });
+            const result = await searchGitHubCode(args);
+            if (result.isError) {
+                return result;
             }
-            // First attempt: Search with current parameters
-            const result = await searchGitHubRepos(enhancedArgs);
-            // Fallback for private repositories: If no results and owner is specified, try with private visibility
-            if (!result.isError) {
-                const resultData = JSON.parse(result.content[0].text);
-                if (resultData.total === 0 &&
-                    enhancedArgs.owner &&
-                    !enhancedArgs.visibility) {
-                    // Try searching with private visibility for organization repos
-                    const privateSearchArgs = {
-                        ...enhancedArgs,
-                        visibility: 'private',
-                    };
-                    const privateResult = await searchGitHubRepos(privateSearchArgs);
-                    if (!privateResult.isError) {
-                        const privateData = JSON.parse(privateResult.content[0].text);
-                        if (privateData.total > 0) {
-                            // Return private results with note
-                            return createResult({
-                                data: {
-                                    ...privateData,
-                                    note: 'Found results in private repositories within the specified organization.',
-                                },
-                            });
-                        }
-                    }
+            const execResult = JSON.parse(result.content[0].text);
+            const codeResults = execResult.result;
+            // GitHub CLI returns a direct array, not an object with total_count and items
+            const items = Array.isArray(codeResults) ? codeResults : [];
+            // Smart handling for no results - provide actionable suggestions
+            if (items.length === 0) {
+                // Provide progressive search guidance based on current parameters
+                let specificSuggestion = SUGGESTIONS.CODE_SEARCH_NO_RESULTS;
+                // If filters were used, suggest removing them first
+                if (args.language || args.owner || args.filename || args.extension) {
+                    specificSuggestion = SUGGESTIONS.CODE_SEARCH_NO_RESULTS;
                 }
+                return createResult({
+                    error: getErrorWithSuggestion({
+                        baseError: createNoResultsError('code'),
+                        suggestion: specificSuggestion,
+                    }),
+                });
             }
-            return result;
+            // Transform to optimized format
+            const optimizedResult = transformToOptimizedFormat$1(items);
+            return createResult({ data: optimizedResult });
         }
         catch (error) {
-            return createResult({
-                error: 'Repository search failed - verify connection or simplify query',
-            });
+            const errorMessage = error.message || '';
+            return handleSearchError(errorMessage);
         }
     });
 }
-async function searchGitHubRepos(params) {
-    const cacheKey = generateCacheKey('gh-repos', params);
+/**
+ * Handles various search errors and returns a formatted CallToolResult.
+ */
+function handleSearchError(errorMessage) {
+    // Common GitHub search errors with helpful suggestions
+    if (errorMessage.includes('JSON')) {
+        return createResult({
+            error: ERROR_MESSAGES.CLI_INVALID_RESPONSE,
+        });
+    }
+    if (errorMessage.includes('authentication')) {
+        return createResult({
+            error: createAuthenticationError(),
+        });
+    }
+    if (errorMessage.includes('rate limit')) {
+        return createResult({
+            error: createRateLimitError(true),
+        });
+    }
+    if (errorMessage.includes('timed out')) {
+        return createResult({
+            error: ERROR_MESSAGES.SEARCH_TIMEOUT,
+        });
+    }
+    if (errorMessage.includes('validation failed') ||
+        errorMessage.includes('Invalid query')) {
+        return createResult({
+            error: ERROR_MESSAGES.INVALID_QUERY_SYNTAX,
+        });
+    }
+    if (errorMessage.includes('repository not found') ||
+        errorMessage.includes('owner not found')) {
+        return createResult({
+            error: ERROR_MESSAGES.REPO_OR_OWNER_NOT_FOUND,
+        });
+    }
+    // Generic fallback with guidance
+    return createResult({
+        error: `Code search failed: ${errorMessage}\n${SUGGESTIONS.SIMPLIFY_QUERY}`,
+    });
+}
+/**
+ * Transform GitHub CLI response to optimized format with enhanced metadata
+ */
+function transformToOptimizedFormat$1(items) {
+    // Extract repository info if single repo search
+    const singleRepo = extractSingleRepository$1(items);
+    const optimizedItems = items.map(item => ({
+        path: item.path,
+        matches: item.textMatches?.map(match => ({
+            context: optimizeTextMatch(match.fragment, 120), // Increased context for better understanding
+            positions: match.matches?.map(m => Array.isArray(m.indices) && m.indices.length >= 2
+                ? [m.indices[0], m.indices[1]]
+                : [0, 0]) || [],
+        })) || [],
+        url: singleRepo ? item.path : simplifyGitHubUrl(item.url),
+    }));
+    const result = {
+        items: optimizedItems,
+        total_count: items.length,
+    };
+    // Add repository info if single repo
+    if (singleRepo) {
+        result.repository = {
+            name: singleRepo.nameWithOwner,
+            url: simplifyRepoUrl(singleRepo.url),
+        };
+    }
+    return result;
+}
+/**
+ * Extract single repository if all results are from same repo
+ */
+function extractSingleRepository$1(items) {
+    if (items.length === 0)
+        return null;
+    const firstRepo = items[0].repository;
+    const allSameRepo = items.every(item => item.repository.nameWithOwner === firstRepo.nameWithOwner);
+    return allSameRepo ? firstRepo : null;
+}
+/**
+ * Build command line arguments for GitHub CLI with improved parameter handling.
+ * Ensures exact string search capability with proper quote and escape handling.
+ *
+ * This function is refactored to correctly distinguish between search qualifiers
+ * (like `language` and `extension`), which will be passed as separate arguments
+ * to `gh search`, and command-line flags (like `--size` and `--limit`).
+ */
+function buildGitHubCliArgs(params) {
+    const args = ['code'];
+    // Extract qualifiers from the query
+    const queryParts = params.query.trim().split(/\s+/);
+    const searchTerms = [];
+    const qualifiers = [];
+    queryParts.forEach(part => {
+        if (part.includes(':')) {
+            qualifiers.push(part);
+        }
+        else {
+            searchTerms.push(part);
+        }
+    });
+    // Add search terms if any
+    if (searchTerms.length > 0) {
+        args.push(searchTerms.join(' '));
+    }
+    // Add extracted qualifiers
+    qualifiers.forEach(qualifier => {
+        args.push(qualifier);
+    });
+    // Add explicit parameters as qualifiers
+    if (params.language && !params.query.includes('language:')) {
+        args.push(`language:${params.language}`);
+    }
+    if (params.owner &&
+        !params.query.includes('org:') &&
+        !params.query.includes('user:')) {
+        const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
+        owners.forEach(owner => args.push(`org:${owner}`));
+    }
+    if (params.filename && !params.query.includes('filename:')) {
+        args.push(`filename:${params.filename}`);
+    }
+    if (params.extension && !params.query.includes('extension:')) {
+        args.push(`extension:${params.extension}`);
+    }
+    if (params.size && !params.query.includes('size:')) {
+        args.push(`size:${params.size}`);
+    }
+    // Handle match parameter
+    if (params.match) {
+        const matches = Array.isArray(params.match) ? params.match : [params.match];
+        args.push(`in:${matches.join(',')}`);
+    }
+    // Add limit
+    if (params.limit) {
+        args.push(`--limit=${params.limit}`);
+    }
+    // Add JSON output format
+    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 { command, args } = buildGitHubReposSearchCommand(params);
-            const result = await executeGitHubCommand(command, args, {
+            const args = buildGitHubCliArgs(params);
+            const result = await executeGitHubCommand('search', args, {
                 cache: false,
             });
-            if (result.isError) {
-                return result;
-            }
-            // Extract the actual content from the exec result
-            const execResult = JSON.parse(result.content[0].text);
-            const rawContent = execResult.result;
-            // Parse JSON results and provide structured analysis
-            let repositories = [];
-            const analysis = {
-                totalFound: 0,
-                languages: new Set(),
-                avgStars: 0,
-                recentlyUpdated: 0,
-                topStarred: [],
-            };
-            // Parse JSON response from GitHub CLI
-            repositories = JSON.parse(rawContent);
-            if (Array.isArray(repositories) && repositories.length > 0) {
-                analysis.totalFound = repositories.length;
-                // Analyze repository data
-                let totalStars = 0;
-                const now = new Date();
-                const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
-                repositories.forEach(repo => {
-                    // Collect languages
-                    if (repo.language) {
-                        analysis.languages.add(repo.language);
-                    }
-                    // Calculate average stars (use correct field name)
-                    if (repo.stargazersCount) {
-                        totalStars += repo.stargazersCount;
-                    }
-                    // Count recently updated repositories (use correct field name)
-                    if (repo.updatedAt) {
-                        const updatedDate = new Date(repo.updatedAt);
-                        if (updatedDate > thirtyDaysAgo) {
-                            analysis.recentlyUpdated++;
-                        }
-                    }
-                });
-                analysis.avgStars =
-                    repositories.length > 0
-                        ? Math.round(totalStars / repositories.length)
-                        : 0;
-                // Get all repositories with comprehensive data
-                analysis.topStarred = repositories.map(repo => ({
-                    name: repo.fullName || repo.name,
-                    stars: repo.stargazersCount || 0,
-                    description: repo.description || 'No description',
-                    language: repo.language || 'Unknown',
-                    url: repo.url,
-                    forks: repo.forksCount || 0,
-                    isPrivate: repo.isPrivate || false,
-                    isArchived: repo.isArchived || false,
-                    isFork: repo.isFork || false,
-                    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,
-                    createdAt: toDDMMYYYY(repo.createdAt),
-                    updatedAt: toDDMMYYYY(repo.updatedAt),
-                    visibility: repo.visibility || 'public',
-                    owner: repo.owner?.login || repo.owner,
-                }));
-            }
-            return createResult({
-                data: {
-                    total_count: analysis.totalFound,
-                    ...(analysis.totalFound > 0
-                        ? {
-                            repositories: analysis.topStarred,
-                            summary: {
-                                languages: Array.from(analysis.languages).slice(0, 10),
-                                avgStars: analysis.avgStars,
-                                recentlyUpdated: analysis.recentlyUpdated,
-                            },
-                        }
-                        : {
-                            repositories: [],
-                            cli_command: execResult.command, // Only on no results
-                        }),
-                },
-            });
+            return result;
         }
         catch (error) {
-            return createResult({
-                error: 'Repository search failed - verify connection or simplify query',
-            });
+            const errorMessage = error.message || '';
+            return handleSearchError(errorMessage); // Delegating error handling
         }
     });
 }
-function buildGitHubReposSearchCommand(params) {
-    // Build query following GitHub CLI patterns
-    const query = params.query?.trim() || '';
-    const args = ['repos'];
-    // Detect embedded qualifiers in query to avoid conflicts and optimize
-    const hasEmbeddedQualifiers = query &&
-        /\b(stars|language|org|repo|topic|user|created|updated|size|license|archived|fork|good-first-issues|help-wanted-issues):/i.test(query);
-    // Handle exact string search - preserve quotes and special characters
-    if (query) {
-        // For exact repository name searches (quoted strings), preserve the quotes
-        // For special characters, pass them through - GitHub CLI handles escaping
-        // Support searches like "microsoft/vscode", "@types/node", etc.
-        args.push(query);
+/**
+ * Enhanced validation with helpful suggestions
+ */
+function validateSearchParameters(params) {
+    // Query validation
+    if (!params.query.trim()) {
+        return ERROR_MESSAGES.EMPTY_QUERY;
     }
-    // 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');
-    // SMART FILTER HANDLING - Avoid conflicts with embedded qualifiers
-    // Only add CLI flags if not already specified in query to prevent conflicts
-    // CORE FILTERS - Handle arrays properly
-    if (params.owner && !hasEmbeddedQualifiers) {
-        // GitHub CLI supports multiple owners with comma separation: --owner=owner1,owner2
-        const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
-        args.push(`--owner=${owners.join(',')}`);
-    }
-    if (params.language && !hasEmbeddedQualifiers)
-        args.push(`--language=${params.language}`);
-    if (params.forks !== undefined && !hasEmbeddedQualifiers)
-        args.push(`--forks=${params.forks}`);
-    // Handle topic as string or array - GitHub CLI expects comma-separated topics
-    if (params.topic && !hasEmbeddedQualifiers) {
-        const topics = Array.isArray(params.topic) ? params.topic : [params.topic];
-        args.push(`--topic=${topics.join(',')}`);
-    }
-    if (params.numberOfTopics !== undefined)
-        args.push(`--number-topics=${params.numberOfTopics}`);
-    // Handle stars as number or string - avoid conflicts with embedded qualifiers
-    if (params.stars !== undefined && !hasEmbeddedQualifiers) {
-        const starsValue = typeof params.stars === 'number'
-            ? params.stars.toString()
-            : params.stars.trim();
-        // Validate numeric patterns for string values
-        if (typeof params.stars === 'number' ||
-            /^(\d+|>\d+|<\d+|\d+\.\.\d+|>=\d+|<=\d+)$/.test(starsValue)) {
-            args.push(`--stars=${starsValue}`);
+    if (params.query.length > 1000) {
+        return ERROR_MESSAGES.QUERY_TOO_LONG_1000;
+    }
+    // Repository validation - ensure owner is provided correctly
+    if (params.owner &&
+        typeof params.owner === 'string' &&
+        params.owner.includes('/')) {
+        return 'Owner parameter should contain only the username/org name, not owner/repo format. For repository-specific searches, use org: or user: qualifiers in the query.';
+    }
+    if (Array.isArray(params.owner)) {
+        const hasSlashFormat = params.owner.some(owner => owner.includes('/'));
+        if (hasSlashFormat) {
+            return 'Owner parameter should contain only usernames/org names, not owner/repo format. For repository-specific searches, use repo: qualifier in the query.';
         }
     }
-    // QUALITY & STATE FILTERS
-    if (params.archived !== undefined)
-        args.push(`--archived=${params.archived}`);
-    if (params.includeForks)
-        args.push(`--include-forks=${params.includeForks}`);
-    if (params.visibility)
-        args.push(`--visibility=${params.visibility}`);
-    // Handle license as string or array
-    if (params.license) {
-        const licenses = Array.isArray(params.license)
-            ? params.license
-            : [params.license];
-        args.push(`--license=${licenses.join(',')}`);
+    // Add validation for file size limit
+    if (params.size) {
+        if (!/^([<>]\d+|\d+\.\.\d+)$/.test(params.size)) {
+            return ERROR_MESSAGES.INVALID_SIZE_FORMAT;
+        }
     }
-    // DATE & SIZE FILTERS
-    if (params.created)
-        args.push(`--created=${params.created}`);
-    if (params.updated)
-        args.push(`--updated=${params.updated}`);
-    if (params.size)
-        args.push(`--size=${params.size}`);
-    // COMMUNITY FILTERS - handle both number and string
-    if (params.goodFirstIssues) {
-        const value = typeof params.goodFirstIssues === 'number'
-            ? params.goodFirstIssues.toString()
-            : params.goodFirstIssues;
-        args.push(`--good-first-issues=${value}`);
-    }
-    if (params.helpWantedIssues) {
-        const value = typeof params.helpWantedIssues === 'number'
-            ? params.helpWantedIssues.toString()
-            : params.helpWantedIssues;
-        args.push(`--help-wanted-issues=${value}`);
-    }
-    if (params.followers !== undefined)
-        args.push(`--followers=${params.followers}`);
-    // SEARCH SCOPE
-    if (params.match)
-        args.push(`--match=${params.match}`);
-    // SORTING AND LIMITS
-    if (params.limit)
-        args.push(`--limit=${params.limit}`);
-    if (params.order)
-        args.push(`--order=${params.order}`);
-    // Use best-match as default, only specify sort if different from default
-    const sortBy = params.sort || 'best-match';
-    if (sortBy !== 'best-match') {
-        args.push(`--sort=${sortBy}`);
+    // Validate search scope
+    if (params.match) {
+        const validScopes = ['file', 'path'];
+        const scopes = Array.isArray(params.match) ? params.match : [params.match];
+        if (!scopes.every(scope => validScopes.includes(scope))) {
+            return ERROR_MESSAGES.INVALID_SEARCH_SCOPE;
+        }
     }
-    return { command: 'search', args };
+    // Note about repository limitations (This is a note, not a hard error)
+    // This return statement was returning null before, so it shouldn't be an issue
+    // if (params.repo || params.owner) {
+    //   return null; // Return warning about repository limitations
+    // }
+    return null; // No validation errors
 }
 
-const TOOL_NAME$5 = 'github_search_commits';
-const DESCRIPTION$5 = `Search commit history effectively with GitHub's commit search. Use simple, specific terms for best results. Complex boolean queries may return limited results - try individual keywords instead.`;
+const GITHUB_SEARCH_COMMITS_TOOL_NAME = 'githubSearchCommits';
+const DESCRIPTION$5 = `Search commit history across GitHub repositories. Supports filtering by repository, author, date ranges, and commit attributes. Parameters: query (optional), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), author (optional), authorName (optional), authorEmail (optional), committer (optional), committerName (optional), committerEmail (optional), authorDate (optional), committerDate (optional), hash (optional), parent (optional), tree (optional), merge (optional), visibility (optional), limit (optional), sort (optional), order (optional).`;
 function registerGitHubSearchCommitsTool(server) {
-    server.registerTool(TOOL_NAME$5, {
+    server.registerTool(GITHUB_SEARCH_COMMITS_TOOL_NAME, {
         description: DESCRIPTION$5,
         inputSchema: {
             query: z
                 .string()
                 .optional()
-                .describe('Search query with boolean logic. Boolean: "fix AND bug", exact phrases: "initial commit", advanced syntax: "author:john OR committer:jane".'),
+                .describe('Search terms. Start simple: "bug fix", "refactor". Use quotes for exact phrases.'),
             // Repository filters
             owner: z
                 .string()
                 .optional()
-                .describe('Repository owner/organization. Leave empty for global search.'),
+                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
                 .optional()
-                .describe('Repository name. Do exploratory search without repo filter first'),
+                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
             // Author filters
-            author: z.string().optional().describe('Filter by commit author'),
-            authorName: z.string().optional().describe('Filter by author name'),
-            authorEmail: z.string().optional().describe('Filter by author email'),
-            // Committer filters
-            committer: z.string().optional().describe('Filter by committer'),
-            committerName: z
+            author: z
+                .string()
+                .optional()
+                .describe('GitHub username of commit author'),
+            authorName: z
                 .string()
                 .optional()
-                .describe('Filter by committer name'),
-            committerEmail: z
+                .describe('Full name of commit author'),
+            authorEmail: z.string().optional().describe('Email of commit author'),
+            // Committer filters
+            committer: z
                 .string()
                 .optional()
-                .describe('Filter by committer email'),
+                .describe('GitHub username of committer'),
+            committerName: z.string().optional().describe('Full name of committer'),
+            committerEmail: z.string().optional().describe('Email of committer'),
             // Date filters
             authorDate: z
                 .string()
                 .optional()
-                .describe('Filter by authored date (format: >2020-01-01, <2023-12-31)'),
+                .describe('When authored. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
             committerDate: z
                 .string()
                 .optional()
-                .describe('Filter by committed date (format: >2020-01-01, <2023-12-31)'),
+                .describe('When committed. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
             // Hash filters
-            hash: z.string().optional().describe('Filter by commit hash'),
-            parent: z.string().optional().describe('Filter by parent hash'),
-            tree: z.string().optional().describe('Filter by tree hash'),
+            hash: z.string().optional().describe('Commit SHA (full or partial)'),
+            parent: z.string().optional().describe('Parent commit SHA'),
+            tree: z.string().optional().describe('Tree SHA'),
             // State filters
-            merge: z.boolean().optional().describe('Filter merge commits'),
+            merge: z
+                .boolean()
+                .optional()
+                .describe('Only merge commits (true) or exclude them (false)'),
             // Visibility
             visibility: z
                 .enum(['public', 'private', 'internal'])
                 .optional()
-                .describe('Filter by repository visibility'),
+                .describe('Repository visibility filter'),
             // Pagination and sorting
             limit: z
                 .number()
@@ -1950,19 +1450,19 @@ function registerGitHubSearchCommitsTool(server) {
                 .max(50)
                 .optional()
                 .default(25)
-                .describe('Maximum results (default: 25, max: 50)'),
+                .describe('Results limit (1-50). Default: 25'),
             sort: z
                 .enum(['author-date', 'committer-date'])
                 .optional()
-                .describe('Sort criteria (default: relevance)'),
+                .describe('Sort by date. Default: best match'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Order (default: desc)'),
+                .describe('Sort order. Default: desc'),
         },
         annotations: {
-            title: 'GitHub Commit Search',
+            title: 'GitHub Commit Search - Smart History Analysis',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -1975,28 +1475,13 @@ function registerGitHubSearchCommitsTool(server) {
                 return result;
             }
             const execResult = JSON.parse(result.content[0].text);
-            const commits = JSON.parse(execResult.result);
+            const commits = execResult.result;
             // GitHub CLI returns a direct array
             const items = Array.isArray(commits) ? commits : [];
-            // Enhanced handling for no results - provide fallback suggestions
+            // Smart handling for no results - provide actionable suggestions
             if (items.length === 0) {
                 return createResult({
-                    data: {
-                        commits: [],
-                        total_count: 0,
-                        cli_command: execResult.command,
-                        suggestions: {
-                            message: 'No commits found. GitHub commit search is limited compared to code/issue search.',
-                            fallback_strategies: [
-                                'Try simpler, shorter queries (single keywords work better)',
-                                "Use broader terms like 'fix' instead of 'fix useState bug'",
-                                'Search by author: add author filter for specific contributors',
-                                'Use date ranges: add authorDate or committerDate filters',
-                                'Try github_search_code tool for finding code patterns instead',
-                            ],
-                            alternative_queries: generateCommitSearchAlternatives(args.query),
-                        },
-                    },
+                    error: createNoResultsError('commits'),
                 });
             }
             // Transform to optimized format
@@ -2007,21 +1492,16 @@ function registerGitHubSearchCommitsTool(server) {
             const errorMessage = error.message || '';
             if (errorMessage.includes('authentication')) {
                 return createResult({
-                    error: 'GitHub authentication required - run api_status_check tool',
+                    error: createAuthenticationError(),
                 });
             }
             if (errorMessage.includes('rate limit')) {
                 return createResult({
-                    error: 'GitHub rate limit exceeded - try more specific filters',
+                    error: createRateLimitError(false),
                 });
             }
             return createResult({
-                error: 'Commit search failed',
-                suggestions: [
-                    'Check authentication with api_status_check',
-                    'Use more specific date ranges or author filters',
-                    'Try simpler boolean queries',
-                ],
+                error: createSearchFailedError('commits'),
             });
         }
     });
@@ -2032,14 +1512,12 @@ function registerGitHubSearchCommitsTool(server) {
 function transformCommitsToOptimizedFormat(items, _params) {
     // Extract repository info if single repo search
     const singleRepo = extractSingleRepository(items);
-    // Get unique authors for metadata
-    const uniqueAuthors = new Set(items.map(item => item.commit?.author?.name || item.author?.login || 'Unknown')).size;
     const optimizedCommits = items
         .map(item => ({
         sha: item.sha,
-        message: getCommitTitle(item.commit?.message || ''),
-        author: item.commit?.author?.name || item.author?.login || 'Unknown',
-        date: toDDMMYYYY(item.commit?.author?.date || ''),
+        message: getCommitTitle(item.commit?.message ?? ''),
+        author: item.commit?.author?.name ?? item.author?.login ?? 'Unknown',
+        date: toDDMMYYYY(item.commit?.author?.date ?? ''),
         repository: singleRepo
             ? undefined
             : simplifyRepoUrl(item.repository?.url || ''),
@@ -2068,13 +1546,6 @@ function transformCommitsToOptimizedFormat(items, _params) {
             description: singleRepo.description,
         };
     }
-    // Add metadata for insights
-    if (items.length > 1) {
-        result.metadata = {
-            timeframe: getTimeframe(items),
-            unique_authors: uniqueAuthors,
-        };
-    }
     return result;
 }
 /**
@@ -2087,58 +1558,6 @@ function extractSingleRepository(items) {
     const allSameRepo = items.every(item => item.repository.fullName === firstRepo.fullName);
     return allSameRepo ? firstRepo : null;
 }
-/**
- * Calculate timeframe of commits
- */
-function getTimeframe(items) {
-    if (items.length === 0)
-        return '';
-    const dates = items.map(item => new Date(item.commit?.author?.date || ''));
-    const oldest = new Date(Math.min(...dates.map(d => d.getTime())));
-    const newest = new Date(Math.max(...dates.map(d => d.getTime())));
-    const diffMs = newest.getTime() - oldest.getTime();
-    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
-    if (diffDays === 0)
-        return 'same day';
-    if (diffDays < 7)
-        return `${diffDays} days`;
-    if (diffDays < 30)
-        return `${Math.floor(diffDays / 7)} weeks`;
-    if (diffDays < 365)
-        return `${Math.floor(diffDays / 30)} months`;
-    return `${Math.floor(diffDays / 365)} years`;
-}
-/**
- * Generate alternative commit search queries when original query fails
- */
-function generateCommitSearchAlternatives(originalQuery) {
-    if (!originalQuery) {
-        return [
-            { query: 'fix', reason: 'Search for general fixes' },
-            { query: 'bug', reason: 'Search for bug-related commits' },
-            { query: 'refactor', reason: 'Search for refactoring commits' },
-        ];
-    }
-    const alternatives = [];
-    const query = originalQuery.toLowerCase();
-    // Extract key terms and create simpler alternatives
-    if (query.includes('fix') && query.includes('bug')) {
-        alternatives.push({ query: 'fix', reason: 'Broader search for all fixes' }, { query: 'bug', reason: 'Search for bug-related commits' });
-    }
-    else if (query.includes(' ')) {
-        // Multi-word query - suggest individual terms
-        const words = query.split(' ').filter(w => w.length > 2);
-        words.slice(0, 2).forEach(word => {
-            alternatives.push({
-                query: word,
-                reason: `Single keyword search for '${word}'`,
-            });
-        });
-    }
-    // Always suggest some common commit patterns
-    alternatives.push({ query: 'feat', reason: 'Search for feature commits' }, { query: 'docs', reason: 'Search for documentation updates' });
-    return alternatives.slice(0, 4); // Limit to 4 suggestions
-}
 async function searchGitHubCommits(params) {
     const cacheKey = generateCacheKey('gh-commits', params);
     return withCache(cacheKey, async () => {
@@ -2153,16 +1572,16 @@ async function searchGitHubCommits(params) {
             const errorMessage = error.message || '';
             if (errorMessage.includes('authentication')) {
                 return createResult({
-                    error: 'GitHub authentication required',
+                    error: createAuthenticationError(),
                 });
             }
             if (errorMessage.includes('rate limit')) {
                 return createResult({
-                    error: 'GitHub rate limit exceeded',
+                    error: createRateLimitError(false),
                 });
             }
             return createResult({
-                error: 'Commit search execution failed',
+                error: createSearchFailedError('commits'),
             });
         }
     });
@@ -2225,85 +1644,133 @@ function buildGitHubCommitCliArgs(params) {
     return args;
 }
 
-// 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 feature implementations, code review patterns, and development workflows.`;
-function registerSearchGitHubPullRequestsTool(server) {
-    server.registerTool(TOOL_NAME$4, {
+const GITHUB_SEARCH_ISSUES_TOOL_NAME = 'githubSearchIssues';
+const DESCRIPTION$4 = `Search GitHub issues for bug discovery and feature analysis. Supports filtering by state, labels, assignee, dates, and more. Parameters: query (required), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), app (optional), archived (optional), assignee (optional), author (optional), closed (optional), commenter (optional), comments (optional), created (optional), includePrs (optional), interactions (optional), involves (optional), labels (optional), language (optional), locked (optional), match (optional), mentions (optional), milestone (optional), noAssignee (optional), noLabel (optional), noMilestone (optional), noProject (optional), project (optional), reactions (optional), state (optional), teamMentions (optional), updated (optional), visibility (optional), sort (optional), order (optional), limit (optional).`;
+function registerSearchGitHubIssuesTool(server) {
+    server.registerTool(GITHUB_SEARCH_ISSUES_TOOL_NAME, {
         description: DESCRIPTION$4,
         inputSchema: {
             query: z
                 .string()
                 .min(1, 'Search query is required and cannot be empty')
-                .describe('Search query with GitHub syntax. Boolean: "fix AND bug", exact phrases: "initial commit", qualifiers: "is:merged review:approved".'),
-            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'),
-            assignee: z.string().optional().describe('Filter by assignee'),
-            mentions: z.string().optional().describe('Filter by user mentions'),
-            commenter: z.string().optional().describe('Filter by comments by user'),
-            involves: z.string().optional().describe('Filter by user involvement'),
-            reviewedBy: z
+                .describe('Search terms. Start simple: "error", "crash". Use quotes for exact phrases.'),
+            owner: z
                 .string()
+                .min(1)
                 .optional()
-                .describe('Filter by user who reviewed'),
-            reviewRequested: z
+                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
+            repo: z
                 .string()
                 .optional()
-                .describe('Filter by user or team requested to review'),
-            state: z
-                .enum(['open', 'closed'])
+                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+            app: z
+                .string()
                 .optional()
-                .describe('Filter by state'),
-            head: z.string().optional().describe('Filter by head branch name'),
-            base: z.string().optional().describe('Filter by base branch name'),
-            language: z.string().optional().describe('Filter by coding language'),
-            created: z.string().optional().describe('Filter by created date'),
-            updated: z.string().optional().describe('Filter by last updated date'),
-            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'])
+                .describe('GitHub App that created the issue'),
+            archived: z
+                .boolean()
                 .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'])
+                .describe('Include archived repositories'),
+            assignee: z.string().optional().describe('GitHub username of assignee'),
+            author: z
+                .string()
                 .optional()
-                .describe('Filter based on review status'),
-            limit: z
+                .describe('GitHub username of issue creator'),
+            closed: z
+                .string()
+                .optional()
+                .describe('When closed. Format: >2020-01-01'),
+            commenter: z
+                .string()
+                .optional()
+                .describe('User who commented on issue'),
+            comments: z
                 .number()
-                .int()
-                .min(1)
-                .max(50)
                 .optional()
-                .default(25)
-                .describe('Maximum results (default: 25, max: 50)'),
+                .describe('Comment count. Format: >10, <5, 5..10'),
+            created: z
+                .string()
+                .optional()
+                .describe('When created. Format: >2020-01-01'),
+            includePrs: z
+                .boolean()
+                .optional()
+                .describe('Include pull requests. Default: false'),
+            interactions: z
+                .number()
+                .optional()
+                .describe('Total interactions (reactions + comments)'),
+            involves: z.string().optional().describe('User involved in any way'),
+            labels: z
+                .string()
+                .optional()
+                .describe('Label names (bug, feature, etc.)'),
+            language: z.string().optional().describe('Repository language'),
+            locked: z.boolean().optional().describe('Conversation locked status'),
+            match: z
+                .enum(['title', 'body', 'comments'])
+                .optional()
+                .describe('Search scope. Default: title and body'),
+            mentions: z.string().optional().describe('Issues mentioning this user'),
+            milestone: z.string().optional().describe('Milestone name'),
+            noAssignee: z.boolean().optional().describe('Issues without assignee'),
+            noLabel: z.boolean().optional().describe('Issues without labels'),
+            noMilestone: z
+                .boolean()
+                .optional()
+                .describe('Issues without milestone'),
+            noProject: z.boolean().optional().describe('Issues not in projects'),
+            project: z.string().optional().describe('Project board number'),
+            reactions: z
+                .number()
+                .optional()
+                .describe('Reaction count. Format: >10'),
+            state: z
+                .enum(['open', 'closed'])
+                .optional()
+                .describe('Issue state. Default: all'),
+            teamMentions: z.string().optional().describe('Team mentioned in issue'),
+            updated: z
+                .string()
+                .optional()
+                .describe('When updated. Format: >2020-01-01'),
+            visibility: z
+                .enum(['public', 'private', 'internal'])
+                .optional()
+                .describe('Repository visibility'),
             sort: z
                 .enum([
                 'comments',
+                'created',
+                'interactions',
                 'reactions',
                 'reactions-+1',
                 'reactions--1',
-                'reactions-smile',
-                'reactions-thinking_face',
                 'reactions-heart',
+                'reactions-smile',
                 'reactions-tada',
-                'interactions',
-                'created',
+                'reactions-thinking_face',
                 'updated',
+                'best-match',
             ])
                 .optional()
-                .describe('Sort criteria'),
+                .describe('Sort by activity or reactions. Default: best match'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Order (default: desc)'),
+                .describe('Sort order. Default: desc'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(25)
+                .describe('Results limit (1-50). Default: 25'),
         },
         annotations: {
-            title: 'GitHub Pull Requests Search',
+            title: 'GitHub Issues Search - Bug & Feature Discovery',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -2312,750 +1779,912 @@ function registerSearchGitHubPullRequestsTool(server) {
     }, async (args) => {
         if (!args.query?.trim()) {
             return createResult({
-                error: 'Search query is required and cannot be empty - provide keywords to search for pull requests',
+                error: `${ERROR_MESSAGES.QUERY_REQUIRED} ${SUGGESTIONS.PROVIDE_KEYWORDS}`,
             });
         }
         if (args.query.length > 256) {
             return createResult({
-                error: 'Search query is too long. Please limit to 256 characters or less - simplify your search terms',
+                error: ERROR_MESSAGES.QUERY_TOO_LONG,
             });
         }
         try {
-            return await searchGitHubPullRequests(args);
+            return await searchGitHubIssues(args);
         }
         catch (error) {
+            const errorMessage = error instanceof Error ? error.message : '';
+            if (errorMessage.includes('authentication')) {
+                return createResult({
+                    error: createAuthenticationError(),
+                });
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createResult({
+                    error: createRateLimitError(false),
+                });
+            }
+            // Generic fallback
             return createResult({
-                error: 'GitHub pull requests search failed - verify repository access and query syntax',
+                error: createSearchFailedError('issues'),
             });
         }
     });
 }
-async function searchGitHubPullRequests(params) {
-    const cacheKey = generateCacheKey('gh-prs', params);
+async function searchGitHubIssues(params) {
+    const cacheKey = generateCacheKey('gh-issues', params);
     return withCache(cacheKey, async () => {
-        const { command, args } = buildGitHubPullRequestsAPICommand(params);
+        const { command, args } = buildGitHubIssuesAPICommand(params);
         const result = await executeGitHubCommand(command, args, { cache: false });
         if (result.isError) {
             return result;
         }
         const execResult = JSON.parse(result.content[0].text);
-        const apiResponse = JSON.parse(execResult.result);
-        const pullRequests = apiResponse.items || [];
-        const cleanPRs = pullRequests.map((pr) => {
-            const result = {
-                number: pr.number,
-                title: pr.title,
-                state: pr.state,
-                author: pr.user?.login || '',
-                repository: pr.repository_url?.split('/').slice(-2).join('/') || 'unknown',
-                labels: pr.labels?.map(l => l.name) || [],
-                created_at: toDDMMYYYY(pr.created_at),
-                updated_at: toDDMMYYYY(pr.updated_at),
-                url: pr.html_url,
-                comments: pr.comments,
-                reactions: pr.reactions?.total_count || 0,
-                draft: pr.draft,
-            };
-            // Only include optional fields if they have values
-            if (pr.merged_at)
-                result.merged_at = pr.merged_at;
-            if (pr.closed_at)
-                result.closed_at = toDDMMYYYY(pr.closed_at);
-            if (pr.head?.ref)
-                result.head = pr.head.ref;
-            if (pr.base?.ref)
-                result.base = pr.base.ref;
-            return result;
-        });
+        const apiResponse = execResult.result;
+        const issues = apiResponse.items || [];
+        const cleanIssues = issues.map((issue) => ({
+            number: issue.number,
+            title: issue.title,
+            state: issue.state,
+            author: issue.user?.login || '',
+            repository: issue.repository_url?.split('/').slice(-2).join('/') || 'unknown',
+            labels: issue.labels?.map(l => l.name) || [],
+            created_at: toDDMMYYYY(issue.created_at),
+            updated_at: toDDMMYYYY(issue.updated_at),
+            url: issue.html_url,
+            comments: issue.comments,
+            reactions: issue.reactions?.total_count || 0,
+        }));
         const searchResult = {
-            results: cleanPRs,
-            total_count: apiResponse.total_count || cleanPRs.length,
-            metadata: {
-                incomplete_results: apiResponse.incomplete_results || false,
-            },
+            results: cleanIssues,
         };
         return createResult({ data: searchResult });
     });
 }
-function buildGitHubPullRequestsAPICommand(params) {
-    const queryParts = [params.query?.trim() || ''];
-    // Repository/organization qualifiers
+function buildGitHubIssuesAPICommand(params) {
+    const queryParts = [];
+    // Start with the base query, but filter out qualifiers that will be added separately
+    const baseQuery = params.query?.trim() || '';
+    // Extract and remove qualifiers from the main query to avoid conflicts
+    const qualifierPatterns = [
+        /\bis:(open|closed)\b/gi,
+        /\blabel:("[^"]*"|[^\s]+)/gi,
+        /\bcreated:([^\s]+)/gi,
+        /\bupdated:([^\s]+)/gi,
+        /\bauthor:([^\s]+)/gi,
+        /\bassignee:([^\s]+)/gi,
+        /\bstate:(open|closed)/gi,
+        /\brepo:([^\s]+)/gi,
+        /\borg:([^\s]+)/gi,
+    ];
+    // Remove extracted qualifiers from base query
+    let cleanQuery = baseQuery;
+    qualifierPatterns.forEach(pattern => {
+        cleanQuery = cleanQuery.replace(pattern, '').trim();
+    });
+    // Add the cleaned query if it has content
+    if (cleanQuery) {
+        queryParts.push(cleanQuery);
+    }
+    // Repository/organization qualifiers - prioritize function params over query
     if (params.owner && params.repo) {
         queryParts.push(`repo:${params.owner}/${params.repo}`);
     }
     else if (params.owner) {
         queryParts.push(`org:${params.owner}`);
     }
-    // Build search qualifiers from params
+    // Build search qualifiers from function parameters (these take precedence)
     const qualifiers = {
         author: params.author,
         assignee: params.assignee,
         mentions: params.mentions,
         commenter: params.commenter,
         involves: params.involves,
+        language: params.language,
         state: params.state,
         created: params.created,
         updated: params.updated,
         closed: params.closed,
-        language: params.language,
     };
     Object.entries(qualifiers).forEach(([key, value]) => {
         if (value)
             queryParts.push(`${key}:${value}`);
     });
-    // Special qualifiers
-    if (params.reviewedBy)
-        queryParts.push(`reviewed-by:${params.reviewedBy}`);
-    if (params.reviewRequested)
-        queryParts.push(`review-requested:${params.reviewRequested}`);
-    if (params.head)
-        queryParts.push(`head:${params.head}`);
-    if (params.base)
-        queryParts.push(`base:${params.base}`);
-    if (params.mergedAt)
-        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(' ');
-    const limit = Math.min(params.limit || 25, 100);
-    let apiPath = `search/issues?q=${encodeURIComponent(query)}&per_page=${limit}`;
-    if (params.sort)
-        apiPath += `&sort=${params.sort}`;
-    if (params.order)
-        apiPath += `&order=${params.order}`;
-    return { command: 'api', args: [apiPath] };
-}
-
-const TOOL_NAME$3 = 'npm_package_search';
-const DESCRIPTION$3 = `Search npm packages by keywords using fuzzy matching. Use space-separated keywords like "react hooks" or "cli typescript". No boolean operators supported.`;
-const MAX_DESCRIPTION_LENGTH = 100;
-const MAX_KEYWORDS = 10;
-function registerNpmSearchTool(server) {
-    server.registerTool(TOOL_NAME$3, {
-        description: DESCRIPTION$3,
-        inputSchema: {
-            queries: z
-                .union([z.string(), z.array(z.string())])
-                .describe('Package names or keywords to search for. Use simple space-separated keywords like "react hooks" or "typescript cli" for fuzzy matching.'),
-            searchlimit: z
-                .number()
-                .int()
-                .min(1)
-                .max(50)
-                .optional()
-                .default(20)
-                .describe('Max results per query (default: 20, max: 50)'),
-        },
-        annotations: {
-            title: 'NPM Package Search',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: true,
-        },
-    }, async (args) => {
-        try {
-            const queries = Array.isArray(args.queries)
-                ? args.queries
-                : [args.queries];
-            const searchLimit = args.searchlimit || 20;
-            const allPackages = [];
-            // Search for each query term
-            for (const query of queries) {
-                const result = await executeNpmCommand('search', [query, `--searchlimit=${searchLimit}`, '--json'], { cache: true });
-                if (!result.isError && result.content?.[0]?.text) {
-                    const packages = parseNpmSearchOutput(result.content[0].text);
-                    allPackages.push(...packages);
-                }
-            }
-            const deduplicatedPackages = deduplicatePackages(allPackages);
-            if (deduplicatedPackages.length > 0) {
-                return createResult({
-                    data: {
-                        total_count: deduplicatedPackages.length,
-                        results: deduplicatedPackages,
-                    },
-                });
-            }
-            return createResult({
-                error: 'No packages found',
-                cli_command: `npm search ${Array.isArray(args.queries) ? args.queries.join(' ') : args.queries}`,
-            });
-        }
-        catch (error) {
-            return createResult({
-                error: 'Package search failed - check terms or try different keywords',
-                cli_command: `npm search ${Array.isArray(args.queries) ? args.queries.join(' ') : args.queries}`,
-            });
-        }
-    });
-}
-function deduplicatePackages(packages) {
-    const seen = new Set();
-    return packages.filter(pkg => {
-        if (seen.has(pkg.name))
-            return false;
-        seen.add(pkg.name);
-        return true;
-    });
-}
-function normalizePackage(pkg) {
-    const description = pkg.description || null;
-    const truncatedDescription = description && description.length > MAX_DESCRIPTION_LENGTH
-        ? description.substring(0, MAX_DESCRIPTION_LENGTH) + '...'
-        : description;
-    const keywords = pkg.keywords || [];
-    const limitedKeywords = keywords.slice(0, MAX_KEYWORDS);
-    return {
-        name: pkg.name || '',
-        version: pkg.version || '',
-        description: truncatedDescription,
-        keywords: limitedKeywords,
-        repository: pkg.links?.repository || pkg.repository?.url || null,
-    };
-}
-function parseNpmSearchOutput(output) {
-    try {
-        const wrapper = JSON.parse(output);
-        const commandResult = typeof wrapper.result === 'string'
-            ? JSON.parse(wrapper.result)
-            : wrapper.result;
-        let packages = [];
-        // Handle different npm search output formats
-        if (Array.isArray(commandResult)) {
-            packages = commandResult;
-        }
-        else if (commandResult?.objects && Array.isArray(commandResult.objects)) {
-            packages = commandResult.objects.map((obj) => obj.package || obj);
+    // Special qualifiers - handle labels carefully
+    if (params.labels) {
+        queryParts.push(`label:"${params.labels}"`);
+    }
+    if (params.milestone)
+        queryParts.push(`milestone:"${params.milestone}"`);
+    if (params.noAssignee)
+        queryParts.push('no:assignee');
+    if (params.noLabel)
+        queryParts.push('no:label');
+    if (params.noMilestone)
+        queryParts.push('no:milestone');
+    if (params.archived !== undefined)
+        queryParts.push(`archived:${params.archived}`);
+    if (params.locked)
+        queryParts.push('is:locked');
+    if (params.visibility)
+        queryParts.push(`is:${params.visibility}`);
+    // Extract qualifiers from original query and add them if not already set by params
+    if (baseQuery.includes('is:') && !params.state) {
+        const isMatch = baseQuery.match(/\bis:(open|closed)\b/i);
+        if (isMatch && !queryParts.some(part => part.startsWith('state:'))) {
+            queryParts.push(`state:${isMatch[1].toLowerCase()}`);
         }
-        else if (commandResult?.results && Array.isArray(commandResult.results)) {
-            packages = commandResult.results;
+    }
+    if (baseQuery.includes('label:') && !params.labels) {
+        const labelMatch = baseQuery.match(/\blabel:("[^"]*"|[^\s]+)/i);
+        if (labelMatch) {
+            const labelValue = labelMatch[1].replace(/"/g, '');
+            queryParts.push(`label:"${labelValue}"`);
         }
-        return packages.map(normalizePackage);
     }
-    catch {
-        return [];
+    if (baseQuery.includes('created:') && !params.created) {
+        const createdMatch = baseQuery.match(/\bcreated:([^\s]+)/i);
+        if (createdMatch) {
+            queryParts.push(`created:${createdMatch[1]}`);
+        }
     }
+    const query = queryParts.filter(Boolean).join(' ');
+    const limit = Math.min(params.limit || 25, 100);
+    let apiPath = `search/issues?q=${encodeURIComponent(query)}&per_page=${limit}`;
+    if (params.sort)
+        apiPath += `&sort=${params.sort}`;
+    if (params.order)
+        apiPath += `&order=${params.order}`;
+    return { command: 'api', args: [apiPath] };
 }
 
-const TOOL_NAME$2 = 'github_get_contents';
-const DESCRIPTION$2 = `Browse repository structure and verify file existence. Smart branch detection with fallbacks. Use before fetching files to understand organization.`;
-function registerViewRepositoryStructureTool(server) {
-    server.registerTool(TOOL_NAME$2, {
-        description: DESCRIPTION$2,
+// TODO: add PR commeents. e.g, gh pr view <PR_NUMBER_OR_URL_OR_BRANCH> --comments
+const GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME = 'githubSearchPullRequests';
+const DESCRIPTION$3 = `Search pull requests for implementation discovery and code review analysis. Supports filtering by state, review status, branches, and more. Parameters: query (required), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), author (optional), assignee (optional), mentions (optional), commenter (optional), involves (optional), reviewedBy (optional), reviewRequested (optional), state (optional), head (optional), base (optional), language (optional), created (optional), updated (optional), mergedAt (optional), closed (optional), draft (optional), checks (optional), merged (optional), review (optional), limit (optional), sort (optional), order (optional).`;
+function registerSearchGitHubPullRequestsTool(server) {
+    server.registerTool(GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME, {
+        description: DESCRIPTION$3,
         inputSchema: {
+            query: z
+                .string()
+                .min(1, 'Search query is required and cannot be empty')
+                .describe('Search terms. Start simple: "refactor", "optimization". Use quotes for exact phrases.'),
             owner: z
                 .string()
-                .min(1)
-                .max(100)
-                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/, 'Invalid GitHub username/org format')
-                .describe(`Repository owner/organization.`),
+                .optional()
+                .describe('Repository owner/org name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). Use with repo parameter for repository-specific searches.'),
             repo: z
                 .string()
-                .min(1)
-                .max(100)
-                .regex(/^[a-zA-Z0-9._-]+$/, 'Invalid repository name format')
-                .describe('Repository name. Case-sensitive.'),
-            branch: z
+                .optional()
+                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+            author: z.string().optional().describe('GitHub username of PR author'),
+            assignee: z.string().optional().describe('GitHub username of assignee'),
+            mentions: z.string().optional().describe('PRs mentioning this user'),
+            commenter: z.string().optional().describe('User who commented on PR'),
+            involves: z.string().optional().describe('User involved in any way'),
+            reviewedBy: z.string().optional().describe('User who reviewed the PR'),
+            reviewRequested: z
                 .string()
-                .min(1)
-                .max(255)
-                .regex(/^[^\s]+$/, 'Branch name cannot contain spaces')
-                .describe('Target branch name. Auto-detects default if not found.'),
-            path: z
+                .optional()
+                .describe('User/team requested for review'),
+            state: z
+                .enum(['open', 'closed'])
+                .optional()
+                .describe('PR state. Default: all'),
+            head: z.string().optional().describe('Source branch name'),
+            base: z
                 .string()
                 .optional()
-                .default('')
-                .refine(path => !path.includes('..'), 'Path traversal not allowed')
-                .refine(path => path.length <= 500, 'Path too long')
-                .describe('Directory path within repository. Leave empty for root.'),
+                .describe('Target branch name (main, develop, etc.)'),
+            language: z.string().optional().describe('Repository language'),
+            created: z
+                .string()
+                .optional()
+                .describe('When created. Format: >2020-01-01'),
+            updated: z
+                .string()
+                .optional()
+                .describe('When updated. Format: >2020-01-01'),
+            mergedAt: z
+                .string()
+                .optional()
+                .describe('When merged. Format: >2020-01-01'),
+            closed: z
+                .string()
+                .optional()
+                .describe('When closed. Format: >2020-01-01'),
+            draft: z.boolean().optional().describe('Draft PR status'),
+            checks: z
+                .enum(['pending', 'success', 'failure'])
+                .optional()
+                .describe('CI/CD check status'),
+            merged: z
+                .boolean()
+                .optional()
+                .describe('Only merged PRs (true) or unmerged (false)'),
+            review: z
+                .enum(['none', 'required', 'approved', 'changes_requested'])
+                .optional()
+                .describe('Review status filter'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(25)
+                .describe('Results limit (1-50). Default: 25'),
+            sort: z
+                .enum([
+                'comments',
+                'reactions',
+                'reactions-+1',
+                'reactions--1',
+                'reactions-smile',
+                'reactions-thinking_face',
+                'reactions-heart',
+                'reactions-tada',
+                'interactions',
+                'created',
+                'updated',
+            ])
+                .optional()
+                .describe('Sort by activity or reactions. Default: best match'),
+            order: z
+                .enum(['asc', 'desc'])
+                .optional()
+                .default('desc')
+                .describe('Sort order. Default: desc'),
         },
         annotations: {
-            title: 'GitHub Repository Contents',
+            title: 'GitHub PR Search - Implementation Discovery',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: true,
         },
     }, async (args) => {
+        if (!args.query?.trim()) {
+            return createResult({
+                error: `${ERROR_MESSAGES.QUERY_REQUIRED} ${SUGGESTIONS.PROVIDE_PR_KEYWORDS}`,
+            });
+        }
+        if (args.query.length > 256) {
+            return createResult({
+                error: ERROR_MESSAGES.QUERY_TOO_LONG,
+            });
+        }
         try {
-            const result = await viewRepositoryStructure(args);
-            return result;
+            return await searchGitHubPullRequests(args);
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
             return createResult({
-                error: `Repository exploration failed: ${errorMessage} - verify access and permissions`,
+                error: createSearchFailedError('pull_requests'),
             });
         }
     });
 }
-/**
- * Views the structure of a GitHub repository at a specific path.
- *
- * Features:
- * - Smart branch detection: fetches repository default branch automatically
- * - Intelligent fallback: tries requested -> default -> common branches
- * - Input validation: prevents path traversal and validates GitHub naming
- * - Clear error context: provides descriptive error messages
- * - Efficient caching: avoids redundant API calls
- * - Rich metadata: includes all GitHub API fields (sha, urls, links, etc.)
- */
-async function viewRepositoryStructure(params) {
-    const cacheKey = generateCacheKey('gh-repo-structure', params);
+async function searchGitHubPullRequests(params) {
+    const cacheKey = generateCacheKey('gh-prs', params);
     return withCache(cacheKey, async () => {
-        const { owner, repo, branch, path = '' } = params;
-        try {
-            // Clean up path
-            const cleanPath = path.startsWith('/') ? path.substring(1) : path;
-            // Try the requested branch first, then fallback to main/master
-            const branchesToTry = await getSmartBranchFallback(owner, repo, branch);
-            let items = [];
-            let usedBranch = branch;
-            let lastError = null;
-            for (const tryBranch of branchesToTry) {
-                try {
-                    const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
-                    const result = await executeGitHubCommand('api', [apiPath], {
-                        cache: false,
-                    });
-                    if (!result.isError) {
-                        const execResult = JSON.parse(result.content[0].text);
-                        const apiItems = JSON.parse(execResult.result);
-                        items = Array.isArray(apiItems) ? apiItems : [apiItems];
-                        usedBranch = tryBranch;
-                        break;
-                    }
-                    else {
-                        lastError = new Error(result.content[0].text);
-                    }
-                }
-                catch (error) {
-                    lastError = error instanceof Error ? error : new Error(String(error));
-                    // Try next branch
-                    continue;
-                }
-            }
-            if (items.length === 0) {
-                // Use the most descriptive error message
-                const errorMsg = lastError?.message || 'Unknown error';
-                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
-                    if (path) {
-                        return createResult({
-                            error: `Path "${path}" not found - verify path or use code search`,
-                        });
-                    }
-                    else {
-                        return createResult({
-                            error: `Repository not found: ${owner}/${repo} - verify names`,
-                        });
-                    }
-                }
-                else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
-                    return createResult({
-                        error: `Access denied to ${owner}/${repo} - check permissions`,
-                    });
-                }
-                else {
-                    return createResult({
-                        error: `Access failed: ${owner}/${repo} - check connection`,
-                    });
-                }
-            }
-            // Limit total items to 100 for efficiency
-            const limitedItems = items.slice(0, 100);
-            // Sort: directories first, then alphabetically
-            limitedItems.sort((a, b) => {
-                if (a.type !== b.type) {
-                    return a.type === 'dir' ? -1 : 1;
-                }
-                return a.name.localeCompare(b.name);
-            });
-            // Create simplified, token-efficient structure
-            const files = limitedItems
-                .filter(item => item.type === 'file')
-                .map(item => ({
-                name: item.name,
-                size: item.size,
-                url: item.path, // Use path for fetching
-            }));
-            const folders = limitedItems
-                .filter(item => item.type === 'dir')
-                .map(item => ({
-                name: item.name,
-                url: item.path, // Use path for browsing
-            }));
-            // Simplified result structure - token efficient
-            const result = {
-                repository: `${owner}/${repo}`,
-                branch: usedBranch,
-                path: cleanPath || '/',
-                githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
-                files: {
-                    count: files.length,
-                    files: files,
-                },
-                folders: {
-                    count: folders.length,
-                    folders: folders,
-                },
-                ...((usedBranch !== branch || limitedItems.length === 100) && {
-                    metadata: {
-                        ...(usedBranch !== branch && {
-                            branchFallback: {
-                                requested: branch,
-                                used: usedBranch,
-                            },
-                        }),
-                        ...(limitedItems.length === 100 && {
-                            truncated: true,
-                        }),
-                    },
-                }),
-            };
-            return createResult({ data: result });
+        const { command, args } = buildGitHubPullRequestsAPICommand(params);
+        const result = await executeGitHubCommand(command, args, { cache: false });
+        if (result.isError) {
+            return result;
         }
-        catch (error) {
+        const execResult = JSON.parse(result.content[0].text);
+        const apiResponse = execResult.result;
+        const pullRequests = apiResponse.items || [];
+        if (pullRequests.length === 0) {
             return createResult({
-                error: `Repository access failed - verify repository and authentication: ${error}`,
+                error: createNoResultsError('pull_requests'),
             });
         }
+        const cleanPRs = pullRequests.map((pr) => {
+            const result = {
+                number: pr.number,
+                title: pr.title,
+                state: pr.state,
+                author: pr.user?.login || '',
+                repository: pr.repository_url?.split('/').slice(-2).join('/') || 'unknown',
+                labels: pr.labels?.map(l => l.name) || [],
+                created_at: toDDMMYYYY(pr.created_at),
+                updated_at: toDDMMYYYY(pr.updated_at),
+                url: pr.html_url,
+                comments: pr.comments,
+                reactions: pr.reactions?.total_count || 0,
+                draft: pr.draft,
+            };
+            // Only include optional fields if they have values
+            if (pr.merged_at)
+                result.merged_at = pr.merged_at;
+            if (pr.closed_at)
+                result.closed_at = toDDMMYYYY(pr.closed_at);
+            if (pr.head?.ref)
+                result.head = pr.head.ref;
+            if (pr.base?.ref)
+                result.base = pr.base.ref;
+            return result;
+        });
+        const searchResult = {
+            results: cleanPRs,
+            total_count: apiResponse.total_count || cleanPRs.length,
+        };
+        return createResult({ data: searchResult });
     });
 }
+function buildGitHubPullRequestsAPICommand(params) {
+    const queryParts = [params.query?.trim() || ''];
+    // Repository/organization qualifiers
+    if (params.owner && params.repo) {
+        queryParts.push(`repo:${params.owner}/${params.repo}`);
+    }
+    else if (params.owner) {
+        queryParts.push(`org:${params.owner}`);
+    }
+    // Build search qualifiers from params
+    const qualifiers = {
+        author: params.author,
+        assignee: params.assignee,
+        mentions: params.mentions,
+        commenter: params.commenter,
+        involves: params.involves,
+        state: params.state,
+        created: params.created,
+        updated: params.updated,
+        closed: params.closed,
+        language: params.language,
+    };
+    Object.entries(qualifiers).forEach(([key, value]) => {
+        if (value)
+            queryParts.push(`${key}:${value}`);
+    });
+    // Special qualifiers
+    if (params.reviewedBy)
+        queryParts.push(`reviewed-by:${params.reviewedBy}`);
+    if (params.reviewRequested)
+        queryParts.push(`review-requested:${params.reviewRequested}`);
+    if (params.head)
+        queryParts.push(`head:${params.head}`);
+    if (params.base)
+        queryParts.push(`base:${params.base}`);
+    if (params.mergedAt)
+        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(' ');
+    const limit = Math.min(params.limit || 25, 100);
+    let apiPath = `search/issues?q=${encodeURIComponent(query)}&per_page=${limit}`;
+    if (params.sort)
+        apiPath += `&sort=${params.sort}`;
+    if (params.order)
+        apiPath += `&order=${params.order}`;
+    return { command: 'api', args: [apiPath] };
+}
+
+/**
+ * GitHub Repository Search Tool
+ *
+ * MOST EFFECTIVE PATTERNS (based on testing):
+ *
+ * 1. Quality Discovery:
+ * { topic: ["react", "typescript"], stars: "1000..5000", limit: 10 }
+ *
+ * 2. Organization Research:
+ * { owner: ["microsoft", "google"], language: "python", limit: 10 }
+ *
+ * 3. Beginner Projects:
+ * { goodFirstIssues: ">=5", stars: "100..5000", limit: 10 }
+ *
+ * 4. Recent Quality:
+ * { stars: ">1000", created: ">2023-01-01", limit: 10 }
+ *
+ * AVOID: OR queries + language filter, 5+ filters, multi-word OR
+ * TIP: Use limit parameter instead of adding more filters
+ */
+const GITHUB_SEARCH_REPOSITORIES_TOOL_NAME = 'githubSearchRepositories';
+const DESCRIPTION$2 = `Discover GitHub repositories with smart filtering. Supports language, stars, topics, ownership, dates, and community metrics. Parameters: query (optional), owner (optional - GitHub username/org, NOT owner/repo), language (optional), stars (optional), topic (optional), forks (optional), numberOfTopics (optional), license (optional), archived (optional), includeForks (optional), visibility (optional), created (optional), updated (optional), size (optional), goodFirstIssues (optional), helpWantedIssues (optional), followers (optional), match (optional), sort (optional), order (optional), limit (optional).`;
 /**
- * Intelligently determines the best branches to try for a repository.
- * Attempts to fetch the default branch first, then falls back to common branches.
+ * Extract owner/repo information from various query formats
  */
-async function getSmartBranchFallback(owner, repo, requestedBranch) {
-    const branches = [requestedBranch];
-    try {
-        // Try to get repository info to find default branch
-        const repoInfoResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
-            cache: false,
-        });
-        if (!repoInfoResult.isError) {
-            const repoData = JSON.parse(JSON.parse(repoInfoResult.content[0].text).result);
-            const defaultBranch = repoData.default_branch;
-            if (defaultBranch && !branches.includes(defaultBranch)) {
-                branches.push(defaultBranch);
-            }
+function extractOwnerRepoFromQuery(query) {
+    let cleanedQuery = query;
+    let extractedOwner;
+    let extractedRepo;
+    const patterns = [
+        // Pattern 1: GitHub URLs (https://github.com/owner/repo)
+        /github\.com\/([^\\s]+)\/([^\\s]+)/i,
+        // Pattern 2: owner/repo format in query
+        /\b([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\/([a-zA-Z0-9][a-zA-Z0-9\-.]*[a-zA-Z0-9])\b/,
+        // Pattern 3: NPM package-like references (@scope/package)
+        /@([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\/([a-zA-Z0-9][a-zA-Z0-9\-.]*[a-zA-Z0-9])/,
+    ];
+    for (const pattern of patterns) {
+        const match = cleanedQuery.match(pattern);
+        if (match) {
+            extractedOwner = match[1];
+            extractedRepo = match[2];
+            cleanedQuery = cleanedQuery.replace(match[0], '').trim();
+            break; // Stop after the first successful match
         }
     }
-    catch {
-        // If we can't get repo info, proceed with standard fallbacks
-    }
-    // Add common branch names if not already included
-    const commonBranches = ['main', 'master', 'develop', 'dev'];
-    commonBranches.forEach(branch => {
-        if (!branches.includes(branch)) {
-            branches.push(branch);
-        }
-    });
-    return branches;
+    return {
+        extractedOwner,
+        extractedRepo,
+        cleanedQuery: cleanedQuery || query, // Ensure original query is returned if cleaned is empty
+    };
 }
-
-const TOOL_NAME$1 = 'github_search_issues';
-const DESCRIPTION$1 = `Find GitHub issues with rich metadata. Discover pain points, feature requests, and bug patterns with boolean logic and GitHub qualifiers.`;
-function registerSearchGitHubIssuesTool(server) {
-    server.registerTool(TOOL_NAME$1, {
-        description: DESCRIPTION$1,
+function registerSearchGitHubReposTool(server) {
+    server.registerTool(GITHUB_SEARCH_REPOSITORIES_TOOL_NAME, {
+        description: DESCRIPTION$2,
         inputSchema: {
             query: z
                 .string()
-                .min(1, 'Search query is required and cannot be empty')
-                .describe('Search query with GitHub syntax. Boolean: "bug AND crash", exact phrases: "memory leak", qualifiers: "is:open label:bug".'),
+                .optional()
+                .describe('Search query. START SIMPLE: Use 1-2 words with NO filters first (e.g., "react", "auth"). Add qualifiers only after initial search.'),
+            // CORE FILTERS (GitHub CLI flags)
             owner: z
-                .string()
-                .min(1)
+                .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner/organization. Leave empty for global search.'),
-            repo: z
+                .describe('Repository owner or organization name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). For private repos, use organizations from api_status_check (user_organizations). Can be a single value or array.'),
+            language: z
                 .string()
                 .optional()
-                .describe('Repository name. Do exploratory search without repo filter first'),
-            app: z.string().optional().describe('Filter by GitHub App author'),
-            archived: z
-                .boolean()
+                .describe('Programming language filter. Use when results need refinement.'),
+            stars: z
+                .union([
+                z.number().int().min(0),
+                z.string().regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/),
+            ])
                 .optional()
-                .describe('Filter by repository archived state'),
-            assignee: z.string().optional().describe('Filter by assignee'),
-            author: z.string().optional().describe('Filter by issue author'),
-            closed: z.string().optional().describe('Filter by closed date'),
-            commenter: z
-                .string()
+                .describe('Stars filter. Supports ranges and thresholds.'),
+            topic: z
+                .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Filter by user who commented'),
-            comments: z
+                .describe('Topics filter. Can be a single value or array.'),
+            forks: z.number().optional().describe('Number of forks filter.'),
+            // UPDATED: Match CLI parameter name exactly
+            numberOfTopics: z
                 .number()
                 .optional()
-                .describe('Filter by number of comments'),
-            created: z.string().optional().describe('Filter by created date'),
-            includePrs: z
+                .describe('Filter by number of topics (indicates documentation quality).'),
+            // QUALITY & STATE FILTERS
+            license: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('License filter. Works well as array ["mit", "apache-2.0"].'),
+            archived: z
                 .boolean()
                 .optional()
-                .describe('Include pull requests in results'),
-            interactions: z
-                .number()
+                .describe('Filter archived repositories (true/false).'),
+            includeForks: z
+                .enum(['false', 'true', 'only'])
                 .optional()
-                .describe('Filter by reactions and comments count'),
-            involves: z.string().optional().describe('Filter by user involvement'),
-            labels: z.string().optional().describe('Filter by labels'),
-            language: z.string().optional().describe('Filter by coding language'),
-            locked: z
-                .boolean()
+                .describe('Include forks: false (exclude), true (include), only (forks only).'),
+            visibility: z
+                .enum(['public', 'private', 'internal'])
                 .optional()
-                .describe('Filter by locked conversation status'),
-            match: z
-                .enum(['title', 'body', 'comments'])
+                .describe('Repository visibility filter.'),
+            // DATE & SIZE FILTERS
+            created: z
+                .string()
                 .optional()
-                .describe('Restrict search to specific field'),
-            mentions: z.string().optional().describe('Filter by user mentions'),
-            milestone: z.string().optional().describe('Filter by milestone title'),
-            noAssignee: z
-                .boolean()
+                .describe('Created date filter. Format: ">2020-01-01", "<2023-12-31".'),
+            updated: z
+                .string()
                 .optional()
-                .describe('Filter by missing assignee'),
-            noLabel: z.boolean().optional().describe('Filter by missing label'),
-            noMilestone: z
-                .boolean()
+                .describe('Updated date filter. Good for finding active projects.'),
+            size: z
+                .string()
                 .optional()
-                .describe('Filter by missing milestone'),
-            noProject: z.boolean().optional().describe('Filter by missing project'),
-            project: z.string().optional().describe('Filter by project board'),
-            reactions: z.number().optional().describe('Filter by reactions count'),
-            state: z
-                .enum(['open', 'closed'])
+                .describe('Repository size filter in KB. Format: ">1000", "<500".'),
+            // COMMUNITY FILTERS - Match CLI parameter names exactly
+            goodFirstIssues: z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
+            ])
                 .optional()
-                .describe('Filter by issue state'),
-            teamMentions: z.string().optional().describe('Filter by team mentions'),
-            updated: z.string().optional().describe('Filter by last updated date'),
-            visibility: z
-                .enum(['public', 'private', 'internal'])
+                .describe('Good first issues count. WORKING: Filter for beginner-friendly projects. EXCELLENT when combined with stars "100..5000" for quality beginner projects.'),
+            helpWantedIssues: z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: number, ">5", ">=10", "<20", "<=15", or "5..20"'),
+            ])
+                .optional()
+                .describe('Help wanted issues count. Good for finding projects needing contributors.'),
+            followers: z.number().optional().describe('Followers count filter.'),
+            // SEARCH SCOPE
+            match: z
+                .enum(['name', 'description', 'readme'])
                 .optional()
-                .describe('Filter by repository visibility'),
+                .describe('Search scope: name, description, or readme content.'),
+            // SORTING & LIMITS - Match CLI defaults exactly
             sort: z
                 .enum([
-                'comments',
-                'created',
-                'interactions',
-                'reactions',
-                'reactions-+1',
-                'reactions--1',
-                'reactions-heart',
-                'reactions-smile',
-                'reactions-tada',
-                'reactions-thinking_face',
+                'forks',
+                'help-wanted-issues',
+                'stars',
                 'updated',
                 'best-match',
             ])
                 .optional()
-                .describe('Sort criteria'),
+                .default('best-match')
+                .describe('Sort criteria for results.'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Order (default: desc)'),
+                .describe('Sort order direction.'),
             limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(30)
+                .describe('Maximum results to return (1-100). Default: 30'),
+        },
+        annotations: {
+            title: 'GitHub Repository Search',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        try {
+            // Extract owner/repo from query if present
+            const queryInfo = args.query
+                ? extractOwnerRepoFromQuery(args.query)
+                : {
+                    cleanedQuery: '',
+                    extractedOwner: undefined,
+                    extractedRepo: undefined,
+                };
+            // Merge extracted owner with explicit owner parameter
+            let finalOwner = args.owner;
+            if (queryInfo.extractedOwner && !finalOwner) {
+                finalOwner = queryInfo.extractedOwner;
+            }
+            // Update parameters with extracted information
+            const enhancedArgs = {
+                ...args,
+                query: queryInfo.cleanedQuery || args.query,
+                owner: finalOwner,
+            };
+            // Enhanced validation logic for primary filters
+            const hasPrimaryFilter = enhancedArgs.query?.trim() ||
+                enhancedArgs.owner ||
+                enhancedArgs.language ||
+                enhancedArgs.topic ||
+                enhancedArgs.stars ||
+                enhancedArgs.forks;
+            if (!hasPrimaryFilter) {
+                return createResult({
+                    error: SUGGESTIONS.REPO_SEARCH_PRIMARY_FILTER,
+                });
+            }
+            // First attempt: Search with current parameters
+            const result = await searchGitHubRepos(enhancedArgs);
+            // Fallback for private repositories: If no results and owner is specified, try with private visibility
+            if (!result.isError) {
+                const resultData = JSON.parse(result.content[0].text);
+                if (resultData.total === 0 &&
+                    enhancedArgs.owner &&
+                    !enhancedArgs.visibility) {
+                    // Try searching with private visibility for organization repos
+                    const privateSearchArgs = {
+                        ...enhancedArgs,
+                        visibility: 'private',
+                    };
+                    const privateResult = await searchGitHubRepos(privateSearchArgs);
+                    if (!privateResult.isError) {
+                        const privateData = JSON.parse(privateResult.content[0].text);
+                        if (privateData.total > 0) {
+                            // Return private results with note
+                            return createResult({
+                                data: {
+                                    ...privateData,
+                                    note: 'Found results in private repositories within the specified organization.',
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            return createResult({
+                error: createSearchFailedError('repositories'),
+            });
+        }
+    });
+}
+async function searchGitHubRepos(params) {
+    const cacheKey = generateCacheKey('gh-repos', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const { command, args } = buildGitHubReposSearchCommand(params);
+            const result = await executeGitHubCommand(command, args, {
+                cache: false,
+            });
+            if (result.isError) {
+                return result;
+            }
+            const execResult = JSON.parse(result.content[0].text);
+            const repositories = execResult.result;
+            if (!Array.isArray(repositories) || repositories.length === 0) {
+                return createResult({
+                    error: createNoResultsError('repositories'),
+                });
+            }
+            const analysis = {
+                totalFound: 0,
+                languages: new Set(),
+                avgStars: 0,
+                recentlyUpdated: 0,
+                topStarred: [],
+            };
+            analysis.totalFound = repositories.length;
+            // Analyze repository data
+            let totalStars = 0;
+            const now = new Date();
+            const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+            repositories.forEach(repo => {
+                // Collect languages
+                if (repo.language) {
+                    analysis.languages.add(repo.language);
+                }
+                // Calculate average stars (use correct field name)
+                if (typeof repo.stargazersCount === 'number') {
+                    totalStars += repo.stargazersCount;
+                }
+                // Count recently updated repositories (use correct field name)
+                if (repo.updatedAt) {
+                    const updatedDate = new Date(repo.updatedAt);
+                    if (!isNaN(updatedDate.getTime()) && updatedDate > thirtyDaysAgo) {
+                        analysis.recentlyUpdated++;
+                    }
+                }
+            });
+            analysis.avgStars =
+                repositories.length > 0
+                    ? Math.round(totalStars / repositories.length)
+                    : 0;
+            // Get all repositories with comprehensive data
+            analysis.topStarred = repositories.map(repo => ({
+                name: repo.fullName || repo.name,
+                stars: repo.stargazersCount || 0,
+                description: repo.description || 'No description',
+                language: repo.language || 'Unknown',
+                url: repo.url,
+                forks: repo.forksCount || 0,
+                isPrivate: repo.isPrivate || false,
+                isArchived: repo.isArchived || false,
+                isFork: repo.isFork || false,
+                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,
+                createdAt: toDDMMYYYY(repo.createdAt),
+                updatedAt: toDDMMYYYY(repo.updatedAt),
+                visibility: repo.visibility || 'public',
+                owner: repo.owner?.login || repo.owner,
+            }));
+            return createResult({
+                data: {
+                    total_count: analysis.totalFound,
+                    ...(analysis.totalFound > 0
+                        ? {
+                            repositories: analysis.topStarred,
+                            summary: {
+                                languages: Array.from(analysis.languages).slice(0, 10),
+                                avgStars: analysis.avgStars,
+                                recentlyUpdated: analysis.recentlyUpdated,
+                            },
+                        }
+                        : {
+                            repositories: [],
+                        }),
+                },
+            });
+        }
+        catch (error) {
+            return createResult({
+                error: createSearchFailedError('repositories'),
+            });
+        }
+    });
+}
+function buildGitHubReposSearchCommand(params) {
+    const query = params.query?.trim() || '';
+    const args = ['repos'];
+    const hasEmbeddedQualifiers = query &&
+        /\b(stars|language|org|repo|topic|user|created|updated|size|license|archived|fork|good-first-issues|help-wanted-issues):/i.test(query);
+    if (query) {
+        args.push(query);
+    }
+    args.push('--json=name,fullName,description,language,stargazersCount,forksCount,updatedAt,createdAt,url,owner,isPrivate,license,hasIssues,openIssuesCount,isArchived,isFork,visibility');
+    const addArg = (paramName, cliFlag, condition = true, formatter) => {
+        const value = params[paramName];
+        if (value !== undefined && condition) {
+            if (Array.isArray(value)) {
+                args.push(`--${cliFlag}=${value.join(',')}`);
+            }
+            else if (formatter) {
+                args.push(`--${cliFlag}=${formatter(value)}`);
+            }
+            else {
+                args.push(`--${cliFlag}=${value.toString()}`);
+            }
+        }
+    };
+    // CORE FILTERS
+    addArg('owner', 'owner', !hasEmbeddedQualifiers);
+    addArg('language', 'language', !hasEmbeddedQualifiers);
+    addArg('forks', 'forks', !hasEmbeddedQualifiers);
+    addArg('topic', 'topic', !hasEmbeddedQualifiers);
+    addArg('numberOfTopics', 'number-topics');
+    addArg('stars', 'stars', !hasEmbeddedQualifiers, value => typeof value === 'number' ? value.toString() : value.trim());
+    // QUALITY & STATE FILTERS
+    addArg('archived', 'archived');
+    addArg('includeForks', 'include-forks');
+    addArg('visibility', 'visibility');
+    addArg('license', 'license');
+    // DATE & SIZE FILTERS
+    addArg('created', 'created');
+    addArg('updated', 'updated');
+    addArg('size', 'size');
+    // COMMUNITY FILTERS
+    addArg('goodFirstIssues', 'good-first-issues', true, value => typeof value === 'number' ? value.toString() : value);
+    addArg('helpWantedIssues', 'help-wanted-issues', true, value => typeof value === 'number' ? value.toString() : value);
+    addArg('followers', 'followers');
+    // SEARCH SCOPE
+    addArg('match', 'match');
+    // SORTING AND LIMITS
+    addArg('limit', 'limit');
+    addArg('order', 'order');
+    const sortBy = params.sort || 'best-match';
+    if (sortBy !== 'best-match') {
+        args.push(`--sort=${sortBy}`);
+    }
+    return { command: 'search', args };
+}
+
+const NPM_PACKAGE_SEARCH_TOOL_NAME = 'npmPackageSearch';
+const DESCRIPTION$1 = `Search NPM packages with fuzzy matching. Supports multiple search terms and aggregates results. Use functional keywords like "react hooks", "auth", or "testing". Parameters: queries (required, string or array), searchLimit (optional).`;
+const MAX_DESCRIPTION_LENGTH = 100;
+const MAX_KEYWORDS = 10;
+function registerNpmSearchTool(server) {
+    server.registerTool(NPM_PACKAGE_SEARCH_TOOL_NAME, {
+        description: DESCRIPTION$1,
+        inputSchema: {
+            queries: z
+                .union([z.string(), z.array(z.string())])
+                .describe('Search terms for packages. Use functionality keywords: "react hooks", "cli tool", "testing"'),
+            searchLimit: z
                 .number()
                 .int()
                 .min(1)
                 .max(50)
                 .optional()
-                .default(25)
-                .describe('Maximum results (default: 25, max: 50)'),
+                .default(20)
+                .describe('Results limit per query (1-50). Default: 20'),
         },
         annotations: {
-            title: 'GitHub Issues Search',
+            title: 'NPM Package Search',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: true,
         },
     }, async (args) => {
-        if (!args.query?.trim()) {
-            return createResult({
-                error: 'Search query is required and cannot be empty - provide keywords to search for issues',
-            });
-        }
-        if (args.query.length > 256) {
-            return createResult({
-                error: 'Search query is too long. Please limit to 256 characters or less - simplify your search terms',
-            });
-        }
         try {
-            return await searchGitHubIssues(args);
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : '';
-            if (errorMessage.includes('authentication')) {
-                return createResult({
-                    error: 'GitHub authentication required - run api_status_check tool',
-                });
+            const queries = Array.isArray(args.queries)
+                ? args.queries
+                : [args.queries];
+            const searchLimit = args.searchLimit || 20;
+            const allPackages = [];
+            // Search for each query term
+            for (const query of queries) {
+                const result = await executeNpmCommand('search', [query, `--searchlimit=${searchLimit}`, '--json'], { cache: true });
+                if (!result.isError && result.content?.[0]?.text) {
+                    const packages = parseNpmSearchOutput(result.content[0].text);
+                    allPackages.push(...packages);
+                }
             }
-            if (errorMessage.includes('rate limit')) {
+            const deduplicatedPackages = deduplicatePackages(allPackages);
+            if (deduplicatedPackages.length > 0) {
                 return createResult({
-                    error: 'GitHub rate limit exceeded - wait or use specific filters',
+                    data: {
+                        total_count: deduplicatedPackages.length,
+                        results: deduplicatedPackages,
+                    },
                 });
             }
-            // Generic fallback
             return createResult({
-                error: 'GitHub issue search failed - check authentication or simplify query',
+                error: createNoResultsError('packages'),
             });
         }
-    });
-}
-async function searchGitHubIssues(params) {
-    const cacheKey = generateCacheKey('gh-issues', params);
-    return withCache(cacheKey, async () => {
-        const { command, args } = buildGitHubIssuesAPICommand(params);
-        const result = await executeGitHubCommand(command, args, { cache: false });
-        if (result.isError) {
-            return result;
+        catch (error) {
+            return createResult({
+                error: createSearchFailedError('packages'),
+            });
         }
-        const execResult = JSON.parse(result.content[0].text);
-        const apiResponse = JSON.parse(execResult.result);
-        const issues = apiResponse.items || [];
-        const cleanIssues = issues.map((issue) => ({
-            number: issue.number,
-            title: issue.title,
-            state: issue.state,
-            author: issue.user?.login || '',
-            repository: issue.repository_url?.split('/').slice(-2).join('/') || 'unknown',
-            labels: issue.labels?.map(l => l.name) || [],
-            created_at: toDDMMYYYY(issue.created_at),
-            updated_at: toDDMMYYYY(issue.updated_at),
-            url: issue.html_url,
-            comments: issue.comments,
-            reactions: issue.reactions?.total_count || 0,
-        }));
-        const searchResult = {
-            results: cleanIssues,
-            total_count: apiResponse.total_count || cleanIssues.length,
-            metadata: {
-                incomplete_results: apiResponse.incomplete_results || false,
-            },
-        };
-        return createResult({ data: searchResult });
     });
 }
-function buildGitHubIssuesAPICommand(params) {
-    const queryParts = [];
-    // Start with the base query, but filter out qualifiers that will be added separately
-    const baseQuery = params.query?.trim() || '';
-    // Extract and remove qualifiers from the main query to avoid conflicts
-    const qualifierPatterns = [
-        /\bis:(open|closed)\b/gi,
-        /\blabel:("[^"]*"|[^\s]+)/gi,
-        /\bcreated:([^\s]+)/gi,
-        /\bupdated:([^\s]+)/gi,
-        /\bauthor:([^\s]+)/gi,
-        /\bassignee:([^\s]+)/gi,
-        /\bstate:(open|closed)/gi,
-        /\brepo:([^\s]+)/gi,
-        /\borg:([^\s]+)/gi,
-    ];
-    // Remove extracted qualifiers from base query
-    let cleanQuery = baseQuery;
-    qualifierPatterns.forEach(pattern => {
-        cleanQuery = cleanQuery.replace(pattern, '').trim();
+function deduplicatePackages(packages) {
+    const seen = new Set();
+    return packages.filter(pkg => {
+        if (seen.has(pkg.name))
+            return false;
+        seen.add(pkg.name);
+        return true;
     });
-    // Add the cleaned query if it has content
-    if (cleanQuery) {
-        queryParts.push(cleanQuery);
-    }
-    // Repository/organization qualifiers - prioritize function params over query
-    if (params.owner && params.repo) {
-        queryParts.push(`repo:${params.owner}/${params.repo}`);
-    }
-    else if (params.owner) {
-        queryParts.push(`org:${params.owner}`);
-    }
-    // Build search qualifiers from function parameters (these take precedence)
-    const qualifiers = {
-        author: params.author,
-        assignee: params.assignee,
-        mentions: params.mentions,
-        commenter: params.commenter,
-        involves: params.involves,
-        language: params.language,
-        state: params.state,
-        created: params.created,
-        updated: params.updated,
-        closed: params.closed,
+}
+function normalizePackage(pkg) {
+    const description = pkg.description || null;
+    const truncatedDescription = description && description.length > MAX_DESCRIPTION_LENGTH
+        ? description.substring(0, MAX_DESCRIPTION_LENGTH) + '...'
+        : description;
+    const keywords = pkg.keywords || [];
+    const limitedKeywords = keywords.slice(0, MAX_KEYWORDS);
+    return {
+        name: pkg.name || '',
+        version: pkg.version || '',
+        description: truncatedDescription,
+        keywords: limitedKeywords,
+        repository: pkg.links?.repository || pkg.repository?.url || null,
     };
-    Object.entries(qualifiers).forEach(([key, value]) => {
-        if (value)
-            queryParts.push(`${key}:${value}`);
-    });
-    // Special qualifiers - handle labels carefully
-    if (params.labels) {
-        queryParts.push(`label:"${params.labels}"`);
-    }
-    if (params.milestone)
-        queryParts.push(`milestone:"${params.milestone}"`);
-    if (params.noAssignee)
-        queryParts.push('no:assignee');
-    if (params.noLabel)
-        queryParts.push('no:label');
-    if (params.noMilestone)
-        queryParts.push('no:milestone');
-    if (params.archived !== undefined)
-        queryParts.push(`archived:${params.archived}`);
-    if (params.locked)
-        queryParts.push('is:locked');
-    if (params.visibility)
-        queryParts.push(`is:${params.visibility}`);
-    // Extract qualifiers from original query and add them if not already set by params
-    if (baseQuery.includes('is:') && !params.state) {
-        const isMatch = baseQuery.match(/\bis:(open|closed)\b/i);
-        if (isMatch && !queryParts.some(part => part.startsWith('state:'))) {
-            queryParts.push(`state:${isMatch[1].toLowerCase()}`);
+}
+function parseNpmSearchOutput(output) {
+    try {
+        const wrapper = JSON.parse(output);
+        const commandResult = wrapper.result;
+        let packages = [];
+        // Handle different npm search output formats
+        if (Array.isArray(commandResult)) {
+            packages = commandResult;
         }
-    }
-    if (baseQuery.includes('label:') && !params.labels) {
-        const labelMatch = baseQuery.match(/\blabel:("[^"]*"|[^\s]+)/i);
-        if (labelMatch) {
-            const labelValue = labelMatch[1].replace(/"/g, '');
-            queryParts.push(`label:"${labelValue}"`);
+        else if (commandResult?.objects && Array.isArray(commandResult.objects)) {
+            packages = commandResult.objects.map((obj) => obj.package || obj);
         }
-    }
-    if (baseQuery.includes('created:') && !params.created) {
-        const createdMatch = baseQuery.match(/\bcreated:([^\s]+)/i);
-        if (createdMatch) {
-            queryParts.push(`created:${createdMatch[1]}`);
+        else if (commandResult?.results && Array.isArray(commandResult.results)) {
+            packages = commandResult.results;
         }
+        return packages.map(normalizePackage);
+    }
+    catch (error) {
+        logger.warn('Failed to parse NPM search results:', error);
+        return [];
     }
-    const query = queryParts.filter(Boolean).join(' ');
-    const limit = Math.min(params.limit || 25, 100);
-    let apiPath = `search/issues?q=${encodeURIComponent(query)}&per_page=${limit}`;
-    if (params.sort)
-        apiPath += `&sort=${params.sort}`;
-    if (params.order)
-        apiPath += `&order=${params.order}`;
-    return { command: 'api', args: [apiPath] };
 }
 
-const TOOL_NAME = 'npm_view_package';
-const DESCRIPTION = `Get comprehensive NPM package metadata efficiently. Returns repository URL, exports, dependencies, and version history. Essential for finding package source code and understanding project structure.`;
+const NPM_VIEW_PACKAGE_TOOL_NAME = 'npmViewPackage';
+const DESCRIPTION = `View detailed NPM package information including repository URL, exports, version history, dependencies, and download stats. Returns optimized metadata for code navigation. Parameters: packageName (required).`;
 function registerNpmViewPackageTool(server) {
-    server.registerTool(TOOL_NAME, {
+    server.registerTool(NPM_VIEW_PACKAGE_TOOL_NAME, {
         description: DESCRIPTION,
         inputSchema: {
             packageName: z
                 .string()
                 .min(1)
-                .describe('NPM package name to analyze. Returns complete package context including exports (critical for GitHub file discovery), repository URL, dependencies, and version history.'),
+                .describe('NPM package name (e.g., "react", "express", "@types/node")'),
         },
         annotations: {
-            title: 'NPM Package Metadata',
+            title: 'NPM Package Analyzer',
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
@@ -3068,7 +2697,7 @@ function registerNpmViewPackageTool(server) {
                 return result;
             }
             const execResult = JSON.parse(result.content[0].text);
-            const packageData = JSON.parse(execResult.result);
+            const packageData = execResult.result;
             // Transform to optimized format
             const optimizedResult = transformToOptimizedFormat(packageData);
             return createResult({ data: optimizedResult });
@@ -3077,30 +2706,22 @@ function registerNpmViewPackageTool(server) {
             const errorMessage = error.message || '';
             if (errorMessage.includes('not found')) {
                 return createResult({
-                    error: 'Package not found - verify package name spelling',
-                    cli_command: `npm view ${args.packageName} --json`,
+                    error: 'Package not found. Check spelling and use exact package name from npm',
                 });
             }
             if (errorMessage.includes('network')) {
                 return createResult({
-                    error: 'Network error - check internet connection',
-                    cli_command: `npm view ${args.packageName} --json`,
+                    error: 'Network error. Check internet connection and try again',
                 });
             }
             return createResult({
-                error: 'NPM package lookup failed',
-                cli_command: `npm view ${args.packageName} --json`,
-                suggestions: [
-                    'Verify package name is correct',
-                    'Check if package exists on npmjs.com',
-                    'Try again in a moment',
-                ],
+                error: 'Failed to fetch package information. Try again or check npm status',
             });
         }
     });
 }
 /**
- * Transform NPM CLI response to optimized format
+ * Transform NPM CLI response to optimized format for code analysis
  */
 function transformToOptimizedFormat(packageData) {
     // Extract repository URL and simplify
@@ -3112,7 +2733,9 @@ function transformToOptimizedFormat(packageData) {
         : undefined;
     // Get version timestamps from time object and limit to last 5
     const timeData = packageData.time || {};
-    const versionList = packageData.versions || [];
+    const versionList = Array.isArray(packageData.versions)
+        ? packageData.versions
+        : [];
     const recentVersions = versionList.slice(-5).map((version) => ({
         version,
         date: timeData[version] ? toDDMMYYYY(timeData[version]) : 'Unknown',
@@ -3139,7 +2762,7 @@ function transformToOptimizedFormat(packageData) {
     return result;
 }
 /**
- * Simplify exports object to essential entry points
+ * Simplify exports to show only essential entry points for code navigation
  */
 function simplifyExports(exports) {
     if (typeof exports === 'string') {
@@ -3160,8 +2783,9 @@ function simplifyExports(exports) {
                 simplified.main = mainExport.import;
             }
         }
-        // Extract types if available
-        if (exports['./types'] || exports['.']?.types) {
+        // Extract types if available with safe property access
+        if (exports['./types'] ||
+            (exports['.'] && typeof exports['.'] === 'object' && exports['.'].types)) {
             simplified.types = exports['./types'] || exports['.'].types;
         }
         // Add a few other important exports (max 3 total)
@@ -3192,93 +2816,257 @@ async function viewNpmPackage(packageName) {
             const errorMessage = error.message || '';
             if (errorMessage.includes('404')) {
                 return createResult({
-                    error: 'Package not found on NPM registry',
+                    error: 'Package not found on NPM registry. Verify the exact package name',
                 });
             }
             return createResult({
-                error: 'NPM command execution failed',
+                error: 'Failed to execute NPM command. Check npm installation',
             });
         }
     });
 }
 
+const PROMPT_SYSTEM_PROMPT = `You are an expert code research assistant that knows how to understand users needs and search for the right information
+using gh cli for github and npm cli for packages.
+
+CRITICAL SEARCH PRINCIPLES:
+
+## 1. PROGRESSIVE SEARCH STRATEGY (MOST IMPORTANT):
+   a) START BROAD: Begin with simple, general terms (1-2 words max)
+   b) ANALYZE RESULTS: Learn from what you find (repo names, owners, common patterns)
+   c) REFINE GRADUALLY: Add filters only after understanding the landscape
+   d) MULTIPLE ANGLES: Try different search terms if first approach yields no results
+
+## 2. SEARCH PROGRESSION EXAMPLES:
+   - User asks about "React state management"
+     1st search: "state" or "redux" (BROAD)
+     2nd search: "react state" with language:javascript (REFINED)
+     3rd search: owner:facebook with specific terms (TARGETED)
+   
+   - User asks about "authentication libraries"
+     1st search: "auth" or "authentication" (BROAD)
+     2nd search: Add language filter based on results
+     3rd search: Focus on specific owners/topics found
+
+## 3. HANDLING NO RESULTS:
+   - NEVER give up after one failed search
+   - Try progressively BROADER terms
+   - Remove ALL filters and try core keywords
+   - Search for related concepts (e.g., "auth" → "login" → "session")
+   - Check different owners/organizations
+   - For code search: try searching in popular repos first
+
+## 4. SMART FILTER USAGE:
+   - NO FILTERS on first search (unless user specifies)
+   - Add ONE filter at a time based on results
+   - Common progression: query → +language → +stars → +owner
+   - Reserve complex filters for final refinement
+
+## 5. TOOL SYNERGY:
+   - Use repository search to find relevant repos FIRST
+   - Then use code search within those repos
+   - Check npm packages for JavaScript/TypeScript queries
+   - Verify access with api_status_check for private repos
+
+## 6. RESEARCH BEST PRACTICES:
+   - Conduct COMPREHENSIVE research with multiple searches
+   - Learn from each search to improve the next
+   - Provide context about your search strategy
+   - Always verify technical details with actual code
+
+## 7. COMPLEX ANALYSIS PATTERNS:
+
+### Multi-Framework Comparison (e.g., React vs Vue):
+   1. Search repos separately: "react", then "vue"
+   2. Find core implementation files: "scheduler" in React, "reactivity" in Vue
+   3. Search specific features: "concurrent", "fiber", "proxy"
+   4. Compare similar functionalities across repos
+
+### Architecture Analysis (e.g., State Management):
+   1. Start broad: "state" or "store"
+   2. Identify major libraries: Redux, Zustand, Jotai
+   3. Search implementation patterns: "reducer", "atom", "selector"
+   4. Analyze each approach separately, then compare
+
+### Evolution Tracking (e.g., Feature History):
+   1. Use commit search with broad terms first
+   2. Narrow by date ranges progressively
+   3. Track changes in specific files over time
+   4. Identify key contributors and their patterns
+
+### Performance Analysis:
+   1. Search for benchmarks: "benchmark", "perf", "performance"
+   2. Look for optimization commits: "optimize", "faster", "improve"
+   3. Find profiling code: "profile", "measure", "timing"
+   4. Compare implementation strategies
+
+## 8. CROSS-REPOSITORY INTELLIGENCE:
+   - When comparing frameworks, search EACH separately first
+   - Build mental model of each codebase structure
+   - Use discovered patterns to refine searches
+   - Connect findings across repositories for insights
+
+## 9. TOOL-SPECIFIC BEST PRACTICES:
+
+### ${API_STATUS_CHECK_TOOL_NAME}:
+   - Run FIRST when dealing with private repositories
+   - Use organizations list to scope searches
+   - Verify authentication before extensive searches
+
+### ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}:
+   - Start with topic/language, add stars/forks filters later
+   - Use date ranges for trending analysis
+   - Combine multiple searches for comprehensive discovery
+
+### ${GITHUB_SEARCH_CODE_TOOL_NAME}:
+   - Begin with function/class names, not full signatures
+   - Use extension filters for targeted searches
+   - Try partial matches before exact phrases
+
+### ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME}:
+   - Navigate from root, then drill down
+   - Use for understanding project organization
+   - Check common paths: src/, lib/, packages/
+
+### ${GITHUB_GET_FILE_CONTENT_TOOL_NAME}:
+   - Verify file paths with repo structure first
+   - Use for implementation details and documentation
+   - Remember 300KB limit for large files
+
+### ${GITHUB_SEARCH_COMMITS_TOOL_NAME}:
+   - Search by feature keywords, not commit hashes
+   - Use author filter for contributor analysis
+   - Date ranges help track feature evolution
+
+### ${GITHUB_SEARCH_ISSUES_TOOL_NAME} & ${GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME}:
+   - Search for problem descriptions, not solutions
+   - Use state filters progressively
+   - Labels reveal project categorization
+
+### ${NPM_PACKAGE_SEARCH_TOOL_NAME}:
+   - Use functional terms: "router", "validator", "parser"
+   - Search multiple related terms in parallel
+   - Aggregate results for comprehensive view
+
+### ${NPM_VIEW_PACKAGE_TOOL_NAME}:
+   - Check repository field for source code access
+   - Review exports for API understanding
+   - Use version history to gauge stability
+
+## 10. CHAIN OF THOUGHT OPTIMIZATION:
+   - Plan search sequence before executing
+   - Document reasoning for each search refinement
+   - Build knowledge progressively, don't jump to specifics
+   - Validate findings with multiple sources
+`;
+
 const SERVER_CONFIG = {
     name: 'octocode-mcp',
     version: '1.0.0',
-    description: `Comprehensive code analysis assistant: Deep exploration and understanding of complex implementations in GitHub repositories and npm packages.
-       Specialized in architectural analysis, algorithm explanations, and complete technical documentation.`,
+    description: PROMPT_SYSTEM_PROMPT,
 };
 function registerAllTools(server) {
     const toolRegistrations = [
-        { name: 'ApiStatusCheck', fn: registerApiStatusCheckTool },
-        { name: 'GitHubSearchCode', fn: registerGitHubSearchCodeTool },
+        { name: API_STATUS_CHECK_TOOL_NAME, fn: registerApiStatusCheckTool },
+        { name: GITHUB_SEARCH_CODE_TOOL_NAME, fn: registerGitHubSearchCodeTool },
         {
-            name: 'FetchGitHubFileContent',
+            name: GITHUB_GET_FILE_CONTENT_TOOL_NAME,
             fn: registerFetchGitHubFileContentTool,
         },
-        { name: 'SearchGitHubRepos', fn: registerSearchGitHubReposTool },
-        { name: 'SearchGitHubCommits', fn: registerGitHubSearchCommitsTool },
         {
-            name: 'SearchGitHubPullRequests',
+            name: GITHUB_SEARCH_REPOSITORIES_TOOL_NAME,
+            fn: registerSearchGitHubReposTool,
+        },
+        {
+            name: GITHUB_SEARCH_COMMITS_TOOL_NAME,
+            fn: registerGitHubSearchCommitsTool,
+        },
+        {
+            name: GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME,
             fn: registerSearchGitHubPullRequestsTool,
         },
-        { name: 'NpmSearch', fn: registerNpmSearchTool },
+        { name: NPM_PACKAGE_SEARCH_TOOL_NAME, fn: registerNpmSearchTool },
         {
-            name: 'ViewRepositoryStructure',
+            name: GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME,
             fn: registerViewRepositoryStructureTool,
         },
-        { name: 'SearchGitHubIssues', fn: registerSearchGitHubIssuesTool },
-        { name: 'NpmViewPackage', fn: registerNpmViewPackageTool },
+        {
+            name: GITHUB_SEARCH_ISSUES_TOOL_NAME,
+            fn: registerSearchGitHubIssuesTool,
+        },
+        { name: NPM_VIEW_PACKAGE_TOOL_NAME, fn: registerNpmViewPackageTool },
     ];
+    logger.info(`Registering ${toolRegistrations.length} tools...`);
+    let successCount = 0;
     for (const tool of toolRegistrations) {
         try {
+            logger.debug(`Registering tool: ${tool.name}`);
             tool.fn(server);
+            successCount++;
+            logger.info(`✓ Successfully registered: ${tool.name}`);
         }
         catch (error) {
-            // ignore
+            logger.error(`✗ Failed to register ${tool.name}:`, error);
+            // Continue with other tools instead of failing completely
         }
     }
+    if (successCount === 0) {
+        throw new Error('No tools were successfully registered');
+    }
+    logger.info(`All tools registration completed - ${successCount}/${toolRegistrations.length} successful`);
 }
 async function startServer() {
     try {
-        const server = new McpServer(SERVER_CONFIG, {
-            capabilities: {
-                tools: {},
-                resources: {},
-                prompts: {},
-            },
-            instructions: `
-    ${PROMPT_SYSTEM_PROMPT}
-  `,
-        });
+        logger.info('Creating MCP server...');
+        const server = new McpServer(SERVER_CONFIG);
         registerAllTools(server);
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        const gracefulShutdown = async (_signal) => {
+        logger.info('=== Server Connected Successfully ===');
+        // Ensure all buffered output is sent
+        process.stdout.uncork();
+        process.stderr.uncork();
+        const gracefulShutdown = async (signal) => {
             try {
-                await server.close();
+                logger.info(`Received ${signal}, shutting down gracefully...`);
+                clearAllCache();
+                // Give server time to close properly
+                await Promise.race([
+                    server.close(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Server close timeout')), 5000)),
+                ]);
                 process.exit(0);
             }
             catch (error) {
+                logger.error('Error during shutdown:', error);
                 process.exit(1);
             }
         };
+        // Handle process signals
         process.on('SIGINT', () => gracefulShutdown('SIGINT'));
         process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+        // Handle stdin close (important for MCP)
         process.stdin.on('close', async () => {
             await gracefulShutdown('STDIN_CLOSE');
         });
-        process.on('uncaughtException', () => {
+        // Handle uncaught errors
+        process.on('uncaughtException', error => {
+            logger.error('Uncaught exception:', error);
             gracefulShutdown('UNCAUGHT_EXCEPTION');
         });
-        process.on('unhandledRejection', () => {
+        process.on('unhandledRejection', (reason, promise) => {
+            logger.error('Unhandled rejection at:', promise, 'reason:', reason);
             gracefulShutdown('UNHANDLED_REJECTION');
         });
+        // Keep process alive
+        process.stdin.resume();
     }
     catch (error) {
+        logger.error('Error details:', error);
         process.exit(1);
     }
 }
-startServer().catch(() => {
+startServer().catch(error => {
+    logger.error('Error:', error);
     process.exit(1);
 });