octocode-mcp 2.3.4 → 2.3.6

package/build/index.js

@@ -8,83 +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.`;
-
-function createResult(data, isError = false, suggestions) {
-    const text = isError
-        ? `${data}${''}`
-        : JSON.stringify(data, null, 2);
-    return {
-        content: [{ type: 'text', text }],
-        isError,
-    };
-}
-// LEGACY SUPPORT - Remove these once all tools are updated
-function createSuccessResult$1(data) {
-    return createResult(data, false);
-}
-function createErrorResult$1(message, error) {
-    return createResult(`${message}: ${error.message}`, true);
-}
-// ENHANCED PARSING UTILITY
-function parseJsonResponse(responseText, fallback = null) {
-    try {
-        const data = JSON.parse(responseText);
-        return { data, parsed: true };
-    }
-    catch {
-        return { data: (fallback || responseText), parsed: false };
-    }
-}
-/**
- * Determines if a string needs quoting for GitHub search
- */
-//TODO: move to util.ts
-function needsQuoting(str) {
-    return (str.includes(' ') ||
-        str.includes('"') ||
-        str.includes('\t') ||
-        str.includes('\n') ||
-        str.includes('\r') ||
-        /[<>(){}[\]\\|&;]/.test(str));
-}
-
 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());
@@ -105,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
@@ -124,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,
     };
 }
@@ -138,14 +69,16 @@ function isValidGhCommand(command) {
     return ALLOWED_GH_COMMANDS.includes(command);
 }
 /**
- * Get platform-specific shell configuration with PowerShell support
+ * Get platform-specific shell configuration with improved shell detection
  */
 function getShellConfig(preferredWindowsShell) {
     const isWindows = platform() === 'win32';
     if (!isWindows) {
+        // Use user's actual shell instead of hardcoded /bin/sh to avoid alias/function conflicts
+        const userShell = process.env.SHELL || '/bin/sh';
         return {
-            shell: '/bin/sh',
-            shellEnv: '/bin/sh',
+            shell: userShell,
+            shellEnv: userShell,
             type: 'unix',
         };
     }
@@ -165,15 +98,31 @@ function getShellConfig(preferredWindowsShell) {
     };
 }
 /**
- * Escape shell arguments to prevent shell injection and handle special characters
- * Cross-platform compatible escaping for Windows CMD, PowerShell, and Unix shells
+ * Escape shell arguments with improved GitHub CLI query handling
  */
-function escapeShellArg(arg, shellType) {
+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);
@@ -181,7 +130,7 @@ function escapeShellArg(arg, shellType) {
             return escapeWindowsCmdArg(arg);
         case 'unix':
         default:
-            return escapeUnixShellArg(arg);
+            return escapeUnixShellArg(arg, isGitHubQuery);
     }
 }
 /**
@@ -208,11 +157,20 @@ function escapeWindowsCmdArg(arg) {
     return arg;
 }
 /**
- * Escape arguments for Unix shells (/bin/sh, bash, etc.)
+ * Escape arguments for Unix shells with special handling for GitHub CLI queries
  */
-function escapeUnixShellArg(arg) {
-    // Unix shell escaping
-    if (/[^\w\-._/:=@]/.test(arg)) {
+function escapeUnixShellArg(arg, isGitHubQuery) {
+    // 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 (/[^a-zA-Z0-9\-_./=@:]/.test(arg)) {
         return `'${arg.replace(/'/g, "'\"'\"'")}'`;
     }
     return arg;
@@ -243,8 +201,7 @@ async function executeNpmCommand(command, args = [], options = {}) {
     return executeNpmCommand();
 }
 /**
- * Execute GitHub CLI commands safely by validating against allowed commands
- * Security: Only executes commands that start with "gh {ALLOWED_COMMAND}"
+ * Execute GitHub CLI commands safely with improved boolean query handling
  */
 async function executeGitHubCommand(command, args = [], options = {}) {
     // Security check: only allow registered commands
@@ -254,7 +211,22 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     // Get shell configuration
     const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    const escapedArgs = args.map(arg => escapeShellArg(arg, shellConfig.type));
+    // 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 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);
     if (options.cache) {
@@ -268,8 +240,7 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     return executeGhCommand();
 }
 /**
- * Execute shell commands with timeout and error handling
- * Security: Should only be called with pre-validated command prefixes
+ * Execute shell commands with improved environment handling and error detection
  */
 async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     try {
@@ -282,29 +253,50 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
             env: {
                 ...process.env,
                 ...options.env,
-                // Ensure clean shell environment - cross-platform compatible
+                // More conservative shell environment handling
                 SHELL: config.shellEnv,
                 PATH: process.env.PATH,
+                // Only disable problematic shell features, not all of them
+                ...(config.type === 'unix' && {
+                    // Only disable the most problematic shell configurations
+                    BASH_ENV: '', // Prevent auto-sourcing of problematic configs
+                }),
             },
             encoding: 'utf-8',
-            shell: config.shell, // Use platform-appropriate shell
+            shell: config.shell,
         };
         const { stdout, stderr } = await safeExecAsync(fullCommand, execOptions);
-        // Handle different warning patterns for npm vs gh
+        // Improved error detection that ignores shell configuration conflicts
         const shouldTreatAsError = type === 'npm'
-            ? stderr && !stderr.includes('npm WARN')
+            ? stderr &&
+                !stderr.includes('npm WARN') &&
+                !stderr.includes('npm notice')
             : stderr &&
                 !stderr.includes('Warning:') &&
                 !stderr.includes('notice:') &&
-                !stderr.includes('No such file or directory') && // Ignore shell-related errors
+                // Ignore shell configuration conflicts - common in development environments
+                !stderr.includes('No such file or directory') &&
+                !stderr.includes('head: illegal option') &&
+                !stderr.includes('head: |: No such file or directory') &&
+                !stderr.includes('head: cat: No such file or directory') &&
+                !/^head:\s+/.test(stderr) && // Ignore all head command errors (shell conflicts)
+                !/^\s*head:\s+/.test(stderr) && // Ignore head errors with leading whitespace
                 stderr.trim() !== '';
         if (shouldTreatAsError) {
             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(),
@@ -321,17 +313,303 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     }
 }
 
