octocode-mcp 2.3.11 → 2.3.13

package/build/index.js

@@ -144,29 +144,6 @@ function escapeShellArg(arg, shellType, isGitHubQuery // Flag to indicate if thi
         const isWindows = platform() === 'win32';
         shellType = isWindows ? 'cmd' : 'unix';
     }
-    // Special handling for GitHub search queries to preserve AND logic
-    if (isGitHubQuery) {
-        // 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') {
-                return `'${arg.replace(/'/g, "'\"'\"'")}'`;
-            }
-            // For Windows CMD
-            if (shellType === 'cmd') {
-                return `"${arg.replace(/"/g, '""')}"`;
-            }
-            // 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':
             return escapePowerShellArg(arg);
@@ -174,7 +151,7 @@ function escapeShellArg(arg, shellType, isGitHubQuery // Flag to indicate if thi
             return escapeWindowsCmdArg(arg);
         case 'unix':
         default:
-            return escapeUnixShellArg(arg, isGitHubQuery);
+            return escapeUnixShellArg(arg);
     }
 }
 /**
@@ -205,30 +182,10 @@ 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 and quoted phrases
-    if (isGitHubQuery) {
-        // 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
-        // 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, "'\"'\"'")}'`;
-        }
-        // Simple terms don't need escaping
-        return arg;
-    }
     // Standard Unix shell escaping for other arguments
-    if (/[^a-zA-Z0-9\-_./=@:]/.test(arg)) {
+    // Only escape if contains dangerous shell metacharacters
+    // Allow common safe characters: alphanumeric, dash, underscore, dot, slash, equals, at, colon, comma
+    if (/[;&|<>$`\\*?()[\]{}^~]/.test(arg)) {
         return `'${arg.replace(/'/g, "'\"'\"'")}'`;
     }
     return arg;
@@ -245,7 +202,28 @@ async function executeNpmCommand(command, args = [], options = {}) {
     // Get shell configuration
     const shellConfig = getShellConfig(options.windowsShell);
     // Build command with validated prefix and properly escaped arguments
-    const escapedArgs = args.map(arg => escapeShellArg(arg, shellConfig.type));
+    // NPM commands need minimal escaping - most arguments are package names or CLI flags
+    const escapedArgs = args.map(arg => {
+        const isCliFlag = arg.startsWith('--');
+        // CLI flags like --searchlimit=20, --json need minimal escaping
+        if (isCliFlag) {
+            // Only escape CLI flags if they contain dangerous shell characters
+            if (/[;&|<>$`\\]/.test(arg)) {
+                return escapeShellArg(arg, shellConfig.type);
+            }
+            return arg;
+        }
+        // Package names and search terms need minimal escaping
+        // Only escape if contains shell metacharacters that could be dangerous
+        if (/[;&|<>$`\\*?[\]{}]/.test(arg)) {
+            return escapeShellArg(arg, shellConfig.type);
+        }
+        // For arguments with spaces, use minimal quoting
+        if (/\s/.test(arg)) {
+            return `"${arg}"`;
+        }
+        return arg;
+    });
     const fullCommand = `npm ${command} ${escapedArgs.join(' ')}`;
     const executeNpmCommand = () => executeCommand(fullCommand, 'npm', options, shellConfig);
     if (options.cache) {
@@ -269,33 +247,40 @@ 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, 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
+    // For GitHub search commands, we need minimal escaping to avoid interfering with GitHub CLI
     const escapedArgs = args.map((arg, index) => {
         const isMainQueryArgument = command === 'search' && index === 1;
         const isCliFlag = arg.startsWith('--');
-        const isGitHubQualifier = command === 'search' &&
-            index > 1 &&
-            !isCliFlag &&
-            (arg.includes(':') || arg.startsWith('('));
-        // CLI flags like --language=javascript, --repo=owner/repo need standard escaping
+        // CLI flags like --language=javascript, --repo=owner/repo need minimal escaping
         if (isCliFlag) {
-            return escapeShellArg(arg, shellConfig.type, false);
+            // Only escape CLI flags if they contain dangerous shell characters
+            if (/[;&|<>$`\\*?[\]{}]/.test(arg)) {
+                return escapeShellArg(arg, shellConfig.type);
+            }
+            return arg;
         }
-        // GitHub search qualifiers need special handling
-        // Most qualifiers can be passed as-is, but those with shell metacharacters need escaping
-        if (isGitHubQualifier) {
-            // Check if the qualifier contains shell metacharacters that need escaping
-            if (/[<>&|;`$\\]/.test(arg)) {
-                // Escape qualifiers that contain shell metacharacters like size:<1000, size:>500
-                return escapeShellArg(arg, shellConfig.type, false);
+        // For search queries, only escape if absolutely necessary for shell safety
+        if (isMainQueryArgument) {
+            // Only escape if the argument contains shell metacharacters that could be dangerous
+            if (/[;&|<>$`\\*?[\]{}]/.test(arg)) {
+                return escapeShellArg(arg, shellConfig.type);
+            }
+            // For simple queries with spaces or special chars, use minimal quoting
+            if (/\s/.test(arg)) {
+                return `"${arg}"`;
             }
-            // Safe qualifiers like "language:typescript", "user:microsoft" can be passed as-is
             return arg;
         }
-        return escapeShellArg(arg, shellConfig.type, isMainQueryArgument);
+        // For other arguments, use minimal escaping
+        // Only escape if contains shell metacharacters that could be dangerous
+        if (/[;&|<>$`\\*?[\]{}]/.test(arg)) {
+            return escapeShellArg(arg, shellConfig.type);
+        }
+        // For arguments with spaces, use minimal quoting
+        if (/\s/.test(arg)) {
+            return `"${arg}"`;
+        }
+        return arg;
     });
     const fullCommand = `gh ${command} ${escapedArgs.join(' ')}`;
     const executeGhCommand = () => executeCommand(fullCommand, 'github', options, shellConfig);
@@ -944,23 +929,10 @@ function createToolSuggestion(currentTool, suggestedTools) {
 }
 
 const API_STATUS_CHECK_TOOL_NAME = 'apiStatusCheck';
-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`;
+const DESCRIPTION$9 = `initial tool to verify user connections
+
+- Github: check gh login status and list available organizations.
+- Npm: check npm login status and list npm registry.`;
 // Helper function to parse execution results with proper typing
 function parseExecResult(result) {
     if (!result.isError && result.content?.[0]?.text) {
@@ -1119,69 +1091,64 @@ const DESCRIPTION$8 = `Search code across GitHub repositories using GitHub's cod
 
 SEARCH STRATEGY FOR BEST RESULTS:
 
-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)
+EXACT vs TERMS (Choose ONE):
+- exactQuery: Use for exact phrase matching
+- queryTerms: Use minimal words for broader coverage
 
-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
+TERM OPTIMIZATION:
+- BEST: Single terms for maximum coverage
+- GOOD: 2-3 minimal terms 
+- AVOID: Long phrases in queryTerms
 
-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
+MULTI-SEARCH STRATEGY:
+- Use separate searches for different aspects
+- Separate searches provide broader coverage than complex queries
 
 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`;
+- Use filters to narrow scope: language, owner, repo, filename
+- Combine filters strategically: language + owner for organization-wide searches
+- Never use filters on exploratory searches - use to refine results`;
 function registerGitHubSearchCodeTool(server) {
     server.registerTool(GITHUB_SEARCH_CODE_TOOL_NAME, {
         description: DESCRIPTION$8,
         inputSchema: {
-            query: z
+            exactQuery: z
                 .string()
-                .min(1)
-                .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).'),
+                .optional()
+                .describe('Exact phrase/word to search for'),
+            queryTerms: z
+                .array(z.string())
+                .optional()
+                .describe('Array of search terms (AND logic in files). Use minimal words for broader coverage'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter. Uses --language CLI flag. Narrows search to specific language files. Use for language-specific searches.'),
+                .describe('Programming language filter. Narrows search to specific language files.'),
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .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.'),
+                .describe('Repository owner/organization name(s). Organization-wide search.'),
             repo: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .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).'),
+                .describe('Repository filter. Use with owner or full format.'),
             filename: z
                 .string()
                 .optional()
-                .describe('Target specific filename or pattern. Uses --filename CLI flag. Use for file-specific searches.'),
+                .describe('Target specific filename or pattern.'),
             extension: z
                 .string()
                 .optional()
-                .describe('File extension filter. Uses --extension CLI flag. Alternative to language parameter.'),
+                .describe('File extension filter. Alternative to language parameter.'),
             match: z
                 .enum(['file', 'path'])
                 .optional()
-                .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.'),
+                .describe('Search scope: file for file content (default), path for filenames/paths.'),
             size: z
                 .string()
-                .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">10", ">=5", "<100", "<=50", "10..100", or exact number "50"')
+                .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid size format. Use: ">N", ">=N", "<N", "<=N", "N..M", or exact number')
                 .optional()
-                .describe('File size filter in KB. Uses --size CLI flag. Format: ">N" (larger than), "<N" (smaller than), "N..M" (range), "N" (exact).'),
+                .describe('File size filter in KB. Format: ">N" (larger), "<N" (smaller), "N..M" (range).'),
             limit: z
                 .number()
                 .int()
@@ -1189,7 +1156,7 @@ function registerGitHubSearchCodeTool(server) {
                 .max(100)
                 .optional()
                 .default(30)
-                .describe('Maximum number of results to return (1-100). Default: 30. Higher values may increase response time.'),
+                .describe('Maximum number of results to return (1-100).'),
         },
         annotations: {
             title: 'GitHub Code Search - Smart & Efficient',
@@ -1199,6 +1166,19 @@ function registerGitHubSearchCodeTool(server) {
             openWorldHint: true,
         },
     }, async (args) => {
+        // Validate that exactly one search parameter is provided (not both)
+        const hasExactQuery = !!args.exactQuery;
+        const hasQueryTerms = args.queryTerms && args.queryTerms.length > 0;
+        if (!hasExactQuery && !hasQueryTerms) {
+            return createResult({
+                error: 'One search parameter required: exactQuery OR queryTerms',
+            });
+        }
+        if (hasExactQuery && hasQueryTerms) {
+            return createResult({
+                error: 'Use either exactQuery OR queryTerms, not both. Choose one search approach.',
+            });
+        }
         try {
             const result = await searchGitHubCode(args);
             if (result.isError) {
@@ -1354,26 +1334,31 @@ function extractSingleRepository$1(items) {
 }
 /**
  * Build command line arguments for GitHub CLI following the exact CLI format.
- * Uses proper flags (--flag=value) instead of qualifiers where appropriate.
+ * Uses proper flags (--flag=value) for filters and direct query terms.
  */
 function buildGitHubCliArgs(params) {
     const args = ['code'];
-    // 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 (these should remain as qualifiers)
-    extractedQualifiers.forEach(qualifier => {
-        args.push(qualifier);
-    });
+    // Build search query (either exactQuery OR queryTerms, never both)
+    if (params.exactQuery) {
+        // Add exact query - let GitHub CLI handle the quoting
+        args.push(params.exactQuery);
+    }
+    else if (params.queryTerms && params.queryTerms.length > 0) {
+        // Add query terms as separate arguments (for AND logic)
+        // Auto-quote terms with special characters for literal matching
+        const processedTerms = params.queryTerms.map(term => {
+            // Check if term contains special search characters that need quoting
+            const hasSpecialChars = /[()[\]{}*?^$|.\\+]/.test(term);
+            return hasSpecialChars ? `"${term}"` : term;
+        });
+        args.push(...processedTerms);
+    }
     // Add explicit parameters as CLI flags (following GitHub CLI format)
-    if (params.language && !params.query.includes('language:')) {
+    if (params.language) {
         args.push(`--language=${params.language}`);
     }
     // Handle owner and repo parameters properly
-    if (params.repo && !params.query.includes('repo:')) {
+    if (params.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
@@ -1389,30 +1374,27 @@ function buildGitHubCliArgs(params) {
             }
         });
     }
-    else if (params.owner &&
-        !params.query.includes('org:') &&
-        !params.query.includes('user:')) {
+    else if (params.owner) {
         // 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(`--owner=${owner}`));
     }
-    if (params.filename && !params.query.includes('filename:')) {
+    if (params.filename) {
         args.push(`--filename=${params.filename}`);
     }
-    if (params.extension && !params.query.includes('extension:')) {
+    if (params.extension) {
         args.push(`--extension=${params.extension}`);
     }
-    if (params.size && !params.query.includes('size:')) {
+    if (params.size) {
         args.push(`--size=${params.size}`);
     }
     // Handle match parameter - use --match flag
     if (params.match) {
         args.push(`--match=${params.match}`);
     }
-    // Add limit flag
-    if (params.limit) {
-        args.push(`--limit=${params.limit}`);
-    }
+    // Add limit flag (use default 30 if not specified)
+    const limit = params.limit || 30;
+    args.push(`--limit=${limit}`);
     // Add JSON output format
     args.push('--json=repository,path,textMatches,sha,url');
     return args;
@@ -1433,55 +1415,6 @@ async function searchGitHubCode(params) {
         }
     });
 }
-/**
- * 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
- * - 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(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)) {
-            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,
-    };
-}
 
 /***********************************************************************
 
@@ -112365,14 +112298,13 @@ const GITHUB_SEARCH_REPOSITORIES_TOOL_NAME = 'githubSearchRepositories';
 const DESCRIPTION$6 = `Search GitHub repositories using gh search repos CLI.
 
 BEST PRACTICES:
-- Use topics for unknown domains to explore repositories by TOPIC
-- Use owner to explore repositories by ORGANIZATION
-- Search by name and sort by best match / starts to search specific repositories 
-- Use language to explore repositories by LANGUAGE
+- Use topic for discovering repositories by technology/purpose
+- Use query for searching by repository name
+- Use owner to explore specific organizations
+- Use language to filter by programming language
 - Use quality filters (stars, forks) for refinement
-- Use limit to control the number of repositories to return
 
-Seperate queries for different topics and repositories search and use minimal filters to get the most relevant results`;
+Separate searches for different topics and use minimal filters to get the most relevant results`;
 /**
  * Extract owner/repo information from various query formats
  */
@@ -112410,38 +112342,38 @@ function registerSearchGitHubReposTool(server) {
             query: z
                 .string()
                 .optional()
-                .describe('Search query with AND logic between terms. Multiple words require ALL to be present. Use quotes for exact phrases. Examples: "cli shell", "vim plugin". For negation, use embedded qualifiers like "topic:react -topic:vue". Advanced: supports GitHub search qualifiers (stars:>100, language:python, etc.)'),
+                .describe('Search by repository name. Use minimal words for repository names or specific projects. For topic discovery, use topic parameter instead.'),
             // CORE FILTERS (GitHub CLI flags)
             owner: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('Repository owner/organization name(s) (e.g., "facebook", ["google", "microsoft"]). Search within specific organizations. Do NOT use owner/repo format - just the organization/username.'),
+                .describe('Repository owner/organization name(s). Search within specific organizations or users.'),
             language: z
                 .string()
                 .optional()
-                .describe('Programming language filter. Filters repositories by primary language. Essential for language-specific searches.'),
+                .describe('Programming language filter. Filters repositories by primary language.'),
             stars: z
                 .union([
                 z.number().int().min(0),
                 z
                     .string()
-                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">1000", ">=500", "<100", "<=50", "10..100", or exact number "50"'),
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">N", ">=N", "<N", "<=N", "N..M", or exact number'),
             ])
                 .optional()
-                .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).'),
+                .describe('Star count filter. Format: ">N" (more than), "<N" (less than), "N..M" (range).'),
             topic: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('🎯 BEST FOR EXPLORATION: Repository topics filter. Use for discovering projects in unknown domains. Format: single topic "react" or array ["unix", "terminal"]. Topics use kebab-case format.'),
+                .describe('Discover repositories by topic. Use for exploring unknown domains and finding projects by technology or purpose.'),
             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"'),
+                    .regex(/^(>=?\d+|<=?\d+|\d+\.\.\d+|\d+)$/, 'Invalid format. Use: ">N", ">=N", "<N", "<=N", "N..M", or exact number'),
             ])
                 .optional()
