octocode-mcp 2.3.2 → 2.3.5

package/build/index.js

@@ -3,79 +3,44 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { platform } from 'os';
 import NodeCache from 'node-cache';
 import crypto from 'crypto';
 import z from 'zod';
 
-const PROMPT_SYSTEM_PROMPT = `You are an expert code research assistant for developers doing smart research in GitHub and NPM ecosystems (public/private).
-You leverage powerful semantic search using GitHub (gh) and NPM CLI for code discovery.
+const PROMPT_SYSTEM_PROMPT = `Expert code research assistant for GitHub/NPM ecosystems (public/private). Use powerful semantic search for efficient code discovery.
 
-IMPORTANT: check users github organizations and use them in github search tools if needed
+CORE TOOLS:
+ GitHub: Code, repos, issues, PRs, commits - supports boolean logic (AND/OR/NOT) and exact phrases
+ NPM: Package search (fuzzy only, no boolean) + metadata (repo URLs, exports, dependencies)
+ API Status: Check connectivity + user's GitHub organizations for private access
 
-TOOLS:
-- API status: Check npm/gh connectivity and find user's GitHub organizations (for private repo access)
-- GitHub: Search code, repositories, issues, pull requests, commits
-- NPM: Search packages, view metadata (git URL, exports, dependencies, versions with dates)
+SEARCH STRATEGIES:
+GitHub Code/Issues/PRs/Commits:
+ OR (broad): "useState OR setState" - finds alternatives  
+ AND (precise): "react AND hooks" - requires both terms
+ NOT (filter): "auth NOT test" - excludes noise
+ Quotes (exact): "useEffect cleanup" - literal phrases
+ Combine with filters: language, path, owner for focus
 