-const TOOL_NAME$9 = 'api_status_check';
-const DESCRIPTION$9 = `Gets the list of user github  organizations (in case the tool needs to use them in "owner" fields in github search) and checks users gh cli and npm cli login status.
-Use when user asks on specific implementaon in his organization (e.g. - I work at Wix, or search Wix code about X) or when cli is failing.`;
+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 } = options;
+    if (error) {
+        const errorMessage = typeof error === 'string'
+            ? error
+            : error.message || 'Unknown error';
+        const errorResponse = errorMessage;
+        return {
+            content: [{ type: 'text', text: errorResponse }],
+            isError: true,
+        };
+    }
+    try {
+        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
+ */
+function toDDMMYYYY(timestamp) {
+    const date = new Date(timestamp);
+    const day = date.getDate().toString().padStart(2, '0');
+    const month = (date.getMonth() + 1).toString().padStart(2, '0');
+    const year = date.getFullYear();
+    return `${day}/${month}/${year}`;
+}
+/**
+ * Convert repository URL to owner/repo format
+ */
+function simplifyRepoUrl(url) {
+    const match = url.match(/github\.com\/([^/]+\/[^/]+)/);
+    return match ? match[1] : url;
+}
+/**
+ * Extract first line of commit message
+ */
+function getCommitTitle(message) {
+    return message.split('\n')[0].trim();
+}
+/**
+ * Convert bytes to human readable format
+ */
+function humanizeBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${Math.round(bytes / Math.pow(k, i))} ${sizes[i]}`;
+}
+/**
+ * Simplify GitHub URL to relative path
+ */
+function simplifyGitHubUrl(url) {
+    const match = url.match(/github\.com\/[^/]+\/[^/]+\/(?:blob|commit)\/[^/]+\/(.+)$/);
+    return match ? match[1] : url;
+}
+/**
+ * Clean and optimize text match context
+ */
+function optimizeTextMatch(fragment, maxLength = 100) {
+    // Remove excessive whitespace and normalize
+    const cleaned = fragment.replace(/\s+/g, ' ').trim();
+    if (cleaned.length <= maxLength) {
+        return cleaned;
+    }
+    // Try to cut at word boundary
+    const truncated = cleaned.substring(0, maxLength);
+    const lastSpace = truncated.lastIndexOf(' ');
+    if (lastSpace > maxLength * 0.7) {
+        return truncated.substring(0, lastSpace) + '…';
+    }
+    return truncated + '…';
+}
+
+/**
+ * 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.tool(TOOL_NAME$9, DESCRIPTION$9, {}, {
-        title: 'Check API Connections and Github Organizations',
+    server.registerTool(API_STATUS_CHECK_TOOL_NAME, {
         description: DESCRIPTION$9,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: false,
+        inputSchema: {},
+        annotations: {
+            title: 'Check API Connections and Github Organizations',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
     }, async () => {
         try {
             let githubConnected = false;
@@ -342,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())
@@ -402,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) {
@@ -432,404 +689,277 @@ function registerApiStatusCheckTool(server) {
                 npmConnected = false;
             }
             return createResult({
-                github: {
-                    connected: githubConnected,
-                    organizations,
-                },
-                npm: {
-                    connected: npmConnected,
-                    registry,
+                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',
+                        ],
+                    },
                 },
             });
         }
         catch (error) {
-            return createResult('API status check failed - verify GitHub CLI and NPM are installed and accessible', true);
+            return createResult({
+                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 using strategic boolean operators and filters with "gh code search" command.
-
-SEARCH PATTERNS:
- OR (broad): "useState hook" → "useState OR hook" (auto-default for multi-word)
- AND (precise): "react AND hooks" (both terms required)
- NOT (filter): "auth NOT test" (exclude unwanted)
- Exact phrases: "useState hook" (quoted for literal match)
- Combine with filters: language, owner, path for laser focus
-
-RESTRICTIVENESS: OR (broadest) < AND < Exact Phrase (most precise)`;
-function registerGitHubSearchCodeTool(server) {
-    server.tool(TOOL_NAME$8, DESCRIPTION$8, {
-        query: z
-            .string()
-            .min(1)
-            .describe('Search query with strategic boolean operators. SEARCH PATTERNS: OR (auto-default): "useState hook" → "useState OR hook" for BROADEST discovery. AND (explicit): "react AND hooks" requires BOTH terms for RESTRICTIVE intersection. EXACT PHRASE (escaped quotes): "useState hook" finds literal sequence for MOST PRECISE targeting. NOT (filtering): "auth NOT test" excludes unwanted results. USAGE GUIDE: Use OR for exploration/alternatives, AND for specific combinations, exact phrases for documentation/APIs, NOT for removing noise. RESTRICTIVENESS: OR < AND < Exact Phrase. No parentheses - simple boolean logic only.'),
-        owner: z
-            .union([z.string(), z.array(z.string())])
-            .optional()
-            .describe('Repository owner/organization filter. Examples: "microsoft", "google". Combines with other filters for targeted search. get from user orgamizations in case of private repositories search (e.g. for employees of organizations)'),
-        repo: z
-            .union([z.string(), z.array(z.string())])
-            .optional()
-            .describe('Specific repositories in "owner/repo" format. Examples: "facebook/react", "microsoft/vscode". Requires owner parameter.'),
-        language: z
-            .string()
-            .optional()
-            .describe('Programming language filter. Examples: "javascript", "python", "typescript", "go". Highly effective for targeted searches.'),
-        extension: z
-            .string()
-            .optional()
-            .describe('File extension filter without dot. Examples: "js", "ts", "py", "md", "json". Precise file type targeting.'),
-        filename: z
-            .string()
-            .optional()
-            .describe('Exact filename filter. Examples: "package.json", "Dockerfile", "README.md", "index.js". Perfect for config files.'),
-        path: z
-            .string()
-            .optional()
-            .describe('Directory path filter. Examples: "src/", "test/", "docs/", "components/". Focus search on specific directories.'),
-        size: z
-            .string()
-            .optional()
-            .describe('File size filter in KB with operators (e.g., ">100", "<50", "10..100").'),
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .default(30)
-            .describe('Maximum results to return (1-50, default: 30).'),
-        match: z
-            .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
-            .optional()
-            .describe('Search scope: "file" searches code content, "path" searches filenames/paths. Use "path" to find files by name.'),
-        visibility: z
-            .enum(['public', 'private', 'internal'])
-            .optional()
-            .describe('Repository visibility filter: "public", "private", or "internal". Defaults to accessible repositories.'),
-    }, {
-        title: TOOL_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,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            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/org name (e.g., 'microsoft', 'google', NOT 'microsoft/vscode')`),
+            repo: z
+                .string()
+                .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('')
+                .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 Repository Explorer',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         try {
-            // Validate parameter combinations
-            const validationError = validateSearchParameters(args);
-            if (validationError) {
-                return createResult(validationError, true);
-            }
-            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 : [];
-            return createSuccessResult$1({
-                query: args.query,
-                processed_query: parseSearchQuery(args.query, args),
-                total_count: items.length,
-                items: items,
-                cli_command: execResult.command,
-                debug_info: {
-                    has_complex_boolean_logic: hasComplexBooleanLogic(args.query),
-                    escaped_args: buildGitHubCliArgs(args),
-                    original_query: args.query,
-                },
-            });
+            const result = await viewRepositoryStructure(args);
+            return result;
         }
         catch (error) {
-            const errorMessage = error.message || '';
-            // Handle JSON parsing errors
-            if (errorMessage.includes('JSON')) {
-                return createErrorResult$1('GitHub CLI returned invalid response - check if GitHub CLI is up to date with "gh version" and try again', error);
-            }
-            return createErrorResult$1('GitHub code search failed - verify parameters and try with simpler query or specific filters (language, owner, path)', error);
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            return createResult({
+                error: `Failed to explore repository. ${errorMessage}. Verify repository exists and is accessible`,
+            });
         }
     });
 }
 /**
- * Enhanced query parser that handles exact strings, boolean operators, and filters
- */
-function parseSearchQuery(query, filters) {
-    // Step 1: Handle quoted strings more intelligently
-    // Convert escaped quotes to simple quotes to avoid shell escaping issues
-    let processedQuery = query.replace(/\\"/g, '"');
-    // Step 2: Preserve exact phrases (quoted strings)
-    const exactPhrases = [];
-    // Extract quoted strings and replace with placeholders
-    const quotedMatches = processedQuery.match(/"[^"]+"/g) || [];
-    quotedMatches.forEach((match, index) => {
-        const placeholder = `__EXACT_PHRASE_${index}__`;
-        exactPhrases.push(match);
-        processedQuery = processedQuery.replace(match, placeholder);
-    });
-    // Step 3: Check complexity BEFORE adding auto-OR logic
-    const originalHasComplexLogic = hasComplexBooleanLogic(processedQuery);
-    // Step 4: Smart boolean logic - default to OR between terms if no explicit operators
-    let searchQuery = processedQuery;
-    // Check if query already has explicit boolean operators
-    if (!originalHasComplexLogic) {
-        // Split by whitespace and join with OR for better search results
-        const terms = processedQuery
-            .trim()
-            .split(/\s+/)
-            .filter(term => term.length > 0);
-        if (terms.length > 1) {
-            searchQuery = terms.join(' OR ');
-        }
-    }
-    // Step 5: Handle filters differently based on ORIGINAL query complexity
-    const githubFilters = [];
-    // Always add path and visibility to query string (they don't have CLI equivalents)
-    if (filters.path) {
-        githubFilters.push(`path:${filters.path}`);
-    }
-    if (filters.visibility) {
-        githubFilters.push(`visibility:${filters.visibility}`);
-    }
-    // For complex boolean queries, add ALL filters to query string to avoid CLI conflicts
-    if (originalHasComplexLogic) {
-        if (filters.language) {
-            githubFilters.push(`language:${filters.language}`);
-        }
-        // For complex queries with both language and extension, prioritize language
-        if (filters.extension && !filters.language) {
-            githubFilters.push(`extension:${filters.extension}`);
-        }
-        if (filters.filename) {
-            githubFilters.push(`filename:${filters.filename}`);
-        }
-        if (filters.size) {
-            githubFilters.push(`size:${filters.size}`);
-        }
-    }
-    // Step 6: Combine query with GitHub filters using proper spacing
-    if (githubFilters.length > 0) {
-        searchQuery = `${searchQuery} ${githubFilters.join(' ')}`;
-    }
-    // Step 7: Restore exact phrases
-    exactPhrases.forEach((phrase, index) => {
-        const placeholder = `__EXACT_PHRASE_${index}__`;
-        searchQuery = searchQuery.replace(placeholder, phrase);
-    });
-    return searchQuery.trim();
-}
-/**
- * Check if query contains complex boolean logic that might conflict with CLI flags
- */
-function hasComplexBooleanLogic(query) {
-    const booleanOperators = /\b(AND|OR|NOT)\b/i;
-    return booleanOperators.test(query);
-}
-/**
- * Build command line arguments for GitHub CLI with improved parameter handling
+ * Views the structure of a GitHub repository at a specific path.
+ * Optimized for code analysis workflows with smart defaults and clear errors.
  */
-function buildGitHubCliArgs(params) {
-    const args = ['code'];
-    // Parse and add the main search query
-    const searchQuery = parseSearchQuery(params.query, params);
-    args.push(searchQuery);
-    // Determine strategy based on ORIGINAL query complexity, not processed query
-    const hasComplexLogic = hasComplexBooleanLogic(params.query);
-    // For simple queries, use CLI flags for better performance and validation
-    if (!hasComplexLogic) {
-        if (params.language) {
-            args.push(`--language=${params.language}`);
-        }
-        if (params.extension) {
-            args.push(`--extension=${params.extension}`);
-        }
-        if (params.filename) {
-            args.push(`--filename=${params.filename}`);
-        }
-        if (params.size) {
-            args.push(`--size=${params.size}`);
-        }
-    }
-    // For complex queries, filters are already in the query string (handled by parseSearchQuery)
-    // Always add limit
-    if (params.limit) {
-        args.push(`--limit=${params.limit}`);
-    }
-    // Handle match parameter with conflict resolution
-    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.owner && params.repo) {
-        const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
-        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
-        // Create repo filters for each owner/repo combination
-        owners.forEach(owner => {
-            repos.forEach(repo => {
-                // Handle both "owner/repo" format and just "repo" format
-                if (repo.includes('/')) {
-                    args.push(`--repo=${repo}`);
+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 {
-                    args.push(`--repo=${owner}/${repo}`);
+                    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);
             });
-        });
-    }
-    // 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,
+            // 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,
+                    },
+                },
             });
-            return result;
         }
         catch (error) {
-            const errorMessage = error.message || '';
-            // Parse specific GitHub CLI error types
-            if (errorMessage.includes('authentication')) {
-                return createErrorResult$1('GitHub CLI authentication required - run the api_status_check tool to verify authentication and available organizations', error);
-            }
-            if (errorMessage.includes('rate limit')) {
-                return createErrorResult$1('GitHub API rate limit exceeded - wait a few minutes before searching again or use more specific filters to reduce results', error);
-            }
-            if (errorMessage.includes('validation failed') ||
-                errorMessage.includes('Invalid query')) {
-                return createErrorResult$1('Invalid search query syntax - check boolean operators (AND/OR/NOT), quotes for exact phrases, and filter formats. Try simplifying your query', error);
-            }
-            if (errorMessage.includes('repository not found') ||
-                errorMessage.includes('owner not found')) {
-                return createErrorResult$1('Repository or owner not found - run api_status_check tool to verify available organizations and access permissions', error);
-            }
-            if (errorMessage.includes('timeout')) {
-                return createErrorResult$1('Search timeout - query too broad or complex. Try adding filters like language, owner, or path to narrow results', error);
-            }
-            // Generic fallback with helpful guidance
-            return createErrorResult$1('GitHub code search failed - run api_status_check tool to verify authentication and permissions, or try simplifying your query', error);
+            return createResult({
+                error: `Failed to access repository. ${error}. Verify repository name and authentication`,
+            });
         }
     });
 }
 /**
- * Validate parameter combinations to prevent conflicts
+ * Smart branch detection with automatic fallback to common branch names.
  */
-function validateSearchParameters(params) {
-    // Query validation
-    if (!params.query.trim()) {
-        return 'Empty search query - provide a search term like "useState", "function init", or "api AND endpoint"';
-    }
-    if (params.query.length > 1000) {
-        return 'Search query too long - limit to 1000 characters. Try breaking into smaller, focused searches';
-    }
-    // Repository validation
-    if (params.repo && !params.owner) {
-        return 'Missing owner parameter - when searching specific repositories, format as owner/repo (e.g., "microsoft/vscode") or provide both owner and repo parameters';
-    }
-    // Invalid characters in query
-    if (params.query.includes('\\') && !params.query.includes('\\"')) {
-        return 'Invalid escape characters in query - use quotes for exact phrases: "exact phrase" instead of escaping';
-    }
-    // Boolean operator validation
-    const invalidBooleans = params.query.match(/\b(and|or|not)\b/g);
-    if (invalidBooleans) {
-        return `Boolean operators must be uppercase - use ${invalidBooleans.map(op => op.toUpperCase()).join(', ')} instead of ${invalidBooleans.join(', ')}`;
-    }
-    // Unmatched quotes
-    const quoteCount = (params.query.match(/"/g) || []).length;
-    if (quoteCount % 2 !== 0) {
-        return 'Unmatched quotes in query - ensure all quotes are properly paired for exact phrase matching';
+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 execResult = JSON.parse(repoInfoResult.content[0].text);
+            const repoData = execResult.result;
+            const defaultBranch = repoData.default_branch;
+            if (defaultBranch && !branches.includes(defaultBranch)) {
+                branches.push(defaultBranch);
+            }
+        }
     }
-    // Size parameter validation
-    if (params.size && !/^[<>]=?\d+$|^\d+\.\.\d+$|^\d+$/.test(params.size)) {
-        return 'Invalid size format - use ">100", "<50", "10..100", or "100" for file size filtering';
+    catch {
+        // If we can't get repo info, proceed with standard fallbacks
     }
-    return null; // No validation errors
+    // 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;
 }
 
-const TOOL_NAME$7 = 'github_get_file_content';
-const DESCRIPTION$7 = `Read file content. This tool REQUIRES exact path verification from github_get_contents or package view exports. If fetching fails, re-check file existence with github_get_contents or branch name.`;
+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.tool(TOOL_NAME$7, DESCRIPTION$7, {
-        owner: z
-            .string()
-            .min(1)
-            .max(100)
-            .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
-            .describe(`Repository owner/organization (e.g., 'microsoft', 'facebook')`),
-        repo: z
-            .string()
-            .min(1)
-            .max(100)
-            .regex(/^[a-zA-Z0-9._-]+$/)
-            .describe(`Repository name (e.g., 'vscode', 'react'). Case-sensitive.`),
-        branch: z
-            .string()
-            .min(1)
-            .max(255)
-            .regex(/^[^\s]+$/)
-            .describe(`Branch name (e.g., 'main', 'master'). Auto-fallback to common branches if not found.`),
-        filePath: z
-            .string()
-            .min(1)
-            .describe(`File path from repository root (e.g., 'README.md', 'src/index.js'). Use github_get_contents to explore structure.`),
-    }, {
-        title: TOOL_NAME$7,
+    server.registerTool(GITHUB_GET_FILE_CONTENT_TOOL_NAME, {
         description: DESCRIPTION$7,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            owner: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/)
+                .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 only (e.g., 'vscode', 'react', NOT 'microsoft/vscode')`),
+            branch: z
+                .string()
+                .min(1)
+                .max(255)
+                .regex(/^[^\s]+$/)
+                .describe(`Branch name. Falls back to main/master if not found`),
+            filePath: z
+                .string()
+                .min(1)
+                .describe(`Exact file path from repo root (e.g., src/index.js, README.md)`),
+        },
+        annotations: {
+            title: 'GitHub File Content - Direct Access',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         try {
             const result = await fetchGitHubFileContent(args);
-            if (result.content && result.content[0] && !result.isError) {
-                const { data, parsed } = parseJsonResponse(result.content[0].text);
-                if (parsed) {
-                    return createResult({
-                        file: `${args.owner}/${args.repo}/${args.filePath}`,
-                        content: data.content || data,
-                        metadata: {
-                            branch: args.branch,
-                            size: data.size,
-                            encoding: data.encoding,
-                        },
-                    });
-                }
-                else {
-                    // Return raw file content
-                    return createResult({
-                        file: `${args.owner}/${args.repo}/${args.filePath}`,
-                        content: data,
-                        metadata: {
-                            branch: args.branch,
-                        },
-                    });
-                }
-            }
             return result;
         }
         catch (error) {
-            return createResult('File fetch failed - verify file path exists or try github_get_contents first', true);
+            return createResult({
+                error: 'Failed to fetch file. Verify path with github_get_contents first',
+            });
         }
     });
 }
