octocode-mcp 1.1.0 → 2.0.0

package/build/index.js

@@ -14,7 +14,6 @@ const TOOL_NAMES = {
     GITHUB_SEARCH_COMMITS: 'github_search_commits',
     GITHUB_SEARCH_ISSUES: 'github_search_issues',
     GITHUB_SEARCH_PULL_REQUESTS: 'github_search_pull_requests',
-    GITHUB_SEARCH_DISCUSSIONS: 'github_search_discussions',
     GITHUB_SEARCH_TOPICS: 'github_search_topics',
     GITHUB_SEARCH_USERS: 'github_search_users',
     // GitHub Repository API (/repos/*)
@@ -23,27 +22,75 @@ const TOOL_NAMES = {
     GITHUB_GET_FILE_CONTENT: 'github_get_file_content',
     // GitHub Users API (/user/*)
     GITHUB_GET_USER_ORGS: 'github_get_user_organizations',
-    // npm Registry API
+    // npm Registry API - Comprehensive
     NPM_SEARCH_PACKAGES: 'npm_search_packages',
     NPM_GET_PACKAGE: 'npm_get_package',
-    NPM_GET_PACKAGE_STATS: 'npm_get_package_stats',
-    NPM_ANALYZE_DEPENDENCIES: 'npm_analyze_dependencies'};
+    NPM_ANALYZE_DEPENDENCIES: 'npm_analyze_dependencies',
+    // npm Registry API - Focused (minimal token usage)
+    NPM_GET_REPOSITORY: 'npm_get_repository',
+    NPM_GET_DEPENDENCIES: 'npm_get_dependencies',
+    NPM_GET_BUGS: 'npm_get_bugs',
+    NPM_GET_README: 'npm_get_readme',
+    NPM_GET_VERSIONS: 'npm_get_versions',
+    NPM_GET_AUTHOR: 'npm_get_author',
+    NPM_GET_LICENSE: 'npm_get_license',
+    NPM_GET_HOMEPAGE: 'npm_get_homepage',
+    NPM_GET_ID: 'npm_get_id',
+    NPM_GET_RELEASES: 'npm_get_releases',
+    NPM_GET_ENGINES: 'npm_get_engines',
+    NPM_GET_EXPORTS: 'npm_get_exports'};
 
 const PROMPT_SYSTEM_PROMPT = `**Expert Code Discovery Assistant** - Find production-ready implementations from GitHub/npm repositories.
 
 ## CORE STRATEGY
-1. **NPM Primary** - ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.NPM_GET_PACKAGE} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
-2. **Topics Foundation** - ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} for terminology discovery
-3. **Private Organizations** - Auto-detect (@company/) → ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-4. **Code Extraction** - ${TOOL_NAMES.GITHUB_SEARCH_CODE} + ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
-5. **Repository Search** - ${TOOL_NAMES.GITHUB_SEARCH_REPOS} only when NPM+Topics fail
+1. **NPM Primary** - ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
+2. **NPM Focused** - Use focused tools (${TOOL_NAMES.NPM_GET_REPOSITORY}, ${TOOL_NAMES.NPM_GET_DEPENDENCIES}, etc.) for minimal token usage
+3. **Topics Foundation** - ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} for terminology discovery
+4. **Private Organizations** - Auto-detect (@company/) → ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
+5. **Code Extraction** - ${TOOL_NAMES.GITHUB_SEARCH_CODE} + ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
+6. **Repository Search** - ${TOOL_NAMES.GITHUB_SEARCH_REPOS} only when NPM+Topics fail
+
+## ANTI-HALLUCINATION SAFEGUARDS 🚨
+
+### Generic Hallucination Detection
+- **Overly Specific Functions**: Never search for compound function names like "performSomethingOnSomething" without verification
+- **Long CamelCase**: Function names >20 characters are often hallucinated
+- **Multiple Tech Terms**: Avoid "reactNodeExpressAuthFunction" - these don't exist
+- **Discovery-First**: Use broad terms ("function", "class", "export") then narrow down
+- **Verification Strategy**: Search for patterns like "function.*keyword" to find real implementations
+
+### Rate Limit Protection
+- **Progressive Refinement**: Start with single terms, don't jump to specific function names
+- **Existence Verification**: Use repository exploration before searching for specific files
+- **Pattern Matching**: Use regex-like searches ("export.*Component") vs exact matches
+- **Fallback Strategy**: If specific search fails, broaden immediately rather than retry variations
+
+### Known Pitfalls to Avoid
+- ❌ Searching for framework-specific function names without repo exploration
+- ❌ Complex multi-word queries without boolean operators
+- ❌ Specific file paths without checking repository structure first
+- ❌ Function names that combine multiple technology concepts
+- ✅ Use discovery patterns: "export function", "class extends", "import.*from"
 
 ## TOOL PRIORITY ORDER
 
 ### Primary Discovery
 - ${TOOL_NAMES.NPM_SEARCH_PACKAGES} - Package discovery
-- ${TOOL_NAMES.NPM_GET_PACKAGE} - Repository mapping
-- ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} - Security audit
+- ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} - Security audit and dependency analysis
+
+### Focused NPM (Token Efficient)
+- ${TOOL_NAMES.NPM_GET_REPOSITORY} - Repository URL extraction
+- ${TOOL_NAMES.NPM_GET_DEPENDENCIES} - Dependencies analysis
+- ${TOOL_NAMES.NPM_GET_VERSIONS} - Version tracking
+- ${TOOL_NAMES.NPM_GET_AUTHOR} - Maintainer information
+- ${TOOL_NAMES.NPM_GET_LICENSE} - License compliance
+- ${TOOL_NAMES.NPM_GET_BUGS} - Issue tracking
+- ${TOOL_NAMES.NPM_GET_README} - Documentation access
+- ${TOOL_NAMES.NPM_GET_HOMEPAGE} - Official documentation gateway
+- ${TOOL_NAMES.NPM_GET_ID} - Precise package targeting
+- ${TOOL_NAMES.NPM_GET_RELEASES} - Recent releases tracker
+- ${TOOL_NAMES.NPM_GET_ENGINES} - Environment compatibility
+- ${TOOL_NAMES.NPM_GET_EXPORTS} - Import path intelligence
 
 ### Foundation
 - ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} - Ecosystem terminology
@@ -59,16 +106,45 @@ const PROMPT_SYSTEM_PROMPT = `**Expert Code Discovery Assistant** - Find product
 - ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} - Problem discovery
 - ${TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS} - Implementation patterns
 - ${TOOL_NAMES.GITHUB_SEARCH_COMMITS} - Development history
-- ${TOOL_NAMES.NPM_GET_PACKAGE_STATS} - Package maturity
 
 ### Fallback
 - ${TOOL_NAMES.GITHUB_SEARCH_REPOS} - Enhanced repository search (last resort)
 - ${TOOL_NAMES.GITHUB_SEARCH_USERS} - Expert discovery
 
+## EFFICIENCY STRATEGY
+
+### Token Optimization
+- **Repository Discovery**: ${TOOL_NAMES.NPM_GET_REPOSITORY} → ${TOOL_NAMES.GITHUB_GET_REPOSITORY} workflow
+- **Dependency Analysis**: ${TOOL_NAMES.NPM_GET_DEPENDENCIES} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} for security
+- **Focused Queries**: Use specific NPM tools for targeted information instead of comprehensive searches
+
+### Query Selection Logic
+- **"Find repository"** → ${TOOL_NAMES.NPM_GET_REPOSITORY}
+- **"Check dependencies"** → ${TOOL_NAMES.NPM_GET_DEPENDENCIES}
+- **"What license"** → ${TOOL_NAMES.NPM_GET_LICENSE}
+- **"Package versions"** → ${TOOL_NAMES.NPM_GET_VERSIONS}
+- **"Who maintains"** → ${TOOL_NAMES.NPM_GET_AUTHOR}
+- **"Report bug"** → ${TOOL_NAMES.NPM_GET_BUGS}
+- **"Official docs"** → ${TOOL_NAMES.NPM_GET_HOMEPAGE}
+- **"Exact version"** → ${TOOL_NAMES.NPM_GET_ID}
+- **"Package releases"** → ${TOOL_NAMES.NPM_GET_RELEASES}
+- **"Node.js compatibility"** → ${TOOL_NAMES.NPM_GET_ENGINES}
+- **"Import patterns"** → ${TOOL_NAMES.NPM_GET_EXPORTS}
+- **"Security analysis"** → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
+
 ## QUERY WORKFLOWS
 
 ### Discovery Intent ("find react libraries")
-NPM search → Package analysis → Topics → Code extraction
+NPM search → Repository extraction (focused) → Topics → Code extraction
+
+### Repository Focus ("where is react hosted")
+NPM search → ${TOOL_NAMES.NPM_GET_REPOSITORY} → ${TOOL_NAMES.GITHUB_GET_REPOSITORY}
+
+### Dependency Analysis ("react dependencies")
+NPM search → ${TOOL_NAMES.NPM_GET_DEPENDENCIES} → Security audit
+
+### License Compliance ("react license")
+NPM search → ${TOOL_NAMES.NPM_GET_LICENSE}
 
 ### Private Organization ("@wix/package", "I work at Company")
 Auto-trigger: IMMEDIATE ${TOOL_NAMES.GITHUB_GET_USER_ORGS} → NPM search → Private repo access