-APPROACH:
-- Once code/project path is found from tools use it and research it for more data
-- Understand queries semantically to choose optimal tools
-- Optimize tools calls data and be smart about it (e.g. is some tool get information don't use other tools to get the same information)
-- Prioritize efficient, targeted searches with smart fallbacks
-- Use strategic tool combinations for comprehensive results an
-- Balance speed vs throughness based on query type
+NPM Search:
+ Space-separated keywords only: "react state management"
+ No boolean operators supported
+ Use npm_view_package for direct package metadata → GitHub repo URL
 
-GITHUB SEARCH STRATEGY:
-- OR: Explore alternatives ("useState OR setState OR setData")
-- AND: Precise requirements ("react AND testing AND hooks")  
-- NOT: Filter noise ("auth NOT test NOT mock")
-- Quotes: Exact phrases ("import React", "useEffect cleanup")
-- Mix with filters: language, path, repo for laser focus
+OPTIMIZATION:
+ Check user's GitHub orgs for private repo access
+ npm_view_package gives repo URL instantly - avoid GitHub repo search
+ Use targeted searches, avoid redundant tool calls
+ Combine tools strategically: NPM → GitHub file content
+ Discovery: comprehensive multi-tool approach
+ Direct queries: quick targeted approach
 
-GUIDELINES:
-- Discovery queries ("How X works?"): Be comprehensive, use multiple tools strategically
-- Direct queries ("Where is X package repo?"): Use quick, targeted approach
-- Always provide referenced code snippets and documentation
-- Search docs (README.md) for quality information about code flow and architecture`;
+ CLI Help using CLI (use when needed to check failures)
+ gh <command>  --help
+ npm <command> --help
 
-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));
-}
+Always provide code snippets and documentation references.`;
 
 const VERSION = 'v1';
 const cache = new NodeCache({
@@ -133,6 +98,113 @@ function isValidNpmCommand(command) {
 function isValidGhCommand(command) {
     return ALLOWED_GH_COMMANDS.includes(command);
 }
+/**
+ * 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: userShell,
+            shellEnv: userShell,
+            type: 'unix',
+        };
+    }
+    // Windows shell selection
+    const usesPowerShell = preferredWindowsShell === 'powershell';
+    if (usesPowerShell) {
+        return {
+            shell: 'powershell.exe',
+            shellEnv: 'powershell.exe',
+            type: 'powershell',
+        };
+    }
+    return {
+        shell: 'cmd.exe',
+        shellEnv: 'cmd.exe',
+        type: 'cmd',
+    };
+}
+/**
+ * Checks if a query contains GitHub search boolean operators
+ */
+function hasGitHubBooleanOperators(query) {
+    // Check for GitHub boolean operators (must be uppercase)
+    return (/\b(AND|OR|NOT)\b/.test(query) ||
+        /\s+(AND|OR|NOT)\s+/.test(query) ||
+        /"[^"]*\s+(AND|OR|NOT)\s+[^"]*"/.test(query));
+}
+/**
+ * Escape shell arguments with improved GitHub CLI boolean query handling
+ */
+function escapeShellArg(arg, shellType, isGitHubQuery) {
+    // Auto-detect shell type if not provided
+    if (!shellType) {
+        const isWindows = platform() === 'win32';
+        shellType = isWindows ? 'cmd' : 'unix';
+    }
+    switch (shellType) {
+        case 'powershell':
+            return escapePowerShellArg(arg);
+        case 'cmd':
+            return escapeWindowsCmdArg(arg);
+        case 'unix':
+        default:
+            return escapeUnixShellArg(arg, isGitHubQuery);
+    }
+}
+/**
+ * Escape arguments for PowerShell
+ * PowerShell uses single quotes for literal strings and has special escaping rules
+ */
+function escapePowerShellArg(arg) {
+    // PowerShell special characters that need escaping
+    if (/[\s&<>|;`$@"'()[\]{}]/.test(arg)) {
+        // Use single quotes for literal strings in PowerShell
+        // Escape single quotes by doubling them
+        return `'${arg.replace(/'/g, "''")}'`;
+    }
+    return arg;
+}
+/**
+ * Escape arguments for Windows CMD
+ */
+function escapeWindowsCmdArg(arg) {
+    // Windows CMD escaping
+    if (/[\s&<>|^"]/.test(arg)) {
+        return `"${arg.replace(/"/g, '""')}"`;
+    }
+    return arg;
+}
+/**
+ * Escape arguments for Unix shells with special handling for GitHub CLI queries
+ */
+function escapeUnixShellArg(arg, isGitHubQuery) {
+    // Special handling for GitHub CLI search queries to preserve boolean logic
+    if (isGitHubQuery && hasGitHubBooleanOperators(arg)) {
+        // For boolean queries with OR/AND/NOT, use double quotes to preserve operators
+        // GitHub CLI handles boolean logic properly when quoted
+        return `"${arg.replace(/"/g, '\\"')}"`;
+    }
+    // For GitHub queries with spaces but no boolean operators, quote them
+    if (isGitHubQuery &&
+        /\s/.test(arg) &&
+        !arg.startsWith('"') &&
+        !arg.endsWith('"')) {
+        return `"${arg.replace(/"/g, '\\"')}"`;
+    }
+    // For already quoted GitHub queries, pass through with escaped internal quotes
+    if (isGitHubQuery && arg.startsWith('"') && arg.endsWith('"')) {
+        return arg.replace(/\\"/g, '\\\\"'); // Escape already escaped quotes
+    }
+    // Standard Unix shell escaping for other arguments
+    if (/[^\w\-._/:=@]/.test(arg)) {
+        return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+    }
+    return arg;
+}
 /**
  * Execute NPM commands safely by validating against allowed commands
  * Security: Only executes commands that start with "npm {ALLOWED_COMMAND}"
@@ -142,74 +214,94 @@ async function executeNpmCommand(command, args = [], options = {}) {
     if (!isValidNpmCommand(command)) {
         return createErrorResult('Command not registered', new Error(`NPM command '${command}' is not in the allowed list`));
     }
+    // Get shell configuration
+    const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    const escapedArgs = args.map(escapeShellArg);
+    const escapedArgs = args.map(arg => escapeShellArg(arg, shellConfig.type));
     const fullCommand = `npm ${command} ${escapedArgs.join(' ')}`;
-    const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options);
+    const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options, shellConfig);
     if (options.cache) {
-        const cacheKey = generateCacheKey('npm-exec', { command, args });
+        const cacheKey = generateCacheKey('npm-exec', {
+            command,
+            args,
+            shell: shellConfig.type,
+        });
         return withCache(cacheKey, executeNpmCommand);
     }
     return executeNpmCommand();
 }
 /**
- * Escape shell arguments to prevent shell injection and handle special characters
- */
-function escapeShellArg(arg) {
-    // If the argument contains special characters, wrap it in single quotes
-    // and escape any single quotes within the argument
-    if (/[^\w\-._/:=@]/.test(arg)) {
-        return `'${arg.replace(/'/g, "'\"'\"'")}'`;
-    }
-    return arg;
-}
-/**
- * Execute GitHub CLI commands safely by validating against allowed commands
- * Security: Only executes commands that start with "gh {ALLOWED_COMMAND}"
+ * Execute GitHub CLI commands safely with improved boolean query handling
  */
 async function executeGitHubCommand(command, args = [], options = {}) {
     // Security check: only allow registered commands
     if (!isValidGhCommand(command)) {
         return createErrorResult('Command not registered', new Error(`GitHub command '${command}' is not in the allowed list`));
     }
+    // Get shell configuration
+    const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    const escapedArgs = args.map(escapeShellArg);
+    // First argument is typically the search query for GitHub CLI search commands
+    const escapedArgs = args.map((arg, index) => {
+        const isFirstArg = index === 0;
+        // Detect if this is a search query (first non-subcommand argument)
+        const isSearchQuery = command === 'search' && isFirstArg && !arg.startsWith('--');
+        return escapeShellArg(arg, shellConfig.type, isSearchQuery);
+    });
     const fullCommand = `gh ${command} ${escapedArgs.join(' ')}`;
-    const executeGhCommand = () => executeCommand(fullCommand, 'github', options);
+    const executeGhCommand = () => executeCommand(fullCommand, 'github', options, shellConfig);
     if (options.cache) {
-        const cacheKey = generateCacheKey('gh-exec', { command, args });
+        const cacheKey = generateCacheKey('gh-exec', {
+            command,
+            args,
+            shell: shellConfig.type,
+        });
         return withCache(cacheKey, executeGhCommand);
     }
     return executeGhCommand();
 }
 /**
- * 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 = {}) {
+async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     try {
         const defaultTimeout = type === 'npm' ? 30000 : 60000;
+        const config = shellConfig || getShellConfig(options.windowsShell);
         const execOptions = {
             timeout: options.timeout || defaultTimeout,
+            maxBuffer: 5 * 1024 * 1024, // 5MB buffer limit (increased from default 1MB)
             cwd: options.cwd,
             env: {
                 ...process.env,
                 ...options.env,
-                // Ensure clean shell environment
-                SHELL: '/bin/sh',
+                // 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: '/bin/sh', // Use sh instead of default 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';
@@ -220,6 +312,9 @@ async function executeCommand(fullCommand, type, options = {}) {
             result: stdout,
             timestamp: new Date().toISOString(),
             type,
+            platform: platform(),
+            shell: config.shell,
+            shellType: config.type,
             ...(stderr && { warning: stderr }), // Include warnings but don't treat as error
         });
     }
@@ -231,17 +326,110 @@ async function executeCommand(fullCommand, type, options = {}) {
     }
 }
 
+function createResult(options) {
+    const { data, error, suggestions, cli_command } = options;
+    if (error) {
+        const errorMessage = typeof error === 'string'
+            ? error
+            : error.message || 'Unknown error';
+        // Build error response with optional CLI command
+        const errorResponse = { error: errorMessage };
+        if (suggestions) {
+            errorResponse.suggestions = suggestions;
+        }
+        if (cli_command) {
+            errorResponse.cli_command = cli_command;
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(errorResponse, null, 2) }],
+            isError: true,
+        };
+    }
+    // For successful responses, include cli_command if provided (for debugging)
+    if (cli_command && data && typeof data === 'object') {
+        const dataWithCli = { ...data, cli_command };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(dataWithCli, null, 2) }],
+            isError: false,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        isError: false,
+    };
+}
+/**
+ * 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 + '…';
+}
+
 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.`;
+const DESCRIPTION$9 = `Get GitHub organizations list and check CLI authentication status. Use when searching private repos or when CLI tools fail.`;
 function registerApiStatusCheckTool(server) {
-    server.tool(TOOL_NAME$9, DESCRIPTION$9, {}, {
-        title: 'Check API Connections and Github Organizations',
+    server.registerTool(TOOL_NAME$9, {
         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;
@@ -341,111 +529,131 @@ function registerApiStatusCheckTool(server) {
                 }
                 npmConnected = false;
             }
-            return createResult({
-                github: {
-                    connected: githubConnected,
-                    organizations,
-                },
-                npm: {
-                    connected: npmConnected,
-                    registry,
+            // Build structured response object
+            const loginStatus = {
+                login: {
+                    github: {
+                        connected: githubConnected,
+                        user_organizations: organizations,
+                    },
+                    npm: {
+                        connected: npmConnected,
+                        registry: registry || 'https://registry.npmjs.org/',
+                    },
+                    hints: [
+                        'use user organizations: to search on private repositories in case the user asked about private repo - check by query nd structure',
+                    ],
                 },
-            });
+            };
+            return createResult({ data: loginStatus });
         }
         catch (error) {
-            return createResult('API status check failed - verify GitHub CLI and NPM are installed and accessible', true);
+            return createResult({
+                error: `API Status Check Failed\nError: ${error instanceof Error ? error.message : 'Unknown error'}\n\nThis usually indicates a system configuration issue. Please verify GitHub CLI and NPM are properly installed.`,
+            });
         }
     });
 }
 
 const TOOL_NAME$8 = 'github_search_code';
-const DESCRIPTION$8 = `Search code across GitHub repositories using strategic boolean operators and filters usign "gh code search" command.
+const DESCRIPTION$8 = `Search code across GitHub repositories with powerful GitHub search syntax and advanced filtering.
 
-STRATEGIC SEARCH PATTERNS:
+BOOLEAN LOGIC (MOST POWERFUL):
+- "useState OR useEffect" - Find either hook
+- "useState AND useEffect" - Find both hooks together
+- "authentication AND (jwt OR oauth)" - Complex logic combinations
+- "NOT deprecated" - Exclude deprecated code
 
- OR LOGIC (Exploratory Discovery):
-• Auto-applied to multi-word queries: "useState hook" → "useState OR hook"
-• Best for: Learning, finding alternatives, casting wide nets
-• Scope: BROADEST - finds files with ANY of the terms
+EMBEDDED QUALIFIERS:
+- "useState language:javascript filename:*.jsx" - Hook in React files
+- "authentication language:python path:*/security/*" - Security code in Python
+- "docker OR kubernetes language:yaml extension:yml" - Container configs
 
-AND LOGIC (Precise Intersection):
-• Explicit requirement: "react AND hooks" requires BOTH terms present
-• Best for: Finding specific combinations, technology intersections
-• Scope: RESTRICTIVE - only files containing ALL terms
+TRADITIONAL FILTERS (ALSO SUPPORTED):
+- language: "javascript", owner: "microsoft", filename: "package.json"
 
-EXACT PHRASE (Laser Targeting):
-• Escaped quotes: "useState hook" finds literal "useState hook" sequence
-• Best for: Documentation titles, specific API calls, exact implementations
-• Scope: MOST PRECISE - only exact sequence matches
+PROVEN PATTERNS: "authentication" → +language → +owner → +filename
+KEY TIPS: language filter = 90% speed boost, boolean operators work perfectly with filters`;
+function registerGitHubSearchCodeTool(server) {
+    server.registerTool(TOOL_NAME$8, {
+        description: DESCRIPTION$8,
+        inputSchema: {
+            query: z
+                .string()
+                .min(1)
+                .describe(`Search query with GitHub syntax. BOOLEAN LOGIC: "useState OR useEffect", "authentication AND jwt", "NOT deprecated". EMBEDDED QUALIFIERS: "useState language:javascript", "docker path:*/config/*". EXACT PHRASES: "error handling".
 
-NOT LOGIC (Noise Filtering):
-• Exclude unwanted results: "authentication NOT test NOT mock"
-• Best for: Removing examples, tests, deprecated code
+POWERFUL EXAMPLES: "useState OR useEffect language:javascript", "authentication AND (jwt OR oauth)", "docker OR kubernetes language:yaml", "NOT deprecated language:python"
+RULES: Boolean operators MUST be uppercase (AND, OR, NOT). Combines perfectly with traditional filters.`),
+            language: z
+                .string()
+                .optional()
+                .describe(`MOST EFFECTIVE FILTER - 90% speed boost! Essential for popular languages.
 
-RESTRICTIVENESS SCALE: OR < AND < Exact Phrase (Broadest → Most Precise)
+POPULAR: javascript, typescript, python, java, go, rust, php, ruby, swift, kotlin, dart
+SYSTEMS: c, cpp, assembly, shell, dockerfile, yaml`),
+            owner: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe(`HIGH IMPACT - Reduces search space by 95%+
 
-COMBINE FILTERS: Mix query with language, owner, path filters for laser-focused results.`;
-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,
-        description: DESCRIPTION$8,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+EXAMPLES: "microsoft", "google", "facebook" or ["microsoft", "google"]
+POPULAR: microsoft, google, facebook, amazon, apache, hashicorp, kubernetes`),
+            filename: z
+                .string()
+                .optional()
+                .describe(`SURGICAL PRECISION for configs and special files
+
+TARGETS: "package.json", "Dockerfile", "webpack.config.js", ".eslintrc", "README.md"
+STRATEGY: filename:package.json + "react typescript"`),
+            repo: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe(`PRECISE TARGETING for specific repositories
+
+FORMAT: "facebook/react", "microsoft/vscode" or ["facebook/react", "vuejs/vue"]
+USE: Deep dive analysis of specific projects`),
+            extension: z
+                .string()
+                .optional()
+                .describe(`FILE TYPE PRECISION - More specific than language filter
+
+POPULAR: js, ts, jsx, tsx, py, java, go, rs, rb, php, cs, sh, yml, json, md
+USE: extension:tsx (React TypeScript only), extension:dockerfile`),
+            match: z
+                .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
+                .optional()
+                .describe(`SEARCH SCOPE: "file" (content), "path" (filenames), ["file", "path"] (both)
+
+EXAMPLES: match:"path" + "test" (find test files), match:"file" + "useState"`),
+            size: z
+                .string()
+                .optional()
+                .describe(`FILE SIZE FILTER: ">100" (>100KB), "<50" (<50KB), "10..100" (range)
+
+STRATEGY: "<200" (avoid huge files), ">20" (substantial code), "<10" (configs)`),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(30)
+                .describe(`RESULTS: 10-20 (quick), 30 (default), 50-100 (comprehensive). Use filters over high limits.`),
+        },
+        annotations: {
+            title: 'GitHub Code Search - Smart & Efficient',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         try {
-            if (args.repo && !args.owner) {
-                return createResult('Repository search requires owner parameter - specify owner when searching specific repositories', true);
+            // Validate parameter combinations
+            const validationError = validateSearchParameters(args);
+            if (validationError) {
+                return createResult({ error: validationError });
             }
             const result = await searchGitHubCode(args);
             if (result.isError) {
@@ -455,131 +663,436 @@ function registerGitHubSearchCodeTool(server) {
             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,
-                },
-            });
+            // Smart handling for no results - provide actionable suggestions
+            if (items.length === 0) {
+                return handleNoResults(args, execResult.command);
+            }
+            // Transform to optimized format
+            const optimizedResult = transformToOptimizedFormat$1(items, args);
+            return createResult({ data: optimizedResult });
         }
         catch (error) {
-            return createErrorResult$1('GitHub code search failed - check repository access or simplify query', error);
+            const errorMessage = error.message || '';
+            // Handle JSON parsing errors
+            if (errorMessage.includes('JSON')) {
+                return createResult({
+                    error: 'GitHub CLI returned invalid response - check if GitHub CLI is up to date with "gh version" and try again',
+                });
+            }
+            return createResult({
+                error: 'GitHub code search failed',
+                suggestions: [
+                    'Try simpler queries without NOT operators',
+                    'Use filters (language, owner, filename) instead of complex boolean',
+                    'Check authentication with api_status_check',
+                ],
+            });
         }
     });
 }
 /**
- * Enhanced query parser that handles exact strings, boolean operators, and filters
+ * Smart handler for no results - provides actionable suggestions
  */
-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);
+function handleNoResults(params, cliCommand) {
+    const suggestions = generateSmartSuggestions(params);
+    const fallbackQueries = generateFallbackQueries(params);
+    return createResult({
+        data: {
+            items: [],
+            total_count: 0,
+            smart_suggestions: {
+                message: "No results found. Here are smart strategies to find what you're looking for:",
+                suggestions,
+                fallback_queries: fallbackQueries,
+                next_steps: [
+                    'Try one of the fallback queries above',
+                    'Remove some filters to broaden the search',
+                    'Use different keywords or synonyms',
+                    'Check spelling and try variations',
+                ],
+            },
+            metadata: {
+                has_filters: !!(params.language ||
+                    params.owner ||
+                    params.filename ||
+                    params.extension),
+                search_scope: params.match
+                    ? Array.isArray(params.match)
+                        ? params.match.join(',')
+                        : params.match
+                    : 'file',
+            },
+            cli_command: cliCommand,
+        },
     });
-    // Step 3: Smart boolean logic - default to OR between terms if no explicit operators
-    let searchQuery = processedQuery;
-    // Check if query already has explicit boolean operators
-    if (!hasComplexBooleanLogic(processedQuery)) {
-        // Split by whitespace and join with OR for better search results
-        const terms = processedQuery
-            .trim()
-            .split(/\s+/)
-            .filter(term => term.length > 0);
-        if (terms.length > 1) {
-            searchQuery = terms.join(' OR ');
-        }
+}
+/**
+ * Generate smart suggestions based on current search parameters
+ */
+function generateSmartSuggestions(params) {
+    const suggestions = [];
+    // Query-specific suggestions
+    if (params.query.includes('"')) {
+        suggestions.push('Remove quotes to search for individual terms instead of exact phrase');
+    }
+    if (params.query.includes(' AND ') || params.query.includes(' OR ')) {
+        suggestions.push('Try simpler queries without boolean operators');
+    }
+    if (params.query.length > 50) {
+        suggestions.push('Simplify query - shorter terms often work better');
     }
-    // Step 4: Add GitHub-specific filters that go in the query string
-    const githubFilters = [];
-    if (filters.path) {
-        githubFilters.push(`path:${filters.path}`);
+    // Filter-specific suggestions
+    if (!params.language) {
+        suggestions.push('Add language filter - this improves results by 90%');
+    }
+    if (params.language && !params.owner && !params.filename) {
+        suggestions.push('Add owner filter to target specific organizations');
+    }
+    if (params.owner && params.repo) {
+        suggestions.push('Remove repo filter and search across all repos in the organization');
     }
-    if (filters.visibility) {
-        githubFilters.push(`visibility:${filters.visibility}`);
+    if (params.filename) {
+        suggestions.push('Remove filename filter to search all file types');
     }
-    // For complex boolean queries, add language/extension/filename/size to query string
-    const hasComplexLogic = hasComplexBooleanLogic(searchQuery);
-    if (hasComplexLogic) {
-        if (filters.language) {
-            githubFilters.push(`language:${filters.language}`);
+    if (params.extension && params.language) {
+        suggestions.push('Try removing extension filter (language filter might be sufficient)');
+    }
+    // Always provide generic fallbacks
+    if (suggestions.length === 0) {
+        suggestions.push('Try a broader search with fewer filters');
+        suggestions.push('Use more common/general terms');
+        suggestions.push('Check for typos in query or filter values');
+    }
+    return suggestions.slice(0, 5); // Limit to top 5 suggestions
+}
+/**
+ * Generate fallback queries that are likely to succeed
+ */
+function generateFallbackQueries(params) {
+    const fallbacks = [];
+    // Extract key terms from original query
+    const keyTerms = extractKeyTerms(params.query);
+    // Fallback 1: Simplify query, keep language if present
+    if (keyTerms.length > 1) {
+        const simplifiedQuery = keyTerms[0];
+        fallbacks.push({
+            query: simplifiedQuery,
+            description: `Search for just "${simplifiedQuery}"${params.language ? ` in ${params.language}` : ''}`,
+            rationale: 'Single term searches often yield better results',
+        });
+    }
+    // Fallback 2: Remove filters but keep core query
+    if (params.language || params.owner || params.filename || params.extension) {
+        fallbacks.push({
+            query: keyTerms.join(' '),
+            description: `Search "${keyTerms.join(' ')}" without filters`,
+            rationale: 'Removes restrictive filters for broader results',
+        });
+    }
+    // Fallback 3: Language-specific popular search
+    if (params.language) {
+        const popularTerms = getPopularTermsForLanguage(params.language);
+        if (popularTerms.length > 0) {
+            fallbacks.push({
+                query: popularTerms[0],
+                description: `Popular ${params.language} pattern: "${popularTerms[0]}"`,
+                rationale: `Common patterns in ${params.language} development`,
+            });
         }
-        if (filters.extension) {
-            githubFilters.push(`extension:${filters.extension}`);
+    }
+    // Fallback 4: Broader category search
+    const category = inferCategory(params.query);
+    if (category) {
+        fallbacks.push({
+            query: category,
+            description: `Broader search: "${category}"`,
+            rationale: 'Searches the general category for related patterns',
+        });
+    }
+    return fallbacks.slice(0, 4);
+}
+/**
+ * Extract key terms from search query
+ */
+function extractKeyTerms(query) {
+    // Remove quotes, boolean operators, and special characters
+    const cleaned = query
+        .replace(/["']/g, '')
+        .replace(/\b(AND|OR|NOT)\b/gi, '')
+        .replace(/[^\w\s]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned.split(' ').filter(term => term.length > 2);
+}
+/**
+ * Get popular search terms for specific programming languages
+ */
+function getPopularTermsForLanguage(language) {
+    const popularTerms = {
+        javascript: [
+            'useState',
+            'async await',
+            'fetch api',
+            'event listener',
+            'promise',
+        ],
+        typescript: [
+            'interface',
+            'generic type',
+            'type guard',
+            'enum',
+            'namespace',
+        ],
+        python: ['def function', 'import', 'class method', 'lambda', 'decorator'],
+        java: [
+            'public class',
+            'static method',
+            'interface',
+            'annotation',
+            'spring',
+        ],
+        go: ['func main', 'interface', 'goroutine', 'channel', 'struct'],
+        rust: ['fn main', 'impl', 'trait', 'enum', 'match'],
+        cpp: ['class', 'template', 'namespace', 'virtual', 'std::'],
+        c: ['int main', 'struct', 'malloc', 'pointer', 'header'],
+        php: ['function', 'class', 'namespace', 'interface', 'trait'],
+        ruby: ['def', 'class', 'module', 'block', 'gem'],
+        swift: ['func', 'class', 'protocol', 'extension', 'guard'],
+        kotlin: ['fun', 'class', 'interface', 'data class', 'coroutine'],
+        dart: ['class', 'function', 'widget', 'async', 'future'],
+        shell: ['function', 'if then', 'for loop', 'variable', 'script'],
+        yaml: ['version', 'name', 'build', 'deploy', 'config'],
+        dockerfile: ['FROM', 'RUN', 'COPY', 'EXPOSE', 'CMD'],
+    };
+    return popularTerms[language.toLowerCase()] || [];
+}
+/**
+ * Infer search category from query terms
+ */
+function inferCategory(query) {
+    const categories = {
+        authentication: [
+            'auth',
+            'login',
+            'oauth',
+            'jwt',
+            'token',
+            'passport',
+            'session',
+        ],
+        database: ['db', 'sql', 'query', 'model', 'schema', 'migration', 'orm'],
+        api: ['rest', 'graphql', 'endpoint', 'route', 'request', 'response'],
+        testing: ['test', 'spec', 'mock', 'assert', 'unit', 'integration'],
+        config: ['config', 'setting', 'env', 'environment', 'setup'],
+        ui: ['component', 'button', 'form', 'modal', 'layout', 'style'],
+        error: ['error', 'exception', 'try', 'catch', 'throw', 'handle'],
+        performance: ['cache', 'optimization', 'memory', 'speed', 'performance'],
+        security: ['security', 'encrypt', 'hash', 'validate', 'sanitize'],
+    };
+    const queryLower = query.toLowerCase();
+    for (const [category, keywords] of Object.entries(categories)) {
+        if (keywords.some(keyword => queryLower.includes(keyword))) {
+            return category;
         }
-        if (filters.filename) {
-            githubFilters.push(`filename:${filters.filename}`);
+    }
+    return null;
+}
+/**
+ * Transform GitHub CLI response to optimized format with enhanced metadata
+ */
+function transformToOptimizedFormat$1(items, params) {
+    const searchEfficiency = calculateSearchEfficiency(params);
+    // Extract repository info if single repo search
+    const singleRepo = extractSingleRepository$1(items);
+    const optimizedItems = items.map(item => ({
+        path: item.path,
+        matches: item.textMatches.map(match => ({
+            context: optimizeTextMatch(match.fragment, 120), // Increased context for better understanding
+            positions: match.matches.map(m => m.indices),
+        })),
+        url: singleRepo ? item.path : simplifyGitHubUrl(item.url),
+    }));
+    const result = {
+        items: optimizedItems,
+        total_count: items.length,
+    };
+    // Add repository info if single repo
+    if (singleRepo) {
+        result.repository = {
+            name: singleRepo.nameWithOwner,
+            url: simplifyRepoUrl(singleRepo.url),
+        };
+    }
+    // Enhanced metadata with search efficiency and tips
+    result.metadata = {
+        has_filters: !!(params.language ||
+            params.owner ||
+            params.filename ||
+            params.extension),
+        search_scope: params.match
+            ? Array.isArray(params.match)
+                ? params.match.join(',')
+                : params.match
+            : 'file',
+        search_efficiency: searchEfficiency,
+    };
+    // Add performance tips for low-efficiency searches
+    if (searchEfficiency.score < 7) {
+        result.metadata.performance_tips = generatePerformanceTips(params);
+    }
+    return result;
+}
+/**
+ * Calculate search efficiency score and provide insights
+ */
+function calculateSearchEfficiency(params) {
+    let score = 5; // Base score
+    const factors = [];
+    const recommendations = [];
+    // Language filter is huge efficiency boost
+    if (params.language) {
+        score += 3;
+        factors.push('Language filter (+3)');
+    }
+    else {
+        recommendations.push('Add language filter for 90% performance boost');
+    }
+    // Owner filter provides good targeting
+    if (params.owner) {
+        score += 2;
+        factors.push('Owner filter (+2)');
+    }
+    // Filename filter is very efficient
+    if (params.filename) {
+        score += 2;
+        factors.push('Filename filter (+2)');
+    }
+    // Extension filter adds precision
+    if (params.extension) {
+        score += 1;
+        factors.push('Extension filter (+1)');
+    }
+    // Repository filter is highly targeted
+    if (params.repo) {
+        score += 2;
+        factors.push('Repository filter (+2)');
+    }
+    // Size filter helps avoid huge files
+    if (params.size) {
+        score += 1;
+        factors.push('Size filter (+1)');
+    }
+    // Boolean operators are now properly supported
+    if (params.query.includes(' OR ')) {
+        // OR is powerful when used correctly
+        if (params.language || params.owner) {
+            score += 1;
+            factors.push('OR with filters (+1)');
         }
-        if (filters.size) {
-            githubFilters.push(`size:${filters.size}`);
+        else {
+            factors.push('OR operator (neutral)');
+            recommendations.push('Add language or owner filter with OR for better targeting');
         }
     }
-    // Step 5: Combine query with GitHub filters
-    if (githubFilters.length > 0) {
-        searchQuery = `${searchQuery} ${githubFilters.join(' ')}`;
+    if (params.query.includes(' AND ')) {
+        score += 1;
+        factors.push('AND operator (+1)');
     }
-    // Step 6: Restore exact phrases
-    exactPhrases.forEach((phrase, index) => {
-        const placeholder = `__EXACT_PHRASE_${index}__`;
-        searchQuery = searchQuery.replace(placeholder, phrase);
-    });
-    return searchQuery.trim();
+    if (params.query.includes(' NOT ')) {
+        // NOT can be useful but less efficient
+        factors.push('NOT operator (neutral)');
+        recommendations.push('Consider positive filters alongside NOT for better results');
+    }
+    if (params.query.length > 100) {
+        score -= 1;
+        factors.push('Long query (-1)');
+        recommendations.push('Simplify query for better results');
+    }
+    return {
+        score: Math.max(1, Math.min(10, score)),
+        factors,
+        recommendations,
+    };
 }
 /**
- * Check if query contains complex boolean logic that might conflict with CLI flags
+ * Generate performance tips for inefficient searches
  */
-function hasComplexBooleanLogic(query) {
-    const booleanOperators = /\b(AND|OR|NOT)\b/i;
-    return booleanOperators.test(query);
+function generatePerformanceTips(params) {
+    const tips = [];
+    if (!params.language) {
+        tips.push('Add language filter - single biggest performance boost');
+    }
+    if (!params.owner && !params.repo) {
+        tips.push('Add owner filter to target specific organizations');
+    }
+    if (params.query.includes(' OR ') && !params.language && !params.owner) {
+        tips.push('Add language or owner filter with OR for better targeting');
+    }
+    if (params.query.includes(' NOT ')) {
+        tips.push('Combine NOT with positive filters (language, filename, etc.) for best results');
+    }
+    if (!params.filename && !params.extension) {
+        tips.push('Add filename or extension filter for file-type precision');
+    }
+    return tips.slice(0, 3);
+}
+/**
+ * Extract single repository if all results are from same repo
+ */
+function extractSingleRepository$1(items) {
+    if (items.length === 0)
+        return null;
+    const firstRepo = items[0].repository;
+    const allSameRepo = items.every(item => item.repository.nameWithOwner === firstRepo.nameWithOwner);
+    return allSameRepo ? firstRepo : null;
 }
 /**
- * Build command line arguments for GitHub CLI
+ * Build command line arguments for GitHub CLI with improved parameter handling
+ * Ensures exact string search capability with proper quote and escape handling
  */
 function buildGitHubCliArgs(params) {
     const args = ['code'];
-    // Parse and add the main search query
-    const searchQuery = parseSearchQuery(params.query, params);
-    args.push(searchQuery);
-    // Add CLI flags - Always add basic flags, but be careful with complex boolean queries
-    const hasComplexLogic = hasComplexBooleanLogic(searchQuery);
-    // For complex boolean queries, add filters to the query string instead of CLI flags
-    if (hasComplexLogic) ;
+    // Handle exact string search - preserve quotes and special characters
+    const searchQuery = params.query;
+    // For exact string searches (quoted strings), preserve the quotes
+    // For special characters and escape sequences, pass them through
+    // GitHub CLI will handle the proper escaping to the GitHub API
+    if (searchQuery.includes('"') || searchQuery.includes("'")) {
+        // Already has quotes - exact string search
+        args.push(searchQuery);
+    }
+    else if (searchQuery.includes('\\') ||
+        /[<>{}[\]()&|;$`!*?~]/.test(searchQuery)) {
+        // Contains special characters that might need exact matching
+        // Let GitHub CLI handle the escaping - don't double-escape
+        args.push(searchQuery);
+    }
     else {
-        // Simple queries: use CLI flags for better performance
-        if (params.language) {
-            args.push(`--language=${params.language}`);
-        }
-        if (params.extension) {
-            args.push(`--extension=${params.extension}`);
-        }
-        if (params.filename) {
-            args.push(`--filename=${params.filename}`);
-        }
-        if (params.size) {
-            args.push(`--size=${params.size}`);
-        }
+        // Regular search query
+        args.push(searchQuery);
+    }
+    // Add filters in order of effectiveness for better CLI performance
+    if (params.language) {
+        args.push(`--language=${params.language}`);
+    }
+    if (params.filename) {
+        args.push(`--filename=${params.filename}`);
+    }
+    if (params.extension) {
+        args.push(`--extension=${params.extension}`);
     }
+    if (params.size) {
+        args.push(`--size=${params.size}`);
+    }
+    // Always add limit
     if (params.limit) {
         args.push(`--limit=${params.limit}`);
     }
-    // Handle match parameter - can be string or array
+    // Handle match parameter
     if (params.match) {
         const matchValues = Array.isArray(params.match)
             ? params.match
             : [params.match];
-        // GitHub API limitation: can't use both in:file and in:path in same query
         // Use the first match type when multiple are provided
         const matchValue = matchValues[0];
         args.push(`--match=${matchValue}`);
@@ -591,22 +1104,32 @@ function buildGitHubCliArgs(params) {
             : [params.owner];
         ownerValues.forEach(owner => args.push(`--owner=${owner}`));
     }
-    // Handle repository filters
-    if (params.owner && params.repo) {
-        const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
+    // Handle repository filters with improved validation
+    if (params.repo) {
         const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
-        // Create repo filters for each owner/repo combination
-        owners.forEach(owner => {
+        if (params.owner) {
+            const owners = Array.isArray(params.owner)
+                ? params.owner
+                : [params.owner];
+            // Create repo filters for each owner/repo combination
+            owners.forEach(owner => {
+                repos.forEach(repo => {
+                    // Handle both "owner/repo" format and just "repo" format
+                    if (repo.includes('/')) {
+                        args.push(`--repo=${repo}`);
+                    }
+                    else {
+                        args.push(`--repo=${owner}/${repo}`);
+                    }
+                });
+            });
+        }
+        else {
+            // Handle repo without owner (must be in owner/repo format)
             repos.forEach(repo => {
-                // Handle both "owner/repo" format and just "repo" format
-                if (repo.includes('/')) {
-                    args.push(`--repo=${repo}`);
-                }
-                else {
-                    args.push(`--repo=${owner}/${repo}`);
-                }
+                args.push(`--repo=${repo}`);
             });
-        });
+        }
     }
     // JSON output with all available fields
     args.push('--json=repository,path,textMatches,sha,url');
@@ -623,75 +1146,149 @@ async function searchGitHubCode(params) {
             return result;
         }
         catch (error) {
-            return createErrorResult$1('Code search command failed - verify GitHub CLI is authenticated', error);
+            const errorMessage = error.message || '';
+            // Parse specific GitHub CLI error types
+            if (errorMessage.includes('authentication')) {
+                return createResult({
+                    error: 'GitHub authentication required - run api_status_check tool',
+                });
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createResult({
+                    error: 'GitHub rate limit exceeded - use more specific filters or wait',
+                    suggestions: [
+                        'Add language filter to reduce search scope',
+                        'Use owner filter to target specific organizations',
+                        'Add filename filter for precision targeting',
+                        'Wait a few minutes and try again',
+                    ],
+                });
+            }
+            if (errorMessage.includes('validation failed') ||
+                errorMessage.includes('Invalid query')) {
+                return createResult({
+                    error: 'Invalid query syntax. GitHub legacy search has limitations.',
+                    suggestions: [
+                        'Remove NOT operators (use positive filters instead)',
+                        'Simplify OR logic to separate searches',
+                        'Use quotes for exact phrases: "error handling"',
+                        'Try: language:python + "function definition" instead of complex boolean',
+                    ],
+                });
+            }
+            if (errorMessage.includes('repository not found') ||
+                errorMessage.includes('owner not found')) {
+                return createResult({
+                    error: 'Repository or owner not found',
+                    suggestions: [
+                        'Verify exact owner/repository names (case-sensitive)',
+                        'Check if repository is private and you have access',
+                        'Remove repo filter to search across all repositories',
+                        'Use owner filter instead of specific repo for broader search',
+                    ],
+                });
+            }
+            if (errorMessage.includes('timeout')) {
+                return createResult({
+                    error: 'Search timeout - query too broad',
+                    suggestions: [
+                        'Add language filter to narrow scope',
+                        'Use owner or repo filters for targeting',
+                        'Simplify query terms',
+                        'Add filename filter for specific file types',
+                    ],
+                });
+            }
+            // Generic fallback with helpful guidance
+            return createResult({
+                error: 'Code search failed',
+                suggestions: [
+                    'Check GitHub CLI authentication with: gh auth status',
+                    'Simplify query and add language filter',
+                    'Try owner filter for targeted search',
+                    'Use api_status_check tool to verify setup',
+                ],
+            });
         }
     });
 }
+/**
+ * Enhanced validation with helpful suggestions
+ * Supports exact string search with quotes and special characters
+ */
+function validateSearchParameters(params) {
+    // Query validation
+    if (!params.query.trim()) {
+        return 'Empty query. Try: "useState", "authentication", "docker setup", or use filters like language:python';
+    }
+    if (params.query.length > 1000) {
+        return 'Query too long (max 1000 chars). Simplify to key terms like "error handling" instead of full sentences.';
+    }
+    // Repository validation - allow owner/repo format in repo field
+    if (params.repo && !params.owner) {
+        const repoValues = Array.isArray(params.repo) ? params.repo : [params.repo];
+        const hasOwnerFormat = repoValues.every(repo => repo.includes('/'));
+        if (!hasOwnerFormat) {
+            return 'Repository format error. Use "owner/repo" format like "facebook/react" or provide both owner and repo parameters.';
+        }
+    }
+    // Support exact string searches with quotes and special characters
+    // Remove overly restrictive validation for escape characters
+    // GitHub CLI and API can handle special characters properly
+    // Boolean operator validation with suggestions
+    const invalidBooleans = params.query.match(/\b(and|or|not)\b/g);
+    if (invalidBooleans) {
+        const corrected = invalidBooleans.map(op => op.toUpperCase()).join(', ');
+        return `Boolean operators must be uppercase: ${corrected}. Example: "react OR vue" not "react or vue"`;
+    }
+    return null; // No validation errors
+}
 
 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 DESCRIPTION$7 = `Read file content with exact path verification. Smart branch fallbacks and size limits. Use github_get_contents first to verify file existence.`;
 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(TOOL_NAME$7, {
         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/organization`),
+            repo: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-zA-Z0-9._-]+$/)
+                .describe(`Repository name. Case-sensitive.`),
+            branch: z
+                .string()
+                .min(1)
+                .max(255)
+                .regex(/^[^\s]+$/)
+                .describe(`Branch name. Auto-fallback to common branches if not found.`),
+            filePath: z
+                .string()
+                .min(1)
+                .describe(`File path from repository root. Use github_get_contents to explore structure.`),
+        },
+        annotations: {
+            title: 'GitHub File Content Reader',
+            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: 'File fetch failed - verify path or try github_get_contents first',
+            });
         }
     });
 }
@@ -724,19 +1321,45 @@ 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 - verify path with github_get_contents',
+                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                    });
                 }
                 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',
+                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                    });
+                }
+                else if (errorMsg.includes('maxBuffer') ||
+                    errorMsg.includes('stdout maxBuffer length exceeded')) {
+                    return createResult({
+                        error: 'File too large (>300KB) - use github_search_code for patterns instead',
+                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                    });
                 }
                 else {
-                    return createErrorResult$1('Fetch failed - check repository and file path', new Error(errorMsg));
+                    return createResult({
+                        error: 'Fetch failed - check repository and file path',
+                        cli_command: `gh api "/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}"`,
+                    });
                 }
             }
             return await processFileContent(result, owner, repo, branch, filePath);
         }
         catch (error) {
-            return createErrorResult$1('Unexpected error during file fetch - check connection and permissions', error);
+            const errorMessage = error.message;
+            // Handle maxBuffer errors that escape the main try-catch
+            if (errorMessage.includes('maxBuffer') ||
+                errorMessage.includes('stdout maxBuffer length exceeded')) {
+                return createResult({
+                    error: 'File too large (>300KB) - use github_search_code for patterns instead',
+                });
+            }
+            return createResult({
+                error: 'Unexpected error during file fetch - check connection',
+            });
         }
     });
 }
