@nekzus/mcp-server 1.18.3 → 1.19.0-alpha.10

package/dist/index.js

@@ -2,15 +2,16 @@
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import fetch from 'node-fetch';
 import { z } from 'zod';
+import createServer from './src/server.js';
 // Cache configuration
-let NPM_REGISTRY_URL = (process.env.NPM_REGISTRY_URL || 'https://registry.npmjs.org').replace(/\/$/, '');
+export let NPM_REGISTRY_URL = (process.env.NPM_REGISTRY_URL || 'https://registry.npmjs.org').replace(/\/$/, '');
+export function setNpmRegistryUrl(url) {
+    NPM_REGISTRY_URL = url.replace(/\/$/, '');
+}
 // Cache configuration
-const CACHE_TTL_SHORT = 15 * 60 * 1000; // 15 minutes
 const CACHE_TTL_MEDIUM = 60 * 60 * 1000; // 1 hour
 const CACHE_TTL_LONG = 6 * 60 * 60 * 1000; // 6 hours
 const CACHE_TTL_VERY_LONG = 24 * 60 * 60 * 1000; // 24 hours
@@ -73,6 +74,76 @@ function cacheSet(key, value, ttlMilliseconds) {
         }
     }
 }
+// HTTP wrapper configuration
+const HTTP_MAX_RETRIES = 3;
+const HTTP_INITIAL_BACKOFF_MS = 1000;
+const HTTP_MAX_CONCURRENT_REQUESTS = 5;
+const DEFAULT_HEADERS = {
+    Accept: 'application/json',
+    'User-Agent': 'NPM-Sentinel-MCP/1.x',
+};
+// Semaphore for concurrency control
+let activeRequests = 0;
+const requestQueue = [];
+function acquireSlot() {
+    if (activeRequests < HTTP_MAX_CONCURRENT_REQUESTS) {
+        activeRequests++;
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        requestQueue.push(() => {
+            activeRequests++;
+            resolve();
+        });
+    });
+}
+function releaseSlot() {
+    activeRequests--;
+    const next = requestQueue.shift();
+    if (next)
+        next();
+}
+export async function fetchWithRetry(url, options = {}, config = {}) {
+    const maxRetries = config.maxRetries ?? HTTP_MAX_RETRIES;
+    const mergedHeaders = { ...DEFAULT_HEADERS, ...(options.headers || {}) };
+    const mergedOptions = { ...options, headers: mergedHeaders };
+    if (!config.skipThrottle) {
+        await acquireSlot();
+    }
+    try {
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await fetch(url, mergedOptions);
+                if (response.status === 429 || (response.status >= 500 && response.status < 600)) {
+                    if (attempt < maxRetries) {
+                        const retryAfter = response.headers.get('retry-after');
+                        const waitMs = retryAfter
+                            ? parseInt(retryAfter, 10) * 1000
+                            : HTTP_INITIAL_BACKOFF_MS * 2 ** attempt;
+                        await new Promise((resolve) => setTimeout(resolve, waitMs));
+                        continue;
+                    }
+                }
+                return response;
+            }
+            catch (err) {
+                if (attempt < maxRetries) {
+                    const waitMs = HTTP_INITIAL_BACKOFF_MS * 2 ** attempt;
+                    await new Promise((resolve) => setTimeout(resolve, waitMs));
+                    continue;
+                }
+                throw err;
+            }
+        }
+        // Fallback
+        return await fetch(url, mergedOptions);
+    }
+    finally {
+        if (!config.skipThrottle) {
+            releaseSlot();
+        }
+    }
+}
 // Zod schemas for npm package data
 export const NpmMaintainerSchema = z
     .object({
@@ -171,64 +242,7 @@ export const NpmDownloadsDataSchema = z.object({
     end: z.string(),
     package: z.string(),
 });
-function isValidNpmsResponse(data) {
-    if (typeof data !== 'object' || data === null) {
-        console.debug('NpmsApiResponse validation: Response is not an object or is null');
-        return false;
-    }
-    const response = data;
-    // Check score structure
-    if (!response.score ||
-        typeof response.score !== 'object' ||
-        !('final' in response.score) ||
-        typeof response.score.final !== 'number' ||
-        !('detail' in response.score) ||
-        typeof response.score.detail !== 'object') {
-        console.debug('NpmsApiResponse validation: Invalid score structure');
-        return false;
-    }
-    // Check score detail metrics
-    const detail = response.score.detail;
-    if (typeof detail.quality !== 'number' ||
-        typeof detail.popularity !== 'number' ||
-        typeof detail.maintenance !== 'number') {
-        console.debug('NpmsApiResponse validation: Invalid score detail metrics');
-        return false;
-    }
-    // Check collected data structure
-    if (!response.collected ||
-        typeof response.collected !== 'object' ||
-        !response.collected.metadata ||
-        typeof response.collected.metadata !== 'object' ||
-        typeof response.collected.metadata.name !== 'string' ||
-        typeof response.collected.metadata.version !== 'string') {
-        console.debug('NpmsApiResponse validation: Invalid collected data structure');
-        return false;
-    }
-    // Check npm data
-    if (!response.collected.npm ||
-        typeof response.collected.npm !== 'object' ||
-        !Array.isArray(response.collected.npm.downloads) ||
-        typeof response.collected.npm.starsCount !== 'number') {
-        console.debug('NpmsApiResponse validation: Invalid npm data structure');
-        return false;
-    }
-    // Optional github data check
-    if (response.collected.github) {
-        if (typeof response.collected.github !== 'object' ||
-            typeof response.collected.github.starsCount !== 'number' ||
-            typeof response.collected.github.forksCount !== 'number' ||
-            typeof response.collected.github.subscribersCount !== 'number' ||
-            !response.collected.github.issues ||
-            typeof response.collected.github.issues !== 'object' ||
-            typeof response.collected.github.issues.count !== 'number' ||
-            typeof response.collected.github.issues.openCount !== 'number') {
-            console.debug('NpmsApiResponse validation: Invalid github data structure');
-            return false;
-        }
-    }
-    return true;
-}
+// Schema for search results from npm registry v1 search api
 export const NpmSearchResultSchema = z
     .object({
     objects: z.array(z.object({
@@ -266,15 +280,6 @@ export const NpmSearchResultSchema = z
     total: z.number(), // total is a sibling of objects
 })
     .loose();
-// Logger function that uses stderr - only for critical errors
-const log = (...args) => {
-    // Filter out server status messages
-    const message = args[0];
-    if (typeof message === 'string' &&
-        (!message.startsWith('[Server]') || message.includes('error') || message.includes('Error'))) {
-        console.error(...args);
-    }
-};
 // Type guards for API responses
 function isNpmPackageInfo(data) {
     return (typeof data === 'object' &&
@@ -331,11 +336,24 @@ function isValidNpmPackageName(name) {
         !name.startsWith('_') &&
         !name.startsWith('.'));
 }
+export function createEmptyArrayErrorResponse(toolName) {
+    const errorResponse = JSON.stringify({
+        queryPackages: [],
+        results: [],
+        status: 'error',
+        error: 'No package names provided in request',
+        message: `The packages parameter for ${toolName} must contain at least one package name.`,
+    }, null, 2);
+    return {
+        content: [{ type: 'text', text: errorResponse }],
+        isError: true,
+    };
+}
 export async function handleNpmVersions(args) {
     try {
         const packagesToProcess = args.packages || [];
         if (packagesToProcess.length === 0) {
-            throw new Error('No package names provided');
+            return createEmptyArrayErrorResponse('npmVersions');
         }
         const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
             let name = '';
@@ -391,12 +409,7 @@ export async function handleNpmVersions(args) {
                 };
             }
             try {
-                const response = await fetch(`${NPM_REGISTRY_URL}/${name}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
+                const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}`);
                 if (!response.ok) {
                     return {
                         packageInput: pkgInput,
@@ -465,7 +478,7 @@ export async function handleNpmLatest(args) {
     try {
         const packagesToProcess = args.packages || [];
         if (packagesToProcess.length === 0) {
-            throw new Error('No package names provided');
+            return createEmptyArrayErrorResponse('npmLatest');
         }
         const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
             let name = '';
@@ -527,12 +540,7 @@ export async function handleNpmLatest(args) {
                 };
             }
             try {
-                const response = await fetch(`${NPM_REGISTRY_URL}/${name}/${versionTag}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
+                const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}/${versionTag}`);
                 if (!response.ok) {
                     let errorMsg = `Failed to fetch package version: ${response.status} ${response.statusText}`;
                     if (response.status === 404) {
@@ -666,12 +674,7 @@ export async function handleNpmDeps(args) {
                 };
             }
             try {
-                const response = await fetch(`${NPM_REGISTRY_URL}/${name}/${version}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
+                const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}/${version}`);
                 if (!response.ok) {
                     return {
                         package: packageNameForOutput,
@@ -797,12 +800,7 @@ export async function handleNpmTypes(args) {
                 };
             }
             try {
-                const response = await fetch(`${NPM_REGISTRY_URL}/${name}/${version}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
+                const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}/${version}`);
                 if (!response.ok) {
                     return {
                         package: packageNameForOutput,
@@ -824,12 +822,7 @@ export async function handleNpmTypes(args) {
                     isAvailable: false,
                 };
                 try {
-                    const typesResponse = await fetch(`${NPM_REGISTRY_URL}/${typesPackageName}/latest`, {
-                        headers: {
-                            Accept: 'application/json',
-                            'User-Agent': 'NPM-Sentinel-MCP',
-                        },
-                    });
+                    const typesResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${typesPackageName}/latest`);
                     if (typesResponse.ok) {
                         const typesData = (await typesResponse.json());
                         typesPackageInfo = {
@@ -936,12 +929,7 @@ export async function handleNpmSize(args) {
                 };
             }
             try {
-                const response = await fetch(`https://bundlephobia.com/api/size?package=${bundlephobiaQuery}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
+                const response = await fetchWithRetry(`https://bundlephobia.com/api/size?package=${bundlephobiaQuery}`);
                 if (!response.ok) {
                     let errorMsg = `Failed to fetch package size: ${response.status} ${response.statusText}`;
                     if (response.status === 404) {
@@ -1021,9 +1009,7 @@ async function fetchTransitiveDependenciesFromDepsDev(pkgName, version) {
         const encodedName = encodeURIComponent(pkgName);
         const encodedVersion = encodeURIComponent(version);
         const url = `https://api.deps.dev/v3/systems/npm/packages/${encodedName}/versions/${encodedVersion}:dependencies`;
-        const response = await fetch(url, {
-            headers: { Accept: 'application/json', 'User-Agent': 'NPM-Sentinel-MCP' },
-        });
+        const response = await fetchWithRetry(url);
         if (!response.ok) {
             console.warn(`deps.dev API returned ${response.status} for ${pkgName}@${version}`);
             return [];
@@ -1043,12 +1029,46 @@ async function fetchTransitiveDependenciesFromDepsDev(pkgName, version) {
         return [];
     }
 }
+export async function fetchRepoStatsFromDepsDev(owner, repo, ignoreCache = false) {
+    const projectKey = encodeURIComponent(`github.com/${owner}/${repo}`);
+    const cacheKey = generateCacheKey('depsDevProject', owner, repo);
+    const cached = ignoreCache ? undefined : cacheGet(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const response = await fetchWithRetry(`https://api.deps.dev/v3alpha/projects/${projectKey}`, {}, { maxRetries: 1 });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        const result = {
+            starsCount: data.starsCount ?? 0,
+            forksCount: data.forksCount ?? 0,
+            openIssuesCount: data.openIssuesCount ?? 0,
+            license: data.license ?? 'unknown',
+            description: data.description ?? '',
+            homepage: data.homepage ?? '',
+            scorecard: data.scorecard
+                ? {
+                    overallScore: data.scorecard.overallScore,
+                    checks: (data.scorecard.checks || []).map((c) => ({
+                        name: c.name,
+                        score: c.score,
+                        reason: c.reason,
+                    })),
+                }
+                : undefined,
+        };
+        cacheSet(cacheKey, result, CACHE_TTL_VERY_LONG);
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
 // Helper to resolve 'latest' tag to actual version number
 async function resolveLatestVersion(packageName) {
     try {
-        const response = await fetch(`${NPM_REGISTRY_URL}/${packageName}/latest`, {
-            headers: { 'User-Agent': 'NPM-Sentinel-MCP' },
-        });
+        const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/${packageName}/latest`);
         if (!response.ok)
             return null;
         const data = (await response.json());
@@ -1069,9 +1089,7 @@ async function enrichVulnerabilityData(vulnId, ignoreCache = false) {
     if (cached)
         return cached;
     try {
-        const response = await fetch(`https://api.osv.dev/v1/vulns/${vulnId}`, {
-            headers: { 'User-Agent': 'NPM-Sentinel-MCP' },
-        });
+        const response = await fetchWithRetry(`https://api.osv.dev/v1/vulns/${vulnId}`);
         if (!response.ok)
             return null;
         const data = await response.json();
@@ -1218,7 +1236,7 @@ export async function handleNpmVulnerabilities(args) {
         let apiResults = [];
         if (finalBatchQueries.length > 0) {
             // Perform Batch API call to OSV for non-cached items
-            const response = await fetch('https://api.osv.dev/v1/querybatch', {
+            const response = await fetchWithRetry('https://api.osv.dev/v1/querybatch', {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ queries: finalBatchQueries }),
@@ -1370,12 +1388,7 @@ export async function handleNpmTrends(args) {
                 };
             }
             try {
-                const response = await fetch(`https://api.npmjs.org/downloads/point/${period}/${name}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
+                const response = await fetchWithRetry(`https://api.npmjs.org/downloads/point/${period}/${name}`);
                 if (!response.ok) {
                     let errorMsg = `Failed to fetch download trends: ${response.status} ${response.statusText}`;
                     if (response.status === 404) {
@@ -1532,7 +1545,7 @@ export async function handleNpmCompare(args) {
             }
             try {
                 // Fetch package version details from registry
-                const pkgResponse = await fetch(`${NPM_REGISTRY_URL}/${name}/${versionTag}`);
+                const pkgResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}/${versionTag}`);
                 if (!pkgResponse.ok) {
                     throw new Error(`Failed to fetch package info for ${name}@${versionTag}: ${pkgResponse.status} ${pkgResponse.statusText}`);
                 }
@@ -1543,7 +1556,7 @@ export async function handleNpmCompare(args) {
                 // Fetch monthly downloads
                 let monthlyDownloads = null;
                 try {
-                    const downloadsResponse = await fetch(`https://api.npmjs.org/downloads/point/last-month/${name}`);
+                    const downloadsResponse = await fetchWithRetry(`https://api.npmjs.org/downloads/point/last-month/${name}`);
                     if (downloadsResponse.ok) {
                         const downloadsData = await downloadsResponse.json();
                         if (isNpmDownloadsData(downloadsData)) {
@@ -1558,7 +1571,7 @@ export async function handleNpmCompare(args) {
                 // Need to fetch the full package info to get to the 'time' field for specific version
                 let publishDate = null;
                 try {
-                    const fullPkgInfoResponse = await fetch(`${NPM_REGISTRY_URL}/${name}`);
+                    const fullPkgInfoResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}`);
                     if (fullPkgInfoResponse.ok) {
                         const fullPkgInfo = await fullPkgInfoResponse.json();
                         if (isNpmPackageInfo(fullPkgInfo) && fullPkgInfo.time) {
@@ -1623,6 +1636,122 @@ export async function handleNpmCompare(args) {
         };
     }
 }
+export async function getLocalPackageMetrics(name, ignoreCache = false) {
+    const cacheKey = generateCacheKey('localMetrics', name);
+    const cached = ignoreCache ? undefined : cacheGet(cacheKey);
+    if (cached)
+        return cached;
+    // 1. Fetch full packument from registry
+    const registryResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}`);
+    if (!registryResponse.ok) {
+        throw new Error(`Package ${name} not found on registry.`);
+    }
+    const packageInfo = await registryResponse.json();
+    if (!isNpmPackageInfo(packageInfo)) {
+        throw new Error(`Invalid registry data received for ${name}.`);
+    }
+    const latestVersion = packageInfo['dist-tags']?.latest;
+    if (!latestVersion || !packageInfo.versions?.[latestVersion]) {
+        throw new Error(`No latest version found for ${name}.`);
+    }
+    const versionData = packageInfo.versions[latestVersion];
+    const hasTypes = Boolean(versionData.types || versionData.typings || versionData.dependencies?.[`@types/${name}`]);
+    const hasReadme = Boolean(versionData.readme || packageInfo.readme);
+    const dependencyCount = Object.keys(versionData.dependencies || {}).length;
+    // 2. Fetch downloads for last month
+    let downloadsLastMonth = 0;
+    try {
+        const downloadsResponse = await fetchWithRetry(`https://api.npmjs.org/downloads/point/last-month/${name}`);
+        if (downloadsResponse.ok) {
+            const dlData = await downloadsResponse.json();
+            downloadsLastMonth = dlData.downloads || 0;
+        }
+    }
+    catch (dlError) {
+        console.debug(`Could not fetch downloads for ${name}: ${dlError}`);
+    }
+    // 3. Fetch GitHub stats via deps.dev (optional, graceful degradation)
+    let github = {
+        starsCount: 0,
+        forksCount: 0,
+        subscribersCount: 0,
+        openIssuesCount: 0,
+        hasGitHubData: false,
+    };
+    let scorecard;
+    const repoUrl = versionData.repository?.url || packageInfo.repository?.url;
+    if (repoUrl?.includes('github.com')) {
+        const githubMatch = repoUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+        if (githubMatch) {
+            const [, owner, repo] = githubMatch;
+            const cleanRepo = repo.replace(/\.git$/, '');
+            try {
+                const depsDevData = await fetchRepoStatsFromDepsDev(owner, cleanRepo, ignoreCache);
+                if (depsDevData) {
+                    github = {
+                        starsCount: depsDevData.starsCount,
+                        forksCount: depsDevData.forksCount,
+                        subscribersCount: 0,
+                        openIssuesCount: depsDevData.openIssuesCount,
+                        hasGitHubData: true,
+                    };
+                    scorecard = depsDevData.scorecard;
+                }
+            }
+            catch (ghError) {
+                console.debug(`Could not fetch deps.dev project data for ${owner}/${cleanRepo}: ${ghError}`);
+            }
+        }
+    }
+    // 4. Calculate publish age
+    let lastPublishDaysAgo = 365;
+    const timeObj = packageInfo.time;
+    if (timeObj?.[latestVersion]) {
+        const publishDate = new Date(timeObj[latestVersion]);
+        const diffTime = Math.abs(Date.now() - publishDate.getTime());
+        lastPublishDaysAgo = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+    }
+    // 5. Scoring Algorithm
+    const popularityNPM = Math.min(1, Math.log10(Math.max(1, downloadsLastMonth)) / 8);
+    let popularity = popularityNPM;
+    if (github.hasGitHubData) {
+        const popularityGH = Math.min(1, github.starsCount / 50000);
+        popularity = popularityNPM * 0.7 + popularityGH * 0.3;
+    }
+    const quality = (hasTypes ? 0.3 : 0) + (hasReadme ? 0.2 : 0) + Math.max(0, 0.5 - dependencyCount * 0.005);
+    const maintenancePublish = lastPublishDaysAgo < 30
+        ? 1.0
+        : lastPublishDaysAgo < 90
+            ? 0.8
+            : lastPublishDaysAgo < 365
+                ? 0.5
+                : 0.2;
+    let maintenance = maintenancePublish;
+    if (github.hasGitHubData) {
+        const issuesScore = github.openIssuesCount < 50 ? 0.3 : github.openIssuesCount < 200 ? 0.2 : 0.1;
+        maintenance = maintenancePublish * 0.7 + issuesScore;
+    }
+    const finalScore = popularity * 0.4 + quality * 0.3 + maintenance * 0.3;
+    const result = {
+        packageName: name,
+        version: latestVersion,
+        description: versionData.description || null,
+        analyzedAt: new Date().toISOString(),
+        downloadsLastMonth,
+        github,
+        score: {
+            final: finalScore,
+            detail: {
+                quality,
+                popularity,
+                maintenance,
+            },
+        },
+        scorecard,
+    };
+    cacheSet(cacheKey, result, CACHE_TTL_LONG);
+    return result;
+}
 // Function to get package quality metrics
 export async function handleNpmQuality(args) {
     try {
@@ -1634,7 +1763,7 @@ export async function handleNpmQuality(args) {
             let name = '';
             if (typeof pkgInput === 'string') {
                 const atIdx = pkgInput.lastIndexOf('@');
-                name = atIdx > 0 ? pkgInput.slice(0, atIdx) : pkgInput; // Version is ignored by npms.io API endpoint for the main query
+                name = atIdx > 0 ? pkgInput.slice(0, atIdx) : pkgInput;
             }
             else {
                 return {
@@ -1679,57 +1808,20 @@ export async function handleNpmQuality(args) {
                 };
             }
             try {
-                const response = await fetch(`https://api.npms.io/v2/package/${encodeURIComponent(name)}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
-                if (!response.ok) {
-                    let errorMsg = `Failed to fetch quality data: ${response.status} ${response.statusText}`;
-                    if (response.status === 404) {
-                        errorMsg = `Package ${name} not found on npms.io.`;
-                    }
-                    return {
-                        packageInput: pkgInput,
-                        packageName: name,
-                        status: 'error',
-                        error: errorMsg,
-                        data: null,
-                        message: `Could not retrieve quality information for ${name}.`,
-                    };
-                }
-                const rawData = await response.json();
-                if (!isValidNpmsResponse(rawData)) {
-                    return {
-                        packageInput: pkgInput,
-                        packageName: name,
-                        status: 'error',
-                        error: 'Invalid or incomplete response from npms.io API for quality data',
-                        data: null,
-                        message: `Received malformed quality data for ${name}.`,
-                    };
-                }
-                const { score, collected, analyzedAt } = rawData;
-                const qualityScore = score.detail.quality;
+                const metrics = await getLocalPackageMetrics(name, args.ignoreCache);
                 const qualityData = {
-                    analyzedAt: analyzedAt,
-                    versionInScore: collected.metadata.version,
-                    qualityScore: qualityScore,
-                    // Detailed sub-metrics like tests, coverage, linting, types are no longer directly provided
-                    // by the npms.io v2 API in the same way. The overall quality score is the primary metric.
+                    analyzedAt: metrics.analyzedAt,
+                    versionInScore: metrics.version,
+                    qualityScore: metrics.score.detail.quality,
                 };
-                const ttl = !collected.metadata.version.match(/^\d+\.\d+\.\d+$/)
-                    ? CACHE_TTL_SHORT
-                    : CACHE_TTL_LONG;
-                cacheSet(cacheKey, qualityData, ttl);
+                cacheSet(cacheKey, qualityData, CACHE_TTL_LONG);
                 return {
                     packageInput: pkgInput,
                     packageName: name,
                     status: 'success',
                     error: null,
                     data: qualityData,
-                    message: `Successfully fetched quality score for ${name} (version analyzed: ${collected.metadata.version}).`,
+                    message: `Successfully fetched quality score for ${name} (version analyzed: ${metrics.version}).`,
                 };
             }
             catch (error) {
@@ -1762,6 +1854,7 @@ export async function handleNpmQuality(args) {
         };
     }
 }
+// Function to get package maintenance metrics
 export async function handleNpmMaintenance(args) {
     try {
         const packagesToProcess = args.packages || [];
@@ -1817,55 +1910,20 @@ export async function handleNpmMaintenance(args) {
                 };
             }
             try {
-                const response = await fetch(`https://api.npms.io/v2/package/${encodeURIComponent(name)}`, {
-                    headers: {
-                        Accept: 'application/json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
-                if (!response.ok) {
-                    let errorMsg = `Failed to fetch maintenance data: ${response.status} ${response.statusText}`;
-                    if (response.status === 404) {
-                        errorMsg = `Package ${name} not found on npms.io.`;
-                    }
-                    return {
-                        packageInput: pkgInput,
-                        packageName: name,
-                        status: 'error',
-                        error: errorMsg,
-                        data: null,
-                        message: `Could not retrieve maintenance information for ${name}.`,
-                    };
-                }
-                const rawData = await response.json();
-                if (!isValidNpmsResponse(rawData)) {
-                    return {
-                        packageInput: pkgInput,
-                        packageName: name,
-                        status: 'error',
-                        error: 'Invalid or incomplete response from npms.io API for maintenance data',
-                        data: null,
-                        message: `Received malformed maintenance data for ${name}.`,
-                    };
-                }
-                const { score, collected, analyzedAt } = rawData;
-                const maintenanceScoreValue = score.detail.maintenance;
+                const metrics = await getLocalPackageMetrics(name, args.ignoreCache);
                 const maintenanceData = {
-                    analyzedAt: analyzedAt,
-                    versionInScore: collected.metadata.version,
-                    maintenanceScore: maintenanceScoreValue,
+                    analyzedAt: metrics.analyzedAt,
+                    versionInScore: metrics.version,
+                    maintenanceScore: metrics.score.detail.maintenance,
                 };
-                const ttl = !collected.metadata.version.match(/^\d+\.\d+\.\d+$/)
-                    ? CACHE_TTL_SHORT
-                    : CACHE_TTL_LONG;
-                cacheSet(cacheKey, maintenanceData, ttl);
+                cacheSet(cacheKey, maintenanceData, CACHE_TTL_LONG);
                 return {
                     packageInput: pkgInput,
                     packageName: name,
                     status: 'success',
                     error: null,
                     data: maintenanceData,
-                    message: `Successfully fetched maintenance score for ${name} (version analyzed: ${collected.metadata.version}).`,
+                    message: `Successfully fetched maintenance score for ${name} (version analyzed: ${metrics.version}).`,
                 };
             }
             catch (error) {
@@ -2025,6 +2083,7 @@ export async function handleNpmMaintainers(args) {
         };
     }
 }
+// Function to get package score
 export async function handleNpmScore(args) {
     try {
         const packagesToProcess = args.packages || [];
@@ -2078,86 +2137,41 @@ export async function handleNpmScore(args) {
                 };
             }
             try {
-                const response = await fetch(`https://api.npms.io/v2/package/${encodeURIComponent(name)}`);
-                if (!response.ok) {
-                    let errorMsg = `Failed to fetch package score: ${response.status} ${response.statusText}`;
-                    if (response.status === 404) {
-                        errorMsg = `Package ${name} not found on npms.io.`;
-                    }
-                    return {
-                        packageInput: pkgInput,
-                        packageName: name,
-                        status: 'error',
-                        error: errorMsg,
-                        data: null,
-                    };
-                }
-                const rawData = await response.json();
-                if (!isValidNpmsResponse(rawData)) {
-                    return {
-                        packageInput: pkgInput,
-                        packageName: name,
-                        status: 'error',
-                        error: 'Invalid or incomplete response from npms.io API',
-                        data: null,
-                    };
-                }
-                const { score, collected, analyzedAt } = rawData;
-                const { detail } = score;
-                // Calculate total downloads for the last month from the typically first entry in downloads array
-                const lastMonthDownloads = collected.npm?.downloads?.find((d) => {
-                    // Heuristic: find a download period that is roughly 30 days
-                    const from = new Date(d.from);
-                    const to = new Date(d.to);
-                    const diffTime = Math.abs(to.getTime() - from.getTime());
-                    const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
-                    return diffDays >= 28 && diffDays <= 31; // Common range for monthly data
-                })?.count ||
-                    collected.npm?.downloads?.[0]?.count ||
-                    0;
+                const metrics = await getLocalPackageMetrics(name, args.ignoreCache);
                 const scoreData = {
-                    analyzedAt: analyzedAt,
-                    versionInScore: collected.metadata.version,
-                    score: {
-                        final: score.final,
-                        detail: {
-                            quality: detail.quality,
-                            popularity: detail.popularity,
-                            maintenance: detail.maintenance,
-                        },
-                    },
+                    analyzedAt: metrics.analyzedAt,
+                    versionInScore: metrics.version,
+                    score: metrics.score,
                     packageInfoFromScore: {
-                        name: collected.metadata.name,
-                        version: collected.metadata.version,
-                        description: collected.metadata.description || null,
+                        name: metrics.packageName,
+                        version: metrics.version,
+                        description: metrics.description,
                     },
                     npmStats: {
-                        downloadsLastMonth: lastMonthDownloads,
-                        starsCount: collected.npm.starsCount,
+                        downloadsLastMonth: metrics.downloadsLastMonth,
+                        starsCount: metrics.github.hasGitHubData ? metrics.github.starsCount : 0, // Fallback best effort
                     },
-                    githubStats: collected.github
+                    githubStats: metrics.github.hasGitHubData
                         ? {
-                            starsCount: collected.github.starsCount,
-                            forksCount: collected.github.forksCount,
-                            subscribersCount: collected.github.subscribersCount,
+                            starsCount: metrics.github.starsCount,
+                            forksCount: metrics.github.forksCount,
+                            subscribersCount: metrics.github.subscribersCount,
                             issues: {
-                                count: collected.github.issues.count,
-                                openCount: collected.github.issues.openCount,
+                                count: metrics.github.openIssuesCount, // Heuristic default count = open issues
+                                openCount: metrics.github.openIssuesCount,
                             },
                         }
                         : null,
+                    scorecard: metrics.scorecard,
                 };
-                const ttl = !collected.metadata.version.match(/^\d+\.\d+\.\d+$/)
-                    ? CACHE_TTL_SHORT
-                    : CACHE_TTL_LONG;
-                cacheSet(cacheKey, scoreData, ttl);
+                cacheSet(cacheKey, scoreData, CACHE_TTL_LONG);
                 return {
                     packageInput: pkgInput,
                     packageName: name,
                     status: 'success',
                     error: null,
                     data: scoreData,
-                    message: `Successfully fetched score data for ${name} (version analyzed: ${collected.metadata.version}).`,
+                    message: `Successfully fetched score data for ${name} (version analyzed: ${metrics.version}).`,
                 };
             }
             catch (error) {
@@ -2190,6 +2204,27 @@ export async function handleNpmScore(args) {
         };
     }
 }
+export async function fetchReadmeFromCDN(packageName, version) {
+    const cdnUrls = [
+        `https://cdn.jsdelivr.net/npm/${packageName}@${version}/README.md`,
+        `https://unpkg.com/${packageName}@${version}/README.md`,
+    ];
+    for (const cdnUrl of cdnUrls) {
+        try {
+            const response = await fetchWithRetry(cdnUrl, { headers: { Accept: 'text/plain' } }, { maxRetries: 1, skipThrottle: true });
+            if (response.ok) {
+                const text = await response.text();
+                if (text && text.length > 10) {
+                    return text;
+                }
+            }
+        }
+        catch {
+            // Sigue intentando con la próxima URL
+        }
+    }
+    return null;
+}
 export async function handleNpmPackageReadme(args) {
     try {
         const packagesToProcess = args.packages || [];
@@ -2259,7 +2294,7 @@ export async function handleNpmPackageReadme(args) {
                 };
             }
             try {
-                const response = await fetch(`${NPM_REGISTRY_URL}/${name}`);
+                const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}`);
                 if (!response.ok) {
                     let errorMsg = `Failed to fetch package info: ${response.status} ${response.statusText}`;
                     if (response.status === 404) {
@@ -2288,7 +2323,7 @@ export async function handleNpmPackageReadme(args) {
                     };
                 }
                 const versionToUse = versionTag === 'latest' ? packageInfo['dist-tags']?.latest : versionTag;
-                if (!versionToUse || !packageInfo.versions || !packageInfo.versions[versionToUse]) {
+                if (!versionToUse || !packageInfo.versions?.[versionToUse]) {
                     return {
                         packageInput: pkgInput,
                         packageName: name,
@@ -2301,11 +2336,19 @@ export async function handleNpmPackageReadme(args) {
                 }
                 const versionData = packageInfo.versions[versionToUse];
                 // README can be in version-specific data or at the root of packageInfo
-                const readmeContent = versionData.readme || packageInfo.readme || null;
+                let readmeContent = versionData.readme || packageInfo.readme || null;
+                let readmeSource = readmeContent ? 'registry' : null;
+                if (!readmeContent && versionToUse) {
+                    readmeContent = await fetchReadmeFromCDN(name, versionToUse);
+                    if (readmeContent) {
+                        readmeSource = 'cdn';
+                    }
+                }
                 const hasReadme = !!readmeContent;
                 const readmeResultData = {
                     readme: readmeContent,
                     hasReadme: hasReadme,
+                    readmeSource: readmeSource,
                     versionFetched: versionToUse, // Store the actually fetched version
                 };
                 cacheSet(cacheKey, readmeResultData, CACHE_TTL_LONG);
@@ -2316,7 +2359,7 @@ export async function handleNpmPackageReadme(args) {
                     versionFetched: versionToUse,
                     status: 'success',
                     error: null,
-                    data: { readme: readmeContent, hasReadme: hasReadme }, // Return only readme and hasReadme in data field for consistency
+                    data: { readme: readmeContent, hasReadme: hasReadme, readmeSource: readmeSource }, // Return only readme and hasReadme in data field for consistency
                     message: `Successfully fetched README for ${name}@${versionToUse}.`,
                 };
             }
@@ -2370,7 +2413,7 @@ export async function handleNpmSearch(args) {
                 message: `Search results for query '${query}' with limit ${limit} from cache.`,
             };
         }
-        const response = await fetch(`${NPM_REGISTRY_URL}/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`);
+        const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`);
         if (!response.ok) {
             throw new Error(`Failed to search packages: ${response.status} ${response.statusText}`);
         }
@@ -2508,7 +2551,7 @@ export async function handleNpmLicenseCompatibility(args) {
                 };
             }
             try {
-                const response = await fetch(`${NPM_REGISTRY_URL}/${name}/${versionTag}`);
+                const response = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}/${versionTag}`);
                 if (!response.ok) {
                     let errorMsg = `Failed to fetch package info: ${response.status} ${response.statusText}`;
                     if (response.status === 404) {
@@ -2683,7 +2726,7 @@ export async function handleNpmRepoStats(args) {
                 };
             }
             try {
-                const npmResponse = await fetch(`${NPM_REGISTRY_URL}/${name}/latest`);
+                const npmResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}/latest`);
                 if (!npmResponse.ok) {
                     const errorData = {
                         packageInput: pkgInput,
@@ -2735,44 +2778,38 @@ export async function handleNpmRepoStats(args) {
                     return resultNotGitHub;
                 }
                 const [, owner, repo] = githubMatch;
-                const githubRepoApiUrl = `https://api.github.com/repos/${owner}/${repo.replace(/\.git$/, '')}`;
-                const githubResponse = await fetch(githubRepoApiUrl, {
-                    headers: {
-                        Accept: 'application/vnd.github.v3+json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
-                    },
-                });
-                if (!githubResponse.ok) {
+                const cleanRepo = repo.replace(/\.git$/, '');
+                const depsDevData = await fetchRepoStatsFromDepsDev(owner, cleanRepo, args.ignoreCache);
+                if (!depsDevData) {
                     const errorData = {
                         packageInput: pkgInput,
                         packageName: name,
                         status: 'error',
-                        error: `Failed to fetch GitHub repo stats for ${owner}/${repo}: ${githubResponse.status} ${githubResponse.statusText}`,
-                        data: { githubRepoUrl: githubRepoApiUrl },
-                        message: `Could not retrieve GitHub repository statistics from ${githubRepoApiUrl}.`,
+                        error: `Failed to fetch project stats for github.com/${owner}/${cleanRepo} from deps.dev`,
+                        data: { repositoryUrl: repoUrl },
+                        message: `Could not retrieve repository statistics from deps.dev.`,
                     };
-                    // Do not cache GitHub API call failures for now
                     return errorData;
                 }
-                const githubData = (await githubResponse.json());
                 const successResult = {
                     packageInput: pkgInput,
                     packageName: name,
                     status: 'success',
                     error: null,
                     data: {
-                        githubRepoUrl: `https://github.com/${owner}/${repo.replace(/\.git$/, '')}`,
-                        stars: githubData.stargazers_count,
-                        forks: githubData.forks_count,
-                        openIssues: githubData.open_issues_count,
-                        watchers: githubData.watchers_count,
-                        createdAt: githubData.created_at,
-                        updatedAt: githubData.updated_at,
-                        defaultBranch: githubData.default_branch,
-                        hasWiki: githubData.has_wiki,
-                        topics: githubData.topics || [],
+                        githubRepoUrl: `https://github.com/${owner}/${cleanRepo}`,
+                        stars: depsDevData.starsCount,
+                        forks: depsDevData.forksCount,
+                        openIssues: depsDevData.openIssuesCount,
+                        watchers: 0,
+                        createdAt: null,
+                        updatedAt: null,
+                        defaultBranch: null,
+                        hasWiki: null,
+                        topics: [],
+                        scorecard: depsDevData.scorecard,
                     },
-                    message: 'GitHub repository statistics fetched successfully.',
+                    message: 'Repository statistics fetched successfully from deps.dev.',
                 };
                 cacheSet(cacheKey, successResult, CACHE_TTL_LONG);
                 return successResult;
@@ -2860,7 +2897,7 @@ export async function handleNpmDeprecated(args) {
             }
             // console.debug(`[handleNpmDeprecated] Cache miss for ${cacheKey}`);
             try {
-                const mainPkgResponse = await fetch(`${NPM_REGISTRY_URL}/${name}`);
+                const mainPkgResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}`);
                 if (!mainPkgResponse.ok) {
                     return {
                         package: initialPackageNameForOutput,
@@ -2902,7 +2939,7 @@ export async function handleNpmDeprecated(args) {
                         let statusMessage = '';
                         try {
                             // console.debug(`[handleNpmDeprecated] Checking dependency: ${depName}@${depSemVer}`);
-                            const depInfoResponse = await fetch(`${NPM_REGISTRY_URL}/${encodeURIComponent(depName)}`);
+                            const depInfoResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${encodeURIComponent(depName)}`);
                             if (!depInfoResponse.ok) {
                                 statusMessage = `Could not fetch dependency info for '${depName}' (status: ${depInfoResponse.status}). Deprecation status unknown.`;
                                 // console.warn(`[handleNpmDeprecated] ${statusMessage}`);
@@ -3079,7 +3116,7 @@ export async function handleNpmChangelogAnalysis(args) {
                 };
             }
             try {
-                const npmResponse = await fetch(`${NPM_REGISTRY_URL}/${name}`);
+                const npmResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/${name}`);
                 if (!npmResponse.ok) {
                     const errorResult = {
                         packageInput: pkgInput,
@@ -3150,41 +3187,59 @@ export async function handleNpmChangelogAnalysis(args) {
                 let changelogContent = null;
                 let changelogSourceUrl = null;
                 let hasChangelogFile = false;
-                for (const file of changelogFiles) {
-                    try {
-                        const rawChangelogUrl = `https://raw.githubusercontent.com/${owner}/${repoNameForUrl}/master/${file}`;
-                        const response = await fetch(rawChangelogUrl);
-                        if (response.ok) {
-                            changelogContent = await response.text();
-                            changelogSourceUrl = rawChangelogUrl;
-                            hasChangelogFile = true;
-                            break;
+                for (const branch of ['main', 'master']) {
+                    for (const file of changelogFiles) {
+                        try {
+                            const rawChangelogUrl = `https://raw.githubusercontent.com/${owner}/${repoNameForUrl}/${branch}/${file}`;
+                            const response = await fetchWithRetry(rawChangelogUrl, {}, { maxRetries: 0 });
+                            if (response.ok) {
+                                changelogContent = await response.text();
+                                changelogSourceUrl = rawChangelogUrl;
+                                hasChangelogFile = true;
+                                break;
+                            }
+                        }
+                        catch {
+                            // Sigue intentando
                         }
                     }
-                    catch (error) {
-                        console.debug(`Error fetching changelog file ${file} for ${name}: ${error}`);
-                    }
+                    if (hasChangelogFile)
+                        break;
                 }
                 let githubReleases = [];
                 try {
-                    const githubApiResponse = await fetch(`https://api.github.com/repos/${owner}/${repoNameForUrl}/releases?per_page=5`, {
+                    const githubApiResponse = await fetchWithRetry(`https://api.github.com/repos/${owner}/${repoNameForUrl}/releases?per_page=5`, {
                         headers: {
                             Accept: 'application/vnd.github.v3+json',
-                            'User-Agent': 'NPM-Sentinel-MCP',
                         },
-                    });
+                    }, { maxRetries: 0 });
                     if (githubApiResponse.ok) {
                         const releasesData = (await githubApiResponse.json());
                         githubReleases = releasesData.map((r) => ({
                             tag_name: r.tag_name || null,
                             name: r.name || null,
                             published_at: r.published_at || null,
+                            source: 'github-api',
                         }));
                     }
                 }
                 catch (error) {
                     console.debug(`Error fetching GitHub releases for ${name}: ${error}`);
                 }
+                // Fallback to NPM Registry time/publish history if GitHub releases couldn't be fetched
+                const publishTime = npmData.time;
+                if (githubReleases.length === 0 && publishTime) {
+                    const timeKeys = Object.keys(publishTime).filter((k) => k !== 'modified' && k !== 'created');
+                    const sortedVersions = timeKeys.sort((a, b) => {
+                        return new Date(publishTime[b]).getTime() - new Date(publishTime[a]).getTime();
+                    });
+                    githubReleases = sortedVersions.slice(0, 5).map((v) => ({
+                        tag_name: `v${v}`,
+                        name: `Release ${v} (NPM Publish)`,
+                        published_at: publishTime[v],
+                        source: 'npm-registry',
+                    }));
+                }
                 const versions = Object.keys(npmData.versions || {});
                 const npmVersionHistory = {
                     totalVersions: versions.length,
@@ -3198,7 +3253,7 @@ export async function handleNpmChangelogAnalysis(args) {
                         ? `No changelog file or GitHub releases found for ${name}.`
                         : `Changelog analysis for ${name}.`;
                 const resultToCache = {
-                    packageInput: pkgInput, // This might differ on subsequent cache hits, so store the original reference for this specific cache entry
+                    packageInput: pkgInput,
                     packageName: name,
                     versionQueried: versionQueried,
                     status: status,
@@ -3250,20 +3305,45 @@ export async function handleNpmChangelogAnalysis(args) {
         };
     }
 }
+function isAlternativeCandidate(candidateName, candidateDesc, originalName) {
+    const lowerCandidate = candidateName.toLowerCase();
+    const lowerOriginal = originalName.toLowerCase();
+    const lowerDesc = (candidateDesc || '').toLowerCase();
+    if (lowerCandidate === lowerOriginal)
+        return false;
+    if (lowerCandidate.startsWith('@types/'))
+        return false;
+    if (lowerCandidate.startsWith(`${lowerOriginal}-`) ||
+        lowerCandidate.startsWith(`${lowerOriginal}_`) ||
+        lowerCandidate.startsWith(`${lowerOriginal}.`) ||
+        lowerCandidate.endsWith(`-${lowerOriginal}`) ||
+        lowerCandidate.endsWith(`_${lowerOriginal}`) ||
+        lowerCandidate.includes(lowerOriginal)) {
+        return false;
+    }
+    if (lowerDesc.includes(`middleware for ${lowerOriginal}`) ||
+        lowerDesc.includes(`plugin for ${lowerOriginal}`) ||
+        lowerDesc.includes(`adapter for ${lowerOriginal}`) ||
+        lowerDesc.includes(`wrapper for ${lowerOriginal}`) ||
+        lowerDesc.includes(`extension for ${lowerOriginal}`) ||
+        lowerDesc.includes(`${lowerOriginal} middleware`) ||
+        lowerDesc.includes(`${lowerOriginal} plugin`)) {
+        return false;
+    }
+    return true;
+}
 export async function handleNpmAlternatives(args) {
     try {
         const packagesToProcess = args.packages || [];
         if (packagesToProcess.length === 0) {
-            throw new Error('No package names provided to find alternatives.');
+            return createEmptyArrayErrorResponse('npmAlternatives');
         }
         const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
             let originalPackageName = '';
-            let versionQueried;
             if (typeof pkgInput === 'string') {
                 const atIdx = pkgInput.lastIndexOf('@');
                 if (atIdx > 0) {
                     originalPackageName = pkgInput.slice(0, atIdx);
-                    versionQueried = pkgInput.slice(atIdx + 1);
                 }
                 else {
                     originalPackageName = pkgInput;
@@ -3300,35 +3380,34 @@ export async function handleNpmAlternatives(args) {
                 };
             }
             const cacheKey = generateCacheKey('handleNpmAlternatives', originalPackageName);
-            const cachedResult = args.ignoreCache ? undefined : cacheGet(cacheKey); // Expects the full result object
+            const cachedResult = args.ignoreCache ? undefined : cacheGet(cacheKey);
             if (cachedResult) {
                 return {
                     ...cachedResult,
-                    packageInput: pkgInput, // current input context
-                    packageName: originalPackageName, // current name context
-                    // versionQueried is part of cachedResult.data or similar if stored, or add if needed
+                    packageInput: pkgInput,
+                    packageName: originalPackageName,
                     status: `${cachedResult.status}_cache`,
                     message: `${cachedResult.message} (from cache)`,
                 };
             }
             try {
-                const searchResponse = await fetch(`${NPM_REGISTRY_URL}/-/v1/search?text=keywords:${encodeURIComponent(originalPackageName)}&size=10`);
-                if (!searchResponse.ok) {
-                    const errorResult = {
-                        packageInput: pkgInput,
-                        packageName: originalPackageName,
-                        status: 'error',
-                        error: `Failed to search for alternatives: ${searchResponse.status} ${searchResponse.statusText}`,
-                        data: null,
-                        message: 'Could not perform search for alternatives.',
-                    };
-                    return errorResult; // Do not cache API errors for search
-                }
-                const searchData = (await searchResponse.json());
-                const alternativePackagesRaw = searchData.objects || [];
+                let originalPackageKeywords = [];
                 let originalPackageDownloads = 0;
                 try {
-                    const dlResponse = await fetch(`https://api.npmjs.org/downloads/point/last-month/${originalPackageName}`);
+                    const initSearchResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/-/v1/search?text=keywords:${encodeURIComponent(originalPackageName)}&size=5`);
+                    if (initSearchResponse.ok) {
+                        const initSearchData = (await initSearchResponse.json());
+                        const match = (initSearchData.objects || []).find((p) => p.package.name === originalPackageName);
+                        if (match?.package?.keywords) {
+                            originalPackageKeywords = match.package.keywords;
+                        }
+                    }
+                }
+                catch {
+                    // Optional keyword retrieval failure
+                }
+                try {
+                    const dlResponse = await fetchWithRetry(`https://api.npmjs.org/downloads/point/last-month/${originalPackageName}`);
                     if (dlResponse.ok) {
                         originalPackageDownloads =
                             (await dlResponse.json()).downloads || 0;
@@ -3337,34 +3416,80 @@ export async function handleNpmAlternatives(args) {
                 catch (e) {
                     console.debug(`Failed to fetch downloads for original package ${originalPackageName}: ${e}`);
                 }
-                const originalPackageKeywords = alternativePackagesRaw.find((p) => p.package.name === originalPackageName)?.package
-                    .keywords || [];
                 const originalPackageStats = {
                     name: originalPackageName,
                     monthlyDownloads: originalPackageDownloads,
                     keywords: originalPackageKeywords,
                 };
-                if (alternativePackagesRaw.length === 0 ||
-                    (alternativePackagesRaw.length === 1 &&
-                        alternativePackagesRaw[0].package.name === originalPackageName)) {
+                const genericKeywords = originalPackageKeywords.filter((kw) => kw.toLowerCase() !== originalPackageName.toLowerCase() &&
+                    !kw.toLowerCase().includes(originalPackageName.toLowerCase()) &&
+                    kw.length > 2);
+                const domainKeywords = genericKeywords.filter((kw) => ![
+                    'mobile',
+                    'ionic',
+                    'component',
+                    'components',
+                    'ui',
+                    'css',
+                    'react',
+                    'vue',
+                    'angular',
+                    'stencil',
+                    'storybook',
+                    'icon',
+                    'icons',
+                ].includes(kw.toLowerCase()));
+                const selectedKeywords = domainKeywords.length > 0 ? domainKeywords : genericKeywords;
+                let searchQuery = originalPackageName;
+                if (selectedKeywords.length >= 2) {
+                    searchQuery = selectedKeywords.slice(0, 3).join(' ');
+                }
+                else if (selectedKeywords.length === 1) {
+                    searchQuery = selectedKeywords[0];
+                }
+                const searchResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/-/v1/search?text=${encodeURIComponent(searchQuery)}&size=30`);
+                if (!searchResponse.ok) {
+                    const errorResult = {
+                        packageInput: pkgInput,
+                        packageName: originalPackageName,
+                        status: 'error',
+                        error: `Failed to search for alternatives: ${searchResponse.status} ${searchResponse.statusText}`,
+                        data: null,
+                        message: 'Could not perform search for alternatives.',
+                    };
+                    return errorResult;
+                }
+                const searchData = (await searchResponse.json());
+                const alternativePackagesRaw = searchData.objects || [];
+                let validAlternativesRaw = alternativePackagesRaw.filter((alt) => isAlternativeCandidate(alt.package.name, alt.package.description || '', originalPackageName));
+                if (validAlternativesRaw.length === 0 && searchQuery !== originalPackageName) {
+                    try {
+                        const fallbackResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/-/v1/search?text=${encodeURIComponent(originalPackageName)}&size=30`);
+                        if (fallbackResponse.ok) {
+                            const fallbackData = (await fallbackResponse.json());
+                            validAlternativesRaw = (fallbackData.objects || []).filter((alt) => isAlternativeCandidate(alt.package.name, alt.package.description || '', originalPackageName));
+                        }
+                    }
+                    catch {
+                        // Fallback failure
+                    }
+                }
+                if (validAlternativesRaw.length === 0) {
                     const resultNoAlternatives = {
                         packageInput: pkgInput,
                         packageName: originalPackageName,
                         status: 'no_alternatives_found',
                         error: null,
                         data: { originalPackageStats, alternatives: [] },
-                        message: `No significant alternatives found for ${originalPackageName} based on keyword search.`,
+                        message: `No significant alternatives found for ${originalPackageName} based on search.`,
                     };
                     cacheSet(cacheKey, resultNoAlternatives, CACHE_TTL_MEDIUM);
                     return resultNoAlternatives;
                 }
-                const alternativesData = await Promise.all(alternativePackagesRaw
-                    .filter((alt) => alt.package.name !== originalPackageName)
-                    .slice(0, 5)
-                    .map(async (alt) => {
+                const alternativesData = await Promise.all(validAlternativesRaw.slice(0, 5).map(async (alt) => {
                     let altDownloads = 0;
                     try {
-                        const altDlResponse = await fetch(`https://api.npmjs.org/downloads/point/last-month/${alt.package.name}`);
+                        const altDlResponse = await fetchWithRetry(`https://api.npmjs.org/downloads/point/last-month/${alt.package.name}`);
                         if (altDlResponse.ok) {
                             altDownloads = (await altDlResponse.json()).downloads || 0;
                         }
@@ -3427,430 +3552,8 @@ export async function handleNpmAlternatives(args) {
         };
     }
 }
-// Get __dirname in an ES module environment
-// Define session configuration schema
-export const configSchema = z.object({
-    NPM_REGISTRY_URL: z.string().optional().describe('URL of the NPM registry to use'),
-});
-// Create server function for Smithery CLI
-export default function createServer({ config }) {
-    // Apply config overrides
-    if (config.NPM_REGISTRY_URL) {
-        NPM_REGISTRY_URL = config.NPM_REGISTRY_URL.replace(/\/$/, '');
-    }
-    // Handle both ESM and CJS environments
-    let __filename;
-    let __dirname;
-    try {
-        __filename = fileURLToPath(import.meta.url);
-        __dirname = path.dirname(__filename);
-    }
-    catch (error) {
-        // Fallback for CJS environment (Smithery HTTP build)
-        __filename = process.argv[1] || '.';
-        __dirname = path.dirname(__filename);
-    }
-    // Determine package root
-    let packageRoot = __dirname;
-    if (fs.existsSync(path.join(__dirname, 'package.json'))) {
-        packageRoot = __dirname;
-    }
-    else if (fs.existsSync(path.join(__dirname, '..', 'package.json'))) {
-        packageRoot = path.join(__dirname, '..');
-    }
-    // Read version from package.json
-    let serverVersion = '1.0.0';
-    try {
-        const packageJsonPath = path.join(packageRoot, 'package.json');
-        if (fs.existsSync(packageJsonPath)) {
-            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-            serverVersion = packageJson.version;
-        }
-    }
-    catch (error) {
-        console.error('Error reading package.json version:', error);
-    }
-    // Create server instance
-    const server = new McpServer({
-        name: 'npm-sentinel-mcp',
-        version: serverVersion,
-    });
-    // Update paths to be relative to the package
-    const README_PATH = path.join(packageRoot, 'README.md');
-    const LLMS_FULL_TEXT_PATH = path.join(packageRoot, 'llms-full.txt');
-    // Register README.md resource
-    server.registerResource('serverReadme', 'doc://server/readme', {
-        description: 'Main documentation and usage guide for this NPM Info Server.',
-        mimeType: 'text/markdown',
-    }, async (uri) => {
-        try {
-            const readmeContent = fs.readFileSync(README_PATH, 'utf-8');
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        text: readmeContent,
-                        mimeType: 'text/markdown',
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            console.error(`Error reading README.md for resource ${uri.href}:`, error.message);
-            throw {
-                code: -32002,
-                message: `Resource not found or unreadable: ${uri.href}`,
-                data: { uri: uri.href, cause: error.message },
-            };
-        }
-    });
-    // Register llms-full.txt resource (MCP Specification)
-    server.registerResource('mcpSpecification', 'doc://mcp/specification', {
-        description: 'The llms-full.txt content providing a comprehensive overview of the Model Context Protocol.',
-        mimeType: 'text/plain',
-    }, async (uri) => {
-        try {
-            const specContent = fs.readFileSync(LLMS_FULL_TEXT_PATH, 'utf-8');
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        text: specContent,
-                        mimeType: 'text/plain',
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            console.error(`Error reading llms-full.txt for resource ${uri.href}:`, error.message);
-            throw {
-                code: -32002,
-                message: `Resource not found or unreadable: ${uri.href}`,
-                data: { uri: uri.href, cause: error.message },
-            };
-        }
-    });
-    // Register prompts
-    server.registerPrompt('analyze-package', {
-        description: 'Analyze an NPM package for security and quality',
-        argsSchema: {
-            package: z.string().describe('Name of the npm package to analyze'),
-        },
-    }, ({ package: pkgName }) => ({
-        messages: [
-            {
-                role: 'user',
-                content: {
-                    type: 'text',
-                    text: `Please analyze the npm package "${pkgName}". Check for vulnerabilities, maintenance status, and recent issues. Use the available tools to gather information.`,
-                },
-            },
-        ],
-    }));
-    // Add NPM tools - Ensuring each tool registration is complete and correct
-    server.registerTool('npmVersions', {
-        description: 'Get all available versions of an NPM package',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get versions for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get All Package Versions',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmVersions(args);
-    });
-    server.registerTool('npmLatest', {
-        description: 'Get the latest version and changelog of an NPM package',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get latest versions for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get Latest Package Information',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true, // Result for 'latest' tag can change, but call itself is idempotent
-        },
-    }, async (args) => {
-        return await handleNpmLatest(args);
-    });
-    server.registerTool('npmDeps', {
-        description: 'Analyze dependencies and devDependencies of an NPM package',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to analyze dependencies for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get Package Dependencies',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmDeps(args);
-    });
-    server.registerTool('npmTypes', {
-        description: 'Check TypeScript types availability and version for a package',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to check types for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Check TypeScript Type Availability',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmTypes(args);
-    });
-    server.registerTool('npmSize', {
-        description: 'Get package size information including dependencies and bundle size',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get size information for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get Package Size (Bundlephobia)',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmSize(args);
-    });
-    server.registerTool('npmVulnerabilities', {
-        description: 'Check for known vulnerabilities in packages',
-        inputSchema: {
-            packages: z
-                .array(z.string())
-                .describe('List of package names to check for vulnerabilities'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Check Package Vulnerabilities (OSV.dev)',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: false, // Vulnerability data can change frequently
-        },
-    }, async (args) => {
-        return await handleNpmVulnerabilities(args);
-    });
-    server.registerTool('npmTrends', {
-        description: 'Get download trends and popularity metrics for packages',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get trends for'),
-            period: z
-                .enum(['last-week', 'last-month', 'last-year'])
-                .describe('Time period for trends. Options: "last-week", "last-month", "last-year"')
-                .optional()
-                .default('last-month'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get NPM Package Download Trends',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true, // Trends for a fixed past period are idempotent
-        },
-    }, async (args) => {
-        return await handleNpmTrends(args);
-    });
-    server.registerTool('npmCompare', {
-        description: 'Compare multiple NPM packages based on various metrics',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to compare'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Compare NPM Packages',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmCompare(args);
-    });
-    server.registerTool('npmMaintainers', {
-        description: 'Get maintainers information for NPM packages',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get maintainers for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get NPM Package Maintainers',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmMaintainers(args);
-    });
-    server.registerTool('npmScore', {
-        description: 'Get consolidated package score based on quality, maintenance, and popularity metrics',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get scores for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get NPM Package Score (NPMS.io)',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true, // Score for a version is stable, for 'latest' can change
-        },
-    }, async (args) => {
-        return await handleNpmScore(args);
-    });
-    server.registerTool('npmPackageReadme', {
-        description: 'Get the README content for NPM packages',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get READMEs for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get NPM Package README',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmPackageReadme(args);
-    });
-    server.registerTool('npmSearch', {
-        description: 'Search for NPM packages with optional limit',
-        inputSchema: {
-            query: z.string().describe('Search query for packages'),
-            limit: z
-                .number()
-                .min(1)
-                .max(50)
-                .optional()
-                .describe('Maximum number of results to return (default: 10)'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Search NPM Packages',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: false, // Search results can change
-        },
-    }, async (args) => {
-        return await handleNpmSearch(args);
-    });
-    server.registerTool('npmLicenseCompatibility', {
-        description: 'Check license compatibility between multiple packages',
-        inputSchema: {
-            packages: z
-                .array(z.string())
-                .min(1)
-                .describe('List of package names to check for license compatibility'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Check NPM License Compatibility',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmLicenseCompatibility(args);
-    });
-    server.registerTool('npmRepoStats', {
-        description: 'Get repository statistics for NPM packages',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to get repository stats for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Get NPM Package Repository Stats (GitHub)',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true, // Stats for a repo at a point in time, though they change over time
-        },
-    }, async (args) => {
-        return await handleNpmRepoStats(args);
-    });
-    server.registerTool('npmDeprecated', {
-        description: 'Check if packages are deprecated',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to check for deprecation'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Check NPM Package Deprecation Status',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true, // Deprecation status is generally stable for a version
-        },
-    }, async (args) => {
-        return await handleNpmDeprecated(args);
-    });
-    server.registerTool('npmChangelogAnalysis', {
-        description: 'Analyze changelog and release history of packages',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to analyze changelogs for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Analyze NPM Package Changelog (GitHub)',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true,
-        },
-    }, async (args) => {
-        return await handleNpmChangelogAnalysis(args);
-    });
-    server.registerTool('npmAlternatives', {
-        description: 'Find alternative packages with similar functionality',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to find alternatives for'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Find NPM Package Alternatives',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: false, // Search-based, results can change
-        },
-    }, async (args) => {
-        return await handleNpmAlternatives(args);
-    });
-    server.registerTool('npmQuality', {
-        description: 'Analyze package quality metrics',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to analyze'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Analyze NPM Package Quality (NPMS.io)',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true, // Score for a version is stable, for 'latest' can change
-        },
-    }, async (args) => {
-        return await handleNpmQuality(args);
-    });
-    server.registerTool('npmMaintenance', {
-        description: 'Analyze package maintenance metrics',
-        inputSchema: {
-            packages: z.array(z.string()).describe('List of package names to analyze'),
-            ignoreCache: z.boolean().optional().describe('Force a fresh lookup, ignoring the cache'),
-        },
-        annotations: {
-            title: 'Analyze NPM Package Maintenance (NPMS.io)',
-            readOnlyHint: true,
-            openWorldHint: true,
-            idempotentHint: true, // Score for a version is stable, for 'latest' can change
-        },
-    }, async (args) => {
-        return await handleNpmMaintenance(args);
-    });
-    return server.server;
-}
+export { createServer };
+export default createServer;
 // STDIO compatibility for backward compatibility
 async function main() {
     // Create server with empty configuration
@@ -3884,7 +3587,7 @@ function isNpmPackageVersionData(data) {
         }
         return result.success;
     }
-    catch (e) {
+    catch {
         // This catch block might not be strictly necessary with safeParse but kept for safety
         // console.error("isNpmPackageVersionData validation failed unexpectedly:", e);
         return false;