octocode-mcp 2.3.6 → 2.3.7

package/build/index.js

@@ -107,9 +107,9 @@ function escapeShellArg(arg, shellType, isGitHubQuery // Flag to indicate if thi
         const isWindows = platform() === 'win32';
         shellType = isWindows ? 'cmd' : 'unix';
     }
-    // Special handling for GitHub search queries
+    // Special handling for GitHub search queries to preserve AND logic
     if (isGitHubQuery) {
-        // If the argument already contains quotes, preserve them
+        // If the argument already contains quotes, preserve them for exact phrases
         if (arg.includes('"')) {
             // For Unix-like shells, wrap the entire argument in single quotes
             if (shellType === 'unix') {
@@ -122,6 +122,13 @@ function escapeShellArg(arg, shellType, isGitHubQuery // Flag to indicate if thi
             // For PowerShell
             return `'${arg.replace(/'/g, "''")}'`;
         }
+        // For space-separated terms (AND search), minimize escaping
+        if (arg.includes(' ') && shellType === 'unix') {
+            // Only escape if contains dangerous shell characters
+            if (!/[;&|<>$`\\]/.test(arg)) {
+                return `"${arg}"`;
+            }
+        }
     }
     switch (shellType) {
         case 'powershell':
@@ -158,16 +165,28 @@ function escapeWindowsCmdArg(arg) {
 }
 /**
  * Escape arguments for Unix shells with special handling for GitHub CLI queries
+ * Preserves AND search logic by not over-escaping space-separated terms
  */
 function escapeUnixShellArg(arg, isGitHubQuery) {
-    // If it's a GitHub search query with special characters or spaces
-    if (isGitHubQuery && (arg.includes(' ') || /[:"']/g.test(arg))) {
-        // Preserve existing quotes if present
+    // For GitHub search queries, we need to preserve AND logic
+    if (isGitHubQuery) {
+        // If the query contains quotes, preserve them for exact phrase matching
         if (arg.includes('"')) {
+            // Use single quotes to wrap the entire query while preserving internal quotes
+            return `'${arg.replace(/'/g, "'\"'\"'")}'`;
+        }
+        // For space-separated terms (AND search), only escape if absolutely necessary
+        // GitHub CLI expects space-separated terms for AND logic
+        if (arg.includes(' ') && !/[;&|<>$`\\]/.test(arg)) {
+            // Only wrap in quotes if it contains shell metacharacters beyond spaces
+            return `"${arg}"`;
+        }
+        // For single terms or terms with special chars, escape normally
+        if (/[;&|<>$`\\]/.test(arg)) {
             return `'${arg.replace(/'/g, "'\"'\"'")}'`;
         }
-        // Add double quotes for terms that need them
-        return `"${arg}"`;
+        // Simple terms don't need escaping
+        return arg;
     }
     // Standard Unix shell escaping for other arguments
     if (/[^a-zA-Z0-9\-_./=@:]/.test(arg)) {
@@ -313,61 +332,6 @@ async function executeCommand(fullCommand, type, options = {}, shellConfig) {
     }
 }
 
-var LogLevel;
-(function (LogLevel) {
-    LogLevel["ERROR"] = "ERROR";
-    LogLevel["WARN"] = "WARN";
-    LogLevel["INFO"] = "INFO";
-    LogLevel["DEBUG"] = "DEBUG";
-})(LogLevel || (LogLevel = {}));
-class Logger {
-    appName;
-    timestamp;
-    constructor(appName = 'octocode-mcp', timestamp = true) {
-        this.appName = appName;
-        this.timestamp = timestamp;
-    }
-    formatMessage(level, message, ...args) {
-        const timestamp = this.timestamp ? `[${new Date().toISOString()}] ` : '';
-        const prefix = `${timestamp}[${this.appName}] [${level}]`;
-        const formattedArgs = args.length > 0
-            ? ' ' +
-                args
-                    .map(arg => {
-                    if (arg instanceof Error) {
-                        return `${arg.message}\n${arg.stack}`;
-                    }
-                    return typeof arg === 'object'
-                        ? JSON.stringify(arg, null, 2)
-                        : String(arg);
-                })
-                    .join(' ')
-            : '';
-        return `${prefix} ${message}${formattedArgs}`;
-    }
-    error(message, ...args) {
-        // eslint-disable-next-line no-console
-        console.error(this.formatMessage(LogLevel.ERROR, message, ...args));
-    }
-    warn(message, ...args) {
-        // eslint-disable-next-line no-console
-        console.warn(this.formatMessage(LogLevel.WARN, message, ...args));
-    }
-    info(message, ...args) {
-        // eslint-disable-next-line no-console
-        console.log(this.formatMessage(LogLevel.INFO, message, ...args));
-    }
-    debug(message, ...args) {
-        if (process.env.DEBUG === 'true' ||
-            process.env.NODE_ENV === 'development') {
-            // eslint-disable-next-line no-console
-            console.log(this.formatMessage(LogLevel.DEBUG, message, ...args));
-        }
-    }
-}
-// Singleton instance
-const logger = new Logger();
-
 function createResult(options) {
     const { data, error } = options;
     if (error) {
@@ -387,7 +351,6 @@ function createResult(options) {
         };
     }
     catch (jsonError) {
-        logger.error('JSON serialization failed:', jsonError);
         return {
             content: [
                 {
@@ -783,11 +746,13 @@ async function viewRepositoryStructure(params) {
             let usedBranch = branch;
             let lastError = null;
             let attemptCount = 0;
-            const maxAttempts = 3; // Prevent infinite loops
+            const maxAttempts = branchesToTry.length;
+            const triedBranches = [];
             for (const tryBranch of branchesToTry) {
                 if (attemptCount >= maxAttempts)
                     break;
                 attemptCount++;
+                triedBranches.push(tryBranch);
                 try {
                     const apiPath = `/repos/${owner}/${repo}/contents/${cleanPath}?ref=${tryBranch}`;
                     const result = await executeGitHubCommand('api', [apiPath], {
@@ -806,33 +771,52 @@ async function viewRepositoryStructure(params) {
                 }
                 catch (error) {
                     lastError = error instanceof Error ? error : new Error(String(error));
-                    // Try next branch
                     continue;
                 }
             }
             if (items.length === 0) {
-                // Use the most descriptive error message
+                // Check repository existence only after content fetch fails
+                const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+                    cache: false,
+                });
+                if (repoCheckResult.isError) {
+                    const repoErrorMsg = repoCheckResult.content[0].text;
+                    if (repoErrorMsg.includes('404')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" not found. It might have been deleted, renamed, or made private. Use github_search_code to find current location.`,
+                        });
+                    }
+                    else if (repoErrorMsg.includes('403')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" exists but access is denied. Repository might be private or archived. Use api_status_check to verify permissions.`,
+                        });
+                    }
+                }
                 const errorMsg = lastError?.message || 'Unknown error';
                 if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
                     if (path) {
+                        const searchSuggestion = await suggestPathSearchFallback(owner, path);
                         return createResult({
-                            error: `Path "${path}" not found. Verify the path or use github_search_code to find files`,
+                            error: `Path "${path}" not found in any branch (tried: ${triedBranches.join(', ')}).${searchSuggestion}`,
                         });
                     }
                     else {
                         return createResult({
-                            error: `Repository not found: ${owner}/${repo}. Check spelling and case sensitivity`,
+                            error: `Repository "${owner}/${repo}" structure not accessible. Repository might be empty, private, or you might not have sufficient permissions. Use github_search_code with owner="${owner}" to find accessible repositories.`,
                         });
                     }
                 }
                 else if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
                     return createResult({
-                        error: `Access denied to ${owner}/${repo}. Repository may be private - use api_status_check`,
+                        error: `Access denied to "${owner}/${repo}". Repository exists but might be private/archived. Use api_status_check to verify permissions, or github_search_code with owner="${owner}" to find accessible repositories.`,
                     });
                 }
                 else {
+                    const searchSuggestion = path
+                        ? await suggestPathSearchFallback(owner, path)
+                        : '';
                     return createResult({
-                        error: `Failed to access ${owner}/${repo}. Check network connection`,
+                        error: `Failed to access "${owner}/${repo}": ${errorMsg}. Check network connection and repository permissions.${searchSuggestion}`,
                     });
                 }
             }
@@ -877,17 +861,19 @@ async function viewRepositoryStructure(params) {
             });
         }
         catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
             return createResult({
-                error: `Failed to access repository. ${error}. Verify repository name and authentication`,
+                error: `Failed to access repository "${owner}/${repo}": ${errorMessage}. Verify repository name, permissions, and network connection.`,
             });
         }
     });
 }
 /**
  * Smart branch detection with automatic fallback to common branch names.
+ * Now includes more comprehensive branch detection and better error handling.
  */
 async function getSmartBranchFallback(owner, repo, requestedBranch) {
-    const branches = [requestedBranch];
+    const branches = new Set([requestedBranch]);
     try {
         // Try to get repository info to find default branch
         const repoInfoResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
@@ -897,22 +883,48 @@ async function getSmartBranchFallback(owner, repo, requestedBranch) {
             const execResult = JSON.parse(repoInfoResult.content[0].text);
             const repoData = execResult.result;
             const defaultBranch = repoData.default_branch;
-            if (defaultBranch && !branches.includes(defaultBranch)) {
-                branches.push(defaultBranch);
+            if (defaultBranch) {
+                branches.add(defaultBranch);
             }
         }
     }
     catch {
         // If we can't get repo info, proceed with standard fallbacks
     }
-    // Add common branch names if not already included
-    const commonBranches = ['main', 'master', 'develop', 'dev'];
-    commonBranches.forEach(branch => {
-        if (!branches.includes(branch)) {
-            branches.push(branch);
-        }
+    // Add only main/master as fallback branches
+    const commonBranches = ['main', 'master'];
+    commonBranches.forEach(branch => branches.add(branch));
+    // Convert Set back to array, with requested branch first
+    const branchesArray = Array.from(branches);
+    branchesArray.sort((a, b) => {
+        if (a === requestedBranch)
+            return -1;
+        if (b === requestedBranch)
+            return 1;
+        return 0;
     });
-    return branches;
+    return branchesArray;
+}
+// Helper function to suggest path search strategy
+async function suggestPathSearchFallback(owner, path) {
+    try {
+        // Extract last path segment and try to find in same organization
+        const pathSegment = path.split('/').pop() || path;
+        const searchResult = await executeGitHubCommand('api', [
+            `/search/code?q=${encodeURIComponent(pathSegment)}+in:path+org:${owner}`,
+        ], { cache: false });
+        if (!searchResult.isError) {
+            const results = JSON.parse(searchResult.content[0].text);
+            if (results.total_count > 0) {
+                const firstMatch = results.items[0];
+                return ` Directory might be in ${firstMatch.repository.full_name}. Try these searches:\n1. github_search_code with query="${pathSegment}" owner="${owner}"\n2. github_search_code with query="path:${path}" owner="${owner}"`;
+            }
+        }
+    }
+    catch {
+        // Fallback to generic message if search fails
+    }
+    return ` Try these searches:\n1. github_search_code with query="${path.split('/').pop()}" owner="${owner}"\n2. github_search_code with query="path:${path}"`;
 }
 
 const GITHUB_GET_FILE_CONTENT_TOOL_NAME = 'githubGetFileContent';
@@ -969,18 +981,39 @@ async function fetchGitHubFileContent(params) {
         const { owner, repo, branch, filePath } = params;
         try {
             // Try to fetch file content directly
-            const apiPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${branch}`;
+            const apiPath = `/repos/${owner}/${repo}/contents/${filePath}`;
             const result = await executeGitHubCommand('api', [apiPath], {
                 cache: false,
             });
             if (result.isError) {
                 const errorMsg = result.content[0].text;
+                // Check repository existence only after content fetch fails
+                const repoCheckResult = await executeGitHubCommand('api', [`/repos/${owner}/${repo}`], {
+                    cache: false,
+                });
+                if (repoCheckResult.isError) {
+                    const repoErrorMsg = repoCheckResult.content[0].text;
+                    if (repoErrorMsg.includes('404')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" not found. It might have been deleted, renamed, or made private. Use github_search_code to find current location.`,
+                        });
+                    }
+                    else if (repoErrorMsg.includes('403')) {
+                        return createResult({
+                            error: `Repository "${owner}/${repo}" exists but access is denied. Repository might be private or archived. Use api_status_check to verify permissions.`,
+                        });
+                    }
+                }
                 // Try fallback branches if original branch fails
                 if (errorMsg.includes('404') &&
                     branch !== 'main' &&
                     branch !== 'master') {
                     const fallbackBranches = ['main', 'master'];
+                    const triedBranches = [branch];
                     for (const fallbackBranch of fallbackBranches) {
+                        if (triedBranches.includes(fallbackBranch))
+                            continue;
+                        triedBranches.push(fallbackBranch);
                         const fallbackPath = `/repos/${owner}/${repo}/contents/${filePath}?ref=${fallbackBranch}`;
                         const fallbackResult = await executeGitHubCommand('api', [fallbackPath], {
                             cache: false,
@@ -989,27 +1022,32 @@ async function fetchGitHubFileContent(params) {
                             return await processFileContent(fallbackResult, owner, repo, fallbackBranch, filePath);
                         }
                     }
+                    return createResult({
+                        error: `File not found in any common branches (tried: ${triedBranches.join(', ')}). File might have been moved or deleted. Use github_search_code to find current location.`,
+                    });
                 }
-                // Handle common errors
+                // Handle common errors with more context
                 if (errorMsg.includes('404')) {
+                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: 'File not found. Use github_view_repo_structure to explore repository structure',
+                        error: `File "${filePath}" not found in branch "${branch}". Use github_view_repo_structure to verify path.${searchSuggestion}`,
                     });
                 }
                 else if (errorMsg.includes('403')) {
                     return createResult({
-                        error: 'Access denied. Repository may be private - use apiStatusCheck to verify',
+                        error: `Access denied to "${filePath}" in "${owner}/${repo}". Repository or file might be private/archived. Use api_status_check to verify permissions, or github_search_code with query="path:${filePath}" owner="${owner}" to find in accessible repositories.`,
                     });
                 }
                 else if (errorMsg.includes('maxBuffer') ||
                     errorMsg.includes('stdout maxBuffer length exceeded')) {
                     return createResult({
-                        error: 'File too large (>300KB). Use githubSearchCode to search for patterns within the file',
+                        error: `File "${filePath}" is too large (>300KB). Use github_search_code with query="path:${filePath}" to search within the file or download directly from GitHub.`,
                     });
                 }
                 else {
+                    const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: 'Failed to fetch file. Verify repository name and file path',
+                        error: `Failed to fetch "${filePath}". Error: ${errorMsg}. Verify repository name, branch, and file path.${searchSuggestion}`,
                     });
                 }
             }