@@ -746,30 +1369,42 @@ async function processFileContent(result, owner, repo, branch, filePath) {
     const fileData = JSON.parse(execResult.result);
     // Check if it's a directory
     if (Array.isArray(fileData)) {
-        return createErrorResult$1('Path is directory - use github_get_contents to browse directory structure', new Error(filePath));
+        return createResult({
+            error: 'Path is directory - use github_get_contents instead',
+        });
     }
     const fileSize = fileData.size || 0;
-    const MAX_FILE_SIZE = 500 * 1024; // 500KB limit for simplicity
-    // Check file size
+    const MAX_FILE_SIZE = 300 * 1024; // 300KB limit for better performance and reliability
+    // Check file size with helpful message
     if (fileSize > MAX_FILE_SIZE) {
-        return createErrorResult$1('File too large - files over 500KB cannot be fetched', new Error(`${Math.round(fileSize / 1024)}KB > 500KB`));
+        const fileSizeKB = Math.round(fileSize / 1024);
+        const maxSizeKB = Math.round(MAX_FILE_SIZE / 1024);
+        return createResult({
+            error: `File too large (${fileSizeKB}KB > ${maxSizeKB}KB) - use github_search_code for patterns`,
+        });
     }
     // Get and decode content
     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: 'Empty file - 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',
+            });
         }
         decodedContent = buffer.toString('utf-8');
     }
     catch (decodeError) {
-        return createErrorResult$1('Decode failed - file encoding not supported or corrupted', new Error(filePath));
+        return createResult({
+            error: 'Decode failed - file encoding not supported',
+        });
     }
     // Return simplified response
     const response = {
@@ -784,132 +1419,275 @@ async function processFileContent(result, owner, repo, branch, filePath) {
             encoding: 'utf-8',
         },
     };