@@ -862,20 +992,25 @@ async function fetchGitHubFileContent(params) {
                 }
                 // Handle common errors
                 if (errorMsg.includes('404')) {
-                    return createErrorResult$1('File not found - verify path with github_get_contents first', new Error(filePath));
+                    return createResult({
+                        error: 'File not found. Use github_view_repo_structure to explore repository structure',
+                    });
                 }
                 else if (errorMsg.includes('403')) {
-                    return createErrorResult$1('Access denied - repository may be private or require authentication', new Error(`${owner}/${repo}`));
+                    return createResult({
+                        error: 'Access denied. Repository may be private - use apiStatusCheck to verify',
+                    });
                 }
                 else if (errorMsg.includes('maxBuffer') ||
                     errorMsg.includes('stdout maxBuffer length exceeded')) {
-                    return createErrorResult$1(` File too large to fetch (buffer limit exceeded)\n\n` +
-                        `This usually happens with files >300KB. Consider:\n` +
-                        `    Use github_search_code to find specific patterns\n` +
-                        `    Browse directory structure with github_get_contents`, new Error(`Buffer overflow: ${filePath}`));
+                    return createResult({
+                        error: 'File too large (>300KB). Use githubSearchCode to search for patterns within the file',
+                    });
                 }
                 else {
-                    return createErrorResult$1('Fetch failed - check repository and file path', new Error(errorMsg));
+                    return createResult({
+                        error: 'Failed to fetch file. Verify repository name and file path',
+                    });
                 }
             }
             return await processFileContent(result, owner, repo, branch, filePath);
@@ -885,738 +1020,1045 @@ async function fetchGitHubFileContent(params) {
             // Handle maxBuffer errors that escape the main try-catch
             if (errorMessage.includes('maxBuffer') ||
                 errorMessage.includes('stdout maxBuffer length exceeded')) {
-                return createErrorResult$1(` File too large to fetch (buffer limit exceeded)\n\n` +
-                    `This usually happens with files >300KB. Consider:\n` +
-                    `    Use github_search_code to find specific patterns instead of fetching the whole file\n` +
-                    `    Browse directory structure with github_get_contents`, error);
+                return createResult({
+                    error: 'File too large (>300KB). Use github_search_code to search for patterns within the file',
+                });
             }
-            return createErrorResult$1('Unexpected error during file fetch - check connection and permissions', error);
+            return createResult({
+                error: 'Unexpected error. Check network connection and try again',
+            });
         }
     });
 }
 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 createErrorResult$1('Path is directory - use github_get_contents to browse directory structure', new Error(filePath));
