octocode-mcp 2.3.8 → 2.3.9

package/build/index.js

@@ -168,11 +168,13 @@ function escapeWindowsCmdArg(arg) {
  * Preserves AND search logic by not over-escaping space-separated terms
  */
 function escapeUnixShellArg(arg, isGitHubQuery) {
-    // For GitHub search queries, we need to preserve AND logic
+    // For GitHub search queries, we need to preserve AND logic and quoted phrases
     if (isGitHubQuery) {
-        // If the query contains quotes, preserve them for exact phrase matching
+        // If the query contains quotes, we need to preserve them for GitHub CLI
+        // but escape the entire argument for the shell
         if (arg.includes('"')) {
             // Use single quotes to wrap the entire query while preserving internal quotes
+            // This allows GitHub CLI to see: "quoted phrase" other terms
             return `'${arg.replace(/'/g, "'\"'\"'")}'`;
         }
         // For space-separated terms (AND search), only escape if absolutely necessary
@@ -230,14 +232,21 @@ async function executeGitHubCommand(command, args = [], options = {}) {
     // Get shell configuration
     const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    // For GitHub search commands, qualifiers like "language:typescript" should not be escaped
-    // Only the main query term (if it contains spaces) needs escaping
+    // For GitHub search commands, we need to distinguish between:
+    // 1. Main query (index 1) - needs special escaping for AND logic
+    // 2. CLI flags (--flag=value) - standard escaping
+    // 3. Search qualifiers (key:value) - minimal escaping
     const escapedArgs = args.map((arg, index) => {
         const isMainQueryArgument = command === 'search' && index === 1;
+        const isCliFlag = arg.startsWith('--');
         const isGitHubQualifier = command === 'search' &&
             index > 1 &&
-            (arg.includes(':') || arg.startsWith('(')) &&
-            !arg.startsWith('--');
+            !isCliFlag &&
+            (arg.includes(':') || arg.startsWith('('));
+        // CLI flags like --language=javascript, --repo=owner/repo need standard escaping
+        if (isCliFlag) {
+            return escapeShellArg(arg, shellConfig.type, false);
+        }
         // GitHub search qualifiers need special handling
         // Most qualifiers can be passed as-is, but those with shell metacharacters need escaping
         if (isGitHubQualifier) {
@@ -458,24 +467,16 @@ const ERROR_MESSAGES = {
     ISSUE_SEARCH_FAILED: 'Issue search failed - check auth or simplify query',
     PR_SEARCH_FAILED: 'PR search failed - check access and query syntax',
     PACKAGE_SEARCH_FAILED: 'Package search failed - try different keywords',
-    // GitHub CLI errors
-    CLI_INVALID_RESPONSE: 'GitHub CLI invalid response - check "gh version" and update',
-    // Timeout errors
-    SEARCH_TIMEOUT: 'Search timed out - add filters (language, owner) or use specific terms',
     // Query validation errors
     QUERY_TOO_LONG: 'Query too long (max 256 chars) - simplify search terms',
     QUERY_REQUIRED: 'Query required - provide search keywords',
-    EMPTY_QUERY: 'Empty query - try "useState", "authentication", or language:python',
-    QUERY_TOO_LONG_1000: 'Query too long (max 1000 chars) - use key terms like "error handling"',
-    REPO_OR_OWNER_NOT_FOUND: 'Repository/owner not found - check spelling, visibility, and permissions',
-    // Query syntax errors
-    INVALID_QUERY_SYNTAX: 'Invalid syntax - Boolean operators not supported, use quotes for phrases',
-    // Size/format validation errors
-    INVALID_SIZE_FORMAT: 'Invalid size format - use >N, <N, or N..M without quotes',
-    INVALID_SEARCH_SCOPE: 'Invalid scope - use "file" for content, "path" for filenames',
     // API Status check errors
     API_STATUS_CHECK_FAILED: 'API Status Check Failed',
-};
+    // NPM Errors
+    NPM_PACKAGE_NOT_FOUND: 'Package not found on NPM registry',
+    NPM_CONNECTION_FAILED: 'NPM registry connection failed',
+    NPM_CLI_ERROR: 'NPM CLI issue detected',
+    NPM_PERMISSION_ERROR: 'NPM permission issue'};
 const SUGGESTIONS = {
     // Code search suggestions
     CODE_SEARCH_NO_RESULTS: `No results found. Try this progression:
@@ -499,6 +500,31 @@ const SUGGESTIONS = {
 2. Break compound words: "authlib" → "auth"
 3. Search by use case: "user login" vs "authentication"
 4. Try category terms: "framework", "tool", "library"`,
+    // File Content Suggestions
+    FILE_NOT_FOUND_RECOVERY: `Quick fixes:
+• Use github_view_repo_structure to verify path exists
+• Check for typos in file path
+• Try different branch (main/master/develop)`,
+    FILE_TOO_LARGE_RECOVERY: `Alternative strategies:
+• Use github_search_code to search within the file
+• Download directly from GitHub
+• Use github_view_repo_structure to find smaller related files
+• Look for configuration or summary files instead`,
+    // Repository Suggestions
+    REPOSITORY_NOT_FOUND_RECOVERY: `This is often due to incorrect repository name. Steps to resolve:
+1. Use github_search_repositories to find the correct repository
+2. Verify the exact repository name
+3. Check if the repository might have been renamed or moved`,
+    // NPM Suggestions
+    NPM_DISCOVERY_STRATEGIES: `Discovery strategies:
+• Functional search: "validation", "testing", "charts"
+• Ecosystem search: "react", "typescript", "node"
+• Use github_search_repositories for related projects`,
+    NPM_PACKAGE_NAME_ALTERNATIVES: `Try these alternatives:
+• Try with dashes instead of underscores
+• Try without dashes
+• Try scoped package format
+• Use npm_package_search for discovery`,
 };
 // Helper function to get error message with context-specific suggestions
 function getErrorWithSuggestion(options) {
@@ -556,9 +582,348 @@ function createSearchFailedError(type = 'code') {
             return ERROR_MESSAGES.SEARCH_FAILED;
     }
 }
+function createNpmPackageNotFoundError(packageName) {
+    const suggestions = [];
+    if (packageName.includes('_')) {
+        suggestions.push(`• Try with dashes: "${packageName.replace(/_/g, '-')}"`);
+    }
+    if (packageName.includes('-')) {
+        suggestions.push(`• Try without dashes: "${packageName.replace(/-/g, '')}"`);
+    }
+    if (!packageName.includes('/') && packageName.length > 2) {
+        suggestions.push(`• Try scoped format: "@${packageName.slice(0, 3)}/${packageName}"`);
+    }
+    return `${ERROR_MESSAGES.NPM_PACKAGE_NOT_FOUND}: "${packageName}"
+
+${suggestions.length > 0 ? suggestions.join('\n') + '\n\n' : ''}${SUGGESTIONS.NPM_PACKAGE_NAME_ALTERNATIVES}
+
+${SUGGESTIONS.NPM_DISCOVERY_STRATEGIES}`;
+}
+
+/**
+ * Tool relationship map for standardized cross-tool suggestions
+ * Defines how tools connect and when to suggest alternatives
+ */
+const TOOL_NAMES = {
+    API_STATUS_CHECK: 'api_status_check',
+    GITHUB_FETCH_CONTENT: 'github_fetch_content',
+    GITHUB_SEARCH_CODE: 'github_search_code',
+    GITHUB_SEARCH_COMMITS: 'github_search_commits',
+    GITHUB_SEARCH_ISSUES: 'github_search_issues',
+    GITHUB_SEARCH_PULL_REQUESTS: 'github_search_pull_requests',
+    GITHUB_SEARCH_REPOSITORIES: 'github_search_repositories',
+    GITHUB_VIEW_REPO_STRUCTURE: 'github_view_repo_structure',
+    NPM_PACKAGE_SEARCH: 'npm_package_search',
+    NPM_VIEW_PACKAGE: 'npm_view_package',
+};
+const TOOL_RELATIONSHIPS = {
+    [TOOL_NAMES.NPM_PACKAGE_SEARCH]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find repositories by topic or language',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search for package usage examples',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.NPM_VIEW_PACKAGE,
+                reason: 'to get detailed package information and repository URL',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore the package source code structure',
+            },
+        ],
+    },
+    [TOOL_NAMES.NPM_VIEW_PACKAGE]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'to discover similar packages',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find the repository directly',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore repository structure',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to read specific files like README or package.json',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find usage examples',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'if searching for packages or libraries',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search within repository contents',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore repository contents',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+                reason: 'to check open issues and discussions',
+            },
+            {
+                tool: TOOL_NAMES.NPM_VIEW_PACKAGE,
+                reason: 'if repository is an NPM package',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_CODE]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'if searching for package implementations',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find repositories by topic',
+            },
+            {
+                tool: TOOL_NAMES.API_STATUS_CHECK,
+                reason: 'if no results (might be private repos)',
+                condition: 'no_results',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to view full file contents',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore repository structure',
+            },
+        ],
+        prerequisites: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to verify file paths before searching',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_FETCH_CONTENT]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to verify correct file path',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search for similar files',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to explore related files',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find usage examples',
+            },
+        ],
+        prerequisites: [
+            {
+                tool: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE,
+                reason: 'to verify file exists and get correct path',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find the correct repository',
+            },
+            {
+                tool: TOOL_NAMES.API_STATUS_CHECK,
+                reason: 'if access denied (check authentication)',
+                condition: 'access_denied',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to read specific files',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to search within the repository',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_COMMITS]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find repositories first',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+                reason: 'to find related discussions',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to view files changed in commits',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find current implementation',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_ISSUES]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
+                reason: 'to find related PRs',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to find the repository first',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS,
+                reason: 'to find solutions or implementations',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find related code',
+            },
+        ],
+    },
+    [TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS]: {
+        fallbackTools: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_ISSUES,
+                reason: 'to find related issues',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_COMMITS,
+                reason: 'to find related commits',
+            },
+        ],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_FETCH_CONTENT,
+                reason: 'to view PR changes',
+            },
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_CODE,
+                reason: 'to find current implementation',
+            },
+        ],
+    },
+    [TOOL_NAMES.API_STATUS_CHECK]: {
+        fallbackTools: [],
+        nextSteps: [
+            {
+                tool: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
+                reason: 'to search accessible repositories',
+            },
+            {
+                tool: TOOL_NAMES.NPM_PACKAGE_SEARCH,
+                reason: 'to search public packages',
+            },
+        ],
+    },
+};
+/**
+ * Get tool suggestions based on current context
+ */
+function getToolSuggestions(currentTool, context) {
+    const relationships = TOOL_RELATIONSHIPS[currentTool];
+    if (!relationships) {
+        return { fallback: [], nextSteps: [], prerequisites: [] };
+    }
+    // Filter fallback tools based on context
+    const fallback = relationships.fallbackTools.filter(item => {
+        if (!item.condition)
+            return true;
+        switch (item.condition) {
+            case 'no_results':
+                return context.errorType === 'no_results';
+            case 'access_denied':
+                return context.errorType === 'access_denied';
+            default:
+                return true;
+        }
+    });
+    // Return next steps only if operation was successful
+    const nextSteps = context.hasResults ? relationships.nextSteps : [];
+    return {
+        fallback,
+        nextSteps,
+        prerequisites: relationships.prerequisites || [],
+    };
+}
+
+/**
+ * Shared validation utilities for MCP tools
+ * Centralized validation logic to reduce duplication across tools
+ */
+/**
+ * Extracts owner/repo from various query formats
+ * Handles: owner/repo, https://github.com/owner/repo, github.com/owner/repo
+ */
+/**
+ * Creates a standardized tool suggestion message
+ */
+function createToolSuggestion(currentTool, suggestedTools) {
+    if (suggestedTools.length === 0) {
+        return '';
+    }
+    const suggestions = suggestedTools
+        .map(({ tool, reason }) => `• Use ${tool} ${reason}`)
+        .join('\n');
+    return `\n\nCurrent tool: ${currentTool}\nAlternative tools:\n${suggestions}`;
+}
 
 const API_STATUS_CHECK_TOOL_NAME = 'apiStatusCheck';