-    return createSuccessResult$1(response);
+    return createResult({ data: response });
 }
 
+/**
+ * GitHub Repository Search Tool
+ *
+ * MOST EFFECTIVE PATTERNS (based on testing):
+ *
+ * 1. Quality Discovery:
+ *    { topic: ["react", "typescript"], stars: "1000..5000", limit: 10 }
+ *
+ * 2. Organization Research:
+ *    { owner: ["microsoft", "google"], language: "python", limit: 10 }
+ *
+ * 3. Beginner Projects:
+ *    { goodFirstIssues: ">=5", stars: "100..5000", limit: 10 }
+ *
+ * 4. Recent Quality:
+ *    { stars: ">1000", created: ">2023-01-01", limit: 10 }
+ *
+ * AVOID: OR queries + language filter, 5+ filters, multi-word OR
+ * TIP: Use limit parameter instead of adding more filters
+ */
 const TOOL_NAME$6 = 'github_search_repositories';
-const DESCRIPTION$6 = `Search 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`;
+const DESCRIPTION$6 = `Search GitHub repositories with powerful GitHub search syntax and advanced filtering.
+
+EMBEDDED QUALIFIERS (MOST POWERFUL):
+- "vue OR react stars:>1000 language:javascript" - OR logic with constraints
+- "typescript AND framework stars:100..5000" - AND logic with star range  
+- "repo:facebook/react OR repo:vuejs/vue" - Multiple specific repositories
+- "org:microsoft OR org:google language:typescript" - Multiple organizations
+- "topic:react topic:typescript stars:>500" - Multiple topics with quality filter
+
+TRADITIONAL FILTERS (ALSO SUPPORTED):
+- owner: ["microsoft", "google"] - Multiple owners as array
+- topic: ["react", "typescript"] - Multiple topics as array
+- stars: "1000..5000" - Range or threshold filtering
+
+BEST PRACTICES:
+- Use embedded qualifiers for complex queries with OR/AND logic
+- Use traditional filters for simple, clean parameter-based searches
+- Combine both approaches: "vue OR react" + language:"javascript" + stars:">1000"`;
+/**
+ * Extract owner/repo information from various query formats
+ */
+function extractOwnerRepoFromQuery(query) {
+    let cleanedQuery = query;
+    let extractedOwner;
+    let extractedRepo;
+    // Pattern 1: GitHub URLs (https://github.com/owner/repo)
+    const githubUrlMatch = query.match(/github\.com\/([^\\s]+)\/([^\\s]+)/i);
+    if (githubUrlMatch) {
+        extractedOwner = githubUrlMatch[1];
+        extractedRepo = githubUrlMatch[2];
+        cleanedQuery = query
+            .replace(/https?:\/\/github\.com\/[^\\s]+\/[^\\s]+/gi, '')
+            .trim();
+    }
+    // Pattern 2: owner/repo format in query
+    const ownerRepoMatch = query.match(/\b([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\/([a-zA-Z0-9][a-zA-Z0-9\-.]*[a-zA-Z0-9])\b/);
+    if (ownerRepoMatch && !extractedOwner) {
+        extractedOwner = ownerRepoMatch[1];
+        extractedRepo = ownerRepoMatch[2];
+        cleanedQuery = query.replace(ownerRepoMatch[0], '').trim();
+    }
+    // Pattern 3: NPM package-like references (@scope/package)
+    const scopedPackageMatch = query.match(/@([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\/([a-zA-Z0-9][a-zA-Z0-9\-.]*[a-zA-Z0-9])/);
+    if (scopedPackageMatch && !extractedOwner) {
+        extractedOwner = scopedPackageMatch[1];
+        extractedRepo = scopedPackageMatch[2];
+        cleanedQuery = query.replace(scopedPackageMatch[0], '').trim();
+    }
+    return {
+        extractedOwner,
+        extractedRepo,
+        cleanedQuery: cleanedQuery || query,
+    };
+}
 function registerSearchGitHubReposTool(server) {
-    server.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,
+    server.registerTool(TOOL_NAME$6, {
         description: DESCRIPTION$6,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            query: z
+                .string()
+                .optional()
+                .describe('Search query with GitHub search syntax. POWERFUL EXAMPLES: "vue OR react stars:>1000", "typescript AND framework stars:100..5000", "repo:facebook/react OR repo:vuejs/vue", "org:microsoft language:typescript", "topic:react topic:typescript stars:>500". SUPPORTS: OR/AND logic, embedded qualifiers (stars:, language:, org:, repo:, topic:, etc.), exact repository targeting. COMBINES with traditional filters for maximum flexibility.'),
+            // CORE FILTERS (GitHub CLI flags)
+            owner: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('Repository owner/organization. HIGHLY EFFECTIVE as array ["microsoft", "google"]. FIXED: Now supports multiple owners with comma separation. Best for targeted research.'),
+            language: z
+                .string()
+                .optional()
+                .describe('Programming language filter. CAUTION: Restrictive with other filters. Use alone or with stars/owner only.'),
+            stars: z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid stars format. Use: number, ">100", ">=50", "<200", "<=100", or "10..100"'),
+            ])
+                .optional()
+                .describe('Stars filter. MOST EFFECTIVE: ranges "1000..5000", thresholds ">1000". Excellent for quality filtering.'),
+            topic: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('Topics filter. BEST PATTERN: arrays ["react", "typescript"]. FIXED: Now supports comma-separated topics. Preferred over OR queries. Combines well with stars.'),
+            forks: z.number().optional().describe('Number of forks filter.'),
+            // UPDATED: Match CLI parameter name exactly
+            numberOfTopics: z
+                .number()
+                .optional()
+                .describe('Filter by number of topics (indicates documentation quality).'),
+            // QUALITY & STATE FILTERS
+            license: z
+                .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 by: stars, updated, forks, help-wanted-issues, best-match.'),
+            order: z
+                .enum(['asc', 'desc'])
+                .optional()
+                .default('desc')
+                .describe('Sort order: asc or desc.'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(30)
+                .describe('Results limit (1-100). PREFER increasing limit over adding filters.'),
+        },
+        annotations: {
+            title: 'GitHub Repository Search',
+            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;
+            // Extract owner/repo from query if present
+            const queryInfo = args.query
+                ? extractOwnerRepoFromQuery(args.query)
+                : {
+                    cleanedQuery: '',
+                    extractedOwner: undefined,
+                    extractedRepo: undefined,
+                };
+            // Merge extracted owner with explicit owner parameter
+            let finalOwner = args.owner;
+            if (queryInfo.extractedOwner && !finalOwner) {
+                finalOwner = queryInfo.extractedOwner;
+            }
+            // Update parameters with extracted information
+            const enhancedArgs = {
+                ...args,
+                query: queryInfo.cleanedQuery || args.query,
+                owner: finalOwner,
+            };
+            // Enhanced validation logic for primary filters
+            const hasPrimaryFilter = enhancedArgs.query?.trim() ||
+                enhancedArgs.owner ||
+                enhancedArgs.language ||
+                enhancedArgs.topic ||
+                enhancedArgs.stars ||
+                enhancedArgs.forks;
             if (!hasPrimaryFilter) {
-                return createResult('Requires query or primary filter (owner, language, stars, topic, forks)', true);
+                return createResult({
+                    error: 'Requires query or primary filter (owner, language, stars, topic, forks). You can also use owner/repo format like "microsoft/vscode" in the query.',
+                });
+            }
+            // 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.',
+                                },
+                            });
+                        }
+                    }
+                }
             }