@@ -77,7 +153,7 @@ Auto-trigger: IMMEDIATE ${TOOL_NAMES.GITHUB_GET_USER_ORGS} → NPM search → Pr
 NPM packages → Repository analysis → Issues → Code solutions
 
 ### Implementation Intent ("react authentication implementation")
-NPM search → Repository access → Code search → File extraction
+NPM search → Repository extraction → Repository access → Code search → File extraction
 
 ## CRITICAL AUTO-TRIGGERS
 
@@ -88,7 +164,8 @@ NPM search → Repository access → Code search → File extraction
 
 ### Mandatory Workflows  
 - ALWAYS use ${TOOL_NAMES.GITHUB_GET_REPOSITORY} before file operations
-- ALWAYS follow ${TOOL_NAMES.NPM_GET_PACKAGE} with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
+- ALWAYS follow NPM discovery with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} for security
+- PREFER focused tools over comprehensive when specific data needed
 - NEVER retry same terms twice with any tool
 
 ## SUCCESS TARGETS
@@ -141,13 +218,20 @@ NPM search → Repository access → Code search → File extraction
 \`\`\`
 
 **Discovery Path**: Document NPM-first workflow and fallbacks
-**Security Assessment**: Include vulnerability analysis
+**Package Intelligence**: Complete metadata including dependencies, scripts, exports, security attestations
+**Security Assessment**: Include vulnerability analysis from detailed NPM data
 **Repository Status**: Activity level, maintenance quality
 
 ## INTEGRATION EXAMPLES
 
 ### Standard Flow
-npmSearchPackages({query: "react"}) → npmGetPackage({packageName: "react"}) → githubGetRepository({owner: "facebook", repo: "react"}) → githubSearchCode({query: "useState"})
+npmSearchPackages({query: "react"}) → npmGetRepository({packageName: "react"}) → githubGetRepository({owner: "facebook", repo: "react"}) → githubSearchCode({query: "useState"})
+
+### Focused Dependency Analysis
+npmSearchPackages({query: "express"}) → npmGetDependencies({packageName: "express"}) → npmAnalyzeDependencies({packageName: "express"})
+
+### License Compliance Check
+npmSearchPackages({query: "lodash"}) → npmGetLicense({packageName: "lodash"})
 
 ### Private Organization
 Detect @wix/ → githubGetUserOrganizations() → githubSearchRepos({owner: "wix-private"})
@@ -155,7 +239,7 @@ Detect @wix/ → githubGetUserOrganizations() → githubSearchRepos({owner: "wix
 ### Error Recovery  
 npmSearchPackages fails → githubSearchTopics({query: "authentication"}) → githubSearchRepos({query: "auth"})
 
-**OUTPUT GOAL**: Complete, secure, production-ready code with repository citations and security assessment via efficient NPM-first discovery.`;
+**OUTPUT GOAL**: Complete, secure, production-ready code with repository citations and security assessment via efficient NPM-first discovery with minimal token usage.`;
 
 const TOOL_DESCRIPTIONS = {
     [TOOL_NAMES.NPM_SEARCH_PACKAGES]: `**PRIMARY DISCOVERY TOOL** - Main entry point for package and repository discovery.
@@ -171,23 +255,16 @@ const TOOL_DESCRIPTIONS = {
 
 **RESULT OPTIMIZATION:** 0 results → broader terms, 1-20 IDEAL, 100+ → more specific terms
 
-**INTEGRATION:** ALWAYS chain to ${TOOL_NAMES.NPM_GET_PACKAGE} → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}`,
-    [TOOL_NAMES.NPM_GET_PACKAGE]: `**Repository mapping** - Transform npm packages into GitHub repositories for code analysis.
-
-**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_SEARCH_PACKAGES}, user mentions package names, private package detection (@company/).
-
-**WORKFLOW:** Extract repository URL → Parse owner/repo → Detect organizational context → Chain to ${TOOL_NAMES.GITHUB_GET_REPOSITORY} → MANDATORY ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}
-
-**ORGANIZATIONAL DETECTION:** @company/ scoped packages → Trigger ${TOOL_NAMES.GITHUB_GET_USER_ORGS}
-
-**EXAMPLES:** "react" → github.com/facebook/react, "@wix/package" → Private org detection`,
+**INTEGRATION:** ALWAYS chain to focused NPM tools → ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}`,
     [TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES]: `**CRITICAL: Package security analysis** - Essential for package evaluation and organizational detection.
 
-**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_GET_PACKAGE} for complete assessment.
+**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_SEARCH_PACKAGES} for complete assessment.
 
 **ANALYSIS:** Security vulnerabilities, dependency tree, license compatibility, bundle impact, organization detection (@company/).
 
-**ORGANIZATIONAL CONTEXT:** Private packages → Check ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access`,
+**ORGANIZATIONAL CONTEXT:** Private packages → Check ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access
+
+**KNOWN LIMITATION:** Some NPM audit failures may occur (package-specific). Bundle analysis and dependency tree remain reliable.`,
     [TOOL_NAMES.GITHUB_SEARCH_TOPICS]: `**FOUNDATION TOOL** - Essential for ecosystem discovery and terminology mapping.
 
 **SEARCH STRATEGY:** Start global, single terms ("react", "typescript"), multi-term sparingly ("react+typescript"), add owner only when needed.
