@nekzus/mcp-server 1.18.1 → 1.19.0-alpha.1

package/dist/index.js

@@ -10,7 +10,6 @@ import { z } from 'zod';
 // Cache configuration
 let NPM_REGISTRY_URL = (process.env.NPM_REGISTRY_URL || 'https://registry.npmjs.org').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 +72,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 +240,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 +278,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' &&
@@ -391,12 +394,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,
@@ -527,12 +525,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 +659,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 +785,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 +807,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 +914,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 +994,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 [];
@@ -1046,9 +1017,7 @@ async function fetchTransitiveDependenciesFromDepsDev(pkgName, version) {
 // 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 +1038,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 +1185,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 +1337,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 +1494,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 +1505,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 +1520,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 +1585,119 @@ 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 (optional, graceful degradation)
+    let github = {
+        starsCount: 0,
+        forksCount: 0,
+        subscribersCount: 0,
+        openIssuesCount: 0,
+        hasGitHubData: false,
+    };
+    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 ghResponse = await fetchWithRetry(`https://api.github.com/repos/${owner}/${cleanRepo}`, {}, { maxRetries: 0 });
+                if (ghResponse.ok) {
+                    const ghData = await ghResponse.json();
+                    github = {
+                        starsCount: ghData.stargazers_count || 0,
+                        forksCount: ghData.forks_count || 0,
+                        subscribersCount: ghData.subscribers_count || 0,
+                        openIssuesCount: ghData.open_issues_count || 0,
+                        hasGitHubData: true,
+                    };
+                }
+            }
+            catch (ghError) {
+                console.debug(`Could not fetch GitHub 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,
+            },
+        },
+    };
+    cacheSet(cacheKey, result, CACHE_TTL_LONG);
+    return result;
+}
 // Function to get package quality metrics
 export async function handleNpmQuality(args) {
     try {
@@ -1634,7 +1709,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 +1754,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 +1800,7 @@ export async function handleNpmQuality(args) {
         };
     }
 }
+// Function to get package maintenance metrics
 export async function handleNpmMaintenance(args) {
     try {
         const packagesToProcess = args.packages || [];
@@ -1817,55 +1856,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 +2029,7 @@ export async function handleNpmMaintainers(args) {
         };
     }
 }
+// Function to get package score
 export async function handleNpmScore(args) {
     try {
         const packagesToProcess = args.packages || [];
@@ -2078,86 +2083,40 @@ 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,
                 };
-                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 +2149,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 +2239,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) {
@@ -2301,11 +2281,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 +2304,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 +2358,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 +2496,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 +2671,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,
@@ -2736,10 +2724,9 @@ export async function handleNpmRepoStats(args) {
                 }
                 const [, owner, repo] = githubMatch;
                 const githubRepoApiUrl = `https://api.github.com/repos/${owner}/${repo.replace(/\.git$/, '')}`;
-                const githubResponse = await fetch(githubRepoApiUrl, {
+                const githubResponse = await fetchWithRetry(githubRepoApiUrl, {
                     headers: {
                         Accept: 'application/vnd.github.v3+json',
-                        'User-Agent': 'NPM-Sentinel-MCP',
                     },
                 });
                 if (!githubResponse.ok) {
@@ -2860,7 +2847,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 +2889,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 +3066,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,
@@ -3153,7 +3140,7 @@ export async function handleNpmChangelogAnalysis(args) {
                 for (const file of changelogFiles) {
                     try {
                         const rawChangelogUrl = `https://raw.githubusercontent.com/${owner}/${repoNameForUrl}/master/${file}`;
-                        const response = await fetch(rawChangelogUrl);
+                        const response = await fetchWithRetry(rawChangelogUrl);
                         if (response.ok) {
                             changelogContent = await response.text();
                             changelogSourceUrl = rawChangelogUrl;
@@ -3167,10 +3154,9 @@ export async function handleNpmChangelogAnalysis(args) {
                 }
                 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',
                         },
                     });
                     if (githubApiResponse.ok) {
@@ -3258,12 +3244,10 @@ export async function handleNpmAlternatives(args) {
         }
         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;
@@ -3312,7 +3296,7 @@ export async function handleNpmAlternatives(args) {
                 };
             }
             try {
-                const searchResponse = await fetch(`${NPM_REGISTRY_URL}/-/v1/search?text=keywords:${encodeURIComponent(originalPackageName)}&size=10`);
+                const searchResponse = await fetchWithRetry(`${NPM_REGISTRY_URL}/-/v1/search?text=keywords:${encodeURIComponent(originalPackageName)}&size=10`);
                 if (!searchResponse.ok) {
                     const errorResult = {
                         packageInput: pkgInput,
@@ -3328,7 +3312,7 @@ export async function handleNpmAlternatives(args) {
                 const alternativePackagesRaw = searchData.objects || [];
                 let originalPackageDownloads = 0;
                 try {
-                    const dlResponse = await fetch(`https://api.npmjs.org/downloads/point/last-month/${originalPackageName}`);
+                    const dlResponse = await fetchWithRetry(`https://api.npmjs.org/downloads/point/last-month/${originalPackageName}`);
                     if (dlResponse.ok) {
                         originalPackageDownloads =
                             (await dlResponse.json()).downloads || 0;
@@ -3364,7 +3348,7 @@ export async function handleNpmAlternatives(args) {
                     .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;
                         }
@@ -3445,7 +3429,7 @@ export default function createServer({ config }) {
         __filename = fileURLToPath(import.meta.url);
         __dirname = path.dirname(__filename);
     }
-    catch (error) {
+    catch {
         // Fallback for CJS environment (Smithery HTTP build)
         __filename = process.argv[1] || '.';
         __dirname = path.dirname(__filename);
@@ -3884,7 +3868,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;