-                .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).'),
+                .describe('Fork count filter. Format: ">N" (more than), "<N" (less than), "N..M" (range).'),
             // Match CLI parameter name exactly
             'number-topics': z
                 .union([
@@ -112456,7 +112388,7 @@ function registerSearchGitHubReposTool(server) {
             license: z
                 .union([z.string(), z.array(z.string())])
                 .optional()
-                .describe('License filter. Examples: "mit", "apache-2.0", ["mit", "bsd-3-clause"]'),
+                .describe('License filter. Filter repositories by license type.'),
             archived: z
                 .boolean()
                 .optional()
@@ -112520,7 +112452,7 @@ function registerSearchGitHubReposTool(server) {
                 z.array(z.enum(['name', 'description', 'readme'])),
             ])
                 .optional()
-                .describe('Search scope. "name" (repository names only), "description" (descriptions only), "readme" (README content). Can be single value or array.'),
+                .describe('Search scope. Where to search: name, description, or readme content.'),
             // SORTING & LIMITS - Match CLI defaults exactly
             sort: z
                 .enum([
@@ -113485,22 +113417,21 @@ function buildGitHubPullRequestsListCommand(params) {
 }
 
 const NPM_PACKAGE_SEARCH_TOOL_NAME = 'npmPackageSearch';
-const DESCRIPTION$3 = `Search NPM packages by functionality keywords. PRIMARY ENTRY POINT for package-related queries.
+const DESCRIPTION$3 = `Search NPM packages using 'npm search' command. Discover packages by functionality keywords and explore alternatives.
 
-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
+**WHEN TO USE**: Use when users ask questions about npm packages or need to discover packages - provides package discovery and ecosystem insights.
 
-SEARCH APPROACH:
-- Single functional terms work best for discovery
-- Multiple searches for different aspects/use-cases
-- Reveals ecosystem alternatives and quality indicators
+**KEY INSIGHTS**:
+- Another code search mechanism for npm packages (along github repository search)
+- Repo discovery by npm packages search
+- Package descriptions, keywords, and version information
+- Can be used undesrsant npm depndencies better
 
-INTEGRATION WORKFLOW:
-- Package Discovery → Repository Analysis → Implementation Patterns
-- npmPackageSearch → npmViewPackage → GitHub repository tools
-- Compare alternatives by searching different functional terms`;
+**SEARCH STRATEGY**:
+- Use broad functional terms for best discovery
+- Single keywords work better than complex phrases
+- Multiple searches reveal ecosystem alternatives
+- Combine with npm_view_package for detailed analysis of discovered packages`;
 const MAX_DESCRIPTION_LENGTH = 100;
 const MAX_KEYWORDS = 10;
 function registerNpmSearchTool(server) {
@@ -114365,25 +114296,22 @@ function buildGitHubIssuesAPICommand(params) {
 }
 
 const NPM_VIEW_PACKAGE_TOOL_NAME = 'npmViewPackage';
-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`;
+const DESCRIPTION = `View NPM package information using 'npm view' command. Supports field-specific queries and GitHub repository discovery.
+
+**WHEN TO USE**: Use when users ask questions about npm packages - provides comprehensive package data and insights.
+
+**KEY INSIGHTS**:
+- Git repository URL for source code exploration
+- Package exports structure (understand API surface and dependencies)
+- Dependencies/devDependencies for ecosystem analysis
+- Version history, size, performance metrics
+- License and author information
+
+**CAPABILITIES**:
+- Full package info: npm view <package> --json (optimized format)
+- Single field: npm view <package> <field> (version, description, license)
+- Multiple fields: filtered JSON response for specific fields
+- Repository URLs for GitHub integration and source code analysis`;
 function registerNpmViewPackageTool(server) {
     server.registerTool(NPM_VIEW_PACKAGE_TOOL_NAME, {
         description: DESCRIPTION,
@@ -114392,6 +114320,51 @@ function registerNpmViewPackageTool(server) {
                 .string()
                 .min(1)
                 .describe('NPM package name (e.g., "react", "express", "@types/node"). Include @ prefix for scoped packages.'),
+            field: z
+                .string()
+                .optional()
+                .describe('Optional field to get specific information (e.g., "version", "description", "license"). If not provided, returns full package info.'),
+            match: z
+                .union([
+                z.enum([
+                    'version',
+                    'description',
+                    'license',
+                    'author',
+                    'homepage',
+                    'repository',
+                    'dependencies',
+                    'devDependencies',
+                    'keywords',
+                    'main',
+                    'scripts',
+                    'engines',
+                    'files',
+                    'publishConfig',
+                    'dist-tags',
+                    'time',
+                ]),
+                z.array(z.enum([
+                    'version',
+                    'description',
+                    'license',
+                    'author',
+                    'homepage',
+                    'repository',
+                    'dependencies',
+                    'devDependencies',
+                    'keywords',
+                    'main',
+                    'scripts',
+                    'engines',
+                    'files',
+                    'publishConfig',
+                    'dist-tags',
+                    'time',
+                ])),
+            ])
+                .optional()
+                .describe('Specific field(s) to retrieve. Can be single field or array of fields. Examples: "version", ["version", "description"], ["dependencies", "devDependencies"]. When used, returns only the specified fields. use repository to get the repository url in github'),
         },
         annotations: {
             title: 'NPM Package Analyzer',
@@ -114402,13 +114375,48 @@ function registerNpmViewPackageTool(server) {
         },
     }, async (args) => {
         try {
-            const result = await viewNpmPackage(args.packageName);
+            const result = await viewNpmPackage(args.packageName, args.field, args.match);
             if (result.isError) {
                 return result;
             }
+            // If field is specified, npm returns plain text, not JSON
+            if (args.field) {
+                const plainTextResult = result.content[0].text;
+                // Parse the plain text result from npm command
+                const execResult = JSON.parse(plainTextResult);
+                const fieldValue = execResult.result;
+                return createResult({
+                    data: {
+                        field: args.field,
+                        value: fieldValue,
+                        package: args.packageName,
+                    },
+                });
+            }
+            // If match is specified, filter the JSON response to only include matched fields
+            if (args.match) {
+                const execResult = JSON.parse(result.content[0].text);
+                const packageData = execResult.result;
+                const matchFields = Array.isArray(args.match)
+                    ? args.match
+                    : [args.match];
+                const filteredData = {};
+                matchFields.forEach(field => {
+                    if (packageData[field] !== undefined) {
+                        filteredData[field] = packageData[field];
+                    }
+                });
+                return createResult({
+                    data: {
+                        package: args.packageName,
+                        fields: matchFields,
+                        values: filteredData,
+                    },
+                });
+            }
+            // Otherwise return full optimized format (JSON response)
             const execResult = JSON.parse(result.content[0].text);
             const packageData = execResult.result;
-            // Transform to optimized format
             const optimizedResult = transformToOptimizedFormat(packageData);
             return createResult({ data: optimizedResult });
         }
@@ -114418,6 +114426,11 @@ function registerNpmViewPackageTool(server) {
             if (errorMessage.includes('not found') ||
                 errorMessage.includes('404')) {
                 const packageName = args.packageName;
+                const fieldInfo = args.field ? ` (field: ${args.field})` : '';
+                const matchInfo = args.match
+                    ? ` (match: ${Array.isArray(args.match) ? args.match.join(', ') : args.match})`
+                    : '';
+                const paramInfo = fieldInfo || matchInfo;
                 const suggestions = [];
                 // Check for common naming patterns
                 if (packageName.includes('_')) {
@@ -114432,12 +114445,22 @@ function registerNpmViewPackageTool(server) {
                 if (packageName.startsWith('@')) {
                     suggestions.push(`• Try without scope: "${packageName.split('/')[1]}"`);
                 }
+                // Add field/match-specific suggestions
+                if (args.field) {
+                    suggestions.push(`• Try without field parameter to get full package info`);
+                    suggestions.push(`• Common fields: version, description, license, dependencies`);
+                }
+                if (args.match) {
+                    suggestions.push(`• Try without match parameter to get full package info`);
+                    suggestions.push(`• Try single field instead of multiple: field: "version"`);
+                    suggestions.push(`• Common fields: version, description, license, dependencies`);
+                }
                 // 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 "${packageName}" not found on NPM registry.
+                    error: `Package "${packageName}"${paramInfo} not found on NPM registry.
 
 Try these alternatives:
 ${suggestions.join('\n')}
@@ -114582,11 +114605,14 @@ function simplifyExports(exports) {
     }
     return { main: 'index.js' };
 }
-async function viewNpmPackage(packageName) {
-    const cacheKey = generateCacheKey('npm-view', { packageName });
+async function viewNpmPackage(packageName, field, match) {
+    const cacheKey = generateCacheKey('npm-view', { packageName, field, match });
     return withCache(cacheKey, async () => {
         try {
-            const result = await executeNpmCommand('view', [packageName, '--json'], {
+            // Build arguments based on parameters
+            // Priority: field > match > full JSON
+            const args = field ? [packageName, field] : [packageName, '--json']; // For match or full info, we need JSON
+            const result = await executeNpmCommand('view', args, {
                 cache: false,
             });
             return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-mcp",
-  "version": "2.3.11",
+  "version": "2.3.13",
   "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://octocode.ai",