@@ -204,31 +281,49 @@ const TOOL_DESCRIPTIONS = {
 **WORKFLOW:** IMMEDIATE call when organizational context detected → Match company to organizations → Use as 'owner' parameter → Enable private repository access
 
 **INTEGRATION:** MANDATORY first step when private access likely needed`,
-    [TOOL_NAMES.GITHUB_GET_REPOSITORY]: `**CRITICAL FIRST STEP** - Required before all GitHub file operations.
+    [TOOL_NAMES.GITHUB_GET_REPOSITORY]: `**CRITICAL FIRST STEP** - Required before all GitHub file operations, but ONLY after discovery.
 
 **PURPOSE:** Discover default branch and repository metadata to prevent tool failures.
 
+**MANDATORY PREREQUISITES:** Repository owner/name MUST be discovered first through:
+1. ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.NPM_GET_PACKAGE} (for packages)
+2. ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} (for ecosystem discovery)  
+3. ${TOOL_NAMES.GITHUB_SEARCH_REPOS} (last resort)
+
 **REQUIRED BEFORE:** ${TOOL_NAMES.GITHUB_SEARCH_CODE}, ${TOOL_NAMES.GITHUB_GET_CONTENTS}, ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT}
 
-**CRITICAL:** NEVER skip before file operations, NEVER assume branch names, NEVER proceed if branch discovery fails`,
+**CRITICAL:** NEVER call with guessed repository names. ALWAYS use discovery workflow first.`,
     [TOOL_NAMES.GITHUB_SEARCH_CODE]: `**Precision code search** - Advanced search with automatic repository scoping.
 
 **KEY FEATURES:** Every search includes "repo:owner/repository", smart boolean logic, organizational context.
 
+**ANTI-HALLUCINATION SAFEGUARDS:**
+- 🚨 NEVER search for overly specific function names without verification
+- 🔍 DISCOVERY FIRST: Use broad terms ("function", "class", "export") then narrow down
+- 📝 PATTERN DETECTION: Long camelCase names (>20 chars) may not exist
+- ⚠️ COMPOUND PATTERNS: "performSomethingOnSomething" patterns often hallucinated
+- 💡 SAFER APPROACH: "function.*keyword" finds real implementations
+
 **BOOLEAN OPERATIONS:** Default AND ("sparse index" = "sparse AND index"), OR ("useState OR useEffect"), NOT ("error NOT test")
 
 **PATH WARNING:** React uses path:packages (NOT path:src). Using path:src on repositories without top-level src returns zero results.
 
 **RESULT OPTIMIZATION:** 1-10 IDEAL, 100+ TOO BROAD
 
+**PAGINATION LIMITATION:** GitHub CLI limited to --limit parameter only (no page navigation).
+
 **INTEGRATION:** Use after ${TOOL_NAMES.GITHUB_GET_REPOSITORY} for branch discovery`,
     [TOOL_NAMES.GITHUB_GET_FILE_CONTENT]: `**Complete code extraction** - Fetch full working implementations.
 
-**CRITICAL WORKFLOW:** MANDATORY ${TOOL_NAMES.GITHUB_GET_REPOSITORY} first → Find files with ${TOOL_NAMES.GITHUB_SEARCH_CODE} → Extract with this tool
+**CRITICAL WORKFLOW:** MANDATORY discovery → ${TOOL_NAMES.GITHUB_GET_REPOSITORY} → Find files with ${TOOL_NAMES.GITHUB_SEARCH_CODE} or ${TOOL_NAMES.GITHUB_GET_CONTENTS} → Extract with this tool
 
 **AUTO-RECOVERY:** Specified branch → main → master → develop → trunk → try without ref
 
-**ORGANIZATIONAL CONTEXT:** Private repositories → Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access`,
+**ENHANCED ERROR HANDLING:** Provides detailed guidance when files don't exist, with alternative discovery methods
+
+**ORGANIZATIONAL CONTEXT:** Private repositories → Use ${TOOL_NAMES.GITHUB_GET_USER_ORGS} for access
+
+**CRITICAL:** NEVER guess file paths. Use structure exploration or code search first.`,
     [TOOL_NAMES.GITHUB_GET_CONTENTS]: `**Repository structure exploration** - Strategic directory navigation.
 
 **CRITICAL:** MANDATORY ${TOOL_NAMES.GITHUB_GET_REPOSITORY} FIRST for branch discovery.
@@ -240,8 +335,14 @@ const TOOL_DESCRIPTIONS = {
 
 **SEARCH STRATEGY:** Single keywords ("bug", "feature"), then combine ("bug fix"), never complex.
 
+**SEARCH MODES:** 
+- Global search (no owner): Searches issues across all GitHub repositories
+- Scoped search (with owner): Targeted search within specific organization/user
+
 **PROBLEM HIERARCHY:** "React auth JWT error" → "authentication" → "React" → "token expired" → "JWT"
 
+**PAGINATION LIMITATION:** GitHub CLI limited to --limit parameter only (no page navigation).
+
 **RESULT TARGETS:** 0 → broader terms, 1-20 IDEAL, 100+ → add specific terms/filters`,
     [TOOL_NAMES.GITHUB_SEARCH_PULL_REQUESTS]: `**Implementation analysis** - PR search for patterns and repository status.
 
@@ -249,25 +350,24 @@ const TOOL_DESCRIPTIONS = {
 
 **KEY FILTERS:** State (open/closed), draft (false for completed), author/reviewer, language
 
+**PAGINATION LIMITATION:** GitHub CLI limited to --limit parameter only (no page navigation).
+
 **QUALITY FOCUS:** Use review-related filters for thoroughly vetted code examples`,
     [TOOL_NAMES.GITHUB_SEARCH_COMMITS]: `**Development history** - Track code evolution and repository status.
 
 **SEARCH STRATEGY:** Start minimal ("fix", "feature", "update") with owner/repo, progressive expansion.
 
-**LIMITATIONS:** Large organizations may return org-wide results, requires text terms.
+**LIMITATIONS:** Large organizations may return org-wide results, requires text terms. GitHub CLI limited to --limit parameter only (no page navigation).
 
 **ERROR HANDLING:** "Search text required" → Use minimal keywords ("fix", "update")`,
-    [TOOL_NAMES.GITHUB_SEARCH_DISCUSSIONS]: `**Community knowledge** - Access discussions for tutorials and solutions.
-
-**DISCOVERY WORKFLOW:** ${TOOL_NAMES.NPM_GET_PACKAGE} → get repo URL → Search discussions
-
-**SEARCH STRATEGY:** Start simple ("help", "tutorial"), build complexity ("help deployment"), avoid full phrases.
-
-**KEY FILTERS:** Answered: true for validated solutions, category filters, maintainer participation`,
     [TOOL_NAMES.GITHUB_SEARCH_USERS]: `**Developer discovery** - Find experts and community leaders.
 
 **SEARCH METHODOLOGY:** Technology terms ("react", "python") → add context (location, experience) → specialized search.
 
+**SEARCH MODES:** 
+- Global search (no owner): Searches users/orgs across all GitHub
+- Scoped search (with owner): Targeted search within specific organization context
+
 **KEY FILTERS:** Type (user/org), location, language, followers (">100" influential), repos (">10" active)
 
 **DISCOVERY PATTERNS:** Technology experts, local developers, open source contributors, industry leaders`,
@@ -275,22 +375,104 @@ const TOOL_DESCRIPTIONS = {
 
 **MANDATORY PREREQUISITES:** ${TOOL_NAMES.NPM_SEARCH_PACKAGES} and ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} must fail first.
 
-**KEY FEATURES:** Smart multi-term handling, filter validation, fallback strategies.
+**KEY FEATURES:** Smart multi-term handling, filter validation, fallback strategies, global & scoped searches.
+
+**BEST PRACTICES:** Single terms work best ("react", "typescript"), owner is OPTIONAL (leave empty for global searches), validated combinations (microsoft + typescript ✅), progressive refinement.
 
-**BEST PRACTICES:** Single terms work best ("react", "typescript"), validated combinations (microsoft + typescript ✅), progressive refinement.
+**SEARCH MODES:** 
+- Global search (no owner): Searches across all GitHub repositories
+- Scoped search (with owner): Targeted search within specific organization/user
 
 **MULTI-TERM HANDLING:** "react hooks auth" → structured workflow, primary term extraction, workflow guidance.
 
-**CRITICAL:** npm_search_packages → topics workflow provides superior results for 95% of use cases`,
-    [TOOL_NAMES.NPM_GET_PACKAGE_STATS]: `**Package maturity analysis** - Lifecycle assessment for package evaluation.
+**KNOWN LIMITATIONS:** Multi-term repository search breaks down (use NPM→Topics workflow instead). GitHub CLI limited to --limit parameter only (no page navigation).
+
+**CRITICAL:** ${TOOL_NAMES.NPM_SEARCH_PACKAGES} → ${TOOL_NAMES.GITHUB_SEARCH_TOPICS} workflow provides superior results for 95% of use cases`,
+    // Focused NPM tools for minimal token usage
+    [TOOL_NAMES.NPM_GET_REPOSITORY]: `**Repository discovery** - Extract GitHub repository URL and project description.
+
+**MINIMAL OUTPUT:** Package name, description, repository URL, homepage - optimized for token efficiency.
+
+**WHEN TO USE:** When you only need repository location for GitHub operations.
+
+**INTEGRATION:** Perfect first step → ${TOOL_NAMES.GITHUB_GET_REPOSITORY} → Code exploration`,
+    [TOOL_NAMES.NPM_GET_DEPENDENCIES]: `**Dependency analysis** - Extract package dependencies tree.
+
+**MINIMAL OUTPUT:** Dependencies, devDependencies, resolutions - focused dependency data only.
+
+**WHEN TO USE:** When analyzing package ecosystem and compatibility.
+
+**INTEGRATION:** Combine with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES} for security audit`,
+    [TOOL_NAMES.NPM_GET_BUGS]: `**Issue tracking** - Extract bug reporting information.
+
+**MINIMAL OUTPUT:** Package name and bugs URL - direct access to issue tracker.
 
-**WHEN TO USE:** ALWAYS after ${TOOL_NAMES.NPM_GET_PACKAGE} for complete assessment.
+**WHEN TO USE:** When users need to report issues or check known problems.
 
-**ANALYSIS:** Release timeline, version history, distribution tags, maintenance indicators, organizational context.
+**INTEGRATION:** Links to ${TOOL_NAMES.GITHUB_SEARCH_ISSUES} for problem discovery`,
+    [TOOL_NAMES.NPM_GET_README]: `**Documentation access** - Extract README filename information.
 
-**MATURITY INDICATORS:** Stable (regular releases, clear versioning), active development (frequent releases, beta/alpha), abandoned (long gaps, no activity).
+**MINIMAL OUTPUT:** Package name and readme filename - efficient documentation lookup.
 