@@ -1017,15 +1055,14 @@ async function fetchGitHubFileContent(params) {
         }
         catch (error) {
             const errorMessage = error.message;
-            // Handle maxBuffer errors that escape the main try-catch
             if (errorMessage.includes('maxBuffer') ||
                 errorMessage.includes('stdout maxBuffer length exceeded')) {
                 return createResult({
-                    error: 'File too large (>300KB). Use github_search_code to search for patterns within the file',
+                    error: `File "${filePath}" is too large (>300KB). Use github_search_code to search within the file or download directly from GitHub.`,
                 });
             }
             return createResult({
-                error: 'Unexpected error. Check network connection and try again',
+                error: `Unexpected error fetching "${filePath}": ${errorMessage}. Check network connection and try again.`,
             });
         }
     });
@@ -1088,9 +1125,39 @@ async function processFileContent(result, owner, repo, branch, filePath) {
         },
     });
 }
+// Helper function to suggest code search strategy
+async function suggestCodeSearchFallback(owner, filePath) {
+    try {
+        // Extract filename and try to find in same organization
+        const fileName = filePath.split('/').pop() || filePath;
+        const searchResult = await executeGitHubCommand('api', [`/search/code?q=${encodeURIComponent(fileName)}+in:path+org:${owner}`], { cache: false });
+        if (!searchResult.isError) {
+            const results = JSON.parse(searchResult.content[0].text);
+            if (results.total_count > 0) {
+                const firstMatch = results.items[0];
+                return ` File might be in ${firstMatch.repository.full_name}. Try these searches:\n1. github_search_code with query="${fileName}" owner="${owner}"\n2. github_search_code with query="path:${filePath}" owner="${owner}"`;
+            }
+        }
+    }
+    catch {
+        // Fallback to generic message if search fails
+    }
+    return ` Try these searches:\n1. github_search_code with query="${filePath.split('/').pop()}" owner="${owner}"\n2. github_search_code with query="path:${filePath}"`;
+}
 
 const GITHUB_SEARCH_CODE_TOOL_NAME = 'githubSearchCode';