+        return createResult({
+            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 createErrorResult$1(` File too large to display (${fileSizeKB}KB > ${maxSizeKB}KB limit)\n\n` +
-            `For large files like this, consider:\n` +
-            `    Use github_get_contents to browse directory structure\n` +
-            `    Search specific code patterns with github_search_code`, new Error(`File: ${filePath} (${fileSizeKB}KB)`));
+        return createResult({
+            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 createErrorResult$1('Empty file - file has no content to display', new Error(filePath));
+        return createResult({
+            error: 'File is empty - no content to display',
+        });
     }
     let decodedContent;
     try {
         const buffer = Buffer.from(base64Content, 'base64');
         // Simple binary check - look for null bytes
         if (buffer.indexOf(0) !== -1) {
-            return createErrorResult$1('Binary file detected - cannot display binary content as text', new Error(filePath));
+            return createResult({
+                error: 'Binary file detected. Cannot display as text - download directly from GitHub',
+            });
         }
         decodedContent = buffer.toString('utf-8');
     }
     catch (decodeError) {
-        return createErrorResult$1('Decode failed - file encoding not supported or corrupted', new Error(filePath));
-    }
-    // Return simplified response
-    const response = {
-        filePath,
-        owner,
-        repo,
-        branch,
-        content: decodedContent,
-        metadata: {
-            size: fileSize,
-            lines: decodedContent.split('\n').length,
-            encoding: 'utf-8',
+        return createResult({
+            error: 'Failed to decode file. Encoding may not be supported (expected UTF-8)',
+        });
+    }
+    return createResult({
+        data: {
+            filePath,
+            owner,
+            repo,
+            branch,
+            content: decodedContent,
         },
-    };
-    return createSuccessResult$1(response);
+    });
 }
 
-const TOOL_NAME$6 = 'github_search_repositories';
-const DESCRIPTION$6 = `Search repositories by name/description. Start shallow and go broad: use topics for exploratory discovery (e.g., topic:["cli","typescript","api"]) to find ecosystem patterns.
-  PRIMARY FILTERS work alone: owner, language, stars, topic, forks. SECONDARY FILTERS require a query or primary filter: license, created, archived, includeForks, updated, visibility, match.
-  SMART REPOS SEARCH PATTERNS: Use topic:["cli","typescript"] for semantic discovery; stars:">100" for quality; owner:"microsoft" for organization repos. Query supports GitHub syntax: "language:Go OR language:Rust".
-  
-  EFFICIENCY NOTE: If you have a package name, use npm_view_package FIRST to get repositoryGitUrl - this tool becomes UNNECESSARY
-  
-  SMART INTEGRATION: When finding packages → npm_view_package + npm_package_search provide direct repo access
-  AVOID: Searching for "react" repos when npm_view_package("react") gives you the exact repository instantly`;
-function registerSearchGitHubReposTool(server) {
-    server.tool(TOOL_NAME$6, DESCRIPTION$6, {
-        query: z
-            .string()
-            .optional()
-            .describe('Search query with GitHub syntax: "cli shell" (AND), "vim plugin" (phrase), "language:Go OR language:Rust" (OR). Optional - can search with just primary filters.'),
-        // PRIMARY FILTERS (can work alone)
-        owner: z
-            .string()
-            .optional()
-            .describe('Repository owner/organization (e.g., "microsoft", "facebook").'),
-        language: z
-            .string()
-            .optional()
-            .describe('Programming language (e.g., "javascript", "python", "go").'),
-        stars: z
-            .string()
-            .optional()
-            .describe('Stars count with ranges: "100", ">500", "<50", "10..100", ">=1000". Use >100 for quality projects.'),
-        topic: z
-            .array(z.string())
-            .optional()
-            .describe('Filter by topics (e.g., ["cli", "typescript", "api"]).'),
-        forks: z.number().optional().describe('Exact forks count.'),
-        numberOfTopics: z
-            .number()
-            .optional()
-            .describe('Filter on number of topics.'),
-        // SECONDARY FILTERS (require query or primary filter)
-        license: z
-            .array(z.string())
-            .optional()
-            .describe('License types (e.g., ["mit", "apache-2.0"]).'),
-        match: z
-            .enum(['name', 'description', 'readme'])
-            .optional()
-            .describe('Search scope: "name", "description", or "readme".'),
-        visibility: z
-            .enum(['public', 'private', 'internal'])
-            .optional()
-            .describe('Repository visibility filter.'),
-        created: z
-            .string()
-            .optional()
-            .describe('Created date filter: ">2020-01-01", "<2023-12-31", "2022-01-01..2023-12-31".'),
-        updated: z
-            .string()
-            .optional()
-            .describe('Updated date filter (same format as created).'),
-        archived: z.boolean().optional().describe('Filter by archived state.'),
-        includeForks: z
-            .enum(['false', 'true', 'only'])
-            .optional()
-            .describe('Include forks: "false" (default), "true", or "only".'),
-        goodFirstIssues: z
-            .string()
-            .optional()
-            .describe('Filter by good first issues count (e.g., ">=10", ">5").'),
-        helpWantedIssues: z
-            .string()
-            .optional()
-            .describe('Filter by help wanted issues count (e.g., ">=5", ">10").'),
-        followers: z
-            .number()
-            .optional()
-            .describe('Filter by number of followers.'),
-        size: z
-            .string()
-            .optional()
-            .describe('Repository size filter in KB (e.g., ">100", "<50", "10..100").'),
-        // Sorting and limits
-        sort: z
-            .enum(['forks', 'help-wanted-issues', 'stars', 'updated', 'best-match'])
-            .optional()
-            .default('best-match')
-            .describe('Sort criteria (default: best-match)'),
-        order: z
-            .enum(['asc', 'desc'])
-            .optional()
-            .default('desc')
-            .describe('Result order (default: desc)'),
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .default(25)
-            .describe('Maximum results (default: 25, max: 50)'),
-    }, {
-        title: 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,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            query: z
+                .string()
+                .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('Language filter (javascript, python, etc). Use only when needed.'),
+            owner: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .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('Specific filename to search. Use for targeted searches.'),
+            extension: z
+                .string()
+                .optional()
+                .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('Search scope: "file" for content, "path" for filenames. Default: file content.'),
+            size: z
+                .string()
+                .optional()
+                .describe('File size in KB. Format: >10, <100, or 10..50'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(30)
+                .describe('Results limit (1-100). Default: 30'),
+        },
+        annotations: {
+            title: 'GitHub Code Search - Smart & Efficient',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         try {
-            // Updated validation logic for primary filters
-            const hasPrimaryFilter = args.query?.trim() ||
-                args.owner ||
-                args.language ||
-                args.topic ||
-                args.stars ||
-                args.forks;
-            if (!hasPrimaryFilter) {
-                return createResult('Requires query or primary filter (owner, language, stars, topic, forks)', true);
+            // Validate parameter combinations
+            const validationError = validateSearchParameters(args);
+            if (validationError) {
+                return createResult({ error: validationError });
             }
-            // Search repositories using GitHub CLI
-            const result = await searchGitHubRepos(args);
-            return result;
-        }
-        catch (error) {
-            return createResult('Repository search failed - check query syntax, filters, or try broader terms', true);
-        }
-    });
-}
-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,
-            });
+            const result = await searchGitHubCode(args);
             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++;
-                        }
-                    }
+            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,
+                    }),
                 });
-                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: repo.createdAt,
-                    updatedAt: repo.updatedAt,
-                    visibility: repo.visibility || 'public',
-                    owner: repo.owner?.login || repo.owner,
-                }));
             }
-            return createSuccessResult$1({
-                query: params.query,
-                total: analysis.totalFound,
-                ...(analysis.totalFound > 0
-                    ? {
-                        repositories: analysis.topStarred,
-                        summary: {
-                            languages: Array.from(analysis.languages).slice(0, 10),
-                            avgStars: analysis.avgStars,
-                            recentlyUpdated: analysis.recentlyUpdated,
-                        },
-                    }
-                    : {
-                        repositories: [],
-                    }),
-            });
+            // Transform to optimized format
+            const optimizedResult = transformToOptimizedFormat$1(items);
+            return createResult({ data: optimizedResult });
         }
         catch (error) {
-            return createErrorResult$1('GitHub repository search failed - verify connection or try simpler query', error);
+            const errorMessage = error.message || '';
+            return handleSearchError(errorMessage);
         }
     });
 }