-**INTEGRATION:** MANDATORY with ${TOOL_NAMES.NPM_GET_PACKAGE}, combine with ${TOOL_NAMES.NPM_ANALYZE_DEPENDENCIES}`,
+**WHEN TO USE:** When users need documentation without full package metadata.
+
+**INTEGRATION:** Combine with ${TOOL_NAMES.GITHUB_GET_FILE_CONTENT} for full README content`,
+    [TOOL_NAMES.NPM_GET_VERSIONS]: `**Official version tracking** - Extract production-ready semantic versions only.
+
+**MINIMAL OUTPUT:** Official versions (major.minor.patch format), latest version, count - excludes alpha/beta/rc versions.
+
+**WHEN TO USE:** Find stable versions for production deployment, analyze release cadence of stable releases.
+
+**INTEGRATION:** Perfect for production planning - filters out experimental versions for reliable deployment decisions`,
+    [TOOL_NAMES.NPM_GET_AUTHOR]: `**Maintainer information** - Extract author and maintainer details.
+
+**MINIMAL OUTPUT:** Author and maintainers list - focused ownership data.
+
+**WHEN TO USE:** When users need to contact maintainers or assess project ownership.
+
+**INTEGRATION:** Links to ${TOOL_NAMES.GITHUB_SEARCH_USERS} for developer discovery`,
+    [TOOL_NAMES.NPM_GET_LICENSE]: `**License compliance** - Extract package license information.
+
+**MINIMAL OUTPUT:** Package name and license - essential legal compliance data.
+
+**WHEN TO USE:** When users need quick license verification for legal compliance.
+
+**INTEGRATION:** Essential for enterprise package evaluation workflows`,
+    [TOOL_NAMES.NPM_GET_HOMEPAGE]: `**Official documentation gateway** - Extract package homepage for comprehensive project resources.
+
+**MINIMAL OUTPUT:** Package name and homepage URL - direct access to live documentation, tutorials, and demos.
+
+**WHEN TO USE:** Access official docs, interactive examples, getting started guides, and project showcases.
+
+**INTEGRATION:** Complements ${TOOL_NAMES.NPM_GET_REPOSITORY} - homepage often contains better docs than README`,
+    [TOOL_NAMES.NPM_GET_ID]: `**Precise package targeting** - Extract exact name@version for dependency management.
+
+**MINIMAL OUTPUT:** Package name and _id (name@latestVersion format) - canonical package identifier for lockfiles.
+
+**WHEN TO USE:** Pin exact versions, resolve dependency conflicts, generate package-lock entries, version compatibility checks.
+
+**INTEGRATION:** Critical for CI/CD pipelines, dependency auditing, and reproducible builds`,
+    [TOOL_NAMES.NPM_GET_RELEASES]: `**Recent releases tracker** - Get latest release activity and timeline data.
+
+**MINIMAL OUTPUT:** Last modified, created date, version count, and last 10 releases - focused release intelligence.
+
+**WHEN TO USE:** Track recent package activity, analyze release frequency, check latest versions and release dates.
+
+**INTEGRATION:** Essential for monitoring package updates - combine with ${TOOL_NAMES.NPM_GET_VERSIONS} for comprehensive version analysis`,
+    [TOOL_NAMES.NPM_GET_ENGINES]: `**Environment compatibility validator** - Prevent runtime conflicts before installation.
+
+**MINIMAL OUTPUT:** Node.js version requirements, npm constraints - environment compatibility matrix.
+
+**WHEN TO USE:** Pre-deployment validation, Docker image planning, Node.js upgrade decisions, CI/CD environment setup.
+
+**INTEGRATION:** Prevents deployment failures - use before installation in production environments`,
+    [TOOL_NAMES.NPM_GET_EXPORTS]: `**Import path intelligence** - Discover available modules and import strategies.
+
+**MINIMAL OUTPUT:** Export mappings, entry points, submodule paths - complete import guide for developers.
+
+**WHEN TO USE:** Learn correct import syntax, discover tree-shakable exports, find submodules, optimize bundle size.
+
+**INTEGRATION:** CRITICAL for ${TOOL_NAMES.GITHUB_SEARCH_CODE} - enables precise code search with accurate import paths`,
 };
 
 const cache = new NodeCache({
@@ -718,52 +900,54 @@ function analyzeSearchPattern(args) {
     }
     return { patternType, suggestions, warnings };
 }
-// Simplified schema matching official GitHub CLI approach
-const searchGitHubCodeSchema = z.object({
-    query: z
-        .string()
-        .min(1, 'Query cannot be empty')
-        .describe('Search query for code. Use GitHub search syntax like repo:owner/name, language:javascript, path:*.js, or simple keywords.'),
-    owner: z
-        .string()
-        .optional()
-        .describe('Repository owner/organization (e.g., "facebook", "microsoft"). Leave empty for global searches.'),
-    repo: z
-        .string()
-        .optional()
-        .describe('Repository name (e.g., "react", "vscode"). Requires owner parameter.'),
-    extension: z
-        .string()
-        .optional()
-        .describe('File extension to filter by (e.g., "js", "ts", "py").'),
-    filename: z
-        .string()
-        .optional()
-        .describe('Exact filename to search for (e.g., "package.json", "README.md").'),
-    language: z
-        .string()
-        .optional()
-        .describe('Programming language to filter by (e.g., "javascript", "typescript", "python").'),
-    path: z
-        .string()
-        .optional()
-        .describe('Path pattern to filter by (e.g., "src", "lib", "*.js", "/src/**/*.ts").'),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .optional()
-        .default(30)
-        .describe('Maximum number of results to return (default: 30, max: 100).'),
-    match: z.enum(['file', 'path']).optional().describe('Search scope'),
-    branch: z
-        .string()
-        .optional()
-        .describe('Branch for workflow documentation (required but not used by CLI)'),
-});
 function registerGitHubSearchCodeTool(server) {
-    server.tool(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE], searchGitHubCodeSchema.shape, {
+    server.tool(TOOL_NAMES.GITHUB_SEARCH_CODE, TOOL_DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_CODE], {
+        query: z
+            .string()
+            .min(1, 'Query cannot be empty')
+            .describe('Search query for code. Use GitHub search syntax like repo:owner/name, language:javascript, path:*.js, or simple keywords.'),
+        owner: z
+            .string()
+            .optional()
+            .describe('Repository owner/organization (e.g., "facebook", "microsoft"). Leave empty for global searches.'),
+        repo: z
+            .array(z.string())
+            .optional()
+            .describe('Repository names (e.g., ["react", "vscode"]). Requires owner parameter.'),
+        extension: z
+            .string()
+            .optional()
+            .describe('File extension to filter by (e.g., "js", "ts", "py").'),
+        filename: z
+            .string()
+            .optional()
+            .describe('Exact filename to search for (e.g., "package.json", "README.md").'),
+        language: z
+            .string()
+            .optional()
+            .describe('Programming language to filter by (e.g., "javascript", "typescript", "python").'),
+        path: z
+            .string()
+            .optional()
+            .describe('Path pattern to filter by (e.g., "src", "lib", "*.js", "/src/**/*.ts").'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(30)
+            .describe('Maximum number of results to return (default: 30, max: 100).'),
+        match: z.enum(['file', 'path']).optional().describe('Search scope'),
+        branch: z
+            .string()
+            .optional()
+            .describe('Branch for workflow documentation (required but not used by CLI)'),
+        size: z
+            .string()
+            .optional()
+            .describe('Filter on file size range, in kilobytes (e.g., ">1", "<50")'),
+    }, {
         title: 'GitHub Code Search',
         readOnlyHint: true,
         destructiveHint: false,
@@ -859,31 +1043,127 @@ async function fetchGitHubFileContent(params) {
             const args = [apiPath, '--jq', '.content'];
             const result = await executeGitHubCommand('api', args, { cache: false });
             if (result.isError) {
-                return result;
+                // Parse the error message to provide better context
+                const errorMsg = result.content[0].text;
+                // Handle common GitHub API errors
+                if (errorMsg.includes('404') || errorMsg.includes('Not Found')) {
+                    return createErrorResult$1(`File not found: ${params.filePath}`, new Error(`
+❌ FILE NOT FOUND: The file '${params.filePath}' does not exist in ${params.owner}/${params.repo}${params.branch ? ` on branch '${params.branch}'` : ''}.
+
+🔍 COMMON CAUSES:
+• File path is incorrect or has changed
+• Branch '${params.branch || 'default'}' doesn't contain this file
+• File may exist in a different directory
+
+💡 RECOMMENDED ACTIONS:
+1. Use 'github_get_contents' to explore repository structure first
+2. Use 'github_search_code' to find files by name or pattern
+3. Verify the branch contains the expected files
+
+📍 SEARCH ALTERNATIVES:
+• Search for filename: query="${params.filePath.split('/').pop()}"
+• Search in repository: repo:${params.owner}/${params.repo}
+• Explore repository structure starting from root`));
+                }
+                if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                    return createErrorResult$1(`Access denied to file: ${params.filePath}`, new Error(`
+🔒 ACCESS DENIED: You don't have permission to access '${params.filePath}' in ${params.owner}/${params.repo}.
+
+🔍 POSSIBLE CAUSES:
+• Repository is private and you lack access
+• File is in a protected branch
+• Organization restrictions apply
+
+💡 RECOMMENDED ACTIONS:
+1. Check if you're authenticated: gh auth status
+2. Request repository access from owner
+3. Use 'github_get_user_organizations' if this is your organization`));
+                }
+                // Handle rate limiting
+                if (errorMsg.includes('rate limit') || errorMsg.includes('429')) {
+                    return createErrorResult$1('GitHub API rate limit exceeded', new Error(`
+⏱️ RATE LIMIT: GitHub API rate limit has been exceeded.
+
+💡 RECOMMENDED ACTIONS:
+1. Wait a few minutes before trying again
+2. Use authentication to increase rate limits: gh auth login
+3. Try searching for content instead of direct file access`));
+                }
+                // Generic error fallback
+                return createErrorResult$1(`Failed to fetch file content: ${params.filePath}`, new Error(`GitHub API Error: ${errorMsg}
+
+🔧 TROUBLESHOOTING:
+• Verify repository exists: ${params.owner}/${params.repo}
+• Check file path: ${params.filePath}
+• Confirm branch: ${params.branch || 'default'}
+• Use repository exploration tools first`));
             }
             // Extract the actual content from the exec result
             const execResult = JSON.parse(result.content[0].text);
             const base64Content = execResult.result.trim().replace(/\n/g, '');
+            // Validate base64 content
+            if (!base64Content || base64Content === 'null') {
+                return createErrorResult$1(`Empty or invalid file content: ${params.filePath}`, new Error(`
+📄 EMPTY FILE: The file '${params.filePath}' exists but contains no content or returned invalid data.
+
+🔍 POSSIBLE CAUSES:
+• File is empty or binary
+• API returned null content
+• File is too large for API response
+
+💡 ALTERNATIVES:
+• Use 'github_search_code' to find content by pattern
+• Check file in GitHub web interface
+• Try accessing a different file in the same directory`));
+            }
             // Decode base64 content using Node.js Buffer
             let decodedContent;
             try {
                 decodedContent = Buffer.from(base64Content, 'base64').toString('utf-8');
             }
             catch (decodeError) {
-                throw new Error(`Failed to decode base64 content: ${decodeError.message}`);
+                return createErrorResult$1(`Failed to decode file content: ${params.filePath}`, new Error(`
+🔧 DECODE ERROR: Unable to decode base64 content from GitHub API.
+
+📋 DETAILS: ${decodeError.message}
+
+💡 POSSIBLE CAUSES:
+• File contains binary data
+• Corrupted response from API
+• Encoding mismatch
+
+🔍 ALTERNATIVES:
+• Use 'github_search_code' to find text-based content
+• Check if file is binary (images, executables, etc.)
+• Try accessing a different version of the file`));
             }
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: decodedContent,
-                    },
-                ],
-                isError: false,
-            };
+            return createSuccessResult$1({
+                filePath: params.filePath,
+                owner: params.owner,
+                repo: params.repo,
+                branch: params.branch,
+                content: decodedContent,
+                size: decodedContent.length,
+                encoding: 'utf-8',
+            });
         }
         catch (error) {
-            return createErrorResult$1('Failed to retrieve file content', error);
+            return createErrorResult$1(`Unexpected error fetching file content: ${params.filePath}`, new Error(`
+❌ UNEXPECTED ERROR: ${error.message}
+
+📍 FILE DETAILS:
+• Repository: ${params.owner}/${params.repo}
+• File: ${params.filePath}
+• Branch: ${params.branch || 'default'}
+
+🔧 TROUBLESHOOTING STEPS:
+1. Verify repository exists with 'github_get_repository'
+2. Explore structure with 'github_get_contents'
+3. Search for file with 'github_search_code'
+4. Check GitHub authentication: gh auth status
+
+💡 WORKFLOW RECOMMENDATION:
+github_get_repository → github_get_contents → github_search_code → github_get_file_content`));
         }
     });
 }