-const DESCRIPTION$6 = `Search code across GitHub repositories. Start with simple 1-2 word queries, then refine with filters like language, owner, or filename. Supports exact phrase matching with quotes. Parameters: query (required), language (optional), owner (optional - GitHub username/org, NOT owner/repo), filename (optional), extension (optional), match (optional), size (optional), limit (optional).`;
+const DESCRIPTION$6 = `Search code across GitHub repositories using GitHub's code search API.
+
+Search Syntax (all terms must be present with AND logic):
+- Multiple words: react lifecycle → finds files with BOTH "react" AND "lifecycle" (separate words)
+- Exact phrases: "error handling" → finds exact phrase "error handling" (quoted phrase)
+- Mixed: "async function" timeout → finds exact phrase "async function" AND word "timeout"
+- Complex: useState useEffect "custom hook" → finds "useState" AND "useEffect" AND exact phrase "custom hook"
+- Advanced: authentication authorization "jwt token" → finds "authentication" AND "authorization" AND exact phrase "jwt token"
+- Framework: "React.Component" "componentDidMount" → finds both exact phrases in same file
+
+Key difference: Quotes create exact phrases, no quotes = individual words (all must be present).
+Start with 1-2 terms, add more to narrow results. Use filters for precision.`;
 function registerGitHubSearchCodeTool(server) {
     server.registerTool(GITHUB_SEARCH_CODE_TOOL_NAME, {
         description: DESCRIPTION$6,
@@ -1098,31 +1165,36 @@ function registerGitHubSearchCodeTool(server) {
             query: z
                 .string()
                 .min(1)
-                .describe('Search terms. START SIMPLE: Use 1-2 words first (e.g., "useState", "auth"). Add more terms only after seeing initial results.'),
+                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: react lifecycle (both words), "error handling" (exact phrase), async await "try catch" (words + phrase), "function definition" variable scope (phrase + words)'),
             language: z
                 .string()
                 .optional()
-                .describe('Language filter (javascript, python, etc). Use only when needed.'),
+                .describe('Programming language filter (javascript, python, typescript, go, etc). Narrows search to specific language files. Use for language-specific searches.'),
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner/org (for organization-specific searches). Format: username or org-name only, NOT owner/repo. Use this to search within a specific organization.'),
+                .describe('Repository owner or organization name(s) to search within. Format: "microsoft" or ["facebook", "google"]. Drastically narrows search scope. Do NOT use owner/repo format.'),
+            repo: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('Filter on specific repository(ies). Format: "owner/repo" or ["microsoft/vscode", "facebook/react"]. Use for repository-specific searches.'),
             filename: z
                 .string()
                 .optional()
-                .describe('Specific filename to search. Use for targeted searches.'),
+                .describe('Target specific filename or pattern. Examples: "package.json", "*.test.js", "Dockerfile". Use for file-specific searches.'),
             extension: z
                 .string()
                 .optional()
-                .describe('File extension (.js, .py, etc). Alternative to language filter.'),
+                .describe('File extension filter (js, py, ts, go, etc). Alternative to language parameter. Examples: "js", "py", "tsx".'),
             match: z
                 .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
                 .optional()
-                .describe('Search scope: "file" for content, "path" for filenames. Default: file content.'),
+                .describe('Search scope: "file" for file content (default), "path" for filenames/paths, or ["file", "path"] for both. Controls where to search for terms.'),
             size: z
                 .string()
+                .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">10", ">=5", "<100", "<=50", "10..100", or exact number "50"')
                 .optional()
-                .describe('File size in KB. Format: >10, <100, or 10..50'),
+                .describe('File size filter in KB. Format: ">10" (larger than), ">=5" (at least), "<100" (smaller than), "<=50" (at most), "10..50" (range), "25" (exact). Examples from docs: ">10", "10..50", "<100"'),
             limit: z
                 .number()
                 .int()
@@ -1130,7 +1202,7 @@ function registerGitHubSearchCodeTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Results limit (1-100). Default: 30'),
+                .describe('Maximum number of results to return (1-100). Default: 30. Higher values may increase response time.'),
         },
         annotations: {
             title: 'GitHub Code Search - Smart & Efficient',
@@ -1262,32 +1334,18 @@ function extractSingleRepository$1(items) {
 }
 /**
  * Build command line arguments for GitHub CLI with improved parameter handling.
- * Ensures exact string search capability with proper quote and escape handling.
- *
- * This function is refactored to correctly distinguish between search qualifiers
- * (like `language` and `extension`), which will be passed as separate arguments
- * to `gh search`, and command-line flags (like `--size` and `--limit`).
+ * Preserves quoted phrases and supports both AND search and exact phrase matching.
  */
 function buildGitHubCliArgs(params) {
     const args = ['code'];
-    // Extract qualifiers from the query
-    const queryParts = params.query.trim().split(/\s+/);
-    const searchTerms = [];
-    const qualifiers = [];
-    queryParts.forEach(part => {
-        if (part.includes(':')) {
-            qualifiers.push(part);
-        }
-        else {
-            searchTerms.push(part);
-        }
-    });
-    // Add search terms if any
-    if (searchTerms.length > 0) {
-        args.push(searchTerms.join(' '));
-    }
-    // Add extracted qualifiers
-    qualifiers.forEach(qualifier => {
+    // Parse query to preserve quoted phrases and extract qualifiers
+    const { searchQuery, extractedQualifiers } = parseSearchQuery(params.query);
+    // Add the main search query if present
+    if (searchQuery) {
+        args.push(searchQuery);
+    }
+    // Add extracted qualifiers from the query
+    extractedQualifiers.forEach(qualifier => {
         args.push(qualifier);
     });
     // Add explicit parameters as qualifiers
@@ -1300,6 +1358,10 @@ function buildGitHubCliArgs(params) {
         const owners = Array.isArray(params.owner) ? params.owner : [params.owner];
         owners.forEach(owner => args.push(`org:${owner}`));
     }
+    if (params.repo && !params.query.includes('repo:')) {
+        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
+        repos.forEach(repo => args.push(`repo:${repo}`));
+    }
     if (params.filename && !params.query.includes('filename:')) {
         args.push(`filename:${params.filename}`);
     }
@@ -1382,6 +1444,42 @@ function validateSearchParameters(params) {
     // }
     return null; // No validation errors
 }
+/**
+ * Parse search query to preserve quoted phrases and extract qualifiers.
+ * Handles:
+ * - Quoted phrases: "error handling" -> kept as single unit
+ * - Multiple terms: react lifecycle -> both terms for AND search
+ * - Mixed: "error handling" debug -> phrase + term
+ * - Qualifiers: language:javascript -> extracted separately
+ */
+function parseSearchQuery(query) {
+    const qualifiers = [];
+    const searchTerms = [];
+    // Regular expression to match quoted strings or individual words/qualifiers
+    const tokenRegex = /"([^"]+)"|([^\s]+)/g;
+    let match;
+    while ((match = tokenRegex.exec(query)) !== null) {
+        const token = match[1] || match[2]; // match[1] is quoted content, match[2] is unquoted
+        // Check if it's a qualifier (contains : but not inside quotes)
+        if (!match[1] && token.includes(':') && /^[a-zA-Z]+:/.test(token)) {
+            qualifiers.push(token);
+        }
+        else {
+            // It's a search term (either quoted or unquoted)
+            if (match[1]) {
+                // Preserve quotes for exact phrase search
+                searchTerms.push(`"${token}"`);
+            }
+            else {
+                searchTerms.push(token);
+            }
+        }
+    }
+    return {
+        searchQuery: searchTerms.join(' '),
+        extractedQualifiers: qualifiers,
+    };
+}
 
 const GITHUB_SEARCH_COMMITS_TOOL_NAME = 'githubSearchCommits';
 const DESCRIPTION$5 = `Search commit history across GitHub repositories. Supports filtering by repository, author, date ranges, and commit attributes. Parameters: query (optional), owner (optional - GitHub username/org, NOT owner/repo), repo (optional - repository name, use with owner for specific repo), author (optional), authorName (optional), authorEmail (optional), committer (optional), committerName (optional), committerEmail (optional), authorDate (optional), committerDate (optional), hash (optional), parent (optional), tree (optional), merge (optional), visibility (optional), limit (optional), sort (optional), order (optional).`;
@@ -1407,24 +1505,30 @@ function registerGitHubSearchCommitsTool(server) {
                 .string()
                 .optional()
                 .describe('GitHub username of commit author'),
-            authorName: z
+            'author-name': z
                 .string()
                 .optional()
                 .describe('Full name of commit author'),
-            authorEmail: z.string().optional().describe('Email of commit author'),
+            'author-email': z
+                .string()
+                .optional()
+                .describe('Email of commit author'),
             // Committer filters
             committer: z
                 .string()
                 .optional()
                 .describe('GitHub username of committer'),
-            committerName: z.string().optional().describe('Full name of committer'),
-            committerEmail: z.string().optional().describe('Email of committer'),
+            'committer-name': z
+                .string()
+                .optional()
+                .describe('Full name of committer'),
+            'committer-email': z.string().optional().describe('Email of committer'),
             // Date filters
-            authorDate: z
+            'author-date': z
                 .string()
                 .optional()
                 .describe('When authored. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
-            committerDate: z
+            'committer-date': z
                 .string()
                 .optional()
                 .describe('When committed. Format: >2020-01-01, <2023-12-31, 2020-01-01..2023-12-31'),
@@ -1603,22 +1707,22 @@ function buildGitHubCommitCliArgs(params) {
     // Author filters
     if (params.author)
         args.push(`--author=${params.author}`);
-    if (params.authorName)
-        args.push(`--author-name=${params.authorName}`);
-    if (params.authorEmail)
-        args.push(`--author-email=${params.authorEmail}`);
+    if (params['author-name'])
+        args.push(`--author-name=${params['author-name']}`);
+    if (params['author-email'])
+        args.push(`--author-email=${params['author-email']}`);
     // Committer filters
     if (params.committer)
         args.push(`--committer=${params.committer}`);
-    if (params.committerName)
-        args.push(`--committer-name=${params.committerName}`);
-    if (params.committerEmail)
-        args.push(`--committer-email=${params.committerEmail}`);
+    if (params['committer-name'])
+        args.push(`--committer-name=${params['committer-name']}`);
+    if (params['committer-email'])
+        args.push(`--committer-email=${params['committer-email']}`);
     // Date filters
-    if (params.authorDate)
-        args.push(`--author-date=${params.authorDate}`);
-    if (params.committerDate)
-        args.push(`--committer-date=${params.committerDate}`);
+    if (params['author-date'])
+        args.push(`--author-date=${params['author-date']}`);
+    if (params['committer-date'])
+        args.push(`--committer-date=${params['committer-date']}`);
     // Hash filters
     if (params.hash)
         args.push(`--hash=${params.hash}`);
@@ -1628,7 +1732,7 @@ function buildGitHubCommitCliArgs(params) {
         args.push(`--tree=${params.tree}`);
     // State filters
     if (params.merge !== undefined)
-        args.push(`--merge=${params.merge}`);
+        args.push(`--merge`);
     // Visibility
     if (params.visibility)
         args.push(`--visibility=${params.visibility}`);
@@ -1678,33 +1782,45 @@ function registerSearchGitHubIssuesTool(server) {
                 .describe('GitHub username of issue creator'),
             closed: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('When closed. Format: >2020-01-01'),
+                .describe('When closed. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "2020-01-01..2023-12-31" (range)'),
             commenter: z
                 .string()
                 .optional()
                 .describe('User who commented on issue'),
             comments: z
-                .number()
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">10", ">=5", "<20", "<=15", "5..20", or exact number "10"'),
+            ])
                 .optional()
-                .describe('Comment count. Format: >10, <5, 5..10'),
+                .describe('Comment count filter. Format: ">10" (many comments), ">=5" (at least 5), "<5" (few comments), "5..10" (range), "10" (exact)'),
             created: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('When created. Format: >2020-01-01'),
-            includePrs: z
+                .describe('When created. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "2020-01-01..2023-12-31" (range)'),
+            'include-prs': z
                 .boolean()
                 .optional()
                 .describe('Include pull requests. Default: false'),
             interactions: z
-                .number()
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">100", ">=50", "<200", "<=150", "50..200", or exact number "100"'),
+            ])
                 .optional()
-                .describe('Total interactions (reactions + comments)'),
+                .describe('Total interactions (reactions + comments) filter. Format: ">100" (highly engaged), ">=50" (moderately engaged), "<20" (low engagement), "50..200" (range)'),
             involves: z.string().optional().describe('User involved in any way'),
-            labels: z
-                .string()
+            label: z
+                .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Label names (bug, feature, etc.)'),
+                .describe('Label names (bug, feature, etc.). Can be single string or array.'),
             language: z.string().optional().describe('Repository language'),
             locked: z.boolean().optional().describe('Conversation locked status'),
             match: z
@@ -1713,27 +1829,39 @@ function registerSearchGitHubIssuesTool(server) {
                 .describe('Search scope. Default: title and body'),
             mentions: z.string().optional().describe('Issues mentioning this user'),
             milestone: z.string().optional().describe('Milestone name'),
-            noAssignee: z.boolean().optional().describe('Issues without assignee'),
-            noLabel: z.boolean().optional().describe('Issues without labels'),
-            noMilestone: z
+            'no-assignee': z
+                .boolean()
+                .optional()
+                .describe('Issues without assignee'),
+            'no-label': z.boolean().optional().describe('Issues without labels'),
+            'no-milestone': z
                 .boolean()
                 .optional()
                 .describe('Issues without milestone'),
-            noProject: z.boolean().optional().describe('Issues not in projects'),
+            'no-project': z.boolean().optional().describe('Issues not in projects'),
             project: z.string().optional().describe('Project board number'),
             reactions: z
-                .number()
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">10", ">=5", "<50", "<=25", "5..50", or exact number "10"'),
+            ])
                 .optional()
-                .describe('Reaction count. Format: >10'),
+                .describe('Reaction count filter. Format: ">10" (popular), ">=5" (some reactions), "<50" (moderate), "5..50" (range), "10" (exact)'),
             state: z
                 .enum(['open', 'closed'])
                 .optional()
                 .describe('Issue state. Default: all'),
-            teamMentions: z.string().optional().describe('Team mentioned in issue'),
+            'team-mentions': z
+                .string()
+                .optional()
+                .describe('Team mentioned in issue (@org/team-name)'),
             updated: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('When updated. Format: >2020-01-01'),
+                .describe('When updated. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "2020-01-01..2023-12-31" (range)'),
             visibility: z
                 .enum(['public', 'private', 'internal'])
                 .optional()
@@ -1889,23 +2017,40 @@ function buildGitHubIssuesAPICommand(params) {
             queryParts.push(`${key}:${value}`);
     });
     // Special qualifiers - handle labels carefully
-    if (params.labels) {
-        queryParts.push(`label:"${params.labels}"`);
+    if (params.label) {
+        const labels = Array.isArray(params.label) ? params.label : [params.label];
+        labels.forEach(label => queryParts.push(`label:"${label}"`));
     }
     if (params.milestone)
         queryParts.push(`milestone:"${params.milestone}"`);
-    if (params.noAssignee)
+    if (params['no-assignee'])
         queryParts.push('no:assignee');
-    if (params.noLabel)
+    if (params['no-label'])
         queryParts.push('no:label');
-    if (params.noMilestone)
+    if (params['no-milestone'])
         queryParts.push('no:milestone');
+    if (params['no-project'])
+        queryParts.push('no:project');
     if (params.archived !== undefined)
         queryParts.push(`archived:${params.archived}`);
     if (params.locked)
         queryParts.push('is:locked');
     if (params.visibility)
         queryParts.push(`is:${params.visibility}`);
+    if (params['include-prs'])
+        queryParts.push('is:pr');
+    if (params['team-mentions'])
+        queryParts.push(`team:${params['team-mentions']}`);
+    if (params.project)
+        queryParts.push(`project:${params.project}`);
+    if (params.app)
+        queryParts.push(`app:${params.app}`);
+    if (params.comments)
+        queryParts.push(`comments:${params.comments}`);
+    if (params.interactions)
+        queryParts.push(`interactions:${params.interactions}`);
+    if (params.reactions)
+        queryParts.push(`reactions:${params.reactions}`);
     // 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);
@@ -1913,7 +2058,7 @@ function buildGitHubIssuesAPICommand(params) {
             queryParts.push(`state:${isMatch[1].toLowerCase()}`);
         }
     }
-    if (baseQuery.includes('label:') && !params.labels) {
+    if (baseQuery.includes('label:') && !params.label) {
         const labelMatch = baseQuery.match(/\blabel:("[^"]*"|[^\s]+)/i);
         if (labelMatch) {
             const labelValue = labelMatch[1].replace(/"/g, '');
@@ -1960,8 +2105,11 @@ function registerSearchGitHubPullRequestsTool(server) {
             mentions: z.string().optional().describe('PRs mentioning this user'),
             commenter: z.string().optional().describe('User who commented on PR'),
             involves: z.string().optional().describe('User involved in any way'),
-            reviewedBy: z.string().optional().describe('User who reviewed the PR'),
-            reviewRequested: z
+            'reviewed-by': z
+                .string()
+                .optional()
+                .describe('User who reviewed the PR'),
+            'review-requested': z
                 .string()
                 .optional()
                 .describe('User/team requested for review'),
@@ -1983,7 +2131,7 @@ function registerSearchGitHubPullRequestsTool(server) {
                 .string()
                 .optional()
                 .describe('When updated. Format: >2020-01-01'),
-            mergedAt: z
+            'merged-at': z
                 .string()
                 .optional()
                 .describe('When merged. Format: >2020-01-01'),
@@ -2004,6 +2152,49 @@ function registerSearchGitHubPullRequestsTool(server) {
                 .enum(['none', 'required', 'approved', 'changes_requested'])
                 .optional()
                 .describe('Review status filter'),
+            app: z.string().optional().describe('GitHub App that created the PR'),
+            archived: z
+                .boolean()
+                .optional()
+                .describe('Include archived repositories'),
+            comments: z
+                .number()
+                .optional()
+                .describe('Comment count filter. Format: >10, <5, 5..10'),
+            interactions: z
+                .number()
+                .optional()
+                .describe('Total interactions (reactions + comments)'),
+            'team-mentions': z
+                .string()
+                .optional()
+                .describe('Team mentioned in PR (@org/team-name)'),
+            reactions: z
+                .number()
+                .optional()
+                .describe('Reaction count filter. Format: >10'),
+            locked: z.boolean().optional().describe('Conversation locked status'),
+            'no-assignee': z.boolean().optional().describe('PRs without assignee'),
+            'no-label': z.boolean().optional().describe('PRs without labels'),
+            'no-milestone': z
+                .boolean()
+                .optional()
+                .describe('PRs without milestone'),
+            'no-project': z.boolean().optional().describe('PRs not in projects'),
+            label: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('Label names. Can be single string or array.'),
+            milestone: z.string().optional().describe('Milestone title'),
+            project: z.string().optional().describe('Project board owner/number'),
+            visibility: z
+                .enum(['public', 'private', 'internal'])
+                .optional()
+                .describe('Repository visibility'),
+            match: z
+                .enum(['title', 'body', 'comments'])
+                .optional()
+                .describe('Search scope. Default: title and body'),
             limit: z
                 .number()
                 .int()
@@ -2138,16 +2329,16 @@ function buildGitHubPullRequestsAPICommand(params) {
             queryParts.push(`${key}:${value}`);
     });
     // Special qualifiers
-    if (params.reviewedBy)
-        queryParts.push(`reviewed-by:${params.reviewedBy}`);
-    if (params.reviewRequested)
-        queryParts.push(`review-requested:${params.reviewRequested}`);
+    if (params['reviewed-by'])
+        queryParts.push(`reviewed-by:${params['reviewed-by']}`);
+    if (params['review-requested'])
+        queryParts.push(`review-requested:${params['review-requested']}`);
     if (params.head)
         queryParts.push(`head:${params.head}`);
     if (params.base)
         queryParts.push(`base:${params.base}`);
-    if (params.mergedAt)
-        queryParts.push(`merged:${params.mergedAt}`);
+    if (params['merged-at'])
+        queryParts.push(`merged:${params['merged-at']}`);
     if (params.draft !== undefined)
         queryParts.push(`draft:${params.draft}`);
     if (params.checks)
@@ -2156,6 +2347,39 @@ function buildGitHubPullRequestsAPICommand(params) {
         queryParts.push(`is:${params.merged ? 'merged' : 'unmerged'}`);
     if (params.review)
         queryParts.push(`review:${params.review}`);
+    // Additional parameters
+    if (params.app)
+        queryParts.push(`app:${params.app}`);
+    if (params.archived !== undefined)
+        queryParts.push(`archived:${params.archived}`);
+    if (params.comments)
+        queryParts.push(`comments:${params.comments}`);
+    if (params.interactions)
+        queryParts.push(`interactions:${params.interactions}`);
+    if (params.reactions)
+        queryParts.push(`reactions:${params.reactions}`);
+    if (params.locked)
+        queryParts.push('is:locked');
+    if (params.visibility)
+        queryParts.push(`is:${params.visibility}`);
+    if (params['team-mentions'])
+        queryParts.push(`team:${params['team-mentions']}`);
+    if (params['no-assignee'])
+        queryParts.push('no:assignee');
+    if (params['no-label'])
+        queryParts.push('no:label');
+    if (params['no-milestone'])
+        queryParts.push('no:milestone');
+    if (params['no-project'])
+        queryParts.push('no:project');
+    if (params.label) {
+        const labels = Array.isArray(params.label) ? params.label : [params.label];
+        labels.forEach(label => queryParts.push(`label:"${label}"`));
+    }
+    if (params.milestone)
+        queryParts.push(`milestone:"${params.milestone}"`);
+    if (params.project)
+        queryParts.push(`project:${params.project}`);
     // Add type qualifier to search only pull requests
     queryParts.push('type:pr');
     const query = queryParts.filter(Boolean).join(' ');
@@ -2189,7 +2413,22 @@ function buildGitHubPullRequestsAPICommand(params) {
  * TIP: Use limit parameter instead of adding more filters
  */
 const GITHUB_SEARCH_REPOSITORIES_TOOL_NAME = 'githubSearchRepositories';
-const DESCRIPTION$2 = `Discover GitHub repositories with smart filtering. Supports language, stars, topics, ownership, dates, and community metrics. Parameters: query (optional), owner (optional - GitHub username/org, NOT owner/repo), language (optional), stars (optional), topic (optional), forks (optional), numberOfTopics (optional), license (optional), archived (optional), includeForks (optional), visibility (optional), created (optional), updated (optional), size (optional), goodFirstIssues (optional), helpWantedIssues (optional), followers (optional), match (optional), sort (optional), order (optional), limit (optional).`;
+const DESCRIPTION$2 = `Search GitHub repositories using GitHub's repository search API with comprehensive filtering.
+
+Search Logic (AND operation for multiple terms):
+- Multiple words: "react typescript" → repositories containing BOTH "react" AND "typescript"
+- Exact phrases: "web framework" → repositories with exact phrase "web framework"
+- Mixed: "machine learning" python → exact phrase "machine learning" AND word "python"
+- Filter combinations: language:javascript stars:>1000 → JavaScript repos with 1000+ stars
+
+Supported Filters: language, stars (ranges), topics, owner/org, license, dates (created/updated), 
+size, forks, community metrics (good-first-issues, help-wanted), archived status, visibility.
+
+Examples:
+- Popular projects: stars:">1000" language:typescript
+- Beginner-friendly: good-first-issues:">5" stars:"100..5000"
+- Recent quality: created:">2023-01-01" stars:">500"
+- Organization repos: owner:microsoft language:python`;
 /**
  * Extract owner/repo information from various query formats
  */
@@ -2227,65 +2466,83 @@ function registerSearchGitHubReposTool(server) {
             query: z
                 .string()
                 .optional()
-                .describe('Search query. START SIMPLE: Use 1-2 words with NO filters first (e.g., "react", "auth"). Add qualifiers only after initial search.'),
+                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: react typescript (both words), "web framework" (exact phrase), "machine learning" python (phrase + word).'),
             // CORE FILTERS (GitHub CLI flags)
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner or organization name only (e.g., "microsoft", "google", NOT "microsoft/vscode"). For private repos, use organizations from api_status_check (user_organizations). Can be a single value or array.'),
+                .describe('Repository owner or organization name(s). Format: "microsoft" or ["facebook", "google"]. Do NOT use owner/repo format. Dramatically narrows search scope to specific organizations.'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter. Use when results need refinement.'),
+                .describe('Programming language filter (javascript, python, typescript, go, etc). Filters repositories by primary language. Essential for language-specific searches.'),
             stars: z
                 .union([
                 z.number().int().min(0),
-                z.string().regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "10..100", or exact number "50"'),
             ])
                 .optional()
-                .describe('Stars filter. Supports ranges and thresholds.'),
+                .describe('Star count filter. Format: ">1000" (more than), ">=500" (more than or equal), "<100" (less than), "<=50" (less than or equal), "100..1000" (range), "500" (exact). Examples from docs: ">1000", "100..5000", "<100"'),
             topic: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Topics filter. Can be a single value or array.'),
-            forks: z.number().optional().describe('Number of forks filter.'),
-            // UPDATED: Match CLI parameter name exactly
-            numberOfTopics: z
-                .number()
+                .describe('Repository topics filter. Examples: "machine-learning", ["react", "typescript"]. Topics use kebab-case format (machine-learning, web-development).'),
+            forks: z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">100", ">=50", "<10", "<=5", "10..100", or exact number "5"'),
+            ])
                 .optional()
-                .describe('Filter by number of topics (indicates documentation quality).'),
+                .describe('Fork count filter. Format: ">100" (more than), ">=50" (more than or equal), "<10" (less than), "<=5" (less than or equal), "10..100" (range), "5" (exact). Examples from docs: ">100", "10..100", "<10"'),
+            // Match CLI parameter name exactly
+            'number-topics': z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">5", ">=3", "<10", "<=2", "3..10", or exact number "5"'),
+            ])
+                .optional()
+                .describe('Number of topics filter. Format: ">5" (many topics), ">=3" (at least 3), "<10" (few topics), "1..3" (range), "5" (exact). Well-documented projects typically have 3-10 topics.'),
             // QUALITY & STATE FILTERS
             license: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('License filter. Works well as array ["mit", "apache-2.0"].'),
+                .describe('License filter. Examples: "mit", "apache-2.0", ["mit", "apache-2.0"]. Common licenses: mit, apache-2.0, gpl-3.0, bsd-3-clause.'),
             archived: z
                 .boolean()
                 .optional()
-                .describe('Filter archived repositories (true/false).'),
-            includeForks: z
+                .describe('Archive status filter. false (active repos only), true (archived repos only). Use false to find actively maintained projects.'),
+            'include-forks': z
                 .enum(['false', 'true', 'only'])
                 .optional()
-                .describe('Include forks: false (exclude), true (include), only (forks only).'),
+                .describe('Fork inclusion. "false" (exclude forks), "true" (include forks), "only" (forks only). Use "false" for original projects.'),
             visibility: z
                 .enum(['public', 'private', 'internal'])
                 .optional()
-                .describe('Repository visibility filter.'),
+                .describe('Repository visibility. "public" (open source), "private" (private repos you have access to), "internal" (organization internal).'),
             // DATE & SIZE FILTERS
             created: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2020-01-01", ">=2020-01-01", "<2023-12-31", "<=2023-12-31", "2020-01-01..2023-12-31", or exact date "2023-01-01"')
                 .optional()
-                .describe('Created date filter. Format: ">2020-01-01", "<2023-12-31".'),
+                .describe('Repository creation date filter. Format: ">2020-01-01" (after), ">=2020-01-01" (on or after), "<2023-12-31" (before), "<=2023-12-31" (on or before), "2020-01-01..2023-12-31" (range), "2023-01-01" (exact). Examples from docs: ">2020-01-01", "2023-01-01..2023-12-31"'),
             updated: z
                 .string()
+                .regex(/^(>=?\d{4}-\d{2}-\d{2}|<=?\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}|\d{4}-\d{2}-\d{2})$/, 'Invalid date format. Use: ">2024-01-01", ">=2024-01-01", "<2022-01-01", "<=2022-01-01", "2023-01-01..2024-12-31", or exact date "2024-01-01"')
                 .optional()
-                .describe('Updated date filter. Good for finding active projects.'),
+                .describe('Last updated date filter. Format: ">2024-01-01" (recently updated), ">=2024-01-01" (on or after), "<2022-01-01" (not recently updated), "2023-01-01..2024-12-31" (range). Essential for finding actively maintained projects. Examples from docs: ">2024-01-01", "2022-01-01..2023-12-31"'),
             size: z
                 .string()
+                .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">1000", ">=500", "<100", "<=50", "100..1000", or exact number "500"')
                 .optional()
-                .describe('Repository size filter in KB. Format: ">1000", "<500".'),
+                .describe('Repository size filter in KB. Format: ">1000" (large projects), ">=500" (medium-large), "<100" (small projects), "<=50" (tiny), "100..1000" (medium range), "500" (exact). Examples from docs: ">1000", "100..1000", "<100"'),
             // COMMUNITY FILTERS - Match CLI parameter names exactly
-            goodFirstIssues: z
+            'good-first-issues': z
                 .union([
                 z.number().int().min(0),
                 z
@@ -2293,8 +2550,8 @@ function registerSearchGitHubReposTool(server) {
                     .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
+                .describe('Good first issues count. Format: ">5" (many beginner issues), "1..10" (some beginner issues). Perfect for finding beginner-friendly open source projects.'),
+            'help-wanted-issues': z
                 .union([
                 z.number().int().min(0),
                 z
@@ -2302,13 +2559,21 @@ function registerSearchGitHubReposTool(server) {
                     .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.'),
+                .describe('Help wanted issues count. Format: ">10" (many help wanted), "1..5" (some help wanted). Great for finding projects actively seeking contributors.'),
+            followers: z
+                .union([
+                z.number().int().min(0),
+                z
+                    .string()
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "100..1000", or exact number "500"'),
+            ])
+                .optional()
+                .describe('Repository owner followers count. Format: ">1000" (popular developers), ">=500" (established developers), "<100" (smaller developers), "100..1000" (range). Indicates developer/org reputation.'),
             // SEARCH SCOPE
             match: z
                 .enum(['name', 'description', 'readme'])
                 .optional()
-                .describe('Search scope: name, description, or readme content.'),
+                .describe('Search scope. "name" (repository names only), "description" (descriptions only), "readme" (README content). Default searches all fields.'),
             // SORTING & LIMITS - Match CLI defaults exactly
             sort: z
                 .enum([
@@ -2320,12 +2585,12 @@ function registerSearchGitHubReposTool(server) {
             ])
                 .optional()
                 .default('best-match')
-                .describe('Sort criteria for results.'),
+                .describe('Sort criteria. "stars" (popularity), "updated" (recent activity), "forks" (community engagement), "help-wanted-issues" (contribution opportunities), "best-match" (relevance).'),
             order: z
                 .enum(['asc', 'desc'])
                 .optional()
                 .default('desc')
-                .describe('Sort order direction.'),
+                .describe('Sort order direction. "desc" (descending, highest first), "asc" (ascending, lowest first). Default is descending for most useful results.'),
             limit: z
                 .number()
                 .int()
@@ -2333,7 +2598,7 @@ function registerSearchGitHubReposTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Maximum results to return (1-100). Default: 30'),
+                .describe('Maximum number of repositories to return (1-100). Default: 30. Higher values may increase response time.'),
         },
         annotations: {
             title: 'GitHub Repository Search',
@@ -2534,13 +2799,13 @@ function buildGitHubReposSearchCommand(params) {
     // CORE FILTERS
     addArg('owner', 'owner', !hasEmbeddedQualifiers);
     addArg('language', 'language', !hasEmbeddedQualifiers);
-    addArg('forks', 'forks', !hasEmbeddedQualifiers);
+    addArg('forks', 'forks', !hasEmbeddedQualifiers, value => typeof value === 'number' ? value.toString() : value.trim());
     addArg('topic', 'topic', !hasEmbeddedQualifiers);
-    addArg('numberOfTopics', 'number-topics');
+    addArg('number-topics', 'number-topics', true, value => typeof value === 'number' ? value.toString() : value.trim());
     addArg('stars', 'stars', !hasEmbeddedQualifiers, value => typeof value === 'number' ? value.toString() : value.trim());
     // QUALITY & STATE FILTERS
     addArg('archived', 'archived');
-    addArg('includeForks', 'include-forks');
+    addArg('include-forks', 'include-forks');
     addArg('visibility', 'visibility');
     addArg('license', 'license');
     // DATE & SIZE FILTERS
@@ -2548,9 +2813,9 @@ function buildGitHubReposSearchCommand(params) {
     addArg('updated', 'updated');
     addArg('size', 'size');
     // COMMUNITY FILTERS
-    addArg('goodFirstIssues', 'good-first-issues', true, value => typeof value === 'number' ? value.toString() : value);
-    addArg('helpWantedIssues', 'help-wanted-issues', true, value => typeof value === 'number' ? value.toString() : value);
-    addArg('followers', 'followers');
+    addArg('good-first-issues', 'good-first-issues', true, value => typeof value === 'number' ? value.toString() : value);
+    addArg('help-wanted-issues', 'help-wanted-issues', true, value => typeof value === 'number' ? value.toString() : value);
+    addArg('followers', 'followers', true, value => typeof value === 'number' ? value.toString() : value.trim());
     // SEARCH SCOPE
     addArg('match', 'match');
     // SORTING AND LIMITS
@@ -2667,7 +2932,6 @@ function parseNpmSearchOutput(output) {
         return packages.map(normalizePackage);
     }
     catch (error) {
-        logger.warn('Failed to parse NPM search results:', error);
         return [];
     }
 }
@@ -2996,39 +3260,31 @@ function registerAllTools(server) {
         },
         { name: NPM_VIEW_PACKAGE_TOOL_NAME, fn: registerNpmViewPackageTool },
     ];
-    logger.info(`Registering ${toolRegistrations.length} tools...`);
     let successCount = 0;
     for (const tool of toolRegistrations) {
         try {
-            logger.debug(`Registering tool: ${tool.name}`);
             tool.fn(server);
             successCount++;
-            logger.info(`✓ Successfully registered: ${tool.name}`);
         }
         catch (error) {
-            logger.error(`✗ Failed to register ${tool.name}:`, error);
             // Continue with other tools instead of failing completely
         }
     }
     if (successCount === 0) {
         throw new Error('No tools were successfully registered');
     }
-    logger.info(`All tools registration completed - ${successCount}/${toolRegistrations.length} successful`);
 }
 async function startServer() {
     try {
-        logger.info('Creating MCP server...');
         const server = new McpServer(SERVER_CONFIG);
         registerAllTools(server);
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        logger.info('=== Server Connected Successfully ===');
         // Ensure all buffered output is sent
         process.stdout.uncork();
         process.stderr.uncork();
-        const gracefulShutdown = async (signal) => {
+        const gracefulShutdown = async () => {
             try {
-                logger.info(`Received ${signal}, shutting down gracefully...`);
                 clearAllCache();
                 // Give server time to close properly
                 await Promise.race([
@@ -3038,35 +3294,30 @@ async function startServer() {
                 process.exit(0);
             }
             catch (error) {
-                logger.error('Error during shutdown:', error);
                 process.exit(1);
             }
         };
         // Handle process signals
-        process.on('SIGINT', () => gracefulShutdown('SIGINT'));
-        process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+        process.on('SIGINT', gracefulShutdown);
+        process.on('SIGTERM', gracefulShutdown);
         // Handle stdin close (important for MCP)
         process.stdin.on('close', async () => {
-            await gracefulShutdown('STDIN_CLOSE');
+            await gracefulShutdown();
         });
         // Handle uncaught errors
-        process.on('uncaughtException', error => {
-            logger.error('Uncaught exception:', error);
-            gracefulShutdown('UNCAUGHT_EXCEPTION');
+        process.on('uncaughtException', () => {
+            gracefulShutdown();
         });
-        process.on('unhandledRejection', (reason, promise) => {
-            logger.error('Unhandled rejection at:', promise, 'reason:', reason);
-            gracefulShutdown('UNHANDLED_REJECTION');
+        process.on('unhandledRejection', () => {
+            gracefulShutdown();
         });
         // Keep process alive
         process.stdin.resume();
     }
     catch (error) {
-        logger.error('Error details:', error);
         process.exit(1);
     }
 }
-startServer().catch(error => {
-    logger.error('Error:', error);
+startServer().catch(() => {
     process.exit(1);
 });

package/package.json

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