-function buildGitHubReposSearchCommand(params) {
-    // Build query following GitHub CLI patterns
-    const query = params.query?.trim() || '';
-    const args = ['repos'];
-    // Only add query if it exists and handle it properly
-    if (query) {
-        // For repository search, treat multi-word queries as a single quoted string
-        // This matches GitHub CLI expected behavior for repo searches
-        if (query.includes(' ')) {
-            args.push(query); // Let GitHub CLI handle the quoting
+/**
+ * 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 {
-            args.push(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');
-    // PRIMARY FILTERS - Handle owner as single string (BaseSearchParams) or array
-    if (params.owner) {
-        const ownerValue = Array.isArray(params.owner)
-            ? params.owner.join(',')
-            : params.owner;
-        args.push(`--owner=${ownerValue}`);
-    }
-    if (params.language)
-        args.push(`--language=${params.language}`);
-    if (params.forks !== undefined)
-        args.push(`--forks=${params.forks}`);
-    if (params.topic && params.topic.length > 0)
-        args.push(`--topic=${params.topic.join(',')}`);
-    if (params.numberOfTopics !== undefined)
-        args.push(`--number-topics=${params.numberOfTopics}`);
-    // Only add stars filter if it's a valid numeric value or range
-    if (params.stars !== undefined &&
-        params.stars !== '*' &&
-        params.stars.trim() !== '') {
-        // Validate that stars parameter contains valid numeric patterns
-        const starsValue = params.stars.trim();
-        const isValidStars = /^(\d+|>\d+|<\d+|\d+\.\.\d+|>=\d+|<=\d+)$/.test(starsValue);
-        if (isValidStars) {
-            // Don't add quotes around the stars value - GitHub CLI handles this internally
-            args.push(`--stars=${starsValue}`);
-        }
-    }
-    // SECONDARY FILTERS - only add if we have primary filters
-    if (params.archived !== undefined)
-        args.push(`--archived=${params.archived}`);
-    if (params.created)
-        args.push(`--created=${params.created}`);
-    if (params.includeForks)
-        args.push(`--include-forks=${params.includeForks}`);
-    if (params.license && params.license.length > 0)
-        args.push(`--license=${params.license.join(',')}`);
-    if (params.match)
-        args.push(`--match=${params.match}`);
-    if (params.updated)
-        args.push(`--updated=${params.updated}`);
-    if (params.visibility)
-        args.push(`--visibility=${params.visibility}`);
-    if (params.goodFirstIssues)
-        args.push(`--good-first-issues=${params.goodFirstIssues}`);
-    if (params.helpWantedIssues)
-        args.push(`--help-wanted-issues=${params.helpWantedIssues}`);
-    if (params.followers !== undefined)
-        args.push(`--followers=${params.followers}`);
-    if (params.size)
-        args.push(`--size=${params.size}`);
-    // SORTING AND LIMITS
-    if (params.limit)
+            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}`);
-    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}`);
     }
-    return { command: 'search', args };
+    // Add JSON output format
+    args.push('--json=repository,path,textMatches,sha,url');
+    return args;
 }
-
-const TOOL_NAME$5 = 'github_search_commits';
-const DESCRIPTION$5 = `Search commit history with powerful boolean logic and exact phrase matching. Use advanced GitHub search syntax including AND/OR operators for precise commit discovery. Understand code evolution patterns, track bug fixes, and analyze development workflows over time. Filter by author, date ranges, commit content, and repository metadata with surgical precision.`;
-function registerSearchGitHubCommitsTool(server) {
-    server.tool(TOOL_NAME$5, DESCRIPTION$5, {
-        query: z
-            .string()
-            .optional()
-            .describe('Search query with POWERFUL boolean logic and exact phrase matching. BOOLEAN OPERATORS: "fix AND bug" (both required), "fix OR update" (either term), "readme typo" (implicit AND). EXACT PHRASES: "initial commit" (precise phrase matching). ADVANCED SYNTAX: "author:john OR committer:jane" (user qualifiers), "-- -author:botuser" (exclusions). STRENGTH: Surgical precision for commit discovery across millions of repositories. Optional - can search with just filters.'),
-        // Basic filters
-        owner: z
-            .string()
-            .optional()
-            .describe('Repository owner/organization. Leave empty for global search.'),
-        repo: z
-            .string()
-            .optional()
-            .describe('Repository name. Do exploratory search without repo filter first'),
-        // Author filters
-        author: z.string().optional().describe('Filter by commit author'),
-        authorDate: z
-            .string()
-            .optional()
-            .describe('Filter by authored date (format: >2020-01-01, <2023-12-31)'),
-        authorEmail: z.string().optional().describe('Filter by author email'),
-        authorName: z.string().optional().describe('Filter by author name'),
-        // Committer filters
-        committer: z.string().optional().describe('Filter by committer'),
-        committerDate: z
-            .string()
-            .optional()
-            .describe('Filter by committed date (format: >2020-01-01, <2023-12-31)'),
-        committerEmail: z
-            .string()
-            .optional()
-            .describe('Filter by committer email'),
-        committerName: z.string().optional().describe('Filter by committer name'),
-        // 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'),
-        // Boolean filters
-        merge: z.boolean().optional().describe('Filter merge commits'),
-        visibility: z
-            .enum(['public', 'private', 'internal'])
-            .optional()
-            .describe('Filter by repository visibility'),
-        // Sorting and limits
-        sort: z
-            .enum(['author-date', 'committer-date', 'best-match'])
-            .optional()
-            .default('best-match')
-            .describe('Sort criteria (default: best-match)'),
-        order: z
-            .enum(['asc', 'desc'])
-            .optional()
-            .default('desc')
-            .describe('Order (default: desc)'),
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .default(25)
-            .describe('Maximum results (default: 25, max: 50)'),
-    }, {
-        title: TOOL_NAME$5,
-        description: DESCRIPTION$5,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    }, async (args) => {
+async function searchGitHubCode(params) {
+    const cacheKey = generateCacheKey('gh-code', params);
+    return withCache(cacheKey, async () => {
         try {
-            // Query is optional - can search with just filters
-            if (!args.query?.trim() &&
-                !args.owner &&
-                !args.author &&
-                !args.committer &&
-                !args.repo) {
-                return createResult('Either query or at least one filter is required', true);
-            }
-            const result = await searchGitHubCommits(args);
+            const args = buildGitHubCliArgs(params);
+            const result = await executeGitHubCommand('search', args, {
+                cache: false,
+            });
             return result;
         }
         catch (error) {
-            return createResult('Commit search failed - check query syntax, filters, or repository access', true);
+            const errorMessage = error.message || '';
+            return handleSearchError(errorMessage); // Delegating error handling
         }
     });
 }
-async function searchGitHubCommits(params) {
-    const cacheKey = generateCacheKey('gh-commits', params);
-    return withCache(cacheKey, async () => {
+/**
+ * Enhanced validation with helpful suggestions
+ */
+function validateSearchParameters(params) {
+    // Query validation
+    if (!params.query.trim()) {
+        return ERROR_MESSAGES.EMPTY_QUERY;
+    }
+    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.';
+        }
+    }
+    // Add validation for file size limit
+    if (params.size) {
+        if (!/^([<>]\d+|\d+\.\.\d+)$/.test(params.size)) {
+            return ERROR_MESSAGES.INVALID_SIZE_FORMAT;
+        }
+    }
+    // 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;
+        }
+    }
+    // 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 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(GITHUB_SEARCH_COMMITS_TOOL_NAME, {
+        description: DESCRIPTION$5,
+        inputSchema: {
+            query: z
+                .string()
+                .optional()
+                .describe('Search terms. Start simple: "bug fix", "refactor". Use quotes for exact phrases.'),
+            // Repository filters
+            owner: z
+                .string()
+                .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()
+                .optional()
+                .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('GitHub username of commit author'),
+            authorName: z
+                .string()
+                .optional()
+                .describe('Full name of commit author'),
+            authorEmail: z.string().optional().describe('Email of commit author'),
+            // Committer filters
+            committer: z
+                .string()
+                .optional()
+                .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('When authored. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
+            committerDate: z
+                .string()
+                .optional()
+                .describe('When committed. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
+            // Hash filters
+            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('Only merge commits (true) or exclude them (false)'),
+            // Visibility
+            visibility: z
+                .enum(['public', 'private', 'internal'])
+                .optional()
+                .describe('Repository visibility filter'),
+            // Pagination and sorting
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(25)
+                .describe('Results limit (1-50). Default: 25'),
+            sort: z
+                .enum(['author-date', 'committer-date'])
+                .optional()
+                .describe('Sort by date. Default: best match'),
+            order: z
+                .enum(['asc', 'desc'])
+                .optional()
+                .default('desc')
+                .describe('Sort order. Default: desc'),
+        },
+        annotations: {
+            title: 'GitHub Commit Search - Smart History Analysis',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
         try {
-            const { command, args } = buildGitHubCommitsSearchCommand(params);
-            const result = await executeGitHubCommand(command, args, {
-                cache: false,
-            });
+            const result = await searchGitHubCommits(args);
             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 commits = [];
-            const analysis = {
-                totalFound: 0,
-                recentCommits: 0,
-                topAuthors: [],
-                repositories: new Set(),
-            };
-            // Parse JSON response from GitHub CLI
-            commits = JSON.parse(rawContent);
-            if (Array.isArray(commits) && commits.length > 0) {
-                analysis.totalFound = commits.length;
-                // Simple analysis
-                const now = new Date();
-                const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
-                const authorCounts = {};
-                commits.forEach(commit => {
-                    // Count recent commits
-                    const commitDate = commit.commit?.author?.date || commit.commit?.committer?.date;
-                    if (commitDate && new Date(commitDate) > thirtyDaysAgo) {
-                        analysis.recentCommits++;
-                    }
-                    // Count authors
-                    const authorName = commit.commit?.author?.name || commit.author?.login || 'Unknown';
-                    authorCounts[authorName] = (authorCounts[authorName] || 0) + 1;
-                    // Track repositories
-                    if (commit.repository?.fullName) {
-                        analysis.repositories.add(commit.repository.fullName);
-                    }
-                });
-                // Get top authors
-                analysis.topAuthors = Object.entries(authorCounts)
-                    .sort(([, a], [, b]) => b - a)
-                    .slice(0, 5)
-                    .map(([name, count]) => ({ name, commits: count }));
-                // Format commits for output
-                const formattedCommits = commits.map(commit => ({
-                    sha: commit.sha,
-                    message: commit.commit?.message || '',
-                    author: {
-                        name: commit.commit?.author?.name,
-                        email: commit.commit?.author?.email,
-                        date: commit.commit?.author?.date,
-                        login: commit.author?.login,
-                    },
-                    committer: {
-                        name: commit.commit?.committer?.name,
-                        email: commit.commit?.committer?.email,
-                        date: commit.commit?.committer?.date,
-                        login: commit.committer?.login,
-                    },
-                    repository: commit.repository
-                        ? {
-                            name: commit.repository.name,
-                            fullName: commit.repository.fullName,
-                            url: commit.repository.url,
-                            description: commit.repository.description,
-                        }
-                        : null,
-                    url: commit.url,
-                    parents: commit.parents?.map((p) => p.sha) || [],
-                }));
-                return createSuccessResult$1({
-                    query: params.query,
-                    total: analysis.totalFound,
-                    commits: formattedCommits,
-                    summary: {
-                        recentCommits: analysis.recentCommits,
-                        topAuthors: analysis.topAuthors,
-                        repositories: Array.from(analysis.repositories),
-                    },
+            const commits = execResult.result;
+            // GitHub CLI returns a direct array
+            const items = Array.isArray(commits) ? commits : [];
+            // Smart handling for no results - provide actionable suggestions
+            if (items.length === 0) {
+                return createResult({
+                    error: createNoResultsError('commits'),
                 });
             }
-            return createSuccessResult$1({
-                query: params.query,
-                total: 0,
-                commits: [],
-            });
+            // Transform to optimized format
+            const optimizedResult = transformCommitsToOptimizedFormat(items, args);
+            return createResult({ data: optimizedResult });
         }
         catch (error) {
-            return createErrorResult$1('GitHub commit search failed - verify repository exists or try different filters', error);
+            const errorMessage = error.message || '';
+            if (errorMessage.includes('authentication')) {
+                return createResult({
+                    error: createAuthenticationError(),
+                });
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createResult({
+                    error: createRateLimitError(false),
+                });
+            }
+            return createResult({
+                error: createSearchFailedError('commits'),
+            });
         }
     });
 }
-function buildGitHubCommitsSearchCommand(params) {
-    // Build query following GitHub CLI patterns
-    const query = params.query?.trim() || '';
-    // Handle complex queries (with qualifiers, operators, or --) differently
-    const hasComplexSyntax = query.includes('--') ||
-        query.includes(':') ||
-        query.includes('OR') ||
-        query.includes('AND') ||
-        query.includes('(') ||
-        query.includes(')') ||
-        query.startsWith('-');
-    const args = ['commits'];
-    // Only add query if it exists
-    if (query) {
-        if (hasComplexSyntax) {
-            // For complex queries with special syntax, handle carefully
-            const queryParts = query.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
-            queryParts.forEach(part => {
-                // If part contains shell special characters, quote it
-                if (/[><=&|$`(){}[\];\\]/.test(part) && !part.includes('"')) {
-                    args.push(`"${part}"`);
-                }
-                else {
-                    args.push(part);
-                }
-            });
-        }
-        else {
-            // For simple queries, use quoting logic
-            const queryString = needsQuoting(query) ? `"${query}"` : query;
-            args.push(queryString);
-        }
-    }
-    // Add JSON output with commit fields
-    args.push('--json', 'author,commit,committer,id,parents,repository,sha,url');
-    // Add all filters
-    if (params.author)
-        args.push(`--author=${params.author}`);
-    if (params.authorDate)
-        args.push(`--author-date="${params.authorDate}"`);
+/**
+ * Transform GitHub CLI response to optimized format
+ */
+function transformCommitsToOptimizedFormat(items, _params) {
+    // Extract repository info if single repo search
+    const singleRepo = extractSingleRepository(items);
+    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 ?? ''),
+        repository: singleRepo
+            ? undefined
+            : simplifyRepoUrl(item.repository?.url || ''),
+        url: singleRepo
+            ? item.sha
+            : `${simplifyRepoUrl(item.repository?.url || '')}@${item.sha}`,
+    }))
+        .map(commit => {
+        // Remove undefined fields
+        const cleanCommit = {};
+        Object.entries(commit).forEach(([key, value]) => {
+            if (value !== undefined) {
+                cleanCommit[key] = value;
+            }
+        });
+        return cleanCommit;
+    });
+    const result = {
+        commits: optimizedCommits,
+        total_count: items.length,
+    };
+    // Add repository info if single repo
+    if (singleRepo) {
+        result.repository = {
+            name: singleRepo.fullName,
+            description: singleRepo.description,
+        };
+    }
+    return result;
+}
+/**
+ * Extract single repository if all results are from same repo
+ */
+function extractSingleRepository(items) {
+    if (items.length === 0)
+        return null;
+    const firstRepo = items[0].repository;
+    const allSameRepo = items.every(item => item.repository.fullName === firstRepo.fullName);
+    return allSameRepo ? firstRepo : null;
+}
+async function searchGitHubCommits(params) {
+    const cacheKey = generateCacheKey('gh-commits', params);
+    return withCache(cacheKey, async () => {
+        try {
+            const args = buildGitHubCommitCliArgs(params);
+            const result = await executeGitHubCommand('search', args, {
+                cache: false,
+            });
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error.message || '';
+            if (errorMessage.includes('authentication')) {
+                return createResult({
+                    error: createAuthenticationError(),
+                });
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createResult({
+                    error: createRateLimitError(false),
+                });
+            }
+            return createResult({
+                error: createSearchFailedError('commits'),
+            });
+        }
+    });
+}
+function buildGitHubCommitCliArgs(params) {
+    const args = ['commits'];
+    // Add query if provided - simplified approach for better results
+    if (params.query) {
+        // Simple, direct query handling - GitHub commit search works better with straightforward queries
+        args.push(params.query.trim());
+    }
+    // Repository filters
+    if (params.owner && params.repo) {
+        args.push(`--repo=${params.owner}/${params.repo}`);
+    }
+    else if (params.owner) {
+        args.push(`--owner=${params.owner}`);
+    }
+    // Author filters
+    if (params.author)
+        args.push(`--author=${params.author}`);
+    if (params.authorName)
+        args.push(`--author-name=${params.authorName}`);
     if (params.authorEmail)
         args.push(`--author-email=${params.authorEmail}`);
-    if (params.authorName)
-        args.push(`--author-name="${params.authorName}"`);
+    // Committer filters
     if (params.committer)
         args.push(`--committer=${params.committer}`);
-    if (params.committerDate)
-        args.push(`--committer-date="${params.committerDate}"`);
+    if (params.committerName)
+        args.push(`--committer-name=${params.committerName}`);
     if (params.committerEmail)
         args.push(`--committer-email=${params.committerEmail}`);
-    if (params.committerName)
-        args.push(`--committer-name="${params.committerName}"`);
+    // Date filters
+    if (params.authorDate)
+        args.push(`--author-date=${params.authorDate}`);
+    if (params.committerDate)
+        args.push(`--committer-date=${params.committerDate}`);
+    // Hash filters
     if (params.hash)
         args.push(`--hash=${params.hash}`);
     if (params.parent)
         args.push(`--parent=${params.parent}`);
     if (params.tree)
         args.push(`--tree=${params.tree}`);
-    if (params.merge)
-        args.push('--merge');
+    // State filters
+    if (params.merge !== undefined)
+        args.push(`--merge=${params.merge}`);
+    // Visibility
     if (params.visibility)
         args.push(`--visibility=${params.visibility}`);
-    // Handle repo and owner
-    if (params.repo && params.owner) {
-        args.push(`--repo=${params.owner}/${params.repo}`);
+    // Sorting and pagination
+    if (params.sort)
+        args.push(`--sort=${params.sort}`);
+    if (params.order)
+        args.push(`--order=${params.order}`);
+    if (params.limit)
+        args.push(`--limit=${params.limit}`);
+    // JSON output
+    args.push('--json=sha,commit,author,committer,repository,url,parents');
+    return args;
+}
+
+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 terms. Start simple: "error", "crash". Use quotes for exact phrases.'),
+            owner: z
+                .string()
+                .min(1)
+                .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()
+                .optional()
+                .describe('Repository name only (e.g., "vscode", "react", NOT "owner/repo"). Must be used together with owner parameter.'),
+            app: z
+                .string()
+                .optional()
+                .describe('GitHub App that created the issue'),
+            archived: z
+                .boolean()
+                .optional()
+                .describe('Include archived repositories'),
+            assignee: z.string().optional().describe('GitHub username of assignee'),
+            author: z
+                .string()
+                .optional()
+                .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()
+                .optional()
+                .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-heart',
+                'reactions-smile',
+                'reactions-tada',
+                'reactions-thinking_face',
+                'updated',
+                'best-match',
+            ])
+                .optional()
+                .describe('Sort by activity or reactions. Default: best match'),
+            order: z
+                .enum(['asc', 'desc'])
+                .optional()
+                .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 Issues Search - Bug & Feature Discovery',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args) => {
+        if (!args.query?.trim()) {
+            return createResult({
+                error: `${ERROR_MESSAGES.QUERY_REQUIRED} ${SUGGESTIONS.PROVIDE_KEYWORDS}`,
+            });
+        }
+        if (args.query.length > 256) {
+            return createResult({
+                error: ERROR_MESSAGES.QUERY_TOO_LONG,
+            });
+        }
+        try {
+            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: createSearchFailedError('issues'),
+            });
+        }
+    });
+}
+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;
+        }
+        const execResult = JSON.parse(result.content[0].text);
+        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: cleanIssues,
+        };
+        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();
+    });
+    // Add the cleaned query if it has content
+    if (cleanQuery) {
+        queryParts.push(cleanQuery);
     }
-    else if (params.repo) {
-        args.push(`--repo=${params.repo}`);
+    // Repository/organization qualifiers - prioritize function params over query
+    if (params.owner && params.repo) {
+        queryParts.push(`repo:${params.owner}/${params.repo}`);
     }
     else if (params.owner) {
-        args.push(`--owner=${params.owner}`);
+        queryParts.push(`org:${params.owner}`);
     }
-    // Sorting
-    const sortBy = params.sort || 'best-match';
-    if (sortBy !== 'best-match') {
-        args.push(`--sort=${sortBy}`);
+    // 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,
+    };
+    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()}`);
+        }
+    }
+    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}"`);
+        }
     }
+    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)
-        args.push(`--order=${params.order}`);
-    // Limit
-    if (params.limit)
-        args.push(`--limit=${params.limit}`);
-    return { command: 'search', args };
+        apiPath += `&order=${params.order}`;
+    return { command: 'api', args: [apiPath] };
 }
 
 // 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.
-
-SEARCH PATTERNS:
- Boolean: "fix AND bug", "refactor OR cleanup", "feature NOT draft"
- Exact phrases: "initial commit" (quoted)
- GitHub qualifiers: "is:merged review:approved base:main"
- Combine with filters for targeted PR discovery`;
+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.tool(TOOL_NAME$4, DESCRIPTION$4, {
-        query: z
-            .string()
-            .min(1, 'Search query is required and cannot be empty')
-            .describe('Search query with GITHUB SEARCH SYNTAX support. BOOLEAN OPERATORS: "fix AND bug" (both required), "refactor OR cleanup" (either term), "feature NOT draft" (excludes). EXACT PHRASES: "initial commit" (precise matching). GITHUB QUALIFIERS: "is:merged review:approved base:main" (native GitHub syntax). COMBINED: Mix boolean logic with qualifiers for precise PR discovery.'),
-        owner: z.string().optional().describe('Repository owner/organization'),
-        repo: z.string().optional().describe('Repository name'),
-        author: z.string().optional().describe('Filter by pull request author'),
-        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.string().optional().describe('Filter by user who reviewed'),
-        reviewRequested: z
-            .string()
-            .optional()
-            .describe('Filter by user or team requested to review'),
-        state: z.enum(['open', 'closed']).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 (e.g., '>2022-01-01')"),
-        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'])
-            .optional()
-            .describe('Filter based on status of the checks'),
-        merged: z.boolean().optional().describe('Filter based on merged state'),
-        review: z
-            .enum(['none', 'required', 'approved', 'changes_requested'])
-            .optional()
-            .describe('Filter based on review status'),
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .default(25)
-            .describe('Maximum results (default: 25, max: 50)'),
-        sort: z
-            .enum([
-            'comments',
-            'reactions',
-            'reactions-+1',
-            'reactions--1',
-            'reactions-smile',
-            'reactions-thinking_face',
-            'reactions-heart',
-            'reactions-tada',
-            'interactions',
-            'created',
-            'updated',
-        ])
-            .optional()
-            .describe('Sort criteria'),
-        order: z
-            .enum(['asc', 'desc'])
-            .optional()
-            .default('desc')
-            .describe('Order (default: desc)'),
-    }, {
-        title: TOOL_NAME$4,
-        description: DESCRIPTION$4,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+    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()
+                .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()
+                .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()
+                .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()
+                .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 PR Search - Implementation Discovery',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         if (!args.query?.trim()) {
-            return createErrorResult$1('Search query is required and cannot be empty - provide keywords to search for pull requests', new Error('Invalid query'));
+            return createResult({
+                error: `${ERROR_MESSAGES.QUERY_REQUIRED} ${SUGGESTIONS.PROVIDE_PR_KEYWORDS}`,
+            });
         }
         if (args.query.length > 256) {
-            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less - simplify your search terms', new Error('Query too long'));
+            return createResult({
+                error: ERROR_MESSAGES.QUERY_TOO_LONG,
+            });
         }
         try {
             return await searchGitHubPullRequests(args);
         }
         catch (error) {
-            return createErrorResult$1('GitHub pull requests search failed - verify repository access and query syntax', error);
+            return createResult({
+                error: createSearchFailedError('pull_requests'),
+            });
         }
     });
 }
@@ -1629,8 +2071,13 @@ async function searchGitHubPullRequests(params) {
             return result;
         }
         const execResult = JSON.parse(result.content[0].text);
-        const apiResponse = JSON.parse(execResult.result);
+        const apiResponse = execResult.result;
         const pullRequests = apiResponse.items || [];
+        if (pullRequests.length === 0) {
+            return createResult({
+                error: createNoResultsError('pull_requests'),
+            });
+        }
         const cleanPRs = pullRequests.map((pr) => {
             const result = {
                 number: pr.number,
@@ -1639,8 +2086,8 @@ async function searchGitHubPullRequests(params) {
                 author: pr.user?.login || '',
                 repository: pr.repository_url?.split('/').slice(-2).join('/') || 'unknown',
                 labels: pr.labels?.map(l => l.name) || [],
-                created_at: pr.created_at,
-                updated_at: pr.updated_at,
+                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,
@@ -1650,7 +2097,7 @@ async function searchGitHubPullRequests(params) {
             if (pr.merged_at)
                 result.merged_at = pr.merged_at;
             if (pr.closed_at)
-                result.closed_at = pr.closed_at;
+                result.closed_at = toDDMMYYYY(pr.closed_at);
             if (pr.head?.ref)
                 result.head = pr.head.ref;
             if (pr.base?.ref)
@@ -1658,15 +2105,10 @@ async function searchGitHubPullRequests(params) {
             return result;
         });
         const searchResult = {
-            searchType: 'prs',
-            query: params.query || '',
             results: cleanPRs,
-            metadata: {
-                total_count: apiResponse.total_count || 0,
-                incomplete_results: apiResponse.incomplete_results || false,
-            },
+            total_count: apiResponse.total_count || cleanPRs.length,
         };
-        return createSuccessResult$1(searchResult);
+        return createResult({ data: searchResult });
     });
 }
 function buildGitHubPullRequestsAPICommand(params) {
@@ -1726,83 +2168,477 @@ function buildGitHubPullRequestsAPICommand(params) {
     return { command: 'api', args: [apiPath] };
 }
 
-const TOOL_NAME$3 = 'npm_package_search';
-const DESCRIPTION$3 = `Search npm packages by keywords using fuzzy matching. 
-
-IMPORTANT LIMITATIONS:
- NO BOOLEAN OPERATORS: NPM search does NOT support AND/OR/NOT - use space-separated keywords for broader search
- FUZZY MATCHING ONLY: No exact phrase matching - searches are approximate keyword matching
- KEYWORD-BASED: Best results with simple, space-separated terms like "react hooks" or "cli typescript"
-
-Required when package name is unknown. If you have the exact package name, use npm_view_package directly. This reduces the need to use GitHub search when packages are found.`;
-const MAX_DESCRIPTION_LENGTH = 100;
-const MAX_KEYWORDS = 10;
-function registerNpmSearchTool(server) {
-    server.tool(TOOL_NAME$3, DESCRIPTION$3, {
-        queries: z
-            .union([z.string(), z.array(z.string())])
-            .describe('Package names or keywords to search for. NOTE: No boolean operators (AND/OR/NOT) supported - use simple space-separated keywords like "react hooks" or "typescript cli" for fuzzy matching.'),
-        searchlimit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .default(20)
-            .describe('Max results per query (default: 20, max: 50)'),
-    }, {
-        title: TOOL_NAME$3,
-        description: DESCRIPTION$3,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+/**
+ * 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).`;
+/**
+ * Extract owner/repo information from various query formats
+ */
+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
+        }
+    }
+    return {
+        extractedOwner,
+        extractedRepo,
+        cleanedQuery: cleanedQuery || query, // Ensure original query is returned if cleaned is empty
+    };
+}
+function registerSearchGitHubReposTool(server) {
+    server.registerTool(GITHUB_SEARCH_REPOSITORIES_TOOL_NAME, {
+        description: DESCRIPTION$2,
+        inputSchema: {
+            query: z
+                .string()
+                .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
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .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('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('Stars filter. Supports ranges and thresholds.'),
+            topic: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .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 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('Filter archived repositories (true/false).'),
+            includeForks: z
+                .enum(['false', 'true', 'only'])
+                .optional()
+                .describe('Include forks: false (exclude), true (include), only (forks only).'),
+            visibility: z
+                .enum(['public', 'private', 'internal'])
+                .optional()
+                .describe('Repository visibility filter.'),
+            // DATE & SIZE FILTERS
+            created: 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 criteria for results.'),
+            order: z
+                .enum(['asc', 'desc'])
+                .optional()
+                .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 {
-            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);
-                }
+            // 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;
             }
-            const deduplicatedPackages = deduplicatePackages(allPackages);
-            if (deduplicatedPackages.length > 0) {
+            // 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({
-                    query: Array.isArray(args.queries)
-                        ? args.queries.join(', ')
-                        : args.queries,
-                    total: deduplicatedPackages.length,
-                    results: deduplicatedPackages,
+                    error: SUGGESTIONS.REPO_SEARCH_PRIMARY_FILTER,
                 });
             }
-            return createResult('No packages found', true);
+            // 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('NPM package search failed - check search terms or try different keywords', true);
+            return createResult({
+                error: createSearchFailedError('repositories'),
+            });
         }
     });
 }