-            // 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);
+            return createResult({
+                error: 'Repository search failed - verify connection or simplify query',
+            });
         }
     });
 }
@@ -980,129 +1758,124 @@ async function searchGitHubRepos(params) {
                     license: repo.license?.name || null,
                     hasIssues: repo.hasIssues || false,
                     openIssuesCount: repo.openIssuesCount || 0,
-                    createdAt: repo.createdAt,
-                    updatedAt: repo.updatedAt,
+                    createdAt: toDDMMYYYY(repo.createdAt),
+                    updatedAt: toDDMMYYYY(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: [],
-                    }),
+            return createResult({
+                data: {
+                    total_count: analysis.totalFound,
+                    ...(analysis.totalFound > 0
+                        ? {
+                            repositories: analysis.topStarred,
+                            summary: {
+                                languages: Array.from(analysis.languages).slice(0, 10),
+                                avgStars: analysis.avgStars,
+                                recentlyUpdated: analysis.recentlyUpdated,
+                            },
+                        }
+                        : {
+                            repositories: [],
+                            cli_command: execResult.command, // Only on no results
+                        }),
+                },
             });
         }
         catch (error) {
-            return createErrorResult$1('GitHub repository search failed - verify connection or try simpler query', error);
+            return createResult({
+                error: 'Repository search failed - verify connection or simplify query',
+            });
         }
     });
 }
 function buildGitHubReposSearchCommand(params) {
-    // Build query following GitHub CLI patterns
-    const query = params.query?.trim() || '';
-    // Handle complex queries (with qualifiers, operators, or --) differently
-    const hasComplexSyntax = query.includes('--') ||
-        query.includes(':') ||
-        query.includes('OR') ||
-        query.includes('AND') ||
-        query.includes('(') ||
-        query.includes(')') ||
-        query.startsWith('-');
-    const args = ['repos'];
-    // Only add query if it exists
-    if (query) {
-        if (hasComplexSyntax) {
-            // For complex queries with special syntax, we need to be more careful
-            // Split by spaces but preserve quoted strings and handle special characters
-            const queryParts = query.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
-            queryParts.forEach(part => {
-                // If part contains shell special characters, quote it
-                if (/[><=&|$`(){}[\];\\]/.test(part) && !part.includes('"')) {
-                    args.push(`"${part}"`);
-                }
-                else {
-                    args.push(part);
-                }
-            });
-        }
-        else {
-            // For simple queries, split by spaces to match GitHub CLI examples
-            // "cli shell" becomes separate args: cli shell
-            const queryParts = query.split(/\s+/).filter(part => part.length > 0);
-            queryParts.forEach(part => {
-                // Only quote if the part contains special characters
-                if (needsQuoting(part)) {
-                    args.push(`"${part}"`);
-                }
-                else {
-                    args.push(part);
-                }
-            });
-        }
+    // Build query following GitHub CLI patterns
+    const query = params.query?.trim() || '';
+    const args = ['repos'];
+    // Detect embedded qualifiers in query to avoid conflicts and optimize
+    const hasEmbeddedQualifiers = query &&
+        /\b(stars|language|org|repo|topic|user|created|updated|size|license|archived|fork|good-first-issues|help-wanted-issues):/i.test(query);
+    // Handle exact string search - preserve quotes and special characters
+    if (query) {
+        // For exact repository name searches (quoted strings), preserve the quotes
+        // For special characters, pass them through - GitHub CLI handles escaping
+        // Support searches like "microsoft/vscode", "@types/node", etc.
+        args.push(query);
     }
     // 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}`);
+    args.push('--json=name,fullName,description,language,stargazersCount,forksCount,updatedAt,createdAt,url,owner,isPrivate,license,hasIssues,openIssuesCount,isArchived,isFork,visibility');
+    // SMART FILTER HANDLING - Avoid conflicts with embedded qualifiers
+    // Only add CLI flags if not already specified in query to prevent conflicts
+    // CORE FILTERS - Handle arrays properly
+    if (params.owner && !hasEmbeddedQualifiers) {
+        // GitHub CLI supports multiple owners with comma separation: --owner=owner1,owner2
+        const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
+        args.push(`--owner=${owners.join(',')}`);
     }
-    if (params.language)
+    if (params.language && !hasEmbeddedQualifiers)
         args.push(`--language=${params.language}`);
-    if (params.forks !== undefined)
+    if (params.forks !== undefined && !hasEmbeddedQualifiers)
         args.push(`--forks=${params.forks}`);
-    if (params.topic && params.topic.length > 0)
-        args.push(`--topic=${params.topic.join(',')}`);
+    // Handle topic as string or array - GitHub CLI expects comma-separated topics
+    if (params.topic && !hasEmbeddedQualifiers) {
+        const topics = Array.isArray(params.topic) ? params.topic : [params.topic];
+        args.push(`--topic=${topics.join(',')}`);
+    }
     if (params.numberOfTopics !== undefined)
         args.push(`--number-topics=${params.numberOfTopics}`);
-    // 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) {
-            args.push(`--stars=${params.stars}`);
+    // Handle stars as number or string - avoid conflicts with embedded qualifiers
+    if (params.stars !== undefined && !hasEmbeddedQualifiers) {
+        const starsValue = typeof params.stars === 'number'
+            ? params.stars.toString()
+            : params.stars.trim();
+        // Validate numeric patterns for string values
+        if (typeof params.stars === 'number' ||
+            /^(\d+|>\d+|<\d+|\d+\.\.\d+|>=\d+|<=\d+)$/.test(starsValue)) {
+            args.push(`--stars=${starsValue}`);
         }
     }
-    // SECONDARY FILTERS - only add if we have primary filters
+    // QUALITY & STATE 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}`);
+    // Handle license as string or array
+    if (params.license) {
+        const licenses = Array.isArray(params.license)
+            ? params.license
+            : [params.license];
+        args.push(`--license=${licenses.join(',')}`);
+    }
+    // DATE & SIZE FILTERS
+    if (params.created)
+        args.push(`--created=${params.created}`);
+    if (params.updated)
+        args.push(`--updated=${params.updated}`);
     if (params.size)
         args.push(`--size=${params.size}`);
+    // COMMUNITY FILTERS - handle both number and string
+    if (params.goodFirstIssues) {
+        const value = typeof params.goodFirstIssues === 'number'
+            ? params.goodFirstIssues.toString()
+            : params.goodFirstIssues;
+        args.push(`--good-first-issues=${value}`);
+    }
+    if (params.helpWantedIssues) {
+        const value = typeof params.helpWantedIssues === 'number'
+            ? params.helpWantedIssues.toString()
+            : params.helpWantedIssues;
+        args.push(`--help-wanted-issues=${value}`);
+    }
+    if (params.followers !== undefined)
+        args.push(`--followers=${params.followers}`);
+    // SEARCH SCOPE
+    if (params.match)
+        args.push(`--match=${params.match}`);
     // SORTING AND LIMITS
     if (params.limit)
         args.push(`--limit=${params.limit}`);
@@ -1117,376 +1890,443 @@ function buildGitHubReposSearchCommand(params) {
 }
 
 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,
+const DESCRIPTION$5 = `Search commit history effectively with GitHub's commit search. Use simple, specific terms for best results. Complex boolean queries may return limited results - try individual keywords instead.`;
+function registerGitHubSearchCommitsTool(server) {
+    server.registerTool(TOOL_NAME$5, {
         description: DESCRIPTION$5,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            query: z
+                .string()
+                .optional()
+                .describe('Search query with boolean logic. Boolean: "fix AND bug", exact phrases: "initial commit", advanced syntax: "author:john OR committer:jane".'),
+            // Repository 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'),
+            authorName: z.string().optional().describe('Filter by author name'),
+            authorEmail: z.string().optional().describe('Filter by author email'),
+            // Committer filters
+            committer: z.string().optional().describe('Filter by committer'),
+            committerName: z
+                .string()
+                .optional()
+                .describe('Filter by committer name'),
+            committerEmail: z
+                .string()
+                .optional()
+                .describe('Filter by committer email'),
+            // Date filters
+            authorDate: z
+                .string()
+                .optional()
+                .describe('Filter by authored date (format: >2020-01-01, <2023-12-31)'),
+            committerDate: z
+                .string()
+                .optional()
+                .describe('Filter by committed date (format: >2020-01-01, <2023-12-31)'),
+            // Hash filters
+            hash: z.string().optional().describe('Filter by commit hash'),
+            parent: z.string().optional().describe('Filter by parent hash'),
+            tree: z.string().optional().describe('Filter by tree hash'),
+            // State filters
+            merge: z.boolean().optional().describe('Filter merge commits'),
+            // Visibility
+            visibility: z
+                .enum(['public', 'private', 'internal'])
+                .optional()
+                .describe('Filter by repository visibility'),
+            // Pagination and sorting
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(25)
+                .describe('Maximum results (default: 25, max: 50)'),
+            sort: z
+                .enum(['author-date', 'committer-date'])
+                .optional()
+                .describe('Sort criteria (default: relevance)'),
+            order: z
+                .enum(['asc', 'desc'])
+                .optional()
+                .default('desc')
+                .describe('Order (default: desc)'),
+        },
+        annotations: {
+            title: 'GitHub Commit Search',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         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);
-            return result;
+            if (result.isError) {
+                return result;
+            }
+            const execResult = JSON.parse(result.content[0].text);
+            const commits = JSON.parse(execResult.result);
+            // GitHub CLI returns a direct array
+            const items = Array.isArray(commits) ? commits : [];
+            // Enhanced handling for no results - provide fallback suggestions
+            if (items.length === 0) {
+                return createResult({
+                    data: {
+                        commits: [],
+                        total_count: 0,
+                        cli_command: execResult.command,
+                        suggestions: {
+                            message: 'No commits found. GitHub commit search is limited compared to code/issue search.',
+                            fallback_strategies: [
+                                'Try simpler, shorter queries (single keywords work better)',
+                                "Use broader terms like 'fix' instead of 'fix useState bug'",
+                                'Search by author: add author filter for specific contributors',
+                                'Use date ranges: add authorDate or committerDate filters',
+                                'Try github_search_code tool for finding code patterns instead',
+                            ],
+                            alternative_queries: generateCommitSearchAlternatives(args.query),
+                        },
+                    },
+                });
+            }
+            // Transform to optimized format
+            const optimizedResult = transformCommitsToOptimizedFormat(items, args);
+            return createResult({ data: optimizedResult });
         }
         catch (error) {
-            return createResult('Commit search failed - check query syntax, filters, or repository access', true);
+            const errorMessage = error.message || '';
+            if (errorMessage.includes('authentication')) {
+                return createResult({
+                    error: 'GitHub authentication required - run api_status_check tool',
+                });
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createResult({
+                    error: 'GitHub rate limit exceeded - try more specific filters',
+                });
+            }
+            return createResult({
+                error: 'Commit search failed',
+                suggestions: [
+                    'Check authentication with api_status_check',
+                    'Use more specific date ranges or author filters',
+                    'Try simpler boolean queries',
+                ],
+            });
         }
     });
 }
+/**
+ * Transform GitHub CLI response to optimized format
+ */
+function transformCommitsToOptimizedFormat(items, _params) {
+    // Extract repository info if single repo search
+    const singleRepo = extractSingleRepository(items);
+    // Get unique authors for metadata
+    const uniqueAuthors = new Set(items.map(item => item.commit?.author?.name || item.author?.login || 'Unknown')).size;
+    const optimizedCommits = items
+        .map(item => ({
+        sha: item.sha,
+        message: getCommitTitle(item.commit?.message || ''),
+        author: item.commit?.author?.name || item.author?.login || 'Unknown',
+        date: toDDMMYYYY(item.commit?.author?.date || ''),
+        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,
+        };
+    }
+    // Add metadata for insights
+    if (items.length > 1) {
+        result.metadata = {
+            timeframe: getTimeframe(items),
+            unique_authors: uniqueAuthors,
+        };
+    }
+    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;
+}
+/**
+ * Calculate timeframe of commits
+ */
+function getTimeframe(items) {
+    if (items.length === 0)
+        return '';
+    const dates = items.map(item => new Date(item.commit?.author?.date || ''));
+    const oldest = new Date(Math.min(...dates.map(d => d.getTime())));
+    const newest = new Date(Math.max(...dates.map(d => d.getTime())));
+    const diffMs = newest.getTime() - oldest.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays === 0)
+        return 'same day';
+    if (diffDays < 7)
+        return `${diffDays} days`;
+    if (diffDays < 30)
+        return `${Math.floor(diffDays / 7)} weeks`;
+    if (diffDays < 365)
+        return `${Math.floor(diffDays / 30)} months`;
+    return `${Math.floor(diffDays / 365)} years`;
+}
+/**
+ * Generate alternative commit search queries when original query fails
+ */
+function generateCommitSearchAlternatives(originalQuery) {
+    if (!originalQuery) {
+        return [
+            { query: 'fix', reason: 'Search for general fixes' },
+            { query: 'bug', reason: 'Search for bug-related commits' },
+            { query: 'refactor', reason: 'Search for refactoring commits' },
+        ];
+    }
+    const alternatives = [];
+    const query = originalQuery.toLowerCase();
+    // Extract key terms and create simpler alternatives
+    if (query.includes('fix') && query.includes('bug')) {
+        alternatives.push({ query: 'fix', reason: 'Broader search for all fixes' }, { query: 'bug', reason: 'Search for bug-related commits' });
+    }
+    else if (query.includes(' ')) {
+        // Multi-word query - suggest individual terms
+        const words = query.split(' ').filter(w => w.length > 2);
+        words.slice(0, 2).forEach(word => {
+            alternatives.push({
+                query: word,
+                reason: `Single keyword search for '${word}'`,
+            });
+        });
+    }
+    // Always suggest some common commit patterns
+    alternatives.push({ query: 'feat', reason: 'Search for feature commits' }, { query: 'docs', reason: 'Search for documentation updates' });
+    return alternatives.slice(0, 4); // Limit to 4 suggestions
+}
 async function searchGitHubCommits(params) {
     const cacheKey = generateCacheKey('gh-commits', params);
     return withCache(cacheKey, async () => {
         try {
-            const { command, args } = buildGitHubCommitsSearchCommand(params);
-            const result = await executeGitHubCommand(command, args, {
+            const args = buildGitHubCommitCliArgs(params);
+            const result = await executeGitHubCommand('search', args, {
                 cache: false,
             });
-            if (result.isError) {
-                return result;
-            }
-            // Extract the actual content from the exec result
-            const execResult = JSON.parse(result.content[0].text);
-            const rawContent = execResult.result;
-            // Parse JSON results and provide structured analysis
-            let 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);
-                    }
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error.message || '';
+            if (errorMessage.includes('authentication')) {
+                return createResult({
+                    error: 'GitHub authentication required',
                 });
-                // 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),
-                    },
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createResult({
+                    error: 'GitHub rate limit exceeded',
                 });
             }
-            return createSuccessResult$1({
-                query: params.query,
-                total: 0,
-                commits: [],
+            return createResult({
+                error: 'Commit search execution failed',
             });
         }
-        catch (error) {
-            return createErrorResult$1('GitHub commit search failed - verify repository exists or try different filters', error);
-        }
     });
 }
-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('-');
+function buildGitHubCommitCliArgs(params) {
     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 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());
     }
-    // Add JSON output with commit fields
-    args.push('--json', 'author,commit,committer,id,parents,repository,sha,url');
-    // Add all filters
+    // 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.authorDate)
-        args.push(`--author-date="${params.authorDate}"`);
+    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}`);
-    }
-    else if (params.repo) {
-        args.push(`--repo=${params.repo}`);
-    }
-    else if (params.owner) {
-        args.push(`--owner=${params.owner}`);
-    }
-    // Sorting
-    const sortBy = params.sort || 'best-match';
-    if (sortBy !== 'best-match') {
-        args.push(`--sort=${sortBy}`);
-    }
+    // Sorting and pagination
+    if (params.sort)
+        args.push(`--sort=${params.sort}`);
     if (params.order)
         args.push(`--order=${params.order}`);
-    // Limit
     if (params.limit)
         args.push(`--limit=${params.limit}`);
-    return { command: 'search', args };
+    // JSON output
+    args.push('--json=sha,commit,author,committer,repository,url,parents');
+    return args;
 }
 
 // TODO: add PR commeents. e.g, gh pr view <PR_NUMBER_OR_URL_OR_BRANCH> --comments
 const TOOL_NAME$4 = 'github_search_pull_requests';
-const DESCRIPTION$4 = `Find pull requests and implementations with detailed metadata. Discover how features were implemented, code review patterns, and development workflows.
-
-SEARCH PATTERNS SUPPORTED:
-• BOOLEAN OPERATORS: "fix AND bug" (both required), "refactor OR cleanup" (either term), "feature NOT draft" (excludes draft)
-• EXACT PHRASES: "initial commit" (precise phrase matching)
-• GITHUB QUALIFIERS: Built-in support for "is:merged", "review:approved", "base:main", etc.
-• COMBINABLE: Mix search terms with filters for targeted PR discovery
-
-Filter by state, author, reviewer, or merge status for comprehensive development workflow analysis.`;
+const DESCRIPTION$4 = `Find pull requests and implementations with detailed metadata. Discover feature implementations, code review patterns, and development workflows.`;
 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,
+    server.registerTool(TOOL_NAME$4, {
         description: DESCRIPTION$4,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            query: z
+                .string()
+                .min(1, 'Search query is required and cannot be empty')
+                .describe('Search query with GitHub syntax. Boolean: "fix AND bug", exact phrases: "initial commit", qualifiers: "is:merged review:approved".'),
+            owner: z.string().optional().describe('Repository owner/organization'),
+            repo: z.string().optional().describe('Repository name'),
+            author: z.string().optional().describe('Filter by pull request author'),
+            assignee: z.string().optional().describe('Filter by assignee'),
+            mentions: z.string().optional().describe('Filter by user mentions'),
+            commenter: z.string().optional().describe('Filter by comments by user'),
+            involves: z.string().optional().describe('Filter by user involvement'),
+            reviewedBy: z
+                .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'),
+            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)'),
+        },
+        annotations: {
+            title: 'GitHub Pull Requests Search',
+            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: 'Search query is required and cannot be empty - provide keywords to search for pull requests',
+            });
         }
         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: 'Search query is too long. Please limit to 256 characters or less - simplify your search terms',
+            });
         }
         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: 'GitHub pull requests search failed - verify repository access and query syntax',
+            });
         }
     });
 }
@@ -1509,8 +2349,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,
@@ -1520,7 +2360,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)
@@ -1528,15 +2368,13 @@ async function searchGitHubPullRequests(params) {
             return result;
         });
         const searchResult = {
-            searchType: 'prs',
-            query: params.query || '',
             results: cleanPRs,
+            total_count: apiResponse.total_count || cleanPRs.length,
             metadata: {
-                total_count: apiResponse.total_count || 0,
                 incomplete_results: apiResponse.incomplete_results || false,
             },
         };
-        return createSuccessResult$1(searchResult);
+        return createResult({ data: searchResult });
     });
 }
 function buildGitHubPullRequestsAPICommand(params) {
@@ -1597,36 +2435,32 @@ function buildGitHubPullRequestsAPICommand(params) {
 }
 
 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 DESCRIPTION$3 = `Search npm packages by keywords using fuzzy matching. Use space-separated keywords like "react hooks" or "cli typescript". No boolean operators supported.`;
 const MAX_DESCRIPTION_LENGTH = 100;
 const MAX_KEYWORDS = 10;
 function registerNpmSearchTool(server) {
-    server.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,
+    server.registerTool(TOOL_NAME$3, {
         description: DESCRIPTION$3,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            queries: z
+                .union([z.string(), z.array(z.string())])
+                .describe('Package names or keywords to search for. Use simple space-separated keywords like "react hooks" or "typescript cli" for fuzzy matching.'),
+            searchlimit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(20)
+                .describe('Max results per query (default: 20, max: 50)'),
+        },
+        annotations: {
+            title: 'NPM Package Search',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         try {
             const queries = Array.isArray(args.queries)
@@ -1645,17 +2479,22 @@ function registerNpmSearchTool(server) {
             const deduplicatedPackages = deduplicatePackages(allPackages);
             if (deduplicatedPackages.length > 0) {
                 return createResult({
-                    query: Array.isArray(args.queries)
-                        ? args.queries.join(', ')
-                        : args.queries,
-                    total: deduplicatedPackages.length,
-                    results: deduplicatedPackages,
+                    data: {
+                        total_count: deduplicatedPackages.length,
+                        results: deduplicatedPackages,
+                    },
                 });
             }
-            return createResult('No packages found', true);
+            return createResult({
+                error: 'No packages found',
+                cli_command: `npm search ${Array.isArray(args.queries) ? args.queries.join(' ') : args.queries}`,
+            });
         }
         catch (error) {
-            return createResult('NPM package search failed - check search terms or try different keywords', true);
+            return createResult({
+                error: 'Package search failed - check terms or try different keywords',
+                cli_command: `npm search ${Array.isArray(args.queries) ? args.queries.join(' ') : args.queries}`,
+            });
         }
     });
 }
@@ -1708,70 +2547,54 @@ function parseNpmSearchOutput(output) {
 }
 
 const TOOL_NAME$2 = 'github_get_contents';
-const DESCRIPTION$2 = `Browse repository structure and verify file existence. Use before github_get_file_content to confirm files exist and understand organization, especially when the path is uncertain.`;
+const DESCRIPTION$2 = `Browse repository structure and verify file existence. Smart branch detection with fallbacks. Use before fetching files to understand organization.`;
 function registerViewRepositoryStructureTool(server) {
-    server.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,
+    server.registerTool(TOOL_NAME$2, {
         description: DESCRIPTION$2,
-        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/organization.`),
+            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('Target branch name. Auto-detects default 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 Contents',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, async (args) => {
         try {
             const result = await viewRepositoryStructure(args);
-            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;
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            return createResult(`Repository exploration failed: ${errorMessage} - verify repository exists and is accessible`, true);
+            return createResult({
+                error: `Repository exploration failed: ${errorMessage} - verify access and permissions`,
+            });
         }
     });
 }
@@ -1784,6 +2607,7 @@ function registerViewRepositoryStructureTool(server) {
  * - Input validation: prevents path traversal and validates GitHub naming
  * - Clear error context: provides descriptive error messages
  * - Efficient caching: avoids redundant API calls
+ * - Rich metadata: includes all GitHub API fields (sha, urls, links, etc.)
  */
 async function viewRepositoryStructure(params) {
     const cacheKey = generateCacheKey('gh-repo-structure', params);
@@ -1825,17 +2649,25 @@ async function viewRepositoryStructure(params) {
                 const errorMsg = lastError?.message || 'Unknown error';
                 if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
                     if (path) {
-                        throw new Error(`Path "${path}" not found - verify path exists or use github_search_code to find files`);
+                        return createResult({
+                            error: `Path "${path}" not found - verify path or use code search`,
+                        });
                     }
                     else {
-                        throw new Error(`Repository not found: ${owner}/${repo} - verify owner/repo names or use github_search_repositories`);
+                        return createResult({
+                            error: `Repository not found: ${owner}/${repo} - verify names`,
+                        });
                     }
                 }
                 else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
-                    throw new Error(`Access denied to repository ${owner}/${repo} - repository may be private or require authentication`);
+                    return createResult({
+                        error: `Access denied to ${owner}/${repo} - check permissions`,
+                    });
                 }
                 else {
-                    throw new Error(`Access failed: ${owner}/${repo} - check connection or repository permissions`);
+                    return createResult({
+                        error: `Access failed: ${owner}/${repo} - check connection`,
+                    });
                 }
             }
             // Limit total items to 100 for efficiency
@@ -1847,53 +2679,54 @@ async function viewRepositoryStructure(params) {
                 }
                 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
+            // Create simplified, token-efficient structure
             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
-                };
-            });
+                .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 => `${item.name}/`);
+                .map(item => ({
+                name: item.name,
+                url: item.path, // Use path for browsing
+            }));
+            // Simplified result structure - token efficient
             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}'`,