-const DESCRIPTION$9 = `Check GitHub and NPM authentication status and available organizations. Verifies API connections and returns user organizations for accessing private repositories. Essential for troubleshooting access issues. No parameters required.`;
+const DESCRIPTION$9 = `Verify API connections and discover available organizations. FIRST STEP for private repository research.
+
+AUTHENTICATION VERIFICATION:
+- Check GitHub and NPM CLI authentication status
+- Troubleshoot access issues before extensive searches
+- Verify API connectivity and permissions
+
+ORGANIZATION DISCOVERY:
+- List available GitHub organizations for scoped searches  
+- Identify accessible private repositories
+- Guide repository search strategy based on permissions
+
+WORKFLOW OPTIMIZATION:
+- Run first when dealing with private/organizational repositories
+- Prevents access errors in subsequent tool usage
+- Informs search scope and strategy decisions
+- Essential for comprehensive organizational research`;
 // Helper function to parse execution results with proper typing
 function parseExecResult(result) {
     if (!result.isError && result.content?.[0]?.text) {
@@ -664,6 +1029,19 @@ function registerApiStatusCheckTool(server) {
                 }
                 npmConnected = false;
             }
+            const { nextSteps } = getToolSuggestions(TOOL_NAMES.API_STATUS_CHECK, {
+                hasResults: true,
+            });
+            const hints = [
+                'Use user organizations to search private repositories when requested - verify access by checking query and repository structure',
+            ];
+            // Add tool suggestions as hints
+            if (nextSteps.length > 0) {
+                hints.push('Next steps:');
+                nextSteps.forEach(({ tool, reason }) => {
+                    hints.push(`- ${tool}: ${reason}`);
+                });
+            }
             return createResult({
                 data: {
                     login: {
@@ -675,23 +1053,48 @@ function registerApiStatusCheckTool(server) {
                             connected: npmConnected,
                             registry: registry || 'https://registry.npmjs.org/',
                         },
-                        hints: [
-                            'Use user organizations to search private repositories when requested - verify access by checking query and repository structure',
-                        ],
+                        hints,
                     },
                 },
             });
         }
         catch (error) {
+            const { nextSteps } = getToolSuggestions(TOOL_NAMES.API_STATUS_CHECK, {
+                });
+            const toolSuggestions = createToolSuggestion(TOOL_NAMES.API_STATUS_CHECK, nextSteps);
             return createResult({
-                error: `${ERROR_MESSAGES.API_STATUS_CHECK_FAILED}\nError: ${error instanceof Error ? error.message : 'Unknown error'}\n\nThis usually indicates a system configuration issue. Please verify GitHub CLI and NPM are properly installed.`,
+                error: getErrorWithSuggestion({
+                    baseError: [
+                        ERROR_MESSAGES.API_STATUS_CHECK_FAILED,
+                        `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        '',
+                        'This usually indicates a system configuration issue. Please verify GitHub CLI and NPM are properly installed.',
+                    ],
+                    suggestion: toolSuggestions,
+                }),
             });
         }
     });
 }
 
 const GITHUB_GET_FILE_CONTENT_TOOL_NAME = 'githubGetFileContent';
-const DESCRIPTION$8 = `Fetch file content from GitHub repositories. Automatically handles branch fallback (main/master) and files up to 300KB. Returns decoded file content with metadata. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), filePath (required).`;
+const DESCRIPTION$8 = `Access GitHub file content for implementation analysis. USE AFTER repository structure validation.
+
+IMPLEMENTATION ANALYSIS:
+- Examine configuration files, documentation, key source code
+- Understand actual implementations and patterns
+- Extract technical details and architecture decisions
+
+VALIDATION REQUIREMENTS:
+- ALWAYS verify repository structure first with githubViewRepoStructure
+- Confirm file paths exist before accessing
+- Navigate from known structure to specific files
+
+CONTENT CAPABILITIES:
+- Handles text files up to 300KB efficiently
+- Automatic branch fallback (main/master)
+- Provides decoded content with metadata
+- Optimized for code analysis workflows`;
 function registerFetchGitHubFileContentTool(server) {
     server.registerTool(GITHUB_GET_FILE_CONTENT_TOOL_NAME, {
         description: DESCRIPTION$8,
@@ -793,24 +1196,61 @@ async function fetchGitHubFileContent(params) {
                 if (errorMsg.includes('404')) {
                     const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: `File "${filePath}" not found in branch "${branch}". Use github_view_repo_structure to verify path.${searchSuggestion}`,
+                        error: `File "${filePath}" not found in branch "${branch}".
+
+Quick fixes:
+• Use github_view_repo_structure to verify path exists
+• Check for typos in file path
+• Try different branch (main/master/develop)${searchSuggestion}
+
+Alternative strategies:
+• Use github_search_code with query="filename:${filePath.split('/').pop()}" owner="${owner}"
+• Use github_search_code with query="path:${filePath}" to find similar paths`,
                     });
                 }
                 else if (errorMsg.includes('403')) {
                     return createResult({
-                        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.`,
+                        error: `Access denied to "${filePath}" in "${owner}/${repo}".
+
+Possible causes & solutions:
+• Private repository: use api_status_check to verify permissions
+• File in private directory: check repository access level
+• Rate limiting: wait 5-10 minutes and retry
+• Authentication: run gh auth login
+
+Alternative approaches:
+• Use github_search_code with query="path:${filePath}" owner="${owner}"
+• Use github_view_repo_structure to explore accessible paths
+• Check repository on GitHub.com for public access`,
                     });
                 }
                 else if (errorMsg.includes('maxBuffer') ||
                     errorMsg.includes('stdout maxBuffer length exceeded')) {
                     return createResult({
-                        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.`,
+                        error: `File "${filePath}" is too large (>300KB).
+
+Alternative strategies:
+• Use github_search_code to search within the file
+• Download directly from: https://github.com/${owner}/${repo}/blob/${branch}/${filePath}
+• Use github_view_repo_structure to find smaller related files
+• Look for configuration or summary files instead`,
                     });
                 }
                 else {
                     const searchSuggestion = await suggestCodeSearchFallback(owner, filePath);
                     return createResult({
-                        error: `Failed to fetch "${filePath}". Error: ${errorMsg}. Verify repository name, branch, and file path.${searchSuggestion}`,
+                        error: `Failed to fetch "${filePath}": ${errorMsg}
+
+Troubleshooting steps:
+1. Verify repository exists: github_view_repo_structure
+2. Check network connection and GitHub status
+3. Verify authentication: gh auth status
+4. Try different branch names${searchSuggestion}
+
+Recovery strategies:
+• Use github_search_code for content discovery
+• Try github_search_repos to find similar repositories
+• Check file on GitHub.com: https://github.com/${owner}/${repo}/blob/${branch}/${filePath}`,
                     });
                 }
             }
@@ -909,24 +1349,36 @@ async function suggestCodeSearchFallback(owner, filePath) {
 }
 
 const GITHUB_SEARCH_CODE_TOOL_NAME = 'githubSearchCode';
-const DESCRIPTION$7 = `Search code across GitHub repositories using GitHub's code search API.
+const DESCRIPTION$7 = `Search code across GitHub repositories using GitHub's code search API via GitHub CLI.
 
-Never use filters and flags on exploretory searches and on initial searches.
-Use filters and flags on subsequent searches when you know what to search for or if the user asks for it explicitly.
-Using too many flags might make miss relevant results. Use filters and flags to narrow down the results when getting too many.
+SEARCH STRATEGY FOR BEST RESULTS:
 
-Search Syntax - ALL terms must be present (AND logic):
-The search finds files that contain ALL specified terms. Each space-separated term is required to be present in the same file.
-- Multiple terms: All individual words must exist in the file
-- Quoted phrases: Exact phrase matching for multi-word expressions  
-- Mixed terms: Combination of individual words AND exact phrases, all must be present
-- Additional filters: Language, owner, repository, filename, extension, size and other flags supported
+TERM OPTIMIZATION (IMPORTANT):
+- BEST: Single terms for maximum coverage and relevance
+- GOOD: 2 terms when you need both to be present  
+- RESTRICTIVE: 3+ terms - very specific but may miss relevant results
+- Example: "useState" (best coverage) vs "react hook useState" (specific but restrictive)
 
-Key behavior: All search terms are combined with AND logic - every term must be found in the file.
-Quotes create exact phrase matching, unquoted terms are individual word requirements.
-Start with 1-2 terms, add more to narrow results. Use filters and flags for precision.
+MULTI-SEARCH STRATEGY:
+- Use SEPARATE searches for different aspects instead of complex single queries
+- Example: Search "authentication" separately, then "login" separately
+- Separate searches provide broader coverage than restrictive AND logic
 
-`;
+Search Logic:
+- Multiple terms = ALL must be present (AND logic) - very restrictive
+- Single terms = maximum results and coverage
+- Quoted phrases = exact phrase matching
+- Mixed queries: "exact phrase" additional_term (phrase + term)
+
+Quote Usage:
+- Single terms: NO quotes (useState, authentication)
+- Multi-word phrases: WITH quotes ("error handling", "user authentication")
+- Mixed queries: "exact phrase" single_term another_term
+
+Filter Usage:
+- All filters use GitHub CLI flags (--language, --owner, --repo, etc.)
+- Combine filters to narrow scope: language + owner, repo + filename
+- Never use filters on exploratory searches - use to refine when too many results`;
 function registerGitHubSearchCodeTool(server) {
     server.registerTool(GITHUB_SEARCH_CODE_TOOL_NAME, {
         description: DESCRIPTION$7,
@@ -934,36 +1386,36 @@ function registerGitHubSearchCodeTool(server) {
             query: z
                 .string()
                 .min(1)
-                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases.'),
+                .describe('Search query with AND logic between terms. OPTIMIZATION: Single terms give best coverage, 2 terms when both needed, 3+ terms very restrictive. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: "useState" (best coverage), "error handling" (exact phrase), "react hook useState" (specific but restrictive).'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter. Narrows search to specific language files. Use for language-specific searches.'),
+                .describe('Programming language filter. Uses --language CLI flag. Narrows search to specific language files. Use for language-specific searches.'),
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner/organization name(s) to search within (e.g., "facebook", ["google", "microsoft"]). Use this to search within specific organizations. Do NOT use owner/repo format - just the organization/username.'),
+                .describe('Repository owner/organization name(s) to search within (e.g., "facebook", ["google", "microsoft"]). Uses --owner CLI flag for organization-wide search. Can be combined with repo parameter for specific repository search. Do NOT use owner/repo format - just the organization/username.'),
             repo: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Filter on specific repository(ies). Must use full "owner/repo" format (e.g., "facebook/react", ["vuejs/vue", "angular/angular"]). Use this for searching within specific repositories.'),
+                .describe('Filter on specific repository(ies). Uses --repo CLI flag. Two usage patterns: (1) Use with owner parameter - provide just repo name (e.g., owner="facebook", repo="react" → --repo=facebook/react), or (2) Use alone - provide full "owner/repo" format (e.g., "facebook/react" → --repo=facebook/react).'),
             filename: z
                 .string()
                 .optional()
-                .describe('Target specific filename or pattern. Use for file-specific searches.'),
+                .describe('Target specific filename or pattern. Uses --filename CLI flag. Use for file-specific searches.'),
             extension: z
                 .string()
                 .optional()
-                .describe('File extension filter. Alternative to language parameter.'),
+                .describe('File extension filter. Uses --extension CLI flag. Alternative to language parameter.'),
             match: z
-                .union([z.enum(['file', 'path']), z.array(z.enum(['file', 'path']))])
+                .enum(['file', 'path'])
                 .optional()
-                .describe('Search scope: "file" for file content (default), "path" for filenames/paths, or ["file", "path"] for both. Controls where to search for terms.'),
+                .describe('Search scope: "file" for file content (default), "path" for filenames/paths. Uses --match CLI flag. Single value only - multiple scopes not supported by GitHub CLI.'),
             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 filter in KB. Format: ">N" (larger than), "<N" (smaller than), "N..M" (range), "N" (exact).'),
+                .describe('File size filter in KB. Uses --size CLI flag. Format: ">N" (larger than), "<N" (smaller than), "N..M" (range), "N" (exact).'),
             limit: z
                 .number()
                 .int()
@@ -982,11 +1434,6 @@ function registerGitHubSearchCodeTool(server) {
         },
     }, async (args) => {
         try {
-            // Validate parameter combinations
-            const validationError = validateSearchParameters(args);
-            if (validationError) {
-                return createResult({ error: validationError });
-            }
             const result = await searchGitHubCode(args);
             if (result.isError) {
                 return result;
@@ -1021,45 +1468,79 @@ function registerGitHubSearchCodeTool(server) {
     });
 }
 /**
- * Handles various search errors and returns a formatted CallToolResult.
+ * Handles various search errors and returns a formatted CallToolResult with smart fallbacks.
  */
 function handleSearchError(errorMessage) {
-    // Common GitHub search errors with helpful suggestions
-    if (errorMessage.includes('JSON')) {
+    // Rate limit with smart timing guidance
+    if (errorMessage.includes('rate limit') || errorMessage.includes('403')) {
         return createResult({
-            error: ERROR_MESSAGES.CLI_INVALID_RESPONSE,
+            error: `GitHub API rate limit reached. Try again in 5-10 minutes, or use these strategies:
+• Search fewer terms per query
+• Use owner/repo filters to narrow scope
+• Try npm package search for package-related queries
+• Use separate searches instead of complex queries`,
         });
     }
-    if (errorMessage.includes('authentication')) {
+    // Authentication with clear next steps
+    if (errorMessage.includes('authentication') || errorMessage.includes('401')) {
         return createResult({
-            error: createAuthenticationError(),
+            error: `GitHub authentication required. Fix with:
+1. Run: gh auth login
+2. Verify access: gh auth status
+3. For private repos: use api_status_check to verify org access`,
         });
     }
-    if (errorMessage.includes('rate limit')) {
+    // Network/timeout with fallback suggestions
+    if (errorMessage.includes('timed out') || errorMessage.includes('network')) {
         return createResult({
-            error: createRateLimitError(true),
-        });
-    }
-    if (errorMessage.includes('timed out')) {
-        return createResult({
-            error: ERROR_MESSAGES.SEARCH_TIMEOUT,
+            error: `Network timeout. Try these alternatives:
+• Reduce search scope with owner or language filters
+• Use github_search_repos to find repositories first
+• Try npm package search for package discovery
+• Check network connection and retry`,
         });
     }
+    // Invalid query with specific fixes
     if (errorMessage.includes('validation failed') ||
         errorMessage.includes('Invalid query')) {
         return createResult({
-            error: ERROR_MESSAGES.INVALID_QUERY_SYNTAX,
+            error: `Invalid search query. Common fixes:
+• Remove special characters: ()[]{}*?^$|.\\
+• Use quotes only for exact phrases: "error handling"
+• Avoid escaped quotes: use term instead of "term"
+• Try broader terms: "react" instead of "React.Component"`,
         });
     }
+    // Repository not found with discovery suggestions
     if (errorMessage.includes('repository not found') ||
         errorMessage.includes('owner not found')) {
         return createResult({
-            error: ERROR_MESSAGES.REPO_OR_OWNER_NOT_FOUND,
+            error: `Repository/owner not found. Discovery strategies:
+• Use github_search_repos to find correct names
+• Check for typos in owner/repo names
+• Try without owner filter for broader search
+• Use npm package search if looking for packages`,
         });
     }
-    // Generic fallback with guidance
+    // JSON parsing with system guidance
+    if (errorMessage.includes('JSON')) {
+        return createResult({
+            error: `GitHub CLI response parsing failed. System issue - try:
+• Update GitHub CLI: gh extension upgrade
+• Retry in a few moments
+• Use github_search_repos as alternative
+• Check gh auth status for authentication`,
+        });
+    }
+    // Generic fallback with progressive strategy
     return createResult({
-        error: `Code search failed: ${errorMessage}\n${SUGGESTIONS.SIMPLIFY_QUERY}`,
+        error: `Code search failed: ${errorMessage}
+
+Progressive recovery strategy:
+1. Try broader search terms
+2. Use github_search_repos to find repositories
+3. Use npm package search for package-related queries
+4. Check github CLI status: gh auth status`,
     });
 }
 /**
@@ -1106,8 +1587,8 @@ function extractSingleRepository$1(items) {
     return allSameRepo ? firstRepo : null;
 }
 /**
- * Build command line arguments for GitHub CLI with improved parameter handling.
- * Preserves quoted phrases and supports both AND search and exact phrase matching.
+ * Build command line arguments for GitHub CLI following the exact CLI format.
+ * Uses proper flags (--flag=value) instead of qualifiers where appropriate.
  */
 function buildGitHubCliArgs(params) {
     const args = ['code'];
@@ -1117,39 +1598,52 @@ function buildGitHubCliArgs(params) {
     if (searchQuery) {
         args.push(searchQuery);
     }
-    // Add extracted qualifiers from the query
+    // Add extracted qualifiers from the query (these should remain as qualifiers)
     extractedQualifiers.forEach(qualifier => {
         args.push(qualifier);
     });
-    // Add explicit parameters as qualifiers
+    // Add explicit parameters as CLI flags (following GitHub CLI format)
     if (params.language && !params.query.includes('language:')) {
-        args.push(`language:${params.language}`);
+        args.push(`--language=${params.language}`);
+    }
+    // Handle owner and repo parameters properly
+    if (params.repo && !params.query.includes('repo:')) {
+        const repos = Array.isArray(params.repo) ? params.repo : [params.repo];
+        repos.forEach(repo => {
+            // If both owner and repo are provided, combine them for --repo flag
+            if (params.owner && !repo.includes('/')) {
+                const owners = Array.isArray(params.owner)
+                    ? params.owner
+                    : [params.owner];
+                owners.forEach(owner => args.push(`--repo=${owner}/${repo}`));
+            }
+            else {
+                // Repo is already in owner/repo format or no owner provided
+                args.push(`--repo=${repo}`);
+            }
+        });
     }
-    if (params.owner &&
+    else if (params.owner &&
         !params.query.includes('org:') &&
         !params.query.includes('user:')) {
+        // Only owner provided, no repo - use --owner flag for organization-wide search
         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}`));
+        owners.forEach(owner => args.push(`--owner=${owner}`));
     }
     if (params.filename && !params.query.includes('filename:')) {
-        args.push(`filename:${params.filename}`);
+        args.push(`--filename=${params.filename}`);
     }
     if (params.extension && !params.query.includes('extension:')) {
-        args.push(`extension:${params.extension}`);
+        args.push(`--extension=${params.extension}`);
     }
     if (params.size && !params.query.includes('size:')) {
-        args.push(`size:${params.size}`);
+        args.push(`--size=${params.size}`);
     }
-    // Handle match parameter
+    // Handle match parameter - use --match flag
     if (params.match) {
-        const matches = Array.isArray(params.match) ? params.match : [params.match];
-        args.push(`in:${matches.join(',')}`);
+        args.push(`--match=${params.match}`);
     }
-    // Add limit
+    // Add limit flag
     if (params.limit) {
         args.push(`--limit=${params.limit}`);
     }
@@ -1169,54 +1663,10 @@ async function searchGitHubCode(params) {
         }
         catch (error) {
             const errorMessage = error.message || '';
-            return handleSearchError(errorMessage); // Delegating error handling
+            return handleSearchError(errorMessage);
         }
     });
 }
-/**
- * Enhanced validation with helpful suggestions
- */
-function validateSearchParameters(params) {
-    // Query validation
-    if (!params.query.trim()) {
-        return ERROR_MESSAGES.EMPTY_QUERY;
-    }
-    if (params.query.length > 1000) {
-        return ERROR_MESSAGES.QUERY_TOO_LONG_1000;
-    }
-    // Repository validation - ensure owner is provided correctly
-    if (params.owner &&
-        typeof params.owner === 'string' &&
-        params.owner.includes('/')) {
-        return 'Owner parameter should contain only the username/org name, not owner/repo format. For repository-specific searches, use org: or user: qualifiers in the query.';
-    }
-    if (Array.isArray(params.owner)) {
-        const hasSlashFormat = params.owner.some(owner => owner.includes('/'));
-        if (hasSlashFormat) {
-            return 'Owner parameter should contain only usernames/org names, not owner/repo format. For repository-specific searches, use repo: qualifier in the query.';
-        }
-    }
-    // Add validation for file size limit
-    if (params.size) {
-        if (!/^([<>]\d+|\d+\.\.\d+)$/.test(params.size)) {
-            return ERROR_MESSAGES.INVALID_SIZE_FORMAT;
-        }
-    }
-    // Validate search scope
-    if (params.match) {
-        const validScopes = ['file', 'path'];
-        const scopes = Array.isArray(params.match) ? params.match : [params.match];
-        if (!scopes.every(scope => validScopes.includes(scope))) {
-            return ERROR_MESSAGES.INVALID_SEARCH_SCOPE;
-        }
-    }
-    // Note about repository limitations (This is a note, not a hard error)
-    // This return statement was returning null before, so it shouldn't be an issue
-    // if (params.repo || params.owner) {
-    //   return null; // Return warning about repository limitations
-    // }
-    return null; // No validation errors
-}
 /**
  * Parse search query to preserve quoted phrases and extract qualifiers.
  * Handles:
@@ -1224,14 +1674,27 @@ function validateSearchParameters(params) {
  * - Multiple terms: react lifecycle -> both terms for AND search
  * - Mixed: "error handling" debug -> phrase + term
  * - Qualifiers: language:javascript -> extracted separately
+ * - Quote escaping issues: automatically fixes common mistakes
  */
 function parseSearchQuery(query) {
     const qualifiers = [];
     const searchTerms = [];
+    // Clean up common quote escaping issues
+    let cleanedQuery = query;
+    // Fix escaped quotes that shouldn't be escaped
+    if (cleanedQuery.includes('\\"') && !cleanedQuery.includes(' ')) {
+        cleanedQuery = cleanedQuery.replace(/\\"/g, '');
+    }
+    // Fix single-word queries wrapped in quotes unnecessarily
+    if (cleanedQuery.startsWith('"') &&
+        cleanedQuery.endsWith('"') &&
+        !cleanedQuery.slice(1, -1).includes(' ')) {
+        cleanedQuery = cleanedQuery.slice(1, -1);
+    }
     // Regular expression to match quoted strings or individual words/qualifiers
     const tokenRegex = /"([^"]+)"|([^\s]+)/g;
     let match;
-    while ((match = tokenRegex.exec(query)) !== null) {
+    while ((match = tokenRegex.exec(cleanedQuery)) !== 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)) {
@@ -1734,6 +2197,51 @@ async function searchGitHubIssues(params) {
             comments: issue.comments,
             reactions: issue.reactions?.total_count || 0,
         }));
+        // Smart fallback suggestions for no results
+        if (cleanIssues.length === 0) {
+            const fallbackSuggestions = [];
+            // Analyze search parameters for specific suggestions
+            if (params.state === 'closed') {
+                fallbackSuggestions.push('• Try state:open or remove state filter');
+            }
+            if (params.author) {
+                fallbackSuggestions.push('• Remove author filter for broader search');
+                fallbackSuggestions.push(`• Use github_search_code to find ${params.author}'s contributions`);
+            }
+            if (params.label) {
+                const labels = Array.isArray(params.label)
+                    ? params.label
+                    : [params.label];
+                fallbackSuggestions.push(`• Try broader labels or remove label filter`);
+                fallbackSuggestions.push(`• Search for label variations: ${labels.map(l => `"${l}"`).join(', ')}`);
+            }
+            if (params.owner && params.repo) {
+                fallbackSuggestions.push('• Check repository name spelling');
+                fallbackSuggestions.push('• Use github_view_repo_structure to verify repository exists');
+            }
+            else if (params.owner) {
+                fallbackSuggestions.push('• Remove owner filter for global search');
+                fallbackSuggestions.push('• Use github_search_repos to find organization repositories');
+            }
+            if (params.created || params.updated) {
+                fallbackSuggestions.push('• Expand date range or remove date filters');
+            }
+            // Add general alternatives
+            fallbackSuggestions.push('• Try broader search terms');
+            fallbackSuggestions.push('• Use github_search_pull_requests for related development activity');
+            fallbackSuggestions.push('• Use github_search_code to find implementation patterns');
+            return createResult({
+                error: `No issues found for query: "${params.query}"
+
+Try these alternatives:
+${fallbackSuggestions.join('\n')}
+
+Discovery strategies:
+• Broader terms: "error" instead of "TypeError"
+• Remove filters: state, labels, author
+• Related searches: pull requests, code implementations`,
+            });
+        }
         const searchResult = {
             results: cleanIssues,
         };
@@ -2195,11 +2703,22 @@ function buildGitHubPullRequestsAPICommand(params) {
  * TIP: Use limit parameter instead of adding more filters
  */
 const GITHUB_SEARCH_REPOSITORIES_TOOL_NAME = 'githubSearchRepositories';
-const DESCRIPTION$3 = `Search GitHub repositories by name, description, topics, language, or organization. Find projects based on stars, forks, activity, and community metrics. Returns repository details including name, description, stars, language, and owner information for project discovery.
+const DESCRIPTION$3 = `Search GitHub repositories for project discovery and ecosystem analysis. TOPICS are the most powerful discovery feature.
+
+TOPIC-DRIVEN DISCOVERY:
+- Topics reveal ecosystem relationships and quality indicators  
+- Combine topics for targeted discovery: ["framework", "use-case", "language"]
+- Topics beat keyword searches for unknown project exploration
+
+PROGRESSIVE SEARCH STRATEGY:
+- Start with topic combinations for broad discovery
+- Add quality filters (stars, activity) for refinement
+- Use multiple separate searches vs complex single queries
 
-Search Syntax - ALL terms must be present (AND logic):
-Multiple search terms require ALL to be found in the repository (name, description, or README).
-Use quotes for exact phrase matching. Additional filters supported via parameters.`;
+RESEARCH INTEGRATION:
+- Repository discovery → structure analysis → implementation patterns
+- Quality assessment via community metrics and activity
+- Bridge to code search and file analysis tools`;
 /**
  * Extract owner/repo information from various query formats
  */
@@ -2411,34 +2930,87 @@ function registerSearchGitHubReposTool(server) {
                 enhancedArgs.forks;
             if (!hasPrimaryFilter) {
                 return createResult({
-                    error: SUGGESTIONS.REPO_SEARCH_PRIMARY_FILTER,
+                    error: `Repository search requires at least one filter. Try these patterns:
+• Topic discovery: { topic: ["react", "typescript"] }
+• Quality search: { stars: ">1000", language: "javascript" }
+• Organization: { owner: "microsoft", language: "python" }
+• Recent projects: { created: ">2023-01-01", stars: ">100" }`,
                 });
             }
             // First attempt: Search with current parameters
             const result = await searchGitHubRepos(enhancedArgs);
+            if (result.isError) {
+                const errorMsg = result.content?.[0]?.text || '';
+                // Smart fallbacks based on error type
+                if (errorMsg.includes('rate limit')) {
+                    return createResult({
+                        error: `GitHub API rate limit. Smart alternatives:
+• Try npm package search for package discovery
+• Use broader filters (remove stars/forks constraints)
+• Search fewer organizations at once
+• Wait 5-10 minutes and retry`,
+                    });
+                }
+                if (errorMsg.includes('authentication')) {
+                    return createResult({
+                        error: `Authentication required. Quick fix:
+1. Run: gh auth login
+2. For private repos: use api_status_check to verify access
+3. Public repos should work without auth - check query`,
+                    });
+                }
+                return result; // Return original error for other cases
+            }
+            // Check if we got results
+            const resultData = JSON.parse(result.content[0].text);
+            const hasResults = resultData.total_count > 0;
+            // Smart fallback strategies for no results
+            if (!hasResults) {
+                const fallbackSuggestions = [];
+                if (enhancedArgs.query) {
+                    fallbackSuggestions.push('• Try broader search terms or remove query filter');
+                }
+                if (enhancedArgs.language) {
+                    fallbackSuggestions.push('• Remove language filter for broader discovery');
+                }
+                if (enhancedArgs.stars || enhancedArgs.forks) {
+                    fallbackSuggestions.push('• Lower quality thresholds (stars/forks)');
+                }
+                if (!enhancedArgs.topic) {
+                    fallbackSuggestions.push('• Try topic-based search: { topic: ["web", "api"] }');
+                }
+                if (enhancedArgs.owner) {
+                    fallbackSuggestions.push('• Search without owner filter for global discovery');
+                    fallbackSuggestions.push('• Use npm package search if looking for packages');
+                }
+                return createResult({
+                    error: `No repositories found. Try these alternatives:
+${fallbackSuggestions.join('\n')}
+
+Discovery patterns:
+• Topic exploration: { topic: ["react"] }
+• Quality discovery: { stars: ">100", language: "python" }
+• Recent activity: { updated: ">2024-01-01" }`,
+                });
+            }
             // 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.',
-                                },
-                            });
-                        }
+            if (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_count > 0) {
+                        // Return private results with note
+                        return createResult({
+                            data: {
+                                ...privateData,
+                                note: 'Found results in private repositories within the specified organization.',
+                            },
+                        });
                     }
                 }
             }
@@ -2593,17 +3165,35 @@ function buildGitHubReposSearchCommand(params) {
     // SEARCH SCOPE
     addArg('match', 'match');
     // SORTING AND LIMITS
-    addArg('limit', 'limit');
-    addArg('order', 'order');
     const sortBy = params.sort || 'best-match';
     if (sortBy !== 'best-match') {
         args.push(`--sort=${sortBy}`);
     }
+    addArg('order', 'order');
+    // Always add limit with default of 30
+    const limit = params.limit || 30;
+    args.push(`--limit=${limit}`);
     return { command: 'search', args };
 }
 
 const GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME = 'githubViewRepoStructure';
-const DESCRIPTION$2 = `Browse GitHub repository file structure and navigate directories. Essential for exploring project layout, finding documentation, configuration files, and source code. Returns file/folder listings with size information. Automatically handles branch detection. Parameters: owner (required - GitHub username/org), repo (required - repository name), branch (required), path (optional - directory path).`;
+const DESCRIPTION$2 = `Explore GitHub repository structure and validate repository access. ESSENTIAL for understanding project organization.
+
+REPOSITORY VALIDATION:
+- Verify repository existence and accessibility
+- Navigate from root to understand project layout  
+- Identify key directories and file patterns
+
+PROJECT UNDERSTANDING:
+- Discover configuration files, documentation, source structure
+- Validate paths before accessing specific files
+- Understand architecture and organization patterns
+
+WORKFLOW INTEGRATION:
+- First step after repository discovery
+- Guides subsequent file access and code search
+- Prevents "file not found" errors through validation
+- Essential for comprehensive repository analysis`;
 function registerViewRepositoryStructureTool(server) {
     server.registerTool(GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME, {
         description: DESCRIPTION$2,
@@ -2853,7 +3443,22 @@ async function suggestPathSearchFallback(owner, path) {
 }
 
 const NPM_PACKAGE_SEARCH_TOOL_NAME = 'npmPackageSearch';
-const DESCRIPTION$1 = `Search NPM packages by name or functionality keywords. Supports multiple search terms for comprehensive package discovery. Returns package name, version, description, keywords, and repository information. Best for finding JavaScript/TypeScript libraries and tools.`;
+const DESCRIPTION$1 = `Search NPM packages by functionality keywords. PRIMARY ENTRY POINT for package-related queries.
+
+PACKAGE-FIRST STRATEGY:
+- Start here when users mention: libraries, dependencies, installations, alternatives
+- Use broad functional terms for discovery (not exact package names)
+- Bridge to GitHub tools via repository URLs from results
+
+SEARCH APPROACH:
+- Single functional terms work best for discovery
+- Multiple searches for different aspects/use-cases
+- Reveals ecosystem alternatives and quality indicators
+
+INTEGRATION WORKFLOW:
+- Package Discovery → Repository Analysis → Implementation Patterns
+- npmPackageSearch → npmViewPackage → GitHub repository tools
+- Compare alternatives by searching different functional terms`;
 const MAX_DESCRIPTION_LENGTH = 100;
 const MAX_KEYWORDS = 10;
 function registerNpmSearchTool(server) {
@@ -2888,28 +3493,136 @@ function registerNpmSearchTool(server) {
             const allPackages = [];
             // Search for each query term
             for (const query of queries) {
-                const result = await executeNpmCommand('search', [query, `--searchlimit=${searchLimit}`, '--json'], { cache: true });
-                if (!result.isError && result.content?.[0]?.text) {
-                    const packages = parseNpmSearchOutput(result.content[0].text);
-                    allPackages.push(...packages);
+                try {
+                    const result = await executeNpmCommand('search', [query, `--searchlimit=${searchLimit}`, '--json'], { cache: true });
+                    if (!result.isError && result.content?.[0]?.text) {
+                        const packages = parseNpmSearchOutput(result.content[0].text);
+                        allPackages.push(...packages);
+                    }
+                    else if (result.isError) {
+                        // Individual query failures are handled silently, continue with others
+                    }
+                }
+                catch (queryError) {
+                    // Continue with other queries even if one fails
                 }
             }
             const deduplicatedPackages = deduplicatePackages(allPackages);
             if (deduplicatedPackages.length > 0) {
+                const { nextSteps } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { hasResults: true });
+                const hints = [];
+                if (nextSteps.length > 0) {
+                    hints.push('Next steps:');
+                    nextSteps.forEach(({ tool, reason }) => {
+                        hints.push(`• Use ${tool} ${reason}`);
+                    });
+                }
                 return createResult({
                     data: {
                         total_count: deduplicatedPackages.length,
                         results: deduplicatedPackages,
+                        hints: hints.length > 0 ? hints : undefined,
                     },
                 });
             }
+            // Smart fallback suggestions based on query patterns
+            const hasSpecificTerms = queries.some(q => q.includes('-') || q.includes('@') || q.length > 15);
+            const hasFrameworkTerms = queries.some(q => ['react', 'vue', 'angular', 'express', 'fastify'].some(fw => q.toLowerCase().includes(fw)));
+            let fallbackSuggestions = [
+                '• Try broader functional terms: "testing" instead of "jest-unit-test"',
+                '• Remove version numbers or specific constraints',
+                '• Use single keywords: "http" instead of "http-client-library"',
+            ];
+            if (hasSpecificTerms) {
+                fallbackSuggestions = [
+                    '• Use simpler terms: "validation" instead of "schema-validation-library"',
+                    '• Try category terms: "database", "testing", "auth"',
+                    ...fallbackSuggestions.slice(1),
+                ];
+            }
+            if (hasFrameworkTerms) {
+                fallbackSuggestions.unshift('• Try specific framework searches: "react hooks", "vue components"');
+            }
+            // Add GitHub integration suggestions
+            fallbackSuggestions.push('• Use github_search_repos with topic filters for project discovery');
+            fallbackSuggestions.push('• Check npm registry status: https://status.npmjs.org');
+            const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, {
+                errorType: 'no_results',
+            });
+            const toolSuggestions = createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback);
             return createResult({
-                error: createNoResultsError('packages'),
+                error: getErrorWithSuggestion({
+                    baseError: createNpmPackageNotFoundError(queries.join(', ')),
+                    suggestion: [fallbackSuggestions.join('\n'), toolSuggestions],
+                }),
             });
         }
         catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            // Network/connectivity issues
+            if (errorMsg.includes('network') ||
+                errorMsg.includes('timeout') ||
+                errorMsg.includes('ENOTFOUND')) {
+                const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { });
+                return createResult({
+                    error: getErrorWithSuggestion({
+                        baseError: ERROR_MESSAGES.NPM_CONNECTION_FAILED,
+                        suggestion: [
+                            '• Check internet connection and npm registry status',
+                            '• Try fewer search terms to reduce load',
+                            '• Retry in a few moments',
+                            createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                        ],
+                    }),
+                });
+            }
+            // NPM CLI issues
+            if (errorMsg.includes('command not found') ||
+                errorMsg.includes('npm')) {
+                const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { });
+                return createResult({
+                    error: getErrorWithSuggestion({
+                        baseError: ERROR_MESSAGES.NPM_CLI_ERROR,
+                        suggestion: [
+                            '• Verify NPM installation: npm --version',
+                            '• Update NPM: npm install -g npm@latest',
+                            '• Check PATH environment variable',
+                            createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                        ],
+                    }),
+                });
+            }
+            // Permission/auth issues
+            if (errorMsg.includes('permission') ||
+                errorMsg.includes('403') ||
+                errorMsg.includes('401')) {
+                const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, { errorType: 'access_denied' });
+                return createResult({
+                    error: getErrorWithSuggestion({
+                        baseError: ERROR_MESSAGES.NPM_PERMISSION_ERROR,
+                        suggestion: [
+                            '• Check npm login status: npm whoami',
+                            '• Use public registry search without auth',
+                            '• Verify npm registry configuration',
+                            createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                        ],
+                    }),
+                });
+            }
+            const { fallback } = getToolSuggestions(TOOL_NAMES.NPM_PACKAGE_SEARCH, {
+                });
             return createResult({
-                error: createSearchFailedError('packages'),
+                error: getErrorWithSuggestion({
+                    baseError: ERROR_MESSAGES.PACKAGE_SEARCH_FAILED,
+                    suggestion: [
+                        `Error details: ${errorMsg}`,
+                        '',
+                        'Fallback strategies:',
+                        '• Check npm status and retry',
+                        '• Use broader search terms',
+                        createToolSuggestion(TOOL_NAMES.NPM_PACKAGE_SEARCH, fallback),
+                    ],
+                }),
             });
         }
     });
@@ -2961,7 +3674,25 @@ function parseNpmSearchOutput(output) {
 }
 
 const NPM_VIEW_PACKAGE_TOOL_NAME = 'npmViewPackage';
-const DESCRIPTION = `Get detailed NPM package information including version, description, repository URL, size, and download statistics. Essential for understanding package details before installation. Returns optimized metadata for package evaluation and code navigation.`;
+const DESCRIPTION = `Analyze NPM packages for repository discovery and dependency insights. BRIDGE to GitHub ecosystem.
+
+PACKAGE ANALYSIS CAPABILITIES:
+- Repository URL discovery for GitHub exploration
+- Version history and release patterns
+- Export analysis for implementation understanding
+- Dependency metadata for ecosystem mapping
+
+GITHUB INTEGRATION:
+- Provides repository links for GitHub repository tools
+- Connects package metadata to source code analysis
+- Enables package-to-implementation research workflows
+- Essential for dependency and alternative evaluation
+
+USE CASES:
+- Repository discovery from package names
+- Version analysis and security assessment
+- Export structure for integration planning
+- Dependency research and ecosystem exploration`;
 function registerNpmViewPackageTool(server) {
     server.registerTool(NPM_VIEW_PACKAGE_TOOL_NAME, {
         description: DESCRIPTION,
@@ -2992,18 +3723,87 @@ function registerNpmViewPackageTool(server) {
         }
         catch (error) {
             const errorMessage = error.message || '';
-            if (errorMessage.includes('not found')) {
+            // Package not found with smart discovery
+            if (errorMessage.includes('not found') ||
+                errorMessage.includes('404')) {
+                const packageName = args.packageName;
+                const suggestions = [];
+                // Check for common naming patterns
+                if (packageName.includes('_')) {
+                    suggestions.push(`• Try with dashes: "${packageName.replace(/_/g, '-')}"`);
+                }
+                if (packageName.includes('-')) {
+                    suggestions.push(`• Try without dashes: "${packageName.replace(/-/g, '')}"`);
+                }
+                if (!packageName.startsWith('@') && packageName.includes('/')) {
+                    suggestions.push(`• Try scoped package: "@${packageName}"`);
+                }
+                if (packageName.startsWith('@')) {
+                    suggestions.push(`• Try without scope: "${packageName.split('/')[1]}"`);
+                }
+                // Add discovery alternatives
+                suggestions.push('• Use npm_package_search for discovery');
+                suggestions.push('• Use github_search_repos to find source repository');
+                suggestions.push('• Check exact spelling on npmjs.com');
                 return createResult({
-                    error: 'Package not found. Check spelling and use exact package name from npm',
+                    error: `Package "${packageName}" not found on NPM registry.
+
+Try these alternatives:
+${suggestions.join('\n')}
+
+Discovery workflow:
+1. Use npm_package_search with functional terms
+2. Use github_search_repos for related projects
+3. Verify exact package name on npmjs.com`,
+                });
+            }
+            // Network issues with fallback strategies
+            if (errorMessage.includes('network') ||
+                errorMessage.includes('timeout') ||
+                errorMessage.includes('ENOTFOUND')) {
+                return createResult({
+                    error: `NPM registry connection failed. Alternative strategies:
+• Check internet connection and npm registry status
+• Use github_search_repos to find package repository
+• Try npm_package_search for broader discovery
+• Visit https://npmjs.com/${args.packageName} directly
+• Retry in a few moments`,
+                });
+            }
+            // NPM CLI issues
+            if (errorMessage.includes('command not found') ||
+                errorMessage.includes('npm')) {
+                return createResult({
+                    error: `NPM CLI issue. Quick fixes:
+• Verify NPM installation: npm --version
+• Update NPM: npm install -g npm@latest  
+• Use github_search_repos to find package repository
+• Check PATH environment variable
+• Try web interface: https://npmjs.com/${args.packageName}`,
                 });
             }
-            if (errorMessage.includes('network')) {
+            // Permission/registry issues
+            if (errorMessage.includes('permission') ||
+                errorMessage.includes('403') ||
+                errorMessage.includes('401')) {
                 return createResult({
-                    error: 'Network error. Check internet connection and try again',
+                    error: `NPM registry access issue. Try these solutions:
+• Check npm configuration: npm config get registry
+• Use public registry: npm config set registry https://registry.npmjs.org/
+• Try github_search_repos for package source code
+• Visit package page: https://npmjs.com/${args.packageName}`,
                 });
             }
+            // Generic error with comprehensive fallbacks
             return createResult({
-                error: 'Failed to fetch package information. Try again or check npm status',
+                error: `Failed to fetch package "${args.packageName}": ${errorMessage}
+
+Fallback strategies:
+• Use npm_package_search for similar packages
+• Use github_search_repos with package name as query
+• Check package on web: https://npmjs.com/${args.packageName}
+• Verify npm status: https://status.npmjs.org
+• Try alternative package managers (yarn info, pnpm view)`,
             });
         }
     });
@@ -3114,130 +3914,120 @@ async function viewNpmPackage(packageName) {
     });
 }
 
-const PROMPT_SYSTEM_PROMPT = `You are an expert code research assistant that knows how to understand users needs and search for the right information
-using gh cli for github and npm cli for packages.
-
-CRITICAL SEARCH PRINCIPLES:
-
-PROGRESSIVE SEARCH STRATEGY (MOST IMPORTANT):
-   a) START BROAD: Begin with simple, general queries and terms (1-2 words max)
-   b) ANALYZE RESULTS: Learn from what you find
-   c) REFINE GRADUALLY: Add filters only after understanding the landscape and if needed (only if the user asks for it explicitly)
-   d) MULTIPLE ANGLES: Try different search terms if first approach yields no results
-
-HANDLING NO RESULTS:
-   - NEVER give up after one failed search. 
-   - Act on fallbacks messages and try to understand the user's intent.
-   - Try progressively BROADER terms (simplify queries and remove filters)
-
-SMART FILTER USAGE:
-   - NO FILTERS on first search (unless user specifies)
-   - Add ONE filter at a time based on results
-   - Common progression: query → +language → +stars → +owner (only if user asks for it explicitly)
-   - Reserve complex filters for final refinement
-
-RESEARCH BEST PRACTICES:
-   - Conduct COMPREHENSIVE research with multiple searches
-   - Learn from each search to improve the next
-   - Provide context about your search strategy
-   - Always verify technical details with actual code
-
-COMPLEX ANALYSIS PATTERNS:
-
-Multi-terms Comparison
-   1. Search repos separately: "repoA", then "repoB"
-   2. Review repositories structure and files
-   3. Review code and documentation
-   4. Compare similar functionalities across repos
-   5. Use filters and flags to narrow down the results
-
-Evolution Tracking (e.g., Feature History):
-   1. Use commit search with broad terms first
-   2. Narrow by date ranges progressively
-   3. Track changes in specific files over time
-   4. Identify key contributors and their patterns
-
-CROSS-REPOSITORY INTELLIGENCE:
-   - When comparing frameworks, search EACH separately first
-   - Build mental model of each codebase structure
-   - Use discovered patterns to refine searches and connect findings across repositories for insights
-
-RESEARCH WORKFLOW BEST PRACTICES:
-
-Discovery Phase (Unknown Projects/Topics):
-   - START with ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME} using TOPICS
-   - Topics are underutilized but extremely powerful for discovery
-   - Example: { topic: ["react", "typescript", "testing"], stars: ">500" }
-
-Understanding Phase
-   - ALWAYS use ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} first to verify repository exists
-   - CRITICAL: Many failures are due to incorrect repository names - verify before proceeding
-   - Check README.md, docs/, configuration files
-   - Understand project structure before searching code
-   - Never make assumptions about repository names or file locations - always verify
-
-Implementation Search (Specific Code):
-   - Fetch importnat files using ${GITHUB_GET_FILE_CONTENT_TOOL_NAME}
-   - Use ${GITHUB_SEARCH_CODE_TOOL_NAME} with NARROW queries
-   - Start precise, broaden only if needed
-   - Use exact phrases when you know patterns
-   - Verify dependences and imports
-
-File Access Validation Workflow:
-   1. VERIFY repository name first with ${GITHUB_SEARCH_CODE_TOOL_NAME} if unsure
-   2. Use ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} to confirm repository structure
-   3. Navigate to parent directory first to understand layout
-   4. Only then use ${GITHUB_GET_FILE_CONTENT_TOOL_NAME} with confirmed paths
-   5. Most "file not found" errors are due to incorrect repository names
-
-TOOL-SPECIFIC BEST PRACTICES:
+const PROMPT_SYSTEM_PROMPT = `You are an expert code research assistant specialized in comprehensive package and repository analysis using GitHub CLI and NPM CLI.
 
-${API_STATUS_CHECK_TOOL_NAME}:
-   - Run FIRST when dealing with private repositories
-   - Use organizations list to scope searches
-   - Verify authentication before extensive searches
+CORE RESEARCH PHILOSOPHY:
+   - PACKAGE-FIRST: When packages mentioned → start with NPM tools → bridge to GitHub
+   - REPOSITORY-FIRST: When repos mentioned → start with GitHub tools → explore dependencies  
+   - CROSS-REFERENCE: Always connect packages to repositories and repositories to packages
+   - PROGRESSIVE: Start broad, refine gradually, use multiple separate searches
+
+CRITICAL SEARCH STRATEGIES:
+
+MULTI-SEARCH APPROACH (MOST EFFECTIVE):
+   a) SEPARATE SEARCHES: Individual terms beat complex queries
+   b) PROGRESSIVE REFINEMENT: Start broad → analyze → narrow down  
+   c) CROSS-TOOL VALIDATION: Verify findings across GitHub and NPM
+   d) TOPIC DISCOVERY: Use topics as primary discovery mechanism
+
+PACKAGE-CENTRIC WORKFLOWS:
+   When users mention: libraries, dependencies, packages, installations, versions
+   → START with ${NPM_PACKAGE_SEARCH_TOOL_NAME} → ${NPM_VIEW_PACKAGE_TOOL_NAME} → GitHub tools
+
+NPM-TO-GITHUB INTEGRATION PATTERNS:
+   1. Package Discovery: ${NPM_PACKAGE_SEARCH_TOOL_NAME} → get repository URLs → ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}
+   2. Dependency Analysis: ${NPM_VIEW_PACKAGE_TOOL_NAME} → repository structure → implementation patterns
+   3. Alternative Research: Multiple ${NPM_PACKAGE_SEARCH_TOOL_NAME} → compare repositories → evaluate quality
+   4. Version Investigation: ${NPM_VIEW_PACKAGE_TOOL_NAME} → commit history → feature evolution
+
+REPOSITORY-CENTRIC WORKFLOWS:
+   When users mention: codebases, implementations, source code, organizations
+   → START with ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME} using TOPICS → drill down to specifics
+
+COMPREHENSIVE RESEARCH PATTERNS:
+
+Discovery Phase (Unknown Territory):
+   - TOPICS FIRST: ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME} with topic combinations
+   - Topics reveal ecosystems, relationships, quality indicators
+   - Example topics: ["framework-name", "use-case", "language"]
+
+Understanding Phase:
+   - Repository Structure: ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME} for project layout
+   - Package Metadata: ${NPM_VIEW_PACKAGE_TOOL_NAME} for dependencies and exports
+   - Cross-validation: Verify package-repo connections
+
+Implementation Phase:
+   - Code Patterns: ${GITHUB_SEARCH_CODE_TOOL_NAME} with SEPARATE single-term searches
+   - File Access: ${GITHUB_GET_FILE_CONTENT_TOOL_NAME} for specific implementations
+   - Historical Context: ${GITHUB_SEARCH_COMMITS_TOOL_NAME} for feature evolution
+
+TOOL INTEGRATION BEST PRACTICES:
+
+${NPM_PACKAGE_SEARCH_TOOL_NAME}:
+   - Primary entry for package-related queries
+   - Use broad functional terms, not exact package names
+   - Bridge to GitHub via repository URLs
+
+${NPM_VIEW_PACKAGE_TOOL_NAME}:
+   - Essential for repository discovery and dependency analysis
+   - Provides GitHub repository links for further exploration
+   - Critical for version and export analysis
 
 ${GITHUB_SEARCH_REPOSITORIES_TOOL_NAME}:
-   - Start with topic/language, add stars/forks filters later
-   - Use date ranges for trending analysis
-   - Combine multiple searches for comprehensive discovery
+   - TOPICS are the most powerful discovery feature
+   - Start with topic/language combinations
+   - Quality indicators: stars, activity, community
 
 ${GITHUB_SEARCH_CODE_TOOL_NAME}:
-   - Begin with function/class names, not full signatures
-   - Use extension filters for targeted searches
-   - Try partial matches before exact phrases
+   - SEPARATE searches outperform complex queries
+   - Single terms without quotes for broad discovery
+   - Multi-word phrases WITH quotes for exact patterns
 
 ${GITHUB_VIEW_REPO_STRUCTURE_TOOL_NAME}:
-   - Navigate from root, then drill down
-   - Use for understanding project organization
-   - Check common paths: src/, lib/, packages/
+   - Always verify repository existence and structure first
+   - Navigate from root to understand project organization
+   - Essential before accessing specific files
 
 ${GITHUB_GET_FILE_CONTENT_TOOL_NAME}:
-   - Verify file paths with repo structure first
-   - Use for implementation details and documentation
+   - Use AFTER structure verification
+   - Focus on configuration, documentation, key implementations
+   - Validate paths through structure exploration
 
 ${GITHUB_SEARCH_COMMITS_TOOL_NAME}:
-   - Search by feature keywords
-   - Date ranges help track feature evolution
+   - Feature evolution and implementation history
+   - Author patterns and development activity
+   - Date ranges for tracking changes
 
 ${GITHUB_SEARCH_ISSUES_TOOL_NAME} & ${GITHUB_SEARCH_PULL_REQUESTS_TOOL_NAME}:
-   - Search for problem descriptions
-   - Use state filters progressively
+   - Problem-solution discovery
+   - Implementation discussions and decisions
+   - Community feedback and feature requests
 
-${NPM_PACKAGE_SEARCH_TOOL_NAME}:
-   - Search npm package in registry - use one term at a time (partial or exact)
+${API_STATUS_CHECK_TOOL_NAME}:
+   - First step for private repository access
+   - Organization discovery for scoped searches
+   - Authentication troubleshooting
 
-${NPM_VIEW_PACKAGE_TOOL_NAME}:
-   - Returns essential data like github path and package metadata like dependencies, exports...
-
-CHAIN OF THOUGHT OPTIMIZATION:
-   - Plan search sequence before executing
-   - Document reasoning for each search refinement
-   - Build knowledge progressively, don't jump to specifics
-   - Validate findings with multiple sources
-   - Ask user for clarification if needed
-   - Learn from results and refine search strategy
-   - Output high level summary of the search and results based on data and not assumptions
+INTELLIGENT SEARCH PROGRESSION:
+
+No Results Strategy:
+   - BROADEN search terms (remove filters)
+   - Try ALTERNATIVE tool (NPM ↔ GitHub)
+   - Use TOPICS for discovery
+   - Check SPELLING and exact names
+
+Quality Research Indicators:
+   - Cross-tool consistency (NPM package ↔ GitHub repo)
+   - Community metrics (stars, downloads, issues)
+   - Recent activity (commits, releases, discussions)
+   - Documentation quality and completeness
+
+CHAIN OF RESEARCH OPTIMIZATION:
+   - Plan multi-tool sequences before execution
+   - Connect findings across NPM and GitHub ecosystems  
+   - Build comprehensive understanding progressively
+   - Validate technical details with actual code
+   - Provide actionable insights based on data patterns
 `;
 
 const SERVER_CONFIG = {