-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;
+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(20)
+                .describe('Results limit per query (1-50). Default: 20'),
+        },
+        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: createNoResultsError('packages'),
+            });
+        }
+        catch (error) {
+            return createResult({
+                error: createSearchFailedError('packages'),
+            });
+        }
+    });
+}
+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 {
@@ -1816,9 +2652,7 @@ function normalizePackage(pkg) {
 function parseNpmSearchOutput(output) {
     try {
         const wrapper = JSON.parse(output);
-        const commandResult = typeof wrapper.result === 'string'
-            ? JSON.parse(wrapper.result)
-            : wrapper.result;
+        const commandResult = wrapper.result;
         let packages = [];
         // Handle different npm search output formats
         if (Array.isArray(commandResult)) {
@@ -1832,619 +2666,407 @@ function parseNpmSearchOutput(output) {
         }
         return packages.map(normalizePackage);
     }
-    catch {
+    catch (error) {
+        logger.warn('Failed to parse NPM search results:', error);
         return [];
     }
 }
 
-const TOOL_NAME$2 = 'github_get_contents';
-const DESCRIPTION$2 = `Browse repository structure and verify file existence. Use before github_get_file_content to confirm files exist and understand organization, especially when the path is uncertain.`;
-function registerViewRepositoryStructureTool(server) {
-    server.tool(TOOL_NAME$2, DESCRIPTION$2, {
-        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 (e.g., 'microsoft', 'facebook'). Use github_search_repositories to discover valid owners.`),
-        repo: z
-            .string()
-            .min(1)
-            .max(100)
-            .regex(/^[a-zA-Z0-9._-]+$/, 'Invalid repository name format')
-            .describe('Repository name (e.g., "vscode", "react"). Case-sensitive. Use github_search_repositories to find exact names.'),
-        branch: z
-            .string()
-            .min(1)
-            .max(255)
-            .regex(/^[^\s]+$/, 'Branch name cannot contain spaces')
-            .describe("Target branch name (e.g., 'main', 'canary', 'develop'). " +
-            'Auto-detects repository default if not found. ' +
-            'Use github_search_repositories or api calls to discover valid branches first.'),
-        path: 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 (e.g., "src/components", "packages/core"). ' +
-            'Leave empty for root. Use previous results to navigate deeper.'),
-    }, {
-        title: TOOL_NAME$2,
-        description: DESCRIPTION$2,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+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(NPM_VIEW_PACKAGE_TOOL_NAME, {
+        description: DESCRIPTION,
+        inputSchema: {
+            packageName: z
+                .string()
+                .min(1)
+                .describe('NPM package name (e.g., "react", "express", "@types/node")'),
+        },
+        annotations: {
+            title: 'NPM Package Analyzer',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         try {
-            const result = await viewRepositoryStructure(args);
+            const result = await viewNpmPackage(args.packageName);
             if (result.isError) {
-                return createResult(result.content[0].text, true);
-            }
-            if (result.content && result.content[0] && !result.isError) {
-                const { data, parsed } = parseJsonResponse(result.content[0].text);
-                if (parsed) {
-                    const typedResult = {
-                        path: data.path,
-                        baseUrl: data.baseUrl,
-                        files: data.files || [],
-                        folders: data.folders || [],
-                        ...(data.branchFallback && {
-                            branchFallback: data.branchFallback,
-                        }),
-                    };
-                    return createResult(typedResult);
-                }
+                return result;
             }
-            return result;
+            const execResult = JSON.parse(result.content[0].text);
+            const packageData = execResult.result;
+            // Transform to optimized format
+            const optimizedResult = transformToOptimizedFormat(packageData);
+            return createResult({ data: optimizedResult });
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            return createResult(`Repository exploration failed: ${errorMessage} - verify repository exists and is accessible`, true);
-        }
-    });
-}
-/**
- * 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
- */
-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;
-            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;
-                }
+            const errorMessage = error.message || '';
+            if (errorMessage.includes('not found')) {
+                return createResult({
+                    error: 'Package not found. Check spelling and use exact package name from npm',
+                });
             }
-            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) {
-                        throw new Error(`Path "${path}" not found - verify path exists or use github_search_code to find files`);
-                    }
-                    else {
-                        throw new Error(`Repository not found: ${owner}/${repo} - verify owner/repo names or use github_search_repositories`);
-                    }
-                }
-                else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
-                    throw new Error(`Access denied to repository ${owner}/${repo} - repository may be private or require authentication`);
-                }
-                else {
-                    throw new Error(`Access failed: ${owner}/${repo} - check connection or repository permissions`);
-                }
+            if (errorMessage.includes('network')) {
+                return createResult({
+                    error: 'Network error. Check internet connection and try again',
+                });
             }
-            // 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 base URL for GitHub API - construct it reliably from the parameters
-            const baseUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${cleanPath ? cleanPath + '/' : ''}`;
-            // Transform to lean structure with simplified paths and URLs
-            const files = limitedItems
-                .filter(item => item.type === 'file')
-                .map(item => {
-                // Simplify path by removing redundant prefix
-                let simplifiedPath = item.name; // Use just the filename for files in current directory
-                // If we're in a subdirectory and the item path is longer than just the name,
-                // show relative path from current directory
-                if (cleanPath && item.path.startsWith(cleanPath + '/')) {
-                    simplifiedPath = item.path.substring(cleanPath.length + 1);
-                }
-                else if (!cleanPath) {
-                    // At root level, use the full path but without leading slash
-                    simplifiedPath = item.path;
-                }
-                // Extract just the filename and query params from the URL
-                const urlParts = item.url.split('/');
-                const filename = urlParts[urlParts.length - 1]; // Gets "filename?ref=branch"
-                return {
-                    name: simplifiedPath,
-                    size: item.size,
-                    url: filename, // Just the filename and query params
-                };
+            return createResult({
+                error: 'Failed to fetch package information. Try again or check npm status',
             });
-            const folders = limitedItems
-                .filter(item => item.type === 'dir')
-                .map(item => `${item.name}/`);
-            const result = {
-                path: `${owner}/${repo}${path ? `/${path}` : ''}`,
-                baseUrl: `${baseUrl}?ref=${usedBranch}`, // Include complete base URL with branch
-                files,
-                folders,
-                ...(usedBranch !== branch && {
-                    branchFallback: {
-                        requested: branch,
-                        used: usedBranch,
-                        message: `Used '${usedBranch}' instead of '${branch}'`,
-                    },
-                }),
-            };
-            return createSuccessResult$1(result);
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return createErrorResult$1('Repository access failed - verify repository exists and check authentication', new Error(errorMessage));
         }
     });
 }
 /**
- * Intelligently determines the best branches to try for a repository.
- * Attempts to fetch the default branch first, then falls back to common branches.
+ * Transform NPM CLI response to optimized format for code analysis
  */
-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);
-            }
-        }
-    }
-    catch {
-        // If we can't get repo info, proceed with standard fallbacks
+function transformToOptimizedFormat(packageData) {
+    // Extract repository URL and simplify
+    const repoUrl = packageData.repository?.url || packageData.repositoryGitUrl || '';
+    const repository = repoUrl ? simplifyRepoUrl(repoUrl) : '';
+    // Simplify exports to essential entry points only
+    const exports = packageData.exports
+        ? simplifyExports(packageData.exports)
+        : undefined;
+    // Get version timestamps from time object and limit to last 5
+    const timeData = packageData.time || {};
+    const versionList = Array.isArray(packageData.versions)
+        ? packageData.versions
+        : [];
+    const recentVersions = versionList.slice(-5).map((version) => ({
+        version,
+        date: timeData[version] ? toDDMMYYYY(timeData[version]) : 'Unknown',
+    }));
+    const result = {
+        name: packageData.name,
+        version: packageData.version,
+        description: packageData.description || '',
+        license: packageData.license || 'Unknown',
+        repository,
+        size: humanizeBytes(packageData.dist?.unpackedSize || 0),
+        created: timeData.created ? toDDMMYYYY(timeData.created) : 'Unknown',
+        updated: timeData.modified ? toDDMMYYYY(timeData.modified) : 'Unknown',
+        versions: recentVersions,
+        stats: {
+            total_versions: versionList.length,
+            weekly_downloads: packageData.weeklyDownloads,
+        },
+    };
+    // Add exports only if they exist and are useful
+    if (exports && Object.keys(exports).length > 0) {
+        result.exports = exports;
     }
-    // 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;
-}
-
-const TOOL_NAME$1 = 'github_search_issues';
-const DESCRIPTION$1 = `Find GitHub issues with rich metadata (labels, reactions, comments, state). Discover pain points, feature requests, and bug patterns with boolean logic and GitHub qualifiers.
-
-SEARCH PATTERNS:
- Boolean: "bug AND crash", "feature OR enhancement", "error NOT test"
- Exact phrases: "memory leak" (quoted)
- GitHub qualifiers: "is:open label:bug author:username"
- Combine with filters for precision`;
-function registerSearchGitHubIssuesTool(server) {
-    server.tool(TOOL_NAME$1, DESCRIPTION$1, {
-        query: z
-            .string()
-            .min(1, 'Search query is required and cannot be empty')
-            .describe('Search query with GITHUB SEARCH SYNTAX support. BOOLEAN OPERATORS: "bug AND crash" (both required), "feature OR enhancement" (either term), "error NOT test" (excludes). EXACT PHRASES: "memory leak" (precise matching). GITHUB QUALIFIERS: "is:open label:bug author:username" (native GitHub syntax). COMBINED: Mix boolean logic with qualifiers for precise issue discovery.'),
-        owner: z
-            .string()
-            .min(1)
-            .optional()
-            .describe('Repository owner/organization. Leave empty for global search.'),
-        repo: 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()
-            .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().optional().describe('Filter by user who commented'),
-        comments: z.number().optional().describe('Filter by number of comments'),
-        created: z
-            .string()
-            .optional()
-            .describe("Filter by created date (e.g., '>2022-01-01')"),
-        includePrs: z
-            .boolean()
-            .optional()
-            .describe('Include pull requests in results'),
-        interactions: z
-            .number()
-            .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()
-            .optional()
-            .describe('Filter by locked conversation status'),
-        match: z
-            .enum(['title', 'body', 'comments'])
-            .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().optional().describe('Filter by missing assignee'),
-        noLabel: z.boolean().optional().describe('Filter by missing label'),
-        noMilestone: z
-            .boolean()
-            .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'])
-            .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'])
-            .optional()
-            .describe('Filter by repository visibility'),
-        sort: z
-            .enum([
-            'comments',
-            'created',
-            'interactions',
-            'reactions',
-            'reactions-+1',
-            'reactions--1',
-            'reactions-heart',
-            'reactions-smile',
-            'reactions-tada',
-            'reactions-thinking_face',
-            'updated',
-            'best-match',
-        ])
-            .optional()
-            .describe('Sort criteria'),
-        order: z
-            .enum(['asc', 'desc'])
-            .optional()
-            .default('desc')
-            .describe('Order (default: desc)'),
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(50)
-            .optional()
-            .default(25)
-            .describe('Maximum results (default: 25, max: 50)'),
-    }, {
-        title: TOOL_NAME$1,
-        description: DESCRIPTION$1,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    }, async (args) => {
-        if (!args.query?.trim()) {
-            return createErrorResult$1('Search query is required and cannot be empty - provide keywords to search for issues', new Error('Invalid query'));
-        }
-        if (args.query.length > 256) {
-            return createErrorResult$1('Search query is too long. Please limit to 256 characters or less - simplify your search terms', new Error('Query too long'));
-        }
-        try {
-            return await searchGitHubIssues(args);
-        }
-        catch (error) {
-            return createErrorResult$1('GitHub issues search failed - check repository exists and query is valid', error);
-        }
-    });
-}
-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;
-        }
-        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: issue.created_at,
-            updated_at: issue.updated_at,
-            url: issue.html_url,
-            comments: issue.comments,
-            reactions: issue.reactions?.total_count || 0,
-        }));
-        const searchResult = {
-            searchType: 'issues',
-            query: params.query || '',
-            results: cleanIssues,
-            metadata: {
-                total_count: apiResponse.total_count || 0,
-                incomplete_results: apiResponse.incomplete_results || false,
-            },
-        };
-        return createSuccessResult$1(searchResult);
-    });
+    return result;
 }