+                repository: `${owner}/${repo}`,
+                branch: usedBranch,
+                path: cleanPath || '/',
+                githubBasePath: `https://api.github.com/repos/${owner}/${repo}/contents/`,
+                files: {
+                    count: files.length,
+                    files: files,
+                },
+                folders: {
+                    count: folders.length,
+                    folders: folders,
+                },
+                ...((usedBranch !== branch || limitedItems.length === 100) && {
+                    metadata: {
+                        ...(usedBranch !== branch && {
+                            branchFallback: {
+                                requested: branch,
+                                used: usedBranch,
+                            },
+                        }),
+                        ...(limitedItems.length === 100 && {
+                            truncated: true,
+                        }),
                     },
                 }),
             };
-            return createSuccessResult$1(result);
+            return createResult({ data: 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));
+            return createResult({
+                error: `Repository access failed - verify repository and authentication: ${error}`,
+            });
         }
     });
 }
@@ -1930,133 +2763,152 @@ async function getSmartBranchFallback(owner, repo, requestedBranch) {
 }
 
 const TOOL_NAME$1 = 'github_search_issues';
-const DESCRIPTION$1 = `Find GitHub issues and problems with rich metadata (labels, reactions, comments, state). Discover pain points, feature requests, bug patterns, and community discussions.
-
-SEARCH PATTERNS SUPPORTED:
-• BOOLEAN OPERATORS: "bug AND crash" (both required), "feature OR enhancement" (either term), "error NOT test" (excludes test)
-• EXACT PHRASES: "memory leak" (precise phrase matching)
-• GITHUB QUALIFIERS: Built-in support for "is:open", "label:bug", "author:username", etc.
-• COMBINABLE: Mix search terms with filters for surgical precision
-
-Filter by state, labels, assignee, or date ranges for comprehensive issue discovery.`;
+const DESCRIPTION$1 = `Find GitHub issues with rich metadata. Discover pain points, feature requests, and bug patterns with boolean logic and GitHub qualifiers.`;
 function registerSearchGitHubIssuesTool(server) {
-    server.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,
+    server.registerTool(TOOL_NAME$1, {
         description: DESCRIPTION$1,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            query: z
+                .string()
+                .min(1, 'Search query is required and cannot be empty')
+                .describe('Search query with GitHub syntax. Boolean: "bug AND crash", exact phrases: "memory leak", qualifiers: "is:open label:bug".'),
+            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'),
+            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)'),
+        },
+        annotations: {
+            title: 'GitHub Issues Search',
+            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'));
+            return createResult({
+                error: 'Search query is required and cannot be empty - provide keywords to search for issues',
+            });
         }
         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: 'Search query is too long. Please limit to 256 characters or less - simplify your search terms',
+            });
         }
         try {
             return await searchGitHubIssues(args);
         }
         catch (error) {
-            return createErrorResult$1('GitHub issues search failed - check repository exists and query is valid', error);
+            const errorMessage = error instanceof Error ? error.message : '';
+            if (errorMessage.includes('authentication')) {
+                return createResult({
+                    error: 'GitHub authentication required - run api_status_check tool',
+                });
+            }
+            if (errorMessage.includes('rate limit')) {
+                return createResult({
+                    error: 'GitHub rate limit exceeded - wait or use specific filters',
+                });
+            }
+            // Generic fallback
+            return createResult({
+                error: 'GitHub issue search failed - check authentication or simplify query',
+            });
         }
     });
 }