@@ -932,21 +1212,160 @@ async function viewGitHubRepositoryInfo(params) {
             const args = ['view', `${owner}/${params.repo}`];
             const result = await executeGitHubCommand('repo', args, { cache: false });
             if (result.isError) {
-                return result;
+                // Parse the error message to provide better context
+                const errorMsg = result.content[0].text;
+                // Handle repository not found
+                if (errorMsg.includes('404') ||
+                    errorMsg.includes('Not Found') ||
+                    errorMsg.includes('could not resolve to a Repository')) {
+                    return createErrorResult$1(`Repository not found: ${owner}/${params.repo}`, new Error(`
+❌ REPOSITORY NOT FOUND: The repository '${owner}/${params.repo}' does not exist or is not accessible.
+
+🔍 COMMON CAUSES:
+• Repository name is incorrect
+• Repository is private and you lack access
+• Owner/organization name is wrong
+• Repository has been deleted or moved
+
+🎯 RECOMMENDED DISCOVERY WORKFLOW (in this order):
+
+1️⃣ **NPM PACKAGE DISCOVERY** (if this is a package):
+   • Use 'npm_search_packages' with keywords: "${params.repo}"
+   • Then 'npm_get_package' to find the GitHub repository URL
+   • This automatically discovers the correct owner/repo
+
+2️⃣ **GITHUB TOPICS SEARCH** (for broader discovery):
+   • Use 'github_search_topics' with terms: "${params.repo}"
+   • Discover related repositories and ecosystems
+   • Find the correct repository among similar projects
+
+3️⃣ **REPOSITORY SEARCH** (last resort):
+   • Use 'github_search_repositories' with query: "${params.repo}"
+   • Add filters like language, stars, etc.
+   • Manual selection from search results
+
+💡 ORGANIZATION ACCESS:
+If this should be a private repository, try:
+• 'github_get_user_organizations' to see your available orgs
+• Use the correct organization name as owner
+
+🔧 VERIFICATION:
+• Check repository exists at: https://github.com/${owner}/${params.repo}
+• Verify spelling and case sensitivity`));
+                }
+                // Handle access denied
+                if (errorMsg.includes('403') || errorMsg.includes('Forbidden')) {
+                    return createErrorResult$1(`Access denied to repository: ${owner}/${params.repo}`, new Error(`
+🔒 ACCESS DENIED: You don't have permission to access '${owner}/${params.repo}'.
+
+🔍 POSSIBLE CAUSES:
+• Repository is private
+• Organization restrictions
+• Invalid authentication
+
+💡 RECOMMENDED ACTIONS:
+1. Check authentication: gh auth status
+2. Request repository access from owner: ${owner}
+3. Use 'github_get_user_organizations' if this is your org
+4. Verify you're logged into the correct GitHub account
+
+🎯 ALTERNATIVE DISCOVERY:
+If you're looking for similar repositories, try:
+• 'npm_search_packages' for packages
+• 'github_search_topics' for general discovery
+• 'github_search_repositories' with broader terms`));
+                }
+                // Handle rate limiting
+                if (errorMsg.includes('rate limit') || errorMsg.includes('429')) {
+                    return createErrorResult$1('GitHub API rate limit exceeded', new Error(`
+⏱️ RATE LIMIT: GitHub API rate limit has been exceeded.
+
+💡 RECOMMENDED ACTIONS:
+1. Wait a few minutes before trying again
+2. Use authentication to increase rate limits: gh auth login
+3. Try discovery tools instead: npm_search_packages or github_search_topics`));
+                }
+                // Generic error fallback
+                return createErrorResult$1(`Failed to access repository: ${owner}/${params.repo}`, new Error(`GitHub CLI Error: ${errorMsg}
+
+🔧 TROUBLESHOOTING:
+• Verify repository exists: https://github.com/${owner}/${params.repo}
+• Check spelling and case sensitivity
+• Confirm authentication: gh auth status
+
+🎯 DISCOVERY WORKFLOW:
+1. npm_search_packages → npm_get_package
+2. github_search_topics  
+3. github_search_repositories
+4. github_get_repository (current step)`));
             }
             // Extract the actual content from the exec result
             const execResult = JSON.parse(result.content[0].text);
             const content = execResult.result;
+            // Parse repository info to extract key details
             const viewResult = {
                 owner,
                 repo: params.repo,
                 repositoryInfo: content,
                 rawOutput: content,
             };
-            return createSuccessResult$1(viewResult);
+            // Try to extract branch information from the output
+            let defaultBranch = 'main'; // fallback
+            try {
+                // The content is usually YAML-like output from gh repo view
+                const lines = content.split('\n');
+                for (const line of lines) {
+                    if (line.includes('default branch:') ||
+                        line.includes('Default branch:')) {
+                        const branchMatch = line.split(':')[1]?.trim();
+                        if (branchMatch) {
+                            defaultBranch = branchMatch;
+                            break;
+                        }
+                    }
+                }
+            }
+            catch (parseError) {
+                // If we can't parse the branch, keep the fallback
+            }
+            return createSuccessResult$1({
+                ...viewResult,
+                defaultBranch,
+                success: true,
+                message: `✅ Repository found: ${owner}/${params.repo}
+        
+📋 REPOSITORY DETAILS:
+• Default branch: ${defaultBranch}
+• Ready for file operations
+
+🔄 NEXT RECOMMENDED STEPS:
+1. Explore structure: github_get_contents
+2. Search for code: github_search_code  
+3. Fetch specific files: github_get_file_content
+
+⚠️ IMPORTANT: Use branch '${defaultBranch}' in subsequent file operations.`,
+            });
         }
         catch (error) {
-            return createErrorResult$1('Failed to view GitHub repository', error);
+            return createErrorResult$1(`Unexpected error accessing repository: ${params.owner}/${params.repo}`, new Error(`
+❌ UNEXPECTED ERROR: ${error.message}
+
+📍 REPOSITORY DETAILS:
+• Owner: ${params.owner}
+• Repository: ${params.repo}
+
+🔧 TROUBLESHOOTING STEPS:
+1. Verify GitHub CLI is installed and authenticated
+2. Check network connectivity
+3. Try discovery workflow instead:
+
+🎯 DISCOVERY WORKFLOW:
+1. npm_search_packages "${params.repo}"
+2. github_search_topics "${params.repo}"  
+3. github_search_repositories query="${params.repo}" owner="${params.owner}"
+4. github_get_repository (retry after discovery)
+
+💡 This ensures you have the correct owner/repo before attempting direct access.`));
         }
     });
 }