-function buildGitHubIssuesAPICommand(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}`);
+/**
+ * Simplify exports to show only essential entry points for code navigation
+ */
+function simplifyExports(exports) {
+    if (typeof exports === 'string') {
+        return { main: exports };
     }
-    // Build search qualifiers from params
-    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,
-    };
-    Object.entries(qualifiers).forEach(([key, value]) => {
-        if (value)
-            queryParts.push(`${key}:${value}`);
-    });
-    // Special qualifiers
-    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}`);
-    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 without needing GitHub searches. Essential for finding package source code and understanding project structure.`;
-function registerNpmViewPackageTool(server) {
-    server.tool(TOOL_NAME, DESCRIPTION, {
-        packageName: z
-            .string()
-            .min(1, 'Package name is required')
-            .describe('NPM package name to analyze. Returns complete package context including exports (critical for GitHub file discovery), repository URL, dependencies, and version history.'),
-    }, {
-        title: TOOL_NAME,
-        description: DESCRIPTION,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    }, async (args) => {
-        try {
-            if (!args.packageName || args.packageName.trim() === '') {
-                return createResult('Package name is required - provide a valid NPM package name', true);
+    if (typeof exports === 'object') {
+        const simplified = {};
+        // Extract main entry point
+        if (exports['.']) {
+            const mainExport = exports['.'];
+            if (typeof mainExport === 'string') {
+                simplified.main = mainExport;
             }
-            // Basic package name validation
-            if (!/^[a-z0-9@._/-]+$/.test(args.packageName)) {
-                return createResult('Invalid package name format - use standard NPM naming (e.g., "package-name" or "@scope/package")', true);
+            else if (mainExport.default) {
+                simplified.main = mainExport.default;
+            }
+            else if (mainExport.import) {
+                simplified.main = mainExport.import;
             }
-            const result = await npmViewPackage(args.packageName);
-            return result;
         }
-        catch (error) {
-            return createResult('Failed to get package metadata - verify package exists on NPM registry', true);
+        // Extract types if available with safe property access
+        if (exports['./types'] ||
+            (exports['.'] && typeof exports['.'] === 'object' && exports['.'].types)) {
+            simplified.types = exports['./types'] || exports['.'].types;
         }
-    });
-}
-// Helper function to process versions
-function processVersions(time) {
-    const semanticVersionRegex = /^\d+\.\d+\.\d+$/;
-    const versions = Object.entries(time || {})
-        .filter(([key]) => key !== 'created' && key !== 'modified')
-        .filter(([version]) => semanticVersionRegex.test(version))
-        .sort(([, a], [, b]) => new Date(b).getTime() - new Date(a).getTime());
-    return {
-        recent: versions
-            .slice(0, 10)
-            .map(([version, releaseDate]) => ({ version, releaseDate })),
-        stats: {
-            total: Object.keys(time || {}).length - 2, // exclude 'created' and 'modified'
-            official: versions.length,
-        },
-    };
+        // Add a few other important exports (max 3 total)
+        let count = 0;
+        for (const [key, value] of Object.entries(exports)) {
+            if (count >= 3 || key === '.' || key === './types')
+                continue;
+            if (key.includes('package.json') || key.includes('node_modules'))
+                continue;
+            simplified[key] =
+                typeof value === 'object' ? value.default || value : value;
+            count++;
+        }
+        return simplified;
+    }
+    return { main: 'index.js' };
 }
-async function npmViewPackage(packageName) {
-    const cacheKey = generateCacheKey('npm-view-package', { packageName });
+async function viewNpmPackage(packageName) {
+    const cacheKey = generateCacheKey('npm-view', { packageName });
     return withCache(cacheKey, async () => {
         try {
             const result = await executeNpmCommand('view', [packageName, '--json'], {
-                cache: true,
+                cache: false,
             });
-            if (result.isError) {
-                return result;
-            }
-            // Parse the result from the executed command
-            const commandOutput = JSON.parse(result.content[0].text);
-            const npmData = JSON.parse(commandOutput.result);
-            // Process versions
-            const versionData = processVersions(npmData.time);
-            // Extract registry URL from tarball
-            const registryUrl = npmData.dist?.tarball?.match(/^(https?:\/\/[^/]+)/)?.[1] || '';
-            // Build result
-            const viewResult = {
-                name: npmData.name,
-                latest: npmData['dist-tags']?.latest || '',
-                license: npmData.license || '',
-                timeCreated: npmData.time?.created || '',
-                timeModified: npmData.time?.modified || '',
-                repositoryGitUrl: npmData.repository?.url || '',
-                registryUrl,
-                description: npmData.description || '',
-                size: npmData.dist?.unpackedSize || 0,
-                dependencies: npmData.dependencies || {},
-                devDependencies: npmData.devDependencies || {},
-                exports: npmData.exports || {},
-                versions: versionData.recent,
-                versionStats: versionData.stats,
-            };
-            return createSuccessResult$1(viewResult);
+            return result;
         }
         catch (error) {
-            return createErrorResult$1('Failed to get npm package metadata - package may not exist or registry unavailable', error);
+            const errorMessage = error.message || '';
+            if (errorMessage.includes('404')) {
+                return createResult({
+                    error: 'Package not found on NPM registry. Verify the exact package name',
+                });
+            }
+            return createResult({
+                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: registerSearchGitHubCommitsTool },
         {
-            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);
 });