@@ -2078,34 +2930,55 @@ async function searchGitHubIssues(params) {
             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,
+            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 = {
-            searchType: 'issues',
-            query: params.query || '',
             results: cleanIssues,
+            total_count: apiResponse.total_count || cleanIssues.length,
             metadata: {
-                total_count: apiResponse.total_count || 0,
                 incomplete_results: apiResponse.incomplete_results || false,
             },
         };
-        return createSuccessResult$1(searchResult);
+        return createResult({ data: searchResult });
     });
 }
 function buildGitHubIssuesAPICommand(params) {
-    const queryParts = [params.query?.trim() || ''];
-    // Repository/organization qualifiers
+    const queryParts = [];
+    // Start with the base query, but filter out qualifiers that will be added separately
+    const baseQuery = params.query?.trim() || '';
+    // Extract and remove qualifiers from the main query to avoid conflicts
+    const qualifierPatterns = [
+        /\bis:(open|closed)\b/gi,
+        /\blabel:("[^"]*"|[^\s]+)/gi,
+        /\bcreated:([^\s]+)/gi,
+        /\bupdated:([^\s]+)/gi,
+        /\bauthor:([^\s]+)/gi,
+        /\bassignee:([^\s]+)/gi,
+        /\bstate:(open|closed)/gi,
+        /\brepo:([^\s]+)/gi,
+        /\borg:([^\s]+)/gi,
+    ];
+    // Remove extracted qualifiers from base query
+    let cleanQuery = baseQuery;
+    qualifierPatterns.forEach(pattern => {
+        cleanQuery = cleanQuery.replace(pattern, '').trim();
+    });
+    // Add the cleaned query if it has content
+    if (cleanQuery) {
+        queryParts.push(cleanQuery);
+    }
+    // Repository/organization qualifiers - prioritize function params over query
     if (params.owner && params.repo) {
         queryParts.push(`repo:${params.owner}/${params.repo}`);
     }
     else if (params.owner) {
         queryParts.push(`org:${params.owner}`);
     }
-    // Build search qualifiers from params
+    // Build search qualifiers from function parameters (these take precedence)
     const qualifiers = {
         author: params.author,
         assignee: params.assignee,
@@ -2122,9 +2995,10 @@ function buildGitHubIssuesAPICommand(params) {
         if (value)
             queryParts.push(`${key}:${value}`);
     });
-    // Special qualifiers
-    if (params.labels)
+    // Special qualifiers - handle labels carefully
+    if (params.labels) {
         queryParts.push(`label:"${params.labels}"`);
+    }
     if (params.milestone)
         queryParts.push(`milestone:"${params.milestone}"`);
     if (params.noAssignee)
@@ -2139,6 +3013,26 @@ function buildGitHubIssuesAPICommand(params) {
         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}`;
@@ -2150,95 +3044,160 @@ function buildGitHubIssuesAPICommand(params) {
 }
 
 const TOOL_NAME = 'npm_view_package';
-const DESCRIPTION = `use npm view to get package metadata. You can get the package
-name from search results or user input. This tool is effieicnt since it gets important package metadata
-on a package fast to optimize tools calls. get package git repository path easily without need to search it (using repo/code search tools),
-exported files of a package are there, along with dependencies and version history.`;
+const DESCRIPTION = `Get comprehensive NPM package metadata efficiently. Returns repository URL, exports, dependencies, and version history. 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,
+    server.registerTool(TOOL_NAME, {
         description: DESCRIPTION,
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
+        inputSchema: {
+            packageName: z
+                .string()
+                .min(1)
+                .describe('NPM package name to analyze. Returns complete package context including exports (critical for GitHub file discovery), repository URL, dependencies, and version history.'),
+        },
+        annotations: {
+            title: 'NPM Package Metadata',
+            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);
-            }
-            // 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);
+            const result = await viewNpmPackage(args.packageName);
+            if (result.isError) {
+                return result;
             }
-            const result = await npmViewPackage(args.packageName);
-            return result;
+            const execResult = JSON.parse(result.content[0].text);
+            const packageData = JSON.parse(execResult.result);
+            // Transform to optimized format
+            const optimizedResult = transformToOptimizedFormat(packageData);
+            return createResult({ data: optimizedResult });
         }
         catch (error) {
-            return createResult('Failed to get package metadata - verify package exists on NPM registry', true);
+            const errorMessage = error.message || '';
+            if (errorMessage.includes('not found')) {
+                return createResult({
+                    error: 'Package not found - verify package name spelling',
+                    cli_command: `npm view ${args.packageName} --json`,
+                });
+            }
+            if (errorMessage.includes('network')) {
+                return createResult({
+                    error: 'Network error - check internet connection',
+                    cli_command: `npm view ${args.packageName} --json`,
+                });
+            }
+            return createResult({
+                error: 'NPM package lookup failed',
+                cli_command: `npm view ${args.packageName} --json`,
+                suggestions: [
+                    'Verify package name is correct',
+                    'Check if package exists on npmjs.com',
+                    'Try again in a moment',
+                ],
+            });
         }
     });
 }