@@ -983,79 +1402,6 @@ function registerViewRepositoryTool(server) {
     });
 }
 
-async function npmView(packageName) {
-    const cacheKey = generateCacheKey('npm-view', { packageName });
-    return withCache(cacheKey, async () => {
-        try {
-            const result = await executeNpmCommand('view', [packageName, '--json'], {
-                cache: true,
-            });
-            if (result.isError) {
-                return result;
-            }
-            // Parse the result from the executed command
-            const commandOutput = JSON.parse(result.content[0].text);
-            const npmData = commandOutput.result;
-            let popularityData = '';
-            try {
-                // Get version count as popularity indicator
-                const versionsResult = await executeNpmCommand('view', [
-                    packageName,
-                    'time',
-                    '--json',
-                ]);
-                if (!versionsResult.isError) {
-                    const versionsOutput = JSON.parse(versionsResult.content[0].text);
-                    const timeData = versionsOutput.result;
-                    const versionCount = Object.keys(timeData).length - 2; // Subtract 'created' and 'modified'
-                    popularityData = `Package versions released: ${versionCount}`;
-                }
-            }
-            catch {
-                // Popularity data is optional
-            }
-            const enhancedResult = {
-                npmData: JSON.parse(JSON.stringify(npmData)),
-                popularityInfo: popularityData,
-                lastAnalyzed: new Date().toISOString(),
-            };
-            return createSuccessResult$1(enhancedResult);
-        }
-        catch (error) {
-            return createErrorResult$1('Failed to get npm repository information', error);
-        }
-    });
-}
-
-function registerNpmViewTool(server) {
-    server.tool(TOOL_NAMES.NPM_GET_PACKAGE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_PACKAGE], {
-        packageName: z
-            .string()
-            .describe("The name of the npm package to analyze (e.g., 'react', '@types/node', 'lodash')"),
-    }, {
-        title: 'View NPM Package',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    }, async (args) => {
-        try {
-            return await npmView(args.packageName);
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to get npm package info: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-}
-
 async function searchGitHubRepos(params) {
     const cacheKey = generateCacheKey('gh-repos', params);
     return withCache(cacheKey, async () => {
@@ -1184,8 +1530,8 @@ function buildGitHubReposSearchCommand(params) {
         args.push(`--include-forks=${params.includeForks}`);
     if (params.language)
         args.push(`--language=${params.language}`);
-    if (params.license)
-        args.push(`--license=${params.license}`);
+    if (params.license && params.license.length > 0)
+        args.push(`--license=${params.license.join(',')}`);
     if (params.limit)
         args.push(`--limit=${params.limit}`);
     if (params.match)
@@ -1196,15 +1542,15 @@ function buildGitHubReposSearchCommand(params) {
         args.push(`--order=${params.order}`);
     if (params.size)
         args.push(`--size="${params.size}"`);
-    // DEFAULT TO UPDATED SORTING for recency prioritization
-    const sortBy = params.sort || 'updated';
+    // Use best-match as default, only specify sort if different from default
+    const sortBy = params.sort || 'best-match';
     if (sortBy !== 'best-match') {
         args.push(`--sort=${sortBy}`);
     }
     if (params.stars !== undefined)
-        args.push(`--stars=${params.stars}`);
-    if (params.topic)
-        args.push(`--topic=${params.topic}`);
+        args.push(`--stars="${params.stars}"`);
+    if (params.topic && params.topic.length > 0)
+        args.push(`--topic=${params.topic.join(',')}`);
     if (params.updated)
         args.push(`--updated="${params.updated}"`);
     if (params.visibility)
@@ -1264,7 +1610,13 @@ function validateFilterCombinations(args) {
             suggestion: 'PROVEN: owner=facebook + query=react without language filter → React (236K⭐), React Native (119K⭐), Create React App',
         },
         {
-            condition: args.language && args.stars !== undefined && args.stars > 10000,
+            condition: args.language &&
+                args.stars &&
+                ((args.stars.includes('>') &&
+                    parseInt(args.stars.replace(/[><]/g, '')) > 10000) ||
+                    (!args.stars.includes('>') &&
+                        !args.stars.includes('<') &&
+                        parseInt(args.stars) > 10000)),
             warning: 'High star threshold with specific language may be too restrictive (TESTING-VALIDATED)',
             suggestion: 'PROVEN: Use >1000 stars for established projects, >100 for active ones. Language filters often miss major projects.',
         },
@@ -1298,8 +1650,8 @@ function validateFilterCombinations(args) {
     if (args.limit && (args.limit < 1 || args.limit > 100)) {
         warnings.push('Limit must be between 1 and 100');
     }
-    if (args.stars !== undefined && args.stars < 0) {
-        warnings.push('Stars filter must be non-negative');
+    if (args.stars && !/^[><]=?\d+$|^\d+$|^\d+\.\.\d+$/.test(args.stars)) {
+        warnings.push('Stars filter must be in format ">100", ">=500", "<1000", "<=200", "50..200" or a simple number');
     }
     if (args.forks !== undefined && args.forks < 0) {
         warnings.push('Forks filter must be non-negative');
@@ -1338,8 +1690,9 @@ function registerSearchGitHubReposTool(server) {
             .describe('Search query for repositories. PRODUCTION TIP: Single terms work best (e.g., "react", "typescript"). Multi-term queries will be auto-decomposed with suggestions.'),
         owner: z
             .string()
-            .min(1, 'Owner is required and cannot be empty')
-            .describe('Repository owner/organization - REQUIRED for scoped, reliable results'),
+            .min(1)
+            .optional()
+            .describe('Repository owner/organization (e.g., "facebook", "microsoft"). OPTIONAL: Leave empty for global searches across all of GitHub. Recommended for scoped, reliable results.'),
         archived: z.boolean().optional().describe('Filter archived state'),
         created: z
             .string()
@@ -1363,7 +1716,10 @@ function registerSearchGitHubReposTool(server) {
             .string()
             .optional()
             .describe('Filter by programming language - WARNING: Can cause empty results with restrictive combinations'),
-        license: z.string().optional().describe('Filter by license type'),
+        license: z
+            .array(z.string())
+            .optional()
+            .describe('Filter based on license type (e.g., ["mit", "apache-2.0"])'),
         limit: z
             .number()
             .optional()
@@ -1373,28 +1729,37 @@ function registerSearchGitHubReposTool(server) {
             .enum(['name', 'description', 'readme'])
             .optional()
             .describe('Search scope restriction'),
-        numberTopics: z.number().optional().describe('Filter by topics count'),
+        numberTopics: z
+            .number()
+            .optional()
+            .describe('Filter on number of topics'),
         order: z
             .enum(['asc', 'desc'])
             .optional()
             .default('desc')
             .describe('Result order (default: desc for newest first)'),
-        size: z.string().optional().describe('Filter by size in KB'),
+        size: z
+            .string()
+            .optional()
+            .describe('Filter on size range, in kilobytes (e.g., ">1000", "50..120")'),
         sort: z
             .enum(['forks', 'help-wanted-issues', 'stars', 'updated', 'best-match'])
             .optional()
-            .default('updated')
-            .describe('Sort criteria (default: updated for recent activity)'),
+            .default('best-match')
+            .describe('Sort fetched repositories (default: best-match)'),
         stars: z
-            .number()
+            .string()
             .optional()
-            .describe('Filter by stars count - TIP: Use >100 for established projects, >10 for active ones'),
-        topic: z.string().optional().describe('Filter by topic/tag'),
+            .describe('Filter by stars count (e.g., ">100", "<1000", ">=500", "50..200" for range queries) - TIP: Use >100 for established projects, >10 for active ones'),
+        topic: z
+            .array(z.string())
+            .optional()
+            .describe('Filter on topic (e.g., ["react", "javascript"])'),
         updated: z.string().optional().describe('Filter by last update date'),
         visibility: z
             .enum(['public', 'private', 'internal'])
             .optional()
-            .describe('Filter by visibility'),
+            .describe('Filter based on repository visibility'),
     }, {
         title: 'Search GitHub Repositories',
         readOnlyHint: true,
@@ -1420,8 +1785,26 @@ function registerSearchGitHubReposTool(server) {
             const result = await searchGitHubRepos(searchArgs);
             // Check if we got empty results and provide helpful guidance
             const resultText = result.content[0].text;
-            const parsedResults = JSON.parse(resultText);
-            const resultCount = JSON.parse(parsedResults.rawOutput).length;
+            // Handle non-JSON responses gracefully
+            let parsedResults;
+            let resultCount = 0;
+            try {
+                parsedResults = JSON.parse(resultText);
+                if (parsedResults.rawOutput) {
+                    const rawData = JSON.parse(parsedResults.rawOutput);
+                    resultCount = Array.isArray(rawData) ? rawData.length : 0;
+                }
+            }
+            catch (parseError) {
+                // If parsing fails, it might be an error message from GitHub CLI
+                if (resultText.includes('Failed to') ||
+                    resultText.includes('Error:')) {
+                    throw new Error(`GitHub CLI error: ${resultText}`);
+                }
+                // For other parsing issues, set reasonable defaults
+                resultCount = 0;
+                parsedResults = { rawOutput: '[]' };
+            }
             let responseText = resultText;
             // Add guidance for multi-term queries
             if (queryAnalysis.shouldDecompose) {
@@ -1462,6 +1845,10 @@ function registerSearchGitHubReposTool(server) {
                     responseText += `\n• SCOPED SEARCH SUCCESS: owner + single term pattern proven effective`;
                     responseText += `\n• PROVEN EXAMPLES: microsoft+typescript→VSCode(173K⭐), facebook+react→React(236K⭐)`;
                 }
+                else if (!args.owner) {
+                    responseText += `\n• GLOBAL SEARCH: Searching across all GitHub repositories`;
+                    responseText += `\n• TIP: Add owner filter for more targeted results if you know specific organizations`;
+                }
                 // Add caching recommendations for testing-validated popular searches
                 const validatedPopularTerms = [
                     'react', // 236K⭐ confirmed
@@ -1494,11 +1881,12 @@ function registerSearchGitHubReposTool(server) {
 🔄 RECOMMENDED FALLBACK WORKFLOW:
 ${fallbacks.map(f => `• ${f}`).join('\n')}
 
-💡 PRODUCTION NOTE: This tool is a last resort. For reliable discovery:
+💡 PRODUCTION NOTE: For reliable discovery:
 1. Start with npm_search_packages for package-based discovery
 2. Use github_search_topics for ecosystem terminology  
 3. Use npm_get_package to extract repository URLs
-4. Only use repository search when NPM + Topics completely fail`;
+4. Use global repository search (without owner) for broad discovery
+5. Use scoped search (with owner) when you know specific organizations`;
             return {
                 content: [
                     {
@@ -2291,8 +2679,9 @@ function registerSearchGitHubIssuesTool(server) {
             .describe("The search query to find issues (e.g., 'bug fix', 'feature request', 'documentation')"),
         owner: z
             .string()
-            .min(1, 'Owner is required and cannot be empty')
-            .describe("Filter by repository owner/organization (e.g., 'example-org')"),
+            .min(1)
+            .optional()
+            .describe("Filter by repository owner/organization (e.g., 'example-org'). OPTIONAL: Leave empty for global searches across all of GitHub."),
         repo: z
             .string()
             .optional()
@@ -2605,6 +2994,8 @@ function buildGitHubUsersAPICommand(params) {
     // Add pagination parameters
     const limit = params.limit || 30;
     queryParams.push(`per_page=${limit}`);
+    const page = params.page || 1;
+    queryParams.push(`page=${page}`);
     if (params.sort)
         queryParams.push(`sort=${params.sort}`);
     if (params.order)
@@ -2623,8 +3014,9 @@ function registerSearchGitHubUsersTool(server) {
             .describe("The search query to find users/organizations (e.g., 'react developer', 'python', 'machine learning')"),
         owner: z
             .string()
-            .min(1, 'Owner is required and cannot be empty')
-            .describe("Filter by repository owner/organization (e.g., 'example-org') obtained from the appropriate tool for fetching user organizations"),
+            .min(1)
+            .optional()
+            .describe("Filter by repository owner/organization (e.g., 'example-org'). OPTIONAL: Leave empty for global searches across all of GitHub."),
         type: z
             .enum(['user', 'org'])
             .optional()
@@ -2663,6 +3055,11 @@ function registerSearchGitHubUsersTool(server) {
             .optional()
             .default(50)
             .describe('Maximum number of users to return (default: 50)'),
+        page: z
+            .number()
+            .optional()
+            .default(1)
+            .describe('The page number of the results to fetch (default: 1)'),
     }, {
         title: 'Search GitHub Users',
         readOnlyHint: true,
@@ -2687,67 +3084,6 @@ function registerSearchGitHubUsersTool(server) {
     });
 }
 
-async function npmPackageStats(packageName) {
-    const cacheKey = generateCacheKey('npm-stats', { packageName });
-    return withCache(cacheKey, async () => {
-        try {
-            // Execute multiple commands in parallel using executeNpmCommand
-            const commands = [
-                executeNpmCommand('view', [packageName, 'time', '--json']),
-                executeNpmCommand('view', [packageName, 'versions', '--json']),
-                executeNpmCommand('view', [packageName, 'dist-tags', '--json']),
-            ];
-            const results = await Promise.allSettled(commands);
-            const stats = {
-                packageName,
-                releaseHistory: results[0].status === 'fulfilled' && !results[0].value.isError
-                    ? JSON.parse(results[0].value.content[0].text).result
-                    : null,
-                versions: results[1].status === 'fulfilled' && !results[1].value.isError
-                    ? JSON.parse(results[1].value.content[0].text).result
-                    : null,
-                distTags: results[2].status === 'fulfilled' && !results[2].value.isError
-                    ? JSON.parse(results[2].value.content[0].text).result
-                    : null,
-                analyzedAt: new Date().toISOString(),
-            };
-            return createSuccessResult$1(stats);
-        }
-        catch (error) {
-            return createErrorResult$1('Failed to get npm package statistics', error);
-        }
-    });
-}
-
-function registerNpmPackageStatsTool(server) {
-    server.tool(TOOL_NAMES.NPM_GET_PACKAGE_STATS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_PACKAGE_STATS], {
-        packageName: z
-            .string()
-            .describe("The name of the npm package to analyze (e.g., 'react', '@types/node', 'lodash')"),
-    }, {
-        title: 'NPM Package Statistics',
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-    }, async (args) => {
-        try {
-            return await npmPackageStats(args.packageName);
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Failed to get npm package statistics: ${error.message}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-}
-
 async function analyzeDependencies(packageName) {
     const cacheKey = generateCacheKey('npm-dep-analysis', { packageName });
     return withCache(cacheKey, async () => {
@@ -2874,6 +3210,699 @@ function registerNpmDependencyAnalysisTool(server) {
     });
 }
 
+async function npmGetRepository(packageName) {
+    const cacheKey = generateCacheKey('npm-get-repository', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only repository-related data
+            const repositoryResult = {
+                packageName: npmData.name,
+                description: npmData.description,
+                repository: npmData.repository,
+                homepage: npmData.homepage,
+            };
+            return createSuccessResult$1(repositoryResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm repository information', error);
+        }
+    });
+}
+
+function registerNpmGetRepositoryTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_REPOSITORY, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_REPOSITORY], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get repository information for (e.g., 'react', 'express', 'lodash'). Returns minimal repository data: package name, description, repository URL, and homepage - optimized for token efficiency."),
+    }, {
+        title: 'NPM Repository Discovery - Extract GitHub Repository URL',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetRepository(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm repository info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetDependencies(packageName) {
+    const cacheKey = generateCacheKey('npm-get-dependencies', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only dependencies data
+            const dependenciesResult = {
+                packageName: npmData.name,
+                dependencies: npmData.dependencies || {},
+                devDependencies: npmData.devDependencies || {},
+                resolutions: npmData.resolutions || {},
+            };
+            return createSuccessResult$1(dependenciesResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm dependencies information', error);
+        }
+    });
+}
+
+function registerNpmGetDependenciesTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_DEPENDENCIES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_DEPENDENCIES], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to analyze dependencies for (e.g., 'react', 'express', 'lodash'). Returns focused dependency data: dependencies, devDependencies, and resolutions - optimized for token efficiency."),
+    }, {
+        title: 'NPM Dependency Analysis - Extract Package Dependencies',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetDependencies(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm dependencies: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetBugs(packageName) {
+    const cacheKey = generateCacheKey('npm-get-bugs', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only bugs data
+            const bugsResult = {
+                packageName: npmData.name,
+                bugs: npmData.bugs,
+            };
+            return createSuccessResult$1(bugsResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm bugs information', error);
+        }
+    });
+}
+
+function registerNpmGetBugsTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_BUGS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_BUGS], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get bug tracking information for (e.g., 'react', 'express', 'lodash'). Returns minimal bug data: package name and bugs URL - optimized for token efficiency."),
+    }, {
+        title: 'NPM Bug Tracking - Extract Issue Tracker URL',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetBugs(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm bugs info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetReadme(packageName) {
+    const cacheKey = generateCacheKey('npm-get-readme', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only readme data
+            const readmeResult = {
+                packageName: npmData.name,
+                readmeFilename: npmData.readmeFilename,
+            };
+            return createSuccessResult$1(readmeResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm readme information', error);
+        }
+    });
+}
+
+function registerNpmGetReadmeTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_README, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_README], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get README information for (e.g., 'react', 'express', 'lodash'). Returns minimal README data: package name and readme filename - optimized for token efficiency."),
+    }, {
+        title: 'NPM Documentation Access - Extract README Filename',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetReadme(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm readme info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetVersions(packageName) {
+    const cacheKey = generateCacheKey('npm-get-versions', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Filter versions to include only official semantic versions (major.minor.patch)
+            // Excludes pre-release versions like alpha, beta, rc, dev, experimental, etc.
+            const semanticVersionRegex = /^\d+\.\d+\.\d+$/;
+            const officialVersions = npmData.versions.filter(version => semanticVersionRegex.test(version));
+            // Extract only versions data with filtered official versions
+            const versionsResult = {
+                packageName: npmData.name,
+                versions: officialVersions,
+                latestVersion: npmData['dist-tags'].latest,
+                versionCount: officialVersions.length,
+            };
+            return createSuccessResult$1(versionsResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm versions information', error);
+        }
+    });
+}
+
+function registerNpmGetVersionsTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_VERSIONS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_VERSIONS], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get version information for (e.g., 'react', 'express', 'lodash'). Returns only official semantic versions (major.minor.patch format), excluding pre-release versions like alpha, beta, rc - optimized for production planning."),
+    }, {
+        title: 'NPM Version Tracking - Extract Package Versions',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetVersions(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm versions: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetAuthor(packageName) {
+    const cacheKey = generateCacheKey('npm-get-author', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only author data
+            const authorResult = {
+                packageName: npmData.name,
+                author: npmData.author,
+                maintainers: npmData.maintainers,
+            };
+            return createSuccessResult$1(authorResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm author information', error);
+        }
+    });
+}
+
+function registerNpmGetAuthorTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_AUTHOR, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_AUTHOR], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get author information for (e.g., 'react', 'express', 'lodash'). Returns focused author data: author and maintainers list - optimized for token efficiency."),
+    }, {
+        title: 'NPM Maintainer Information - Extract Author and Maintainers',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetAuthor(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm author info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetLicense(packageName) {
+    const cacheKey = generateCacheKey('npm-get-license', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only license data
+            const licenseResult = {
+                packageName: npmData.name,
+                license: npmData.license,
+            };
+            return createSuccessResult$1(licenseResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm license information', error);
+        }
+    });
+}
+
+function registerNpmGetLicenseTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_LICENSE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_LICENSE], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get license information for (e.g., 'react', 'express', 'lodash'). Returns minimal license data: package name and license - optimized for token efficiency."),
+    }, {
+        title: 'NPM License Compliance - Extract Package License',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetLicense(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm license info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetHomepage(packageName) {
+    const cacheKey = generateCacheKey('npm-get-homepage', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only homepage data
+            const homepageResult = {
+                packageName: npmData.name,
+                homepage: npmData.homepage,
+            };
+            return createSuccessResult$1(homepageResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm homepage information', error);
+        }
+    });
+}
+
+function registerNpmGetHomepageTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_HOMEPAGE, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_HOMEPAGE], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get homepage information for (e.g., 'react', 'express', 'lodash'). Returns direct access to official documentation, interactive examples, and comprehensive project resources - optimized for token efficiency."),
+    }, {
+        title: 'NPM Homepage Discovery - Extract Project Website URL',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetHomepage(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm homepage info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetId(packageName) {
+    const cacheKey = generateCacheKey('npm-get-id', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only _id data (name@latestVersion format)
+            const idResult = {
+                packageName: npmData.name,
+                id: npmData._id,
+            };
+            return createSuccessResult$1(idResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm ID information', error);
+        }
+    });
+}
+
+function registerNpmGetIdTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_ID, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_ID], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get ID information for (e.g., 'react', 'express', 'lodash'). Returns precise version identifier for dependency management, lockfiles, and reproducible builds - optimized for token efficiency."),
+    }, {
+        title: 'NPM Package Identification - Extract Name@Version ID',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetId(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm ID info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetReleases(packageName) {
+    const cacheKey = generateCacheKey('npm-get-releases', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only version entries (exclude 'created' and 'modified')
+            const versionEntries = Object.entries(npmData.time).filter(([key]) => key !== 'created' && key !== 'modified');
+            // Sort by release date (most recent first) and take last 10
+            const sortedVersions = versionEntries
+                .sort(([, dateA], [, dateB]) => new Date(dateB).getTime() - new Date(dateA).getTime())
+                .slice(0, 10)
+                .map(([version, releaseDate]) => ({ version, releaseDate }));
+            // Create efficient result with only requested data
+            const timeResult = {
+                packageName: npmData.name,
+                lastModified: npmData.time.modified,
+                created: npmData.time.created,
+                versionCount: versionEntries.length,
+                last10Releases: sortedVersions,
+            };
+            return createSuccessResult$1(timeResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm time information', error);
+        }
+    });
+}
+
+function registerNpmGetReleasesTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_RELEASES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_RELEASES], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get release information for (e.g., 'react', 'express', 'lodash'). Returns focused release data: last modified, created date, version count, and last 10 releases - optimized for token efficiency."),
+    }, {
+        title: 'NPM Package Releases - Extract Recent Release Data',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetReleases(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm release info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetEngines(packageName) {
+    const cacheKey = generateCacheKey('npm-get-engines', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only engines data
+            const enginesResult = {
+                packageName: npmData.name,
+                engines: npmData.engines || {},
+            };
+            return createSuccessResult$1(enginesResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm engines information', error);
+        }
+    });
+}
+
+function registerNpmGetEnginesTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_ENGINES, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_ENGINES], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get engines information for (e.g., 'react', 'express', 'lodash'). Returns environment compatibility requirements to prevent deployment failures and runtime conflicts - optimized for token efficiency."),
+    }, {
+        title: 'NPM Runtime Compatibility - Extract Engine Requirements',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetEngines(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm engines info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
+async function npmGetExports(packageName) {
+    const cacheKey = generateCacheKey('npm-get-exports', { packageName });
+    return withCache(cacheKey, async () => {
+        try {
+            const result = await executeNpmCommand('view', [packageName, '--json'], {
+                cache: true,
+            });
+            if (result.isError) {
+                return result;
+            }
+            // Parse the result from the executed command
+            const commandOutput = JSON.parse(result.content[0].text);
+            // The result is a JSON string from npm that needs to be parsed again
+            const npmData = JSON.parse(commandOutput.result);
+            // Extract only exports data
+            const exportsResult = {
+                packageName: npmData.name,
+                exports: npmData.exports || {},
+            };
+            return createSuccessResult$1(exportsResult);
+        }
+        catch (error) {
+            return createErrorResult$1('Failed to get npm exports information', error);
+        }
+    });
+}
+
+function registerNpmGetExportsTool(server) {
+    server.tool(TOOL_NAMES.NPM_GET_EXPORTS, TOOL_DESCRIPTIONS[TOOL_NAMES.NPM_GET_EXPORTS], {
+        packageName: z
+            .string()
+            .describe("The name of the npm package to get exports information for (e.g., 'react', 'express', 'lodash'). Returns import path intelligence: available modules, entry points, and tree-shakable exports for optimal code search - optimized for token efficiency."),
+    }, {
+        title: 'NPM Module Structure - Extract Package Export Mappings',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, async (args) => {
+        try {
+            return await npmGetExports(args.packageName);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to get npm exports info: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+
 function registerUsageGuideResource(server) {
     server.resource('usage-guide', 'help://usage', async (uri) => ({
         contents: [
@@ -3601,7 +4630,7 @@ function registerAllTools(server) {
     registerGitHubSearchCodeTool(server);
     registerFetchGitHubFileContentTool(server);
     registerViewRepositoryTool(server);
-    registerNpmViewTool(server);
+    //Tools.registerNpmViewTool(server);
     registerSearchGitHubReposTool(server);
     registerSearchGitHubCommitsTool(server);
     registerSearchGitHubPullRequestsTool(server);
@@ -3609,12 +4638,22 @@ function registerAllTools(server) {
     registerNpmSearchTool(server);
     registerViewRepositoryStructureTool(server);
     registerSearchGitHubIssuesTool(server);
-    // TODO: add discussions tool after fixing API
-    //Tools.registerSearchGitHubDiscussionsTool(server);
     registerSearchGitHubTopicsTool(server);
     registerSearchGitHubUsersTool(server);
-    registerNpmPackageStatsTool(server);
+    // Focused NPM tools for minimal token usage
     registerNpmDependencyAnalysisTool(server);
+    registerNpmGetRepositoryTool(server);
+    registerNpmGetDependenciesTool(server);
+    registerNpmGetBugsTool(server);
+    registerNpmGetReadmeTool(server);
+    registerNpmGetVersionsTool(server);
+    registerNpmGetAuthorTool(server);
+    registerNpmGetLicenseTool(server);
+    registerNpmGetHomepageTool(server);
+    registerNpmGetIdTool(server);
+    registerNpmGetReleasesTool(server);
+    registerNpmGetEnginesTool(server);
+    registerNpmGetExportsTool(server);
 }
 // Register all resources
 function registerResources(server) {