-// 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 })),
+/**
+ * Transform NPM CLI response to optimized format
+ */
+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 = 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: Object.keys(time || {}).length - 2, // exclude 'created' and 'modified'
-            official: versions.length,
+            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;
+    }
+    return result;
+}
+/**
+ * Simplify exports object to essential entry points
+ */
+function simplifyExports(exports) {
+    if (typeof exports === 'string') {
+        return { main: exports };
+    }
+    if (typeof exports === 'object') {
+        const simplified = {};
+        // Extract main entry point
+        if (exports['.']) {
+            const mainExport = exports['.'];
+            if (typeof mainExport === 'string') {
+                simplified.main = mainExport;
+            }
+            else if (mainExport.default) {
+                simplified.main = mainExport.default;
+            }
+            else if (mainExport.import) {
+                simplified.main = mainExport.import;
+            }
+        }
+        // Extract types if available
+        if (exports['./types'] || exports['.']?.types) {
+            simplified.types = exports['./types'] || exports['.'].types;
+        }
+        // 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',
+                });
+            }
+            return createResult({
+                error: 'NPM command execution failed',
+            });
         }
     });
 }
@@ -2258,7 +3217,7 @@ function registerAllTools(server) {
             fn: registerFetchGitHubFileContentTool,
         },
         { name: 'SearchGitHubRepos', fn: registerSearchGitHubReposTool },
-        { name: 'SearchGitHubCommits', fn: registerSearchGitHubCommitsTool },
+        { name: 'SearchGitHubCommits', fn: registerGitHubSearchCommitsTool },
         {
             name: 'SearchGitHubPullRequests',
             fn: registerSearchGitHubPullRequestsTool,