@nekzus/mcp-server 1.5.6 → 1.6.1

package/dist/index.js

@@ -3,6 +3,41 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import fetch from 'node-fetch';
 import { z } from 'zod';
+// 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
+const MAX_CACHE_SIZE = 500; // Max number of items in cache
+const apiCache = new Map();
+function generateCacheKey(toolName, ...args) {
+    // Simple key generation, ensure consistent order and stringification of args
+    return `${toolName}:${args.map((arg) => String(arg)).join(':')}`;
+}
+function cacheGet(key) {
+    const entry = apiCache.get(key);
+    if (entry && entry.expiresAt > Date.now()) {
+        return entry.data;
+    }
+    if (entry && entry.expiresAt <= Date.now()) {
+        apiCache.delete(key); // Remove stale entry
+    }
+    return undefined;
+}
+function cacheSet(key, value, ttlMilliseconds) {
+    if (ttlMilliseconds <= 0)
+        return; // Do not cache if TTL is zero or negative
+    const expiresAt = Date.now() + ttlMilliseconds;
+    apiCache.set(key, { data: value, expiresAt });
+    // Basic FIFO eviction strategy if cache exceeds max size
+    if (apiCache.size > MAX_CACHE_SIZE) {
+        // To make it FIFO, we need to ensure Map iteration order is insertion order (which it is)
+        const oldestKey = apiCache.keys().next().value;
+        if (oldestKey) {
+            apiCache.delete(oldestKey);
+        }
+    }
+}
 // Zod schemas for npm package data
 export const NpmMaintainerSchema = z
     .object({
@@ -16,7 +51,18 @@ export const NpmPackageVersionSchema = z
     name: z.string(),
     version: z.string(),
     description: z.string().optional(),
-    author: z.union([z.string(), z.object({}).passthrough()]).optional(),
+    author: z
+        .union([
+        z.string(),
+        z
+            .object({
+            name: z.string().optional(),
+            email: z.string().optional(),
+            url: z.string().optional(),
+        })
+            .passthrough(),
+    ])
+        .optional(),
     license: z.string().optional(),
     repository: z
         .object({
@@ -32,6 +78,15 @@ export const NpmPackageVersionSchema = z
         .passthrough()
         .optional(),
     homepage: z.string().optional(),
+    dependencies: z.record(z.string()).optional(),
+    devDependencies: z.record(z.string()).optional(),
+    peerDependencies: z.record(z.string()).optional(),
+    types: z.string().optional(),
+    typings: z.string().optional(),
+    dist: z
+        .object({ shasum: z.string().optional(), tarball: z.string().optional() })
+        .passthrough()
+        .optional(),
 })
     .passthrough();
 export const NpmPackageInfoSchema = z
@@ -79,31 +134,9 @@ export const NpmDownloadsDataSchema = z.object({
     end: z.string(),
     package: z.string(),
 });
-// Schemas for NPM quality, maintenance and popularity metrics
-export const NpmQualitySchema = z.object({
-    score: z.number(),
-    tests: z.number(),
-    coverage: z.number(),
-    linting: z.number(),
-    types: z.number(),
-});
-export const NpmMaintenanceSchema = z.object({
-    score: z.number(),
-    issuesResolutionTime: z.number(),
-    commitsFrequency: z.number(),
-    releaseFrequency: z.number(),
-    lastUpdate: z.string(),
-});
-export const NpmPopularitySchema = z.object({
-    score: z.number(),
-    stars: z.number(),
-    downloads: z.number(),
-    dependents: z.number(),
-    communityInterest: z.number(),
-});
 function isValidNpmsResponse(data) {
     if (typeof data !== 'object' || data === null) {
-        console.debug('Response is not an object or is null');
+        console.debug('NpmsApiResponse validation: Response is not an object or is null');
         return false;
     }
     const response = data;
@@ -114,7 +147,7 @@ function isValidNpmsResponse(data) {
         typeof response.score.final !== 'number' ||
         !('detail' in response.score) ||
         typeof response.score.detail !== 'object') {
-        console.debug('Invalid score structure');
+        console.debug('NpmsApiResponse validation: Invalid score structure');
         return false;
     }
     // Check score detail metrics
@@ -122,7 +155,7 @@ function isValidNpmsResponse(data) {
     if (typeof detail.quality !== 'number' ||
         typeof detail.popularity !== 'number' ||
         typeof detail.maintenance !== 'number') {
-        console.debug('Invalid score detail metrics');
+        console.debug('NpmsApiResponse validation: Invalid score detail metrics');
         return false;
     }
     // Check collected data structure
@@ -132,7 +165,7 @@ function isValidNpmsResponse(data) {
         typeof response.collected.metadata !== 'object' ||
         typeof response.collected.metadata.name !== 'string' ||
         typeof response.collected.metadata.version !== 'string') {
-        console.debug('Invalid collected data structure');
+        console.debug('NpmsApiResponse validation: Invalid collected data structure');
         return false;
     }
     // Check npm data
@@ -140,7 +173,7 @@ function isValidNpmsResponse(data) {
         typeof response.collected.npm !== 'object' ||
         !Array.isArray(response.collected.npm.downloads) ||
         typeof response.collected.npm.starsCount !== 'number') {
-        console.debug('Invalid npm data structure');
+        console.debug('NpmsApiResponse validation: Invalid npm data structure');
         return false;
     }
     // Optional github data check
@@ -153,7 +186,7 @@ function isValidNpmsResponse(data) {
             typeof response.collected.github.issues !== 'object' ||
             typeof response.collected.github.issues.count !== 'number' ||
             typeof response.collected.github.issues.openCount !== 'number') {
-            console.debug('Invalid github data structure');
+            console.debug('NpmsApiResponse validation: Invalid github data structure');
             return false;
         }
     }
@@ -170,6 +203,7 @@ export const NpmSearchResultSchema = z
             publisher: z
                 .object({
                 username: z.string(),
+                email: z.string().optional(),
             })
                 .optional(),
             links: z
@@ -177,8 +211,10 @@ export const NpmSearchResultSchema = z
                 npm: z.string().optional(),
                 homepage: z.string().optional(),
                 repository: z.string().optional(),
+                bugs: z.string().optional(),
             })
                 .optional(),
+            date: z.string().optional(),
         }),
         score: z.object({
             final: z.number(),
@@ -190,7 +226,7 @@ export const NpmSearchResultSchema = z
         }),
         searchScore: z.number(),
     })),
-    total: z.number(),
+    total: z.number(), // total is a sibling of objects
 })
     .passthrough();
 // Logger function that uses stderr - only for critical errors
@@ -202,253 +238,6 @@ const log = (...args) => {
         console.error(...args);
     }
 };
-// Define tools
-const TOOLS = [
-    // NPM Package Analysis Tools
-    {
-        name: 'npmVersions',
-        description: 'Get all available versions of an NPM package',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z.array(z.string()).describe('List of package names to get versions for'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmLatest',
-        description: 'Get the latest version and changelog of an NPM package',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z.array(z.string()).describe('List of package names to get latest versions for'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmDeps',
-        description: 'Analyze dependencies and devDependencies of an NPM package',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z.array(z.string()).describe('List of package names to analyze dependencies for'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmTypes',
-        description: 'Check TypeScript types availability and version for a package',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z.array(z.string()).describe('List of package names to check types for'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmSize',
-        description: 'Get package size information including dependencies and bundle size',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z.array(z.string()).describe('List of package names to get size information for'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmVulnerabilities',
-        description: 'Check for known vulnerabilities in packages',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z
-                    .array(z.string())
-                    .describe('List of package names to check for vulnerabilities'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmTrends',
-        description: 'Get download trends and popularity metrics for packages. Available periods: "last-week" (7 days), "last-month" (30 days), or "last-year" (365 days)',
-        parameters: z.object({
-            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'),
-        }),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packages: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'List of package names to get trends for',
-                },
-                period: {
-                    type: 'string',
-                    enum: ['last-week', 'last-month', 'last-year'],
-                    description: 'Time period for trends. Options: "last-week" (7 days), "last-month" (30 days), or "last-year" (365 days)',
-                    default: 'last-month',
-                },
-            },
-            required: ['packages'],
-        },
-    },
-    {
-        name: 'npmCompare',
-        description: 'Compare multiple NPM packages based on various metrics',
-        parameters: z.object({
-            packages: z.array(z.string()).describe('List of package names to compare'),
-        }),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packages: {
-                    type: 'array',
-                    items: { type: 'string' },
-                },
-            },
-            required: ['packages'],
-        },
-    },
-    {
-        name: 'npmMaintainers',
-        description: 'Get maintainers for an NPM package',
-        parameters: z.object({
-            packageName: z.string().describe('The name of the package'),
-        }),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-            },
-            required: ['packageName'],
-        },
-    },
-    {
-        name: 'npmScore',
-        description: 'Get consolidated package score based on quality, maintenance, and popularity metrics',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z.array(z.string()).describe('List of package names to get scores for'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmPackageReadme',
-        description: 'Get the README for an NPM package',
-        parameters: z.union([
-            z.object({
-                packageName: z.string().describe('The name of the package'),
-            }),
-            z.object({
-                packages: z.array(z.string()).describe('List of package names to get READMEs for'),
-            }),
-        ]),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                packageName: { type: 'string' },
-                packages: { type: 'array', items: { type: 'string' } },
-            },
-            oneOf: [{ required: ['packageName'] }, { required: ['packages'] }],
-        },
-    },
-    {
-        name: 'npmSearch',
-        description: 'Search for NPM packages',
-        parameters: z.object({
-            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)'),
-        }),
-        inputSchema: {
-            type: 'object',
-            properties: {
-                query: { type: 'string' },
-                limit: { type: 'number', minimum: 1, maximum: 50 },
-            },
-            required: ['query'],
-        },
-    },
-];
 // Type guards for API responses
 function isNpmPackageInfo(data) {
     return (typeof data === 'object' &&
@@ -488,850 +277,1855 @@ function isNpmDownloadsData(data) {
     }
 }
 export async function handleNpmVersions(args) {
-    const results = await Promise.all(args.packages.map(async (pkg) => {
-        try {
-            const response = await fetch(`https://registry.npmjs.org/${pkg}`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            });
-            if (!response.ok) {
-                throw new Error(`Failed to fetch package info: ${response.statusText}`);
-            }
-            const data = await response.json();
-            if (!isNpmPackageInfo(data)) {
-                throw new Error('Invalid package info format');
-            }
-            const versions = Object.keys(data.versions);
-            const latestVersion = data['dist-tags']?.latest;
-            return {
-                name: pkg,
-                versions,
-                latest: latestVersion,
-                success: true,
-            };
-        }
-        catch (error) {
-            return {
-                name: pkg,
-                error: error instanceof Error ? error.message : 'Unknown error',
-                success: false,
-            };
-        }
-    }));
-    const content = results.map((result) => ({
-        type: 'text',
-        text: result.success
-            ? `📦 ${result.name}:
-Latest version: ${result.latest}
-Available versions: ${result.versions.join(', ')}`
-            : `❌ Error fetching ${result.name}: ${result.error}`,
-    }));
-    return { content, isError: false };
-}
-export async function handleNpmLatest(args) {
-    const results = await Promise.all(args.packages.map(async (pkg) => {
-        try {
-            const response = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            });
-            if (!response.ok) {
-                throw new Error(`Failed to fetch latest version: ${response.statusText}`);
-            }
-            const data = await response.json();
-            const latestInfo = data;
-            return {
-                name: pkg,
-                version: latestInfo.version,
-                description: latestInfo.description,
-                author: latestInfo.author?.name,
-                license: latestInfo.license,
-                homepage: latestInfo.homepage,
-                success: true,
-            };
-        }
-        catch (err) {
-            return {
-                name: pkg,
-                error: err instanceof Error ? err.message : 'Unknown error',
-                success: false,
-            };
-        }
-    }));
-    const content = results.map((result) => ({
-        type: 'text',
-        text: result.success
-            ? `📦 Latest version of ${result.name}:
-Version: ${result.version}
-Description: ${result.description || 'No description available'}
-Author: ${result.author || 'Unknown'}
-License: ${result.license || 'Unknown'}
-Homepage: ${result.homepage || 'Not specified'}
----`
-            : `❌ Error fetching latest version for ${result.name}: ${result.error}`,
-    }));
-    return { content, isError: false };
-}
-export async function handleNpmDeps(args) {
     try {
         const packagesToProcess = args.packages || [];
         if (packagesToProcess.length === 0) {
             throw new Error('No package names provided');
         }
-        const results = await Promise.all(packagesToProcess.map(async (pkg) => {
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                }
+                else {
+                    name = pkgInput;
+                }
+            }
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                    message: 'Package name could not be determined from input.',
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmVersions', name);
+            const cachedData = cacheGet(cacheKey); // Using any for the diverse structure from this endpoint
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Successfully fetched versions for ${name} from cache.`,
+                };
+            }
             try {
-                const response = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+                const response = await fetch(`https://registry.npmjs.org/${name}`, {
                     headers: {
                         Accept: 'application/json',
                         'User-Agent': 'NPM-Sentinel-MCP',
                     },
                 });
                 if (!response.ok) {
-                    return { name: pkg, error: `Failed to fetch package info: ${response.statusText}` };
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: `Failed to fetch package info: ${response.status} ${response.statusText}`,
+                        data: null,
+                        message: `Could not retrieve information for package ${name}.`,
+                    };
                 }
-                const rawData = await response.json();
-                if (!isNpmPackageData(rawData)) {
-                    return { name: pkg, error: 'Invalid package data received' };
+                const data = await response.json();
+                if (!isNpmPackageInfo(data)) {
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: 'Invalid package info format received from registry',
+                        data: null,
+                        message: `Received malformed data for package ${name}.`,
+                    };
                 }
+                const allVersions = Object.keys(data.versions || {});
+                const tags = data['dist-tags'] || {};
+                const latestVersionTag = tags.latest || null;
+                const resultData = {
+                    allVersions,
+                    tags,
+                    latestVersionTag,
+                };
+                cacheSet(cacheKey, resultData, CACHE_TTL_MEDIUM);
                 return {
-                    name: pkg,
-                    version: rawData.version,
-                    dependencies: rawData.dependencies ?? {},
-                    devDependencies: rawData.devDependencies ?? {},
-                    peerDependencies: rawData.peerDependencies ?? {},
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success',
+                    error: null,
+                    data: resultData,
+                    message: `Successfully fetched versions for ${name}.`,
                 };
             }
             catch (error) {
-                return { name: pkg, error: error instanceof Error ? error.message : 'Unknown error' };
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing ${name}.`,
+                };
             }
         }));
-        let text = '';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
-                continue;
-            }
-            text += `📦 Dependencies for ${result.name}@${result.version}\n\n`;
-            if (Object.keys(result.dependencies).length > 0) {
-                text += 'Dependencies:\n';
-                for (const [dep, version] of Object.entries(result.dependencies)) {
-                    text += `• ${dep}: ${version}\n`;
-                }
-                text += '\n';
-            }
-            if (Object.keys(result.devDependencies).length > 0) {
-                text += 'Dev Dependencies:\n';
-                for (const [dep, version] of Object.entries(result.devDependencies)) {
-                    text += `• ${dep}: ${version}\n`;
-                }
-                text += '\n';
-            }
-            if (Object.keys(result.peerDependencies).length > 0) {
-                text += 'Peer Dependencies:\n';
-                for (const [dep, version] of Object.entries(result.peerDependencies)) {
-                    text += `• ${dep}: ${version}\n`;
-                }
-                text += '\n';
-            }
-            text += '---\n\n';
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+        const responseJson = JSON.stringify({ results: processedResults }, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            results: [],
+            error: `General error fetching versions: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching dependencies: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-export async function handleNpmTypes(args) {
+export async function handleNpmLatest(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            });
-            if (!response.ok) {
-                throw new Error(`Failed to fetch package info: ${response.statusText}`);
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let versionTag = 'latest'; // Default to 'latest'
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    versionTag = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                }
             }
-            const data = (await response.json());
-            let text = `📦 TypeScript support for ${pkg}@${data.version}\n`;
-            const hasTypes = Boolean(data.types || data.typings);
-            if (hasTypes) {
-                text += '✅ Package includes built-in TypeScript types\n';
-                text += `Types path: ${data.types || data.typings}\n`;
-            }
-            const typesPackage = `@types/${pkg.replace('@', '').replace('/', '__')}`;
-            const typesResponse = await fetch(`https://registry.npmjs.org/${typesPackage}/latest`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            }).catch(() => null);
-            if (typesResponse?.ok) {
-                const typesData = (await typesResponse.json());
-                text += `📦 DefinitelyTyped package available: ${typesPackage}@${typesData.version}\n`;
-                text += `Install with: npm install -D ${typesPackage}`;
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    versionQueried: versionTag,
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    versionQueried: versionTag,
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                    message: 'Package name could not be determined from input.',
+                };
             }
-            else if (!hasTypes) {
-                text += '❌ No TypeScript type definitions found';
+            const cacheKey = generateCacheKey('handleNpmLatest', name, versionTag);
+            const cachedData = cacheGet(cacheKey); // Using any for the diverse structure from this endpoint
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Successfully fetched details for ${name}@${versionTag} from cache.`,
+                };
             }
-            return { name: pkg, text };
-        }));
-        let text = '';
-        for (const result of results) {
-            text += `${result.text}\n\n`;
-            if (results.indexOf(result) < results.length - 1) {
-                text += '---\n\n';
+            try {
+                const response = await fetch(`https://registry.npmjs.org/${name}/${versionTag}`, {
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': 'NPM-Sentinel-MCP',
+                    },
+                });
+                if (!response.ok) {
+                    let errorMsg = `Failed to fetch package version: ${response.status} ${response.statusText}`;
+                    if (response.status === 404) {
+                        errorMsg = `Package ${name}@${versionTag} not found.`;
+                    }
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionTag,
+                        status: 'error',
+                        error: errorMsg,
+                        data: null,
+                        message: `Could not retrieve version ${versionTag} for package ${name}.`,
+                    };
+                }
+                const data = await response.json();
+                if (!isNpmPackageVersionData(data)) {
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionTag,
+                        status: 'error',
+                        error: 'Invalid package data format received for version',
+                        data: null,
+                        message: `Received malformed data for ${name}@${versionTag}.`,
+                    };
+                }
+                const versionData = {
+                    name: data.name,
+                    version: data.version,
+                    description: data.description || null,
+                    author: (typeof data.author === 'string' ? data.author : data.author?.name) || null,
+                    license: data.license || null,
+                    homepage: data.homepage || null,
+                    repositoryUrl: data.repository?.url || null,
+                    bugsUrl: data.bugs?.url || null,
+                    dependenciesCount: Object.keys(data.dependencies || {}).length,
+                    devDependenciesCount: Object.keys(data.devDependencies || {}).length,
+                    peerDependenciesCount: Object.keys(data.peerDependencies || {}).length,
+                    dist: data.dist || null,
+                    types: data.types || data.typings || null,
+                };
+                cacheSet(cacheKey, versionData, CACHE_TTL_MEDIUM);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    status: 'success',
+                    error: null,
+                    data: versionData,
+                    message: `Successfully fetched details for ${data.name}@${data.version}.`,
+                };
             }
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing ${pkgInput}.`,
+                };
+            }
+        }));
+        const responseJson = JSON.stringify({ results: processedResults }, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            results: [],
+            error: `General error fetching latest package information: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                { type: 'text', text: `Error checking TypeScript types: ${error.message}` },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-export async function handleNpmSize(args) {
+export async function handleNpmDeps(args) {
     try {
         const packagesToProcess = args.packages || [];
         if (packagesToProcess.length === 0) {
             throw new Error('No package names provided');
         }
-        const results = await Promise.all(packagesToProcess.map(async (pkg) => {
-            const response = await fetch(`https://bundlephobia.com/api/size?package=${pkg}`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            });
-            if (!response.ok) {
-                return { name: pkg, error: `Failed to fetch package size: ${response.statusText}` };
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let version = 'latest'; // Default to 'latest'
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    version = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                }
+            }
+            else {
+                return {
+                    package: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
             }
-            const rawData = await response.json();
-            if (!isBundlephobiaData(rawData)) {
-                return { name: pkg, error: 'Invalid response from bundlephobia' };
+            const packageNameForOutput = version === 'latest' ? name : `${name}@${version}`;
+            // Note: The cache key should ideally use the *resolved* version if 'latest' is input.
+            // However, to get the resolved version, we need an API call. For simplicity in this step,
+            // we'll cache based on the input version string. This means 'latest' will be cached as 'latest'.
+            // A more advanced caching would fetch resolved version first if 'latest' is given.
+            const cacheKey = generateCacheKey('handleNpmDeps', name, version);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    package: cachedData.packageNameForCache || packageNameForOutput, // Use cached name if available
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData.depData,
+                    message: `Dependencies for ${cachedData.packageNameForCache || packageNameForOutput} from cache.`,
+                };
             }
-            return {
-                name: pkg,
-                sizeInKb: Number((rawData.size / 1024).toFixed(2)),
-                gzipInKb: Number((rawData.gzip / 1024).toFixed(2)),
-                dependencyCount: rawData.dependencyCount,
-            };
-        }));
-        let text = '';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
+            try {
+                const response = await fetch(`https://registry.npmjs.org/${name}/${version}`, {
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': 'NPM-Sentinel-MCP',
+                    },
+                });
+                if (!response.ok) {
+                    return {
+                        package: packageNameForOutput,
+                        status: 'error',
+                        error: `Failed to fetch package info: ${response.status} ${response.statusText}`,
+                        data: null,
+                        message: `Could not retrieve information for ${packageNameForOutput}.`,
+                    };
+                }
+                const rawData = await response.json();
+                if (!isNpmPackageData(rawData)) {
+                    return {
+                        package: packageNameForOutput,
+                        status: 'error',
+                        error: 'Invalid package data received from registry',
+                        data: null,
+                        message: `Received malformed data for ${packageNameForOutput}.`,
+                    };
+                }
+                const mapDeps = (deps) => {
+                    if (!deps)
+                        return [];
+                    return Object.entries(deps).map(([depName, depVersion]) => ({
+                        name: depName,
+                        version: depVersion,
+                    }));
+                };
+                const depData = {
+                    dependencies: mapDeps(rawData.dependencies),
+                    devDependencies: mapDeps(rawData.devDependencies),
+                    peerDependencies: mapDeps(rawData.peerDependencies),
+                };
+                const actualVersion = rawData.version || version; // Use version from response if available
+                const finalPackageName = `${name}@${actualVersion}`;
+                // Store with the actual resolved package name if 'latest' was used
+                cacheSet(cacheKey, { depData, packageNameForCache: finalPackageName }, CACHE_TTL_MEDIUM);
+                return {
+                    package: finalPackageName,
+                    status: 'success',
+                    error: null,
+                    data: depData,
+                    message: `Dependencies for ${finalPackageName}`,
+                };
             }
-            else {
-                text += `📦 ${result.name}\n`;
-                text += `Size: ${result.sizeInKb}KB (gzipped: ${result.gzipInKb}KB)\n`;
-                text += `Dependencies: ${result.dependencyCount}\n\n`;
+            catch (error) {
+                return {
+                    package: packageNameForOutput,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing ${packageNameForOutput}.`,
+                };
             }
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+        }));
+        const responseJson = JSON.stringify({ results: processedResults }, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            results: [],
+            error: `General error fetching dependencies: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching package sizes: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-export async function handleNpmVulnerabilities(args) {
+export async function handleNpmTypes(args) {
     try {
         const packagesToProcess = args.packages || [];
         if (packagesToProcess.length === 0) {
             throw new Error('No package names provided');
         }
-        const results = await Promise.all(packagesToProcess.map(async (pkg) => {
-            const response = await fetch('https://api.osv.dev/v1/query', {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify({
-                    package: {
-                        name: pkg,
-                        ecosystem: 'npm',
-                    },
-                }),
-            });
-            if (!response.ok) {
-                return { name: pkg, error: `Failed to fetch vulnerability info: ${response.statusText}` };
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let version = 'latest'; // Default to 'latest'
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    version = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                }
             }
-            const data = (await response.json());
-            return { name: pkg, vulns: data.vulns || [] };
-        }));
-        let text = '🔒 Security Analysis\n\n';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
-                continue;
+            else {
+                return {
+                    package: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
             }
-            text += `📦 ${result.name}\n`;
-            if (result.vulns.length === 0) {
-                text += '✅ No known vulnerabilities\n\n';
+            const packageNameForOutput = version === 'latest' ? name : `${name}@${version}`;
+            // As with handleNpmDeps, we cache based on the input version string for simplicity.
+            const cacheKey = generateCacheKey('handleNpmTypes', name, version);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    package: cachedData.finalPackageName || packageNameForOutput,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData.typesData,
+                    message: `TypeScript information for ${cachedData.finalPackageName || packageNameForOutput} from cache.`,
+                };
             }
-            else {
-                text += `⚠️ Found ${result.vulns.length} vulnerabilities:\n\n`;
-                for (const vuln of result.vulns) {
-                    text += `- ${vuln.summary}\n`;
-                    const severity = typeof vuln.severity === 'object'
-                        ? vuln.severity.type || 'Unknown'
-                        : vuln.severity || 'Unknown';
-                    text += `  Severity: ${severity}\n`;
-                    if (vuln.references && vuln.references.length > 0) {
-                        text += `  More info: ${vuln.references[0].url}\n`;
+            try {
+                const response = await fetch(`https://registry.npmjs.org/${name}/${version}`, {
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': 'NPM-Sentinel-MCP',
+                    },
+                });
+                if (!response.ok) {
+                    return {
+                        package: packageNameForOutput,
+                        status: 'error',
+                        error: `Failed to fetch package info: ${response.status} ${response.statusText}`,
+                        data: null,
+                        message: `Could not retrieve information for ${packageNameForOutput}.`,
+                    };
+                }
+                const mainPackageData = (await response.json());
+                const actualVersion = mainPackageData.version || version; // Use version from response
+                const finalPackageName = `${name}@${actualVersion}`;
+                const hasBuiltInTypes = Boolean(mainPackageData.types || mainPackageData.typings);
+                const typesPath = mainPackageData.types || mainPackageData.typings || null;
+                const typesPackageName = `@types/${name.replace('@', '').replace('/', '__')}`;
+                let typesPackageInfo = {
+                    name: typesPackageName,
+                    version: null,
+                    isAvailable: false,
+                };
+                try {
+                    const typesResponse = await fetch(`https://registry.npmjs.org/${typesPackageName}/latest`, {
+                        headers: {
+                            Accept: 'application/json',
+                            'User-Agent': 'NPM-Sentinel-MCP',
+                        },
+                    });
+                    if (typesResponse.ok) {
+                        const typesData = (await typesResponse.json());
+                        typesPackageInfo = {
+                            name: typesPackageName,
+                            version: typesData.version || 'unknown',
+                            isAvailable: true,
+                        };
                     }
-                    text += '\n';
                 }
-            }
-            text += '---\n\n';
-        }
-        return { content: [{ type: 'text', text }], isError: false };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error checking vulnerabilities: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-}
-export async function handleNpmTrends(args) {
-    try {
-        // Si period es undefined, vacío o inválido, usar el valor por defecto
-        const period = args.period && ['last-week', 'last-month', 'last-year'].includes(args.period)
-            ? args.period
-            : 'last-month';
-        const periodDays = {
-            'last-week': 7,
-            'last-month': 30,
-            'last-year': 365,
-        };
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://api.npmjs.org/downloads/point/${period}/${pkg}`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            });
-            if (!response.ok) {
+                catch (typesError) {
+                    // Keep this debug for visibility on @types fetch failures
+                    console.debug(`Could not fetch @types package ${typesPackageName}: ${typesError}`);
+                }
+                const resultData = {
+                    mainPackage: {
+                        name: name,
+                        version: actualVersion,
+                        hasBuiltInTypes: hasBuiltInTypes,
+                        typesPath: typesPath,
+                    },
+                    typesPackage: typesPackageInfo,
+                };
+                cacheSet(cacheKey, { typesData: resultData, finalPackageName }, CACHE_TTL_LONG);
                 return {
-                    name: pkg,
-                    error: `Failed to fetch download trends: ${response.statusText}`,
-                    success: false,
+                    package: finalPackageName,
+                    status: 'success',
+                    error: null,
+                    data: resultData,
+                    message: `TypeScript information for ${finalPackageName}`,
                 };
             }
-            const data = await response.json();
-            if (!isNpmDownloadsData(data)) {
+            catch (error) {
                 return {
-                    name: pkg,
-                    error: 'Invalid response format from npm downloads API',
-                    success: false,
+                    package: packageNameForOutput,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing ${packageNameForOutput}.`,
                 };
             }
-            return {
-                name: pkg,
-                downloads: data.downloads,
-                success: true,
-            };
         }));
-        let text = '📈 Download Trends\n\n';
-        text += `Period: ${period} (${periodDays[period]} days)\n\n`;
-        // Individual package stats
-        for (const result of results) {
-            if (!result.success) {
-                text += `❌ ${result.name}: ${result.error}\n`;
-                continue;
-            }
-            text += `📦 ${result.name}\n`;
-            text += `Total downloads: ${result.downloads.toLocaleString()}\n`;
-            text += `Average daily downloads: ${Math.round(result.downloads / periodDays[period]).toLocaleString()}\n\n`;
-        }
-        // Total stats
-        const totalDownloads = results.reduce((total, result) => {
-            if (result.success) {
-                return total + result.downloads;
-            }
-            return total;
-        }, 0);
-        text += `Total downloads across all packages: ${totalDownloads.toLocaleString()}\n`;
-        text += `Average daily downloads across all packages: ${Math.round(totalDownloads / periodDays[period]).toLocaleString()}\n`;
-        return { content: [{ type: 'text', text }], isError: false };
+        const responseJson = JSON.stringify({ results: processedResults }, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            results: [],
+            error: `General error checking TypeScript types: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                { type: 'text', text: `Error fetching download trends: ${error.message}` },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-export async function handleNpmCompare(args) {
+export async function handleNpmSize(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const [infoRes, downloadsRes] = await Promise.all([
-                fetch(`https://registry.npmjs.org/${pkg}/latest`),
-                fetch(`https://api.npmjs.org/downloads/point/last-month/${pkg}`),
-            ]);
-            if (!infoRes.ok || !downloadsRes.ok) {
-                throw new Error(`Failed to fetch data for ${pkg}`);
-            }
-            const info = await infoRes.json();
-            const downloads = await downloadsRes.json();
-            if (!isNpmPackageData(info) || !isNpmDownloadsData(downloads)) {
-                throw new Error(`Invalid response format for ${pkg}`);
-            }
-            return {
-                name: pkg,
-                version: info.version,
-                description: info.description,
-                downloads: downloads.downloads,
-                license: info.license,
-                dependencies: Object.keys(info.dependencies || {}).length,
-            };
-        }));
-        let text = '📊 Package Comparison\n\n';
-        // Table header
-        text += 'Package | Version | Monthly Downloads | Dependencies | License\n';
-        text += '--------|---------|------------------|--------------|--------\n';
-        // Table rows
-        for (const pkg of results) {
-            text += `${pkg.name} | ${pkg.version} | ${pkg.downloads.toLocaleString()} | ${pkg.dependencies} | ${pkg.license || 'N/A'}\n`;
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided');
         }
-        return { content: [{ type: 'text', text }], isError: false };
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let version = 'latest'; // Default to 'latest'
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    version = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                }
+            }
+            else {
+                return {
+                    package: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            const bundlephobiaQuery = version === 'latest' ? name : `${name}@${version}`;
+            const packageNameForOutput = bundlephobiaQuery;
+            const cacheKey = generateCacheKey('handleNpmSize', bundlephobiaQuery);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    package: packageNameForOutput, // Or cachedData.packageName if stored
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Size information for ${packageNameForOutput} from cache.`,
+                };
+            }
+            try {
+                const response = await fetch(`https://bundlephobia.com/api/size?package=${bundlephobiaQuery}`, {
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': 'NPM-Sentinel-MCP',
+                    },
+                });
+                if (!response.ok) {
+                    let errorMsg = `Failed to fetch package size: ${response.status} ${response.statusText}`;
+                    if (response.status === 404) {
+                        errorMsg = `Package ${packageNameForOutput} not found or version not available on Bundlephobia.`;
+                    }
+                    return {
+                        package: packageNameForOutput,
+                        status: 'error',
+                        error: errorMsg,
+                        data: null,
+                        message: `Could not retrieve size information for ${packageNameForOutput}.`,
+                    };
+                }
+                const rawData = await response.json();
+                if (rawData.error) {
+                    return {
+                        package: packageNameForOutput,
+                        status: 'error',
+                        error: `Bundlephobia error: ${rawData.error.message || 'Unknown error'}`,
+                        data: null,
+                        message: `Bundlephobia reported an error for ${packageNameForOutput}.`,
+                    };
+                }
+                if (!isBundlephobiaData(rawData)) {
+                    return {
+                        package: packageNameForOutput,
+                        status: 'error',
+                        error: 'Invalid package data received from Bundlephobia',
+                        data: null,
+                        message: `Received malformed size data for ${packageNameForOutput}.`,
+                    };
+                }
+                const typedRawData = rawData;
+                const sizeData = {
+                    name: typedRawData.name || name,
+                    version: typedRawData.version || (version === 'latest' ? 'latest_resolved' : version),
+                    sizeInKb: Number((typedRawData.size / 1024).toFixed(2)),
+                    gzipInKb: Number((typedRawData.gzip / 1024).toFixed(2)),
+                    dependencyCount: typedRawData.dependencyCount,
+                };
+                cacheSet(cacheKey, sizeData, CACHE_TTL_MEDIUM);
+                return {
+                    package: packageNameForOutput,
+                    status: 'success',
+                    error: null,
+                    data: sizeData,
+                    message: `Size information for ${packageNameForOutput}`,
+                };
+            }
+            catch (error) {
+                return {
+                    package: packageNameForOutput,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing ${packageNameForOutput}.`,
+                };
+            }
+        }));
+        const responseJson = JSON.stringify({ results: processedResults }, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            results: [],
+            error: `General error fetching package sizes: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [{ type: 'text', text: `Error comparing packages: ${error.message}` }],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-// Function to get package quality metrics
-export async function handleNpmQuality(args) {
+export async function handleNpmVulnerabilities(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://api.npms.io/v2/package/${encodeURIComponent(pkg)}`, {
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let version = undefined;
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    version = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                }
+            }
+            else if (typeof pkgInput === 'object' && pkgInput !== null) {
+                name = pkgInput.name;
+                version = pkgInput.version;
+            }
+            const packageNameForOutput = version ? `${name}@${version}` : name;
+            const cacheKey = generateCacheKey('handleNpmVulnerabilities', name, version || 'all');
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    package: packageNameForOutput,
+                    versionQueried: version || null,
+                    status: 'success_cache',
+                    vulnerabilities: cachedData.vulnerabilities,
+                    message: `${cachedData.message} (from cache)`,
+                };
+            }
+            const osvBody = {
+                package: {
+                    name,
+                    ecosystem: 'npm',
+                },
+            };
+            if (version) {
+                osvBody.version = version;
+            }
+            const response = await fetch('https://api.osv.dev/v1/query', {
+                method: 'POST',
                 headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
+                    'Content-Type': 'application/json',
                 },
+                body: JSON.stringify(osvBody),
             });
+            const queryVersionSpecified = !!version;
             if (!response.ok) {
-                return { name: pkg, error: `Failed to fetch quality data: ${response.statusText}` };
+                const errorResult = {
+                    package: packageNameForOutput,
+                    versionQueried: version || null,
+                    status: 'error',
+                    error: `OSV API Error: ${response.statusText}`,
+                    vulnerabilities: [],
+                };
+                // Do not cache error responses from OSV API as they might be temporary
+                return errorResult;
             }
-            const rawData = await response.json();
-            if (!isValidNpmsResponse(rawData)) {
-                return { name: pkg, error: 'Invalid response format from npms.io API' };
+            const data = (await response.json());
+            const vulns = data.vulns || [];
+            let message;
+            if (vulns.length === 0) {
+                message = `No known vulnerabilities found${queryVersionSpecified ? ' for the specified version' : ''}.`;
             }
-            const quality = rawData.score.detail.quality;
+            else {
+                message = `${vulns.length} vulnerability(ies) found${queryVersionSpecified ? ' for the specified version' : ''}.`;
+            }
+            const processedVulns = vulns.map((vuln) => {
+                const sev = typeof vuln.severity === 'object'
+                    ? vuln.severity.type || 'Unknown'
+                    : vuln.severity || 'Unknown';
+                const refs = vuln.references ? vuln.references.map((r) => r.url) : [];
+                const affectedRanges = [];
+                const affectedVersionsListed = [];
+                const vulnerabilityDetails = {
+                    summary: vuln.summary,
+                    severity: sev,
+                    references: refs,
+                };
+                if (vuln.affected && vuln.affected.length > 0) {
+                    const lifecycle = {};
+                    const firstAffectedEvents = vuln.affected[0]?.ranges?.[0]?.events;
+                    if (firstAffectedEvents) {
+                        const introducedEvent = firstAffectedEvents.find((e) => e.introduced);
+                        const fixedEvent = firstAffectedEvents.find((e) => e.fixed);
+                        if (introducedEvent?.introduced)
+                            lifecycle.introduced = introducedEvent.introduced;
+                        if (fixedEvent?.fixed)
+                            lifecycle.fixed = fixedEvent.fixed;
+                    }
+                    if (Object.keys(lifecycle).length > 0) {
+                        vulnerabilityDetails.lifecycle = lifecycle;
+                        if (queryVersionSpecified && version && lifecycle.fixed) {
+                            const queriedParts = version.split('.').map(Number);
+                            const fixedParts = lifecycle.fixed.split('.').map(Number);
+                            let isFixedDecision = false;
+                            const maxLength = Math.max(queriedParts.length, fixedParts.length);
+                            for (let i = 0; i < maxLength; i++) {
+                                const qp = queriedParts[i] || 0;
+                                const fp = fixedParts[i] || 0;
+                                if (fp < qp) {
+                                    isFixedDecision = true;
+                                    break;
+                                }
+                                if (fp > qp) {
+                                    isFixedDecision = false;
+                                    break;
+                                }
+                                if (i === maxLength - 1) {
+                                    isFixedDecision = fixedParts.length <= queriedParts.length;
+                                }
+                            }
+                            vulnerabilityDetails.isFixedInQueriedVersion = isFixedDecision;
+                        }
+                    }
+                }
+                if (!queryVersionSpecified && vuln.affected) {
+                    for (const aff of vuln.affected) {
+                        if (aff.ranges) {
+                            for (const range of aff.ranges) {
+                                affectedRanges.push({ type: range.type, events: range.events });
+                            }
+                        }
+                        if (aff.versions && aff.versions.length > 0) {
+                            affectedVersionsListed.push(...aff.versions);
+                        }
+                    }
+                    if (affectedRanges.length > 0) {
+                        vulnerabilityDetails.affectedRanges = affectedRanges;
+                    }
+                    if (affectedVersionsListed.length > 0) {
+                        vulnerabilityDetails.affectedVersionsListed = affectedVersionsListed;
+                    }
+                }
+                return vulnerabilityDetails;
+            });
+            const resultToCache = {
+                vulnerabilities: processedVulns,
+                message: message,
+            };
+            cacheSet(cacheKey, resultToCache, CACHE_TTL_MEDIUM);
             return {
-                name: pkg,
-                ...NpmQualitySchema.parse({
-                    score: Math.round(quality * 100) / 100,
-                    tests: 0, // These values are no longer available in the API
-                    coverage: 0,
-                    linting: 0,
-                    types: 0,
-                }),
+                package: packageNameForOutput,
+                versionQueried: version || null,
+                status: 'success',
+                vulnerabilities: processedVulns,
+                message: message,
             };
         }));
-        let text = '📊 Quality Metrics\n\n';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
-                continue;
-            }
-            text += `📦 ${result.name}\n`;
-            text += `- Overall Score: ${result.score}\n`;
-            text +=
-                '- Note: Detailed metrics (tests, coverage, linting, types) are no longer provided by the API\n\n';
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+        const responseJson = JSON.stringify({ results: processedResults }, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            results: [],
+            error: `General error checking vulnerabilities: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching quality metrics: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-export async function handleNpmMaintenance(args) {
+export async function handleNpmTrends(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://api.npms.io/v2/package/${encodeURIComponent(pkg)}`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            });
-            if (!response.ok) {
-                return { name: pkg, error: `Failed to fetch maintenance data: ${response.statusText}` };
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided for trends analysis.');
+        }
+        const period = args.period && ['last-week', 'last-month', 'last-year'].includes(args.period)
+            ? args.period
+            : 'last-month';
+        const periodDaysMap = {
+            'last-week': 7,
+            'last-month': 30,
+            'last-year': 365,
+        };
+        const daysInPeriod = periodDaysMap[period];
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                name = atIdx > 0 ? pkgInput.slice(0, atIdx) : pkgInput;
             }
-            const rawData = await response.json();
-            if (!isValidNpmsResponse(rawData)) {
-                return { name: pkg, error: 'Invalid response format from npms.io API' };
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmTrends', name, period);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Download trends for ${name} (${period}) from cache.`,
+                };
+            }
+            try {
+                const response = await fetch(`https://api.npmjs.org/downloads/point/${period}/${name}`, {
+                    headers: {
+                        Accept: 'application/json',
+                        'User-Agent': 'NPM-Sentinel-MCP',
+                    },
+                });
+                if (!response.ok) {
+                    let errorMsg = `Failed to fetch download trends: ${response.status} ${response.statusText}`;
+                    if (response.status === 404) {
+                        errorMsg = `Package ${name} not found or no download data for the period.`;
+                    }
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: errorMsg,
+                        data: null,
+                    };
+                }
+                const data = await response.json();
+                if (!isNpmDownloadsData(data)) {
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: 'Invalid response format from npm downloads API',
+                        data: null,
+                    };
+                }
+                const trendData = {
+                    downloads: data.downloads,
+                    period: period,
+                    startDate: data.start,
+                    endDate: data.end,
+                    averageDailyDownloads: Math.round(data.downloads / daysInPeriod),
+                };
+                cacheSet(cacheKey, trendData, CACHE_TTL_MEDIUM);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success',
+                    error: null,
+                    data: trendData,
+                    message: `Successfully fetched download trends for ${name} (${period}).`,
+                };
+            }
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                };
             }
-            const maintenance = rawData.score.detail.maintenance;
-            return {
-                name: pkg,
-                score: Math.round(maintenance * 100) / 100,
-            };
         }));
-        let text = '🛠️ Maintenance Metrics\n\n';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
-                continue;
-            }
-            text += `📦 ${result.name}\n`;
-            text += `- Maintenance Score: ${result.score}\n\n`;
+        let totalSuccessful = 0;
+        let overallTotalDownloads = 0;
+        for (const result of processedResults) {
+            if (result.status === 'success' && result.data) {
+                totalSuccessful++;
+                overallTotalDownloads += result.data.downloads;
+            }
         }
-        return { content: [{ type: 'text', text }], isError: false };
+        const summary = {
+            totalPackagesProcessed: packagesToProcess.length,
+            totalSuccessful: totalSuccessful,
+            totalFailed: packagesToProcess.length - totalSuccessful,
+            overallTotalDownloads: overallTotalDownloads,
+            overallAverageDailyDownloads: totalSuccessful > 0
+                ? Math.round(overallTotalDownloads / daysInPeriod / totalSuccessful)
+                : 0,
+        };
+        const finalResponse = {
+            query: {
+                packagesInput: args.packages,
+                periodUsed: period,
+            },
+            results: processedResults,
+            summary: summary,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            query: { packagesInput: args.packages, periodUsed: args.period || 'last-month' },
+            results: [],
+            summary: null,
+            error: `General error fetching download trends: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching maintenance metrics: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-export async function handleNpmPopularity(args) {
+export async function handleNpmCompare(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://api.npms.io/v2/package/${encodeURIComponent(pkg)}`, {
-                headers: {
-                    Accept: 'application/json',
-                    'User-Agent': 'NPM-Sentinel-MCP',
-                },
-            });
-            if (!response.ok) {
-                return { name: pkg, error: `Failed to fetch popularity data: ${response.statusText}` };
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided for comparison.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let versionTag = 'latest';
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    versionTag = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                }
             }
-            const data = await response.json();
-            if (!isValidNpmsResponse(data)) {
-                return { name: pkg, error: 'Invalid API response format' };
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    versionQueried: versionTag,
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    versionQueried: versionTag,
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmCompare', name, versionTag);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name, // Or cachedData.name if preferred
+                    versionQueried: versionTag,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Comparison data for ${name}@${versionTag} from cache.`,
+                };
+            }
+            try {
+                // Fetch package version details from registry
+                const pkgResponse = await fetch(`https://registry.npmjs.org/${name}/${versionTag}`);
+                if (!pkgResponse.ok) {
+                    throw new Error(`Failed to fetch package info for ${name}@${versionTag}: ${pkgResponse.status} ${pkgResponse.statusText}`);
+                }
+                const pkgData = await pkgResponse.json();
+                if (!isNpmPackageVersionData(pkgData)) {
+                    throw new Error(`Invalid package data format for ${name}@${versionTag}`);
+                }
+                // Fetch monthly downloads
+                let monthlyDownloads = null;
+                try {
+                    const downloadsResponse = await fetch(`https://api.npmjs.org/downloads/point/last-month/${name}`);
+                    if (downloadsResponse.ok) {
+                        const downloadsData = await downloadsResponse.json();
+                        if (isNpmDownloadsData(downloadsData)) {
+                            monthlyDownloads = downloadsData.downloads;
+                        }
+                    }
+                }
+                catch (dlError) {
+                    console.debug(`Could not fetch downloads for ${name}: ${dlError}`);
+                }
+                // Fetch publish date for this specific version
+                // Need to fetch the full package info to get to the 'time' field for specific version
+                let publishDate = null;
+                try {
+                    const fullPkgInfoResponse = await fetch(`https://registry.npmjs.org/${name}`);
+                    if (fullPkgInfoResponse.ok) {
+                        const fullPkgInfo = await fullPkgInfoResponse.json();
+                        if (isNpmPackageInfo(fullPkgInfo) && fullPkgInfo.time) {
+                            publishDate = fullPkgInfo.time[pkgData.version] || null;
+                        }
+                    }
+                }
+                catch (timeError) {
+                    console.debug(`Could not fetch time info for ${name}: ${timeError}`);
+                }
+                const comparisonData = {
+                    name: pkgData.name,
+                    version: pkgData.version,
+                    description: pkgData.description || null,
+                    license: pkgData.license || null,
+                    dependenciesCount: Object.keys(pkgData.dependencies || {}).length,
+                    devDependenciesCount: Object.keys(pkgData.devDependencies || {}).length,
+                    peerDependenciesCount: Object.keys(pkgData.peerDependencies || {}).length,
+                    monthlyDownloads: monthlyDownloads,
+                    publishDate: publishDate,
+                    repositoryUrl: pkgData.repository?.url || null,
+                };
+                cacheSet(cacheKey, comparisonData, CACHE_TTL_MEDIUM);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name, // or comparisonData.name
+                    versionQueried: versionTag,
+                    status: 'success',
+                    error: null,
+                    data: comparisonData,
+                    message: `Successfully fetched comparison data for ${name}@${pkgData.version}.`,
+                };
+            }
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                };
             }
-            const popularityScore = data.score.detail.popularity;
-            return {
-                name: pkg,
-                ...NpmPopularitySchema.parse({
-                    score: Math.round(popularityScore * 100) / 100,
-                    stars: 0,
-                    downloads: 0,
-                    dependents: 0,
-                    communityInterest: 0,
-                }),
-            };
         }));
-        let text = '📈 Popularity Metrics\n\n';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
-                continue;
-            }
-            text += `📦 ${result.name}\n`;
-            text += `- Overall Score: ${result.score}\n`;
-            text += '- Note: Detailed metrics are no longer provided by the API\n\n';
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+            message: `Comparison data for ${args.packages.length} package(s).`,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error comparing packages: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching popularity metrics: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
-export async function handleNpmMaintainers(args) {
+// Function to get package quality metrics
+export async function handleNpmQuality(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkg)}`);
-            if (response.status === 404) {
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided to fetch quality metrics.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            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
+            }
+            else {
                 return {
-                    name: pkg,
-                    error: 'Package not found in the npm registry',
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
                 };
             }
-            if (!response.ok) {
-                throw new Error(`API request failed with status ${response.status} (${response.statusText})`);
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                    message: 'Package name could not be determined from input.',
+                };
             }
-            const data = await response.json();
-            if (!isNpmPackageInfo(data)) {
-                throw new Error('Invalid package info data received');
+            const cacheKey = generateCacheKey('handleNpmQuality', name);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name, // Or cachedData.packageName if stored differently
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Quality score for ${name} (version analyzed: ${cachedData.versionInScore}) from cache.`,
+                };
+            }
+            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 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.
+                };
+                const ttl = !collected.metadata.version.match(/^\d+\.\d+\.\d+$/)
+                    ? CACHE_TTL_SHORT
+                    : CACHE_TTL_LONG;
+                cacheSet(cacheKey, qualityData, ttl);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success',
+                    error: null,
+                    data: qualityData,
+                    message: `Successfully fetched quality score for ${name} (version analyzed: ${collected.metadata.version}).`,
+                };
+            }
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing quality for ${name}.`,
+                };
             }
-            return {
-                name: pkg,
-                maintainers: data.maintainers || [],
-            };
         }));
-        let text = '👥 Package Maintainers\n\n';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
-                continue;
-            }
-            text += `📦 ${result.name}\n`;
-            text += `${'-'.repeat(40)}\n`;
-            const maintainers = result.maintainers || [];
-            if (maintainers.length === 0) {
-                text += '⚠️ No maintainers found.\n';
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
+    }
+    catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error fetching quality metrics: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
+        return {
+            content: [{ type: 'text', text: errorResponse }],
+            isError: true,
+        };
+    }
+}
+export async function handleNpmMaintenance(args) {
+    try {
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided to fetch maintenance metrics.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                name = atIdx > 0 ? pkgInput.slice(0, atIdx) : pkgInput;
             }
             else {
-                text += `👥 Maintainers (${maintainers.length}):\n\n`;
-                for (const maintainer of maintainers) {
-                    text += `• ${maintainer.name}\n`;
-                    text += `  📧 ${maintainer.email}\n\n`;
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                    message: 'Package name could not be determined from input.',
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmMaintenance', name);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Maintenance score for ${name} (version analyzed: ${cachedData.versionInScore}) from cache.`,
+                };
+            }
+            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 maintenanceData = {
+                    analyzedAt: analyzedAt,
+                    versionInScore: collected.metadata.version,
+                    maintenanceScore: maintenanceScoreValue,
+                };
+                const ttl = !collected.metadata.version.match(/^\d+\.\d+\.\d+$/)
+                    ? CACHE_TTL_SHORT
+                    : CACHE_TTL_LONG;
+                cacheSet(cacheKey, maintenanceData, ttl);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success',
+                    error: null,
+                    data: maintenanceData,
+                    message: `Successfully fetched maintenance score for ${name} (version analyzed: ${collected.metadata.version}).`,
+                };
             }
-            if (results.indexOf(result) < results.length - 1) {
-                text += '\n';
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing maintenance for ${name}.`,
+                };
             }
-        }
+        }));
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
+    }
+    catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error fetching maintenance metrics: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text,
-                },
-            ],
-            isError: false,
+            content: [{ type: 'text', text: errorResponse }],
+            isError: true,
+        };
+    }
+}
+export async function handleNpmMaintainers(args) {
+    try {
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided to fetch maintainers.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                name = atIdx > 0 ? pkgInput.slice(0, atIdx) : pkgInput; // Version is ignored for maintainers
+            }
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmMaintainers', name);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Maintainer information for ${name} from cache.`,
+                };
+            }
+            try {
+                const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}`);
+                if (!response.ok) {
+                    let errorMsg = `Failed to fetch package info: ${response.status} ${response.statusText}`;
+                    if (response.status === 404) {
+                        errorMsg = `Package ${name} not found in the npm registry.`;
+                    }
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: errorMsg,
+                        data: null,
+                    };
+                }
+                const data = await response.json();
+                if (!isNpmPackageInfo(data)) {
+                    // Using NpmPackageInfoSchema as it contains maintainers
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: 'Invalid package info data received from registry',
+                        data: null,
+                    };
+                }
+                const maintainers = (data.maintainers || []).map((m) => ({
+                    name: m.name,
+                    email: m.email || null, // Ensure email is null if not present
+                    url: m.url || null, // NpmMaintainerSchema has url optional
+                }));
+                const maintainersData = {
+                    maintainers: maintainers,
+                    maintainersCount: maintainers.length,
+                };
+                cacheSet(cacheKey, maintainersData, CACHE_TTL_VERY_LONG);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success',
+                    error: null,
+                    data: maintainersData,
+                    message: `Successfully fetched maintainer information for ${name}.`,
+                };
+            }
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                };
+            }
+        }));
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+            message: `Maintainer information for ${args.packages.length} package(s).`,
         };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error fetching maintainer information: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching package maintainers: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
 export async function handleNpmScore(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://api.npms.io/v2/package/${encodeURIComponent(pkg)}`);
-            if (response.status === 404) {
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided to fetch scores.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            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
+            }
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                };
+            }
+            if (!name) {
                 return {
-                    name: pkg,
-                    error: 'Package not found in the npm registry',
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
                 };
             }
-            if (!response.ok) {
-                throw new Error(`API request failed with status ${response.status} (${response.statusText})`);
+            const cacheKey = generateCacheKey('handleNpmScore', name);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedData,
+                    message: `Score data for ${name} (version analyzed: ${cachedData.versionInScore}) from cache.`,
+                };
             }
-            const rawData = await response.json();
-            if (!isValidNpmsResponse(rawData)) {
+            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 scoreData = {
+                    analyzedAt: analyzedAt,
+                    versionInScore: collected.metadata.version,
+                    score: {
+                        final: score.final,
+                        detail: {
+                            quality: detail.quality,
+                            popularity: detail.popularity,
+                            maintenance: detail.maintenance,
+                        },
+                    },
+                    packageInfoFromScore: {
+                        name: collected.metadata.name,
+                        version: collected.metadata.version,
+                        description: collected.metadata.description || null,
+                    },
+                    npmStats: {
+                        downloadsLastMonth: lastMonthDownloads,
+                        starsCount: collected.npm.starsCount,
+                    },
+                    githubStats: collected.github
+                        ? {
+                            starsCount: collected.github.starsCount,
+                            forksCount: collected.github.forksCount,
+                            subscribersCount: collected.github.subscribersCount,
+                            issues: {
+                                count: collected.github.issues.count,
+                                openCount: collected.github.issues.openCount,
+                            },
+                        }
+                        : null,
+                };
+                const ttl = !collected.metadata.version.match(/^\d+\.\d+\.\d+$/)
+                    ? CACHE_TTL_SHORT
+                    : CACHE_TTL_LONG;
+                cacheSet(cacheKey, scoreData, ttl);
                 return {
-                    name: pkg,
-                    error: 'Invalid or incomplete response from npms.io API',
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'success',
+                    error: null,
+                    data: scoreData,
+                    message: `Successfully fetched score data for ${name} (version analyzed: ${collected.metadata.version}).`,
                 };
             }
-            const { score, collected } = rawData;
-            const { detail } = score;
-            return {
-                name: pkg,
-                score,
-                detail,
-                collected,
-            };
-        }));
-        let text = '📊 Package Scores\n\n';
-        for (const result of results) {
-            if ('error' in result) {
-                text += `❌ ${result.name}: ${result.error}\n\n`;
-                continue;
-            }
-            text += `📦 ${result.name}\n`;
-            text += `${'-'.repeat(40)}\n`;
-            text += `Overall Score: ${(result.score.final * 100).toFixed(1)}%\n\n`;
-            text += '🎯 Quality Breakdown:\n';
-            text += `• Quality: ${(result.detail.quality * 100).toFixed(1)}%\n`;
-            text += `• Maintenance: ${(result.detail.maintenance * 100).toFixed(1)}%\n`;
-            text += `• Popularity: ${(result.detail.popularity * 100).toFixed(1)}%\n\n`;
-            if (result.collected.github) {
-                text += '📈 GitHub Stats:\n';
-                text += `• Stars: ${result.collected.github.starsCount.toLocaleString()}\n`;
-                text += `• Forks: ${result.collected.github.forksCount.toLocaleString()}\n`;
-                text += `• Watchers: ${result.collected.github.subscribersCount.toLocaleString()}\n`;
-                text += `• Total Issues: ${result.collected.github.issues.count.toLocaleString()}\n`;
-                text += `• Open Issues: ${result.collected.github.issues.openCount.toLocaleString()}\n\n`;
-            }
-            if (result.collected.npm?.downloads?.length > 0) {
-                const lastDownloads = result.collected.npm.downloads[0];
-                text += '📥 NPM Downloads:\n';
-                text += `• Last day: ${lastDownloads.count.toLocaleString()} (${new Date(lastDownloads.from).toLocaleDateString()} - ${new Date(lastDownloads.to).toLocaleDateString()})\n\n`;
-            }
-            if (results.indexOf(result) < results.length - 1) {
-                text += '\n';
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                };
             }
-        }
-        // Retornar en el formato MCP estándar
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text,
-                },
-            ],
-            isError: false,
+        }));
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+            message: `Score information for ${args.packages.length} package(s).`,
         };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
-        // Manejo de errores en formato MCP estándar
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error fetching package scores: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching package scores: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
 export async function handleNpmPackageReadme(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://registry.npmjs.org/${pkg}`);
-            if (!response.ok) {
-                throw new Error(`Failed to fetch package info: ${response.statusText}`);
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided to fetch READMEs.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let versionTag = undefined; // Explicitly undefined if not specified
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    versionTag = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                    versionTag = 'latest'; // Default to latest if no version specified
+                }
             }
-            const rawData = await response.json();
-            if (!isNpmPackageInfo(rawData)) {
-                throw new Error('Invalid package info data received');
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    versionQueried: versionTag,
+                    versionFetched: null,
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                };
             }
-            const latestVersion = rawData['dist-tags']?.latest;
-            if (!latestVersion || !rawData.versions?.[latestVersion]) {
-                throw new Error('No latest version found');
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    versionQueried: versionTag,
+                    versionFetched: null,
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                };
             }
-            const readme = rawData.versions[latestVersion].readme || rawData.readme;
-            if (!readme) {
-                return { name: pkg, version: latestVersion, text: 'No README found' };
+            const cacheKey = generateCacheKey('handleNpmPackageReadme', name, versionTag);
+            const cachedData = cacheGet(cacheKey);
+            if (cachedData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    versionFetched: cachedData.versionFetched, // Retrieve stored fetched version
+                    status: 'success_cache',
+                    error: null,
+                    data: { readme: cachedData.readme, hasReadme: cachedData.hasReadme },
+                    message: `README for ${name}@${cachedData.versionFetched} from cache.`,
+                };
             }
-            return { name: pkg, version: latestVersion, text: readme };
-        }));
-        let text = '';
-        for (const result of results) {
-            text += `${'='.repeat(80)}\n`;
-            text += `📖 ${result.name}@${result.version}\n`;
-            text += `${'='.repeat(80)}\n\n`;
-            text += result.text;
-            if (results.indexOf(result) < results.length - 1) {
-                text += '\n\n';
-                text += `${'='.repeat(80)}\n\n`;
+            try {
+                const response = await fetch(`https://registry.npmjs.org/${name}`);
+                if (!response.ok) {
+                    let errorMsg = `Failed to fetch package info: ${response.status} ${response.statusText}`;
+                    if (response.status === 404) {
+                        errorMsg = `Package ${name} not found.`;
+                    }
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionTag,
+                        versionFetched: null,
+                        status: 'error',
+                        error: errorMsg,
+                        data: null,
+                    };
+                }
+                const packageInfo = await response.json();
+                if (!isNpmPackageInfo(packageInfo)) {
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionTag,
+                        versionFetched: null,
+                        status: 'error',
+                        error: 'Invalid package info data received',
+                        data: null,
+                    };
+                }
+                const versionToUse = versionTag === 'latest' ? packageInfo['dist-tags']?.latest : versionTag;
+                if (!versionToUse || !packageInfo.versions || !packageInfo.versions[versionToUse]) {
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionTag,
+                        versionFetched: versionToUse || null,
+                        status: 'error',
+                        error: `Version ${versionToUse || 'requested'} not found or no version data available.`,
+                        data: null,
+                    };
+                }
+                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;
+                const hasReadme = !!readmeContent;
+                const readmeResultData = {
+                    readme: readmeContent,
+                    hasReadme: hasReadme,
+                    versionFetched: versionToUse, // Store the actually fetched version
+                };
+                cacheSet(cacheKey, readmeResultData, CACHE_TTL_LONG);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    versionFetched: versionToUse,
+                    status: 'success',
+                    error: null,
+                    data: { readme: readmeContent, hasReadme: hasReadme }, // Return only readme and hasReadme in data field for consistency
+                    message: `Successfully fetched README for ${name}@${versionToUse}.`,
+                };
             }
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    versionFetched: null,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                };
+            }
+        }));
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+            message: `README fetching status for ${args.packages.length} package(s).`,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error fetching READMEs: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error fetching READMEs: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
 export async function handleNpmSearch(args) {
     try {
+        const query = args.query;
         const limit = args.limit || 10;
-        const response = await fetch(`https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(args.query)}&size=${limit}`);
+        if (limit < 1 || limit > 250) {
+            // NPM API search limit is typically 250
+            throw new Error('Limit must be between 1 and 250.');
+        }
+        const cacheKey = generateCacheKey('handleNpmSearch', query, limit);
+        const cachedData = cacheGet(cacheKey);
+        if (cachedData) {
+            const cachedResponseJson = JSON.stringify(cachedData, null, 2);
+            return {
+                content: [{ type: 'text', text: cachedResponseJson }],
+                isError: false,
+                message: `Search results for query '${query}' with limit ${limit} from cache.`,
+            };
+        }
+        const response = await fetch(`https://registry.npmjs.org/-/v1/search?text=${encodeURIComponent(query)}&size=${limit}`);
         if (!response.ok) {
-            throw new Error(`Failed to search packages: ${response.statusText}`);
+            throw new Error(`Failed to search packages: ${response.status} ${response.statusText}`);
         }
         const rawData = await response.json();
         const parseResult = NpmSearchResultSchema.safeParse(rawData);
         if (!parseResult.success) {
-            throw new Error('Invalid search results data received');
+            console.error('Invalid search results data received:', parseResult.error.issues);
+            throw new Error('Invalid search results data received from NPM registry.');
         }
         const { objects, total } = parseResult.data;
-        let text = `🔍 Search results for "${args.query}"\n`;
-        text += `Found ${total.toLocaleString()} packages (showing top ${limit})\n\n`;
-        for (const result of objects) {
+        const resultsData = objects.map((result) => {
             const pkg = result.package;
-            const score = result.score;
-            text += `📦 ${pkg.name}@${pkg.version}\n`;
-            if (pkg.description)
-                text += `${pkg.description}\n`;
-            // Normalize and format score to ensure it's between 0 and 1
-            const normalizedScore = Math.min(1, score.final / 100);
-            const finalScore = normalizedScore.toFixed(2);
-            text += `Score: ${finalScore} (${(normalizedScore * 100).toFixed(0)}%)\n`;
-            if (pkg.keywords && pkg.keywords.length > 0) {
-                text += `Keywords: ${pkg.keywords.join(', ')}\n`;
-            }
-            if (pkg.links) {
-                text += 'Links:\n';
-                if (pkg.links.npm)
-                    text += `• NPM: ${pkg.links.npm}\n`;
-                if (pkg.links.homepage)
-                    text += `• Homepage: ${pkg.links.homepage}\n`;
-                if (pkg.links.repository)
-                    text += `• Repository: ${pkg.links.repository}\n`;
-            }
-            text += '\n';
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+            const scoreDetail = result.score.detail;
+            return {
+                name: pkg.name,
+                version: pkg.version,
+                description: pkg.description || null,
+                keywords: pkg.keywords || [],
+                publisher: pkg.publisher
+                    ? { username: pkg.publisher.username, email: pkg.publisher.email || null }
+                    : null, // publisher might not have email
+                date: pkg.date || null,
+                links: {
+                    npm: pkg.links?.npm || null,
+                    homepage: pkg.links?.homepage || null,
+                    repository: pkg.links?.repository || null,
+                    bugs: pkg.links?.bugs || null, // NpmSearchResultSchema needs to be updated if bugs is not there
+                },
+                score: {
+                    final: result.score.final,
+                    detail: {
+                        quality: scoreDetail.quality,
+                        popularity: scoreDetail.popularity,
+                        maintenance: scoreDetail.maintenance,
+                    },
+                },
+                searchScore: result.searchScore,
+            };
+        });
+        const finalResponse = {
+            query: query,
+            limitUsed: limit,
+            totalResults: total,
+            resultsCount: resultsData.length,
+            results: resultsData,
+            message: `Search completed. Found ${total} total packages, returning ${resultsData.length}.`,
+        };
+        cacheSet(cacheKey, finalResponse, CACHE_TTL_MEDIUM);
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            query: args.query,
+            limitUsed: args.limit || 10,
+            totalResults: 0,
+            resultsCount: 0,
+            results: [],
+            error: `Error searching packages: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error searching packages: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
@@ -1339,59 +2133,175 @@ export async function handleNpmSearch(args) {
 // License compatibility checker
 export async function handleNpmLicenseCompatibility(args) {
     try {
-        const licenses = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://registry.npmjs.org/${pkg}/latest`);
-            if (!response.ok) {
-                throw new Error(`Failed to fetch license info for ${pkg}: ${response.statusText}`);
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided for license compatibility analysis.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let versionTag = 'latest';
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    versionTag = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    name = pkgInput;
+                }
+            }
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    versionQueried: versionTag,
+                    versionFetched: null,
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    versionQueried: versionTag,
+                    versionFetched: null,
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                };
+            }
+            const cacheKey = generateCacheKey('npmLicenseInfoForCompatibility', name, versionTag);
+            const cachedLicenseData = cacheGet(cacheKey);
+            if (cachedLicenseData) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    versionFetched: cachedLicenseData.versionFetched,
+                    status: 'success_cache',
+                    error: null,
+                    data: { license: cachedLicenseData.license },
+                    message: `License info for ${name}@${cachedLicenseData.versionFetched} from cache.`,
+                };
+            }
+            try {
+                const response = await fetch(`https://registry.npmjs.org/${name}/${versionTag}`);
+                if (!response.ok) {
+                    let errorMsg = `Failed to fetch package info: ${response.status} ${response.statusText}`;
+                    if (response.status === 404) {
+                        errorMsg = `Package ${name}@${versionTag} not found.`;
+                    }
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionTag,
+                        versionFetched: null,
+                        status: 'error',
+                        error: errorMsg,
+                        data: null,
+                    };
+                }
+                const versionData = await response.json();
+                if (!isNpmPackageVersionData(versionData)) {
+                    return {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionTag,
+                        versionFetched: null, // Could use versionData.version if partially valid
+                        status: 'error',
+                        error: 'Invalid package version data format received',
+                        data: null,
+                    };
+                }
+                const licenseInfoToCache = {
+                    license: versionData.license || 'UNKNOWN', // Default to UNKNOWN if null/undefined
+                    versionFetched: versionData.version,
+                };
+                cacheSet(cacheKey, licenseInfoToCache, CACHE_TTL_VERY_LONG);
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    versionFetched: versionData.version,
+                    status: 'success',
+                    error: null,
+                    data: {
+                        license: versionData.license || 'UNKNOWN', // Default to UNKNOWN if null/undefined
+                    },
+                    message: `Successfully fetched license info for ${name}@${versionData.version}.`,
+                };
+            }
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionTag,
+                    versionFetched: null,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                };
             }
-            const data = (await response.json());
-            return {
-                package: pkg,
-                license: data.license || 'UNKNOWN',
-            };
         }));
-        let text = '📜 License Compatibility Analysis\n\n';
-        text += 'Packages analyzed:\n';
-        for (const { package: pkg, license } of licenses) {
-            text += `• ${pkg}: ${license}\n`;
+        // Perform analysis based on fetched licenses
+        const warnings = [];
+        const licensesFound = processedResults
+            .filter((r) => r.status === 'success' && r.data)
+            .map((r) => r.data.license.toUpperCase()); // Use toUpperCase for case-insensitive matching
+        const uniqueLicenses = [...new Set(licensesFound)];
+        const hasGPL = uniqueLicenses.some((lic) => lic.includes('GPL'));
+        const hasMIT = uniqueLicenses.some((lic) => lic === 'MIT');
+        const hasApache = uniqueLicenses.some((lic) => lic.includes('APACHE')); // Check for APACHE generally
+        const hasUnknown = uniqueLicenses.some((lic) => lic === 'UNKNOWN');
+        const allSuccess = processedResults.every((r) => r.status === 'success');
+        if (!allSuccess) {
+            warnings.push('Could not fetch license information for all packages.');
         }
-        text += '\n';
-        // Basic license compatibility check
-        const hasGPL = licenses.some(({ license }) => license?.includes('GPL'));
-        const hasMIT = licenses.some(({ license }) => license === 'MIT');
-        const hasApache = licenses.some(({ license }) => license?.includes('Apache'));
-        const hasUnknown = licenses.some(({ license }) => license === 'UNKNOWN');
-        text += 'Compatibility Analysis:\n';
-        if (hasUnknown) {
-            text += '⚠️ Warning: Some packages have unknown licenses. Manual review recommended.\n';
+        if (hasUnknown && licensesFound.length > 0) {
+            warnings.push('Some packages have unknown or unspecified licenses. Manual review recommended.');
         }
         if (hasGPL) {
-            text += '⚠️ Contains GPL licensed code. Resulting work may need to be GPL licensed.\n';
+            warnings.push('Contains GPL licensed code. Resulting work may need to be GPL licensed.');
             if (hasMIT || hasApache) {
-                text += '⚠️ Mixed GPL with MIT/Apache licenses. Review carefully for compliance.\n';
+                warnings.push('Mixed GPL with potentially incompatible licenses (e.g., MIT, Apache). Review carefully for compliance.');
             }
         }
-        else if (hasMIT && hasApache) {
-            text += '✅ MIT and Apache 2.0 licenses are compatible.\n';
+        // Further refined compatibility checks can be added here if needed
+        let summary = 'License compatibility analysis completed.';
+        if (warnings.length > 0) {
+            summary = 'License compatibility analysis completed with warnings.';
         }
-        else if (hasMIT) {
-            text += '✅ All MIT licensed. Generally safe to use.\n';
+        else if (licensesFound.length === 0 && allSuccess) {
+            summary = 'No license information found for the queried packages.';
         }
-        else if (hasApache) {
-            text += '✅ All Apache licensed. Generally safe to use.\n';
+        else if (licensesFound.length > 0 && !hasGPL && !hasUnknown) {
+            summary = 'Licenses found appear to be generally compatible (non-GPL, known licenses).';
         }
-        text +=
-            '\nNote: This is a basic analysis. For legal compliance, please consult with a legal expert.\n';
-        return { content: [{ type: 'text', text }], isError: false };
+        const analysis = {
+            summary: summary,
+            warnings: warnings,
+            uniqueLicensesFound: uniqueLicenses,
+        };
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+            analysis: analysis,
+            message: `License compatibility check for ${args.packages.length} package(s). Note: This is a basic analysis. For legal compliance, consult a legal expert.`,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            analysis: null,
+            error: `General error analyzing license compatibility: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error analyzing license compatibility: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
@@ -1399,346 +2309,767 @@ export async function handleNpmLicenseCompatibility(args) {
 // Repository statistics analyzer
 export async function handleNpmRepoStats(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            // First get the package info from npm to find the repository URL
-            const npmResponse = await fetch(`https://registry.npmjs.org/${pkg}/latest`);
-            if (!npmResponse.ok) {
-                throw new Error(`Failed to fetch npm info for ${pkg}: ${npmResponse.statusText}`);
-            }
-            const npmData = (await npmResponse.json());
-            if (!npmData.repository?.url) {
-                return { name: pkg, text: `No repository URL found for package ${pkg}` };
-            }
-            // Extract GitHub repo info from URL
-            const repoUrl = npmData.repository.url;
-            const match = repoUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
-            if (!match) {
-                return { name: pkg, text: `Could not parse GitHub repository URL: ${repoUrl}` };
-            }
-            const [, owner, repo] = match;
-            // Fetch repository stats from GitHub API
-            const githubResponse = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
-                headers: {
-                    Accept: 'application/vnd.github.v3+json',
-                    'User-Agent': 'MCP-Server',
-                },
-            });
-            if (!githubResponse.ok) {
-                throw new Error(`Failed to fetch GitHub stats: ${githubResponse.statusText}`);
-            }
-            const data = (await githubResponse.json());
-            const text = [
-                `${'='.repeat(80)}`,
-                `📊 Repository Statistics for ${pkg}`,
-                `${'='.repeat(80)}\n`,
-                '🌟 Engagement Metrics',
-                `${'─'.repeat(40)}`,
-                `• Stars:       ${data.stargazers_count.toLocaleString().padEnd(10)} ⭐`,
-                `• Forks:       ${data.forks_count.toLocaleString().padEnd(10)} 🔄`,
-                `• Watchers:    ${data.watchers_count.toLocaleString().padEnd(10)} 👀`,
-                `• Open Issues: ${data.open_issues_count.toLocaleString().padEnd(10)} 🔍\n`,
-                '📅 Timeline',
-                `${'─'.repeat(40)}`,
-                `• Created:      ${new Date(data.created_at).toLocaleDateString()}`,
-                `• Last Updated: ${new Date(data.updated_at).toLocaleDateString()}\n`,
-                '🔧 Repository Details',
-                `${'─'.repeat(40)}`,
-                `• Default Branch: ${data.default_branch}`,
-                `• Wiki Enabled:   ${data.has_wiki ? 'Yes' : 'No'}\n`,
-                '🏷️ Topics',
-                `${'─'.repeat(40)}`,
-                data.topics.length
-                    ? data.topics.map((topic) => `• ${topic}`).join('\n')
-                    : '• No topics found',
-                '',
-            ].join('\n');
-            return { name: pkg, text };
-        }));
-        let text = '';
-        for (const result of results) {
-            text += result.text;
-            if (results.indexOf(result) < results.length - 1) {
-                text += '\n\n';
-            }
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided for repository statistics analysis.');
         }
-        return { content: [{ type: 'text', text }], isError: false };
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                name = atIdx > 0 ? pkgInput.slice(0, atIdx) : pkgInput; // Version typically ignored for repo stats
+            }
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                    message: 'Package name could not be determined from input.',
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmRepoStats', name);
+            const cachedResult = cacheGet(cacheKey); // Cache stores the entire result object structure
+            if (cachedResult) {
+                // Return the entire cached result object, which already includes status, data, message
+                return {
+                    ...cachedResult, // Spread the cached result
+                    packageInput: pkgInput, // Add current input for context
+                    packageName: name, // Add current name for context
+                    status: `${cachedResult.status}_cache`, // Append _cache to status
+                    message: `${cachedResult.message} (from cache)`,
+                };
+            }
+            try {
+                const npmResponse = await fetch(`https://registry.npmjs.org/${name}/latest`);
+                if (!npmResponse.ok) {
+                    const errorData = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: `Failed to fetch npm info for ${name}: ${npmResponse.status} ${npmResponse.statusText}`,
+                        data: null,
+                        message: `Could not retrieve NPM package data for ${name}.`,
+                    };
+                    // Do not cache primary API call failures
+                    return errorData;
+                }
+                const npmData = await npmResponse.json();
+                if (!isNpmPackageVersionData(npmData)) {
+                    const errorData = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'error',
+                        error: 'Invalid NPM package data format received.',
+                        data: null,
+                        message: `Malformed NPM package data for ${name}.`,
+                    };
+                    return errorData;
+                }
+                const repoUrl = npmData.repository?.url;
+                if (!repoUrl) {
+                    const resultNoRepo = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'no_repo_found',
+                        error: null,
+                        data: null,
+                        message: `No repository URL found in package data for ${name}.`,
+                    };
+                    cacheSet(cacheKey, resultNoRepo, CACHE_TTL_LONG);
+                    return resultNoRepo;
+                }
+                const githubMatch = repoUrl.match(/github\.com[:\/]([^\/]+)\/([^\/.]+)/);
+                if (!githubMatch) {
+                    const resultNotGitHub = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        status: 'not_github_repo',
+                        error: null,
+                        data: { repositoryUrl: repoUrl },
+                        message: `Repository URL found (${repoUrl}) is not a standard GitHub URL.`,
+                    };
+                    cacheSet(cacheKey, resultNotGitHub, CACHE_TTL_LONG);
+                    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 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}.`,
+                    };
+                    // 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 || [],
+                    },
+                    message: 'GitHub repository statistics fetched successfully.',
+                };
+                cacheSet(cacheKey, successResult, CACHE_TTL_LONG);
+                return successResult;
+            }
+            catch (error) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing ${name}.`,
+                };
+            }
+        }));
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+            message: `Repository statistics analysis for ${args.packages.length} package(s).`,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error analyzing repository stats: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error analyzing repository stats: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
 export async function handleNpmDeprecated(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://registry.npmjs.org/${pkg}`);
-            if (!response.ok) {
-                throw new Error(`Failed to fetch package info: ${response.statusText}`);
-            }
-            const rawData = (await response.json());
-            if (!isNpmPackageInfo(rawData)) {
-                throw new Error('Invalid package info data received');
-            }
-            // Get latest version info
-            const latestVersion = rawData['dist-tags']?.latest;
-            if (!latestVersion || !rawData.versions?.[latestVersion]) {
-                throw new Error('No latest version found');
-            }
-            const latestVersionInfo = rawData.versions[latestVersion];
-            const dependencies = {
-                ...(latestVersionInfo.dependencies || {}),
-                ...(latestVersionInfo.devDependencies || {}),
-                ...(latestVersionInfo.peerDependencies || {}),
-            };
-            // Check each dependency
-            const deprecatedDeps = [];
-            await Promise.all(Object.entries(dependencies).map(async ([dep, version]) => {
-                try {
-                    const depResponse = await fetch(`https://registry.npmjs.org/${dep}`);
-                    if (!depResponse.ok)
-                        return;
-                    const depData = (await depResponse.json());
-                    const depVersion = version.replace(/[^0-9.]/g, '');
-                    if (depData.versions?.[depVersion]?.deprecated) {
-                        deprecatedDeps.push({
-                            name: dep,
-                            version: depVersion,
-                            message: depData.versions[depVersion].deprecated || 'No message provided',
-                        });
-                    }
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let version = 'latest'; // Default to 'latest'
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    version = pkgInput.slice(atIdx + 1);
                 }
-                catch (error) {
-                    console.error(`Error checking ${dep}:`, error);
+                else {
+                    name = pkgInput;
                 }
-            }));
-            // Check if the package itself is deprecated
-            const isDeprecated = latestVersionInfo.deprecated;
-            let text = `📦 Deprecation Check for ${pkg}@${latestVersion}\n\n`;
-            if (isDeprecated) {
-                text += '⚠️ WARNING: This package is deprecated!\n';
-                text += `Deprecation message: ${latestVersionInfo.deprecated}\n\n`;
             }
             else {
-                text += '✅ This package is not deprecated\n\n';
+                return {
+                    package: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            const initialPackageNameForOutput = version === 'latest' ? name : `${name}@${version}`;
+            const cacheKey = generateCacheKey('handleNpmDeprecated', name, version);
+            const cachedResult = cacheGet(cacheKey);
+            if (cachedResult) {
+                // console.debug(`[handleNpmDeprecated] Cache hit for ${cacheKey}`);
+                return {
+                    package: cachedResult.package,
+                    status: 'success_cache',
+                    error: null,
+                    data: cachedResult.data,
+                    message: `${cachedResult.message} (from cache)`,
+                };
             }
-            if (deprecatedDeps.length > 0) {
-                text += `Found ${deprecatedDeps.length} deprecated dependencies:\n\n`;
-                for (const dep of deprecatedDeps) {
-                    text += `⚠️ ${dep.name}@${dep.version}\n`;
-                    text += `   Message: ${dep.message}\n\n`;
+            // console.debug(`[handleNpmDeprecated] Cache miss for ${cacheKey}`);
+            try {
+                const mainPkgResponse = await fetch(`https://registry.npmjs.org/${name}`);
+                if (!mainPkgResponse.ok) {
+                    return {
+                        package: initialPackageNameForOutput,
+                        status: 'error',
+                        error: `Failed to fetch package info for ${name}: ${mainPkgResponse.status} ${mainPkgResponse.statusText}`,
+                        data: null,
+                        message: `Could not retrieve main package data for ${name}.`,
+                    };
+                }
+                const mainPkgData = (await mainPkgResponse.json());
+                let versionToFetch = version;
+                if (version === 'latest') {
+                    versionToFetch = mainPkgData['dist-tags']?.latest || 'latest';
+                    if (versionToFetch === 'latest' && !mainPkgData.versions?.[versionToFetch]) {
+                        const availableVersions = Object.keys(mainPkgData.versions || {});
+                        if (availableVersions.length > 0) {
+                            versionToFetch = availableVersions.sort().pop() || 'latest'; // Basic sort
+                        }
+                    }
                 }
+                const finalPackageNameForOutput = `${name}@${versionToFetch}`;
+                const versionInfo = mainPkgData.versions?.[versionToFetch];
+                if (!versionInfo) {
+                    return {
+                        package: finalPackageNameForOutput,
+                        status: 'error',
+                        error: `Version ${versionToFetch} not found for package ${name}.`,
+                        data: null,
+                        message: `Specified version for ${name} does not exist.`,
+                    };
+                }
+                const isPackageDeprecated = !!versionInfo.deprecated;
+                const packageDeprecationMessage = versionInfo.deprecated || null;
+                const processDependencies = async (deps) => {
+                    if (!deps)
+                        return [];
+                    const depChecks = Object.entries(deps).map(async ([depName, depSemVer]) => {
+                        const lookedUpAs = depName; // Strategy: always use original name, no cleaning.
+                        let statusMessage = '';
+                        try {
+                            // console.debug(`[handleNpmDeprecated] Checking dependency: ${depName}@${depSemVer}`);
+                            const depInfoResponse = await fetch(`https://registry.npmjs.org/${encodeURIComponent(depName)}`);
+                            if (!depInfoResponse.ok) {
+                                statusMessage = `Could not fetch dependency info for '${depName}' (status: ${depInfoResponse.status}). Deprecation status unknown.`;
+                                // console.warn(`[handleNpmDeprecated] ${statusMessage}`);
+                                return {
+                                    name: depName,
+                                    version: depSemVer,
+                                    lookedUpAs: lookedUpAs,
+                                    isDeprecated: false, // Assume not deprecated as status is unknown
+                                    deprecationMessage: null,
+                                    statusMessage: statusMessage,
+                                };
+                            }
+                            const depData = (await depInfoResponse.json());
+                            const latestDepVersionTag = depData['dist-tags']?.latest;
+                            const latestDepVersionInfo = latestDepVersionTag
+                                ? depData.versions?.[latestDepVersionTag]
+                                : undefined;
+                            statusMessage = `Successfully checked '${depName}'.`;
+                            return {
+                                name: depName,
+                                version: depSemVer,
+                                lookedUpAs: lookedUpAs,
+                                isDeprecated: !!latestDepVersionInfo?.deprecated,
+                                deprecationMessage: latestDepVersionInfo?.deprecated || null,
+                                statusMessage: statusMessage,
+                            };
+                        }
+                        catch (error) {
+                            const errorMessage = error instanceof Error ? error.message : 'Unknown processing error';
+                            statusMessage = `Error processing dependency '${depName}': ${errorMessage}. Deprecation status unknown.`;
+                            // console.warn(`[handleNpmDeprecated] ${statusMessage}`);
+                            return {
+                                name: depName,
+                                version: depSemVer,
+                                lookedUpAs: lookedUpAs,
+                                isDeprecated: false, // Assume not deprecated as status is unknown
+                                deprecationMessage: null,
+                                statusMessage: statusMessage,
+                            };
+                        }
+                    });
+                    return Promise.all(depChecks);
+                };
+                const directDeps = await processDependencies(versionInfo.dependencies);
+                const devDeps = await processDependencies(versionInfo.devDependencies);
+                const peerDeps = await processDependencies(versionInfo.peerDependencies);
+                const allDeps = [...directDeps, ...devDeps, ...peerDeps];
+                const unverifiableDepsCount = allDeps.filter((dep) => {
+                    const msg = dep.statusMessage.toLowerCase();
+                    return msg.includes('could not fetch') || msg.includes('error processing');
+                }).length;
+                let dependencySummaryMessage = `Processed ${allDeps.length} total dependencies.`;
+                if (unverifiableDepsCount > 0) {
+                    dependencySummaryMessage += ` Could not verify the status for ${unverifiableDepsCount} dependencies (e.g., package name not found in registry or network issues). Their deprecation status is unknown.`;
+                }
+                const resultData = {
+                    isPackageDeprecated,
+                    packageDeprecationMessage,
+                    dependencies: {
+                        direct: directDeps,
+                        development: devDeps,
+                        peer: peerDeps,
+                    },
+                    dependencySummary: {
+                        totalDependencies: allDeps.length,
+                        unverifiableDependencies: unverifiableDepsCount,
+                        message: dependencySummaryMessage,
+                    },
+                };
+                const fullMessage = `Deprecation status for ${finalPackageNameForOutput}. ${dependencySummaryMessage}`;
+                const resultToCache = {
+                    package: finalPackageNameForOutput,
+                    data: resultData,
+                    message: fullMessage,
+                };
+                cacheSet(cacheKey, resultToCache, CACHE_TTL_MEDIUM);
+                // console.debug(`[handleNpmDeprecated] Set cache for ${cacheKey}`);
+                return {
+                    package: finalPackageNameForOutput,
+                    status: 'success',
+                    error: null,
+                    data: resultData,
+                    message: fullMessage,
+                };
             }
-            else {
-                text += '✅ No deprecated dependencies found\n';
+            catch (error) {
+                // console.error(`[handleNpmDeprecated] Error processing ${initialPackageNameForOutput}: ${error}`);
+                return {
+                    package: initialPackageNameForOutput,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while processing ${initialPackageNameForOutput}.`,
+                };
             }
-            return { name: pkg, text };
         }));
-        let text = '';
-        for (const result of results) {
-            text += result.text;
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+        const responseJson = JSON.stringify({ results: processedResults }, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        // console.error(`[handleNpmDeprecated] General error: ${error}`);
+        const errorResponse = JSON.stringify({
+            results: [],
+            error: `General error checking deprecated packages: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error checking deprecated packages: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
 export async function handleNpmChangelogAnalysis(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            // First get the package info from npm to find the repository URL
-            const npmResponse = await fetch(`https://registry.npmjs.org/${pkg}`);
-            if (!npmResponse.ok) {
-                throw new Error(`Failed to fetch npm info for ${pkg}: ${npmResponse.statusText}`);
-            }
-            const npmData = await npmResponse.json();
-            if (!isNpmPackageInfo(npmData)) {
-                throw new Error('Invalid package info data received');
-            }
-            const repository = npmData.repository?.url;
-            if (!repository) {
-                return { name: pkg, text: `No repository found for package ${pkg}` };
-            }
-            // Extract GitHub repo info from URL
-            const match = repository.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
-            if (!match) {
-                return { name: pkg, text: `Could not parse GitHub repository URL: ${repository}` };
-            }
-            const [, owner, repo] = match;
-            // Check common changelog file names
-            const changelogFiles = [
-                'CHANGELOG.md',
-                'changelog.md',
-                'CHANGES.md',
-                'changes.md',
-                'HISTORY.md',
-                'history.md',
-                'NEWS.md',
-                'news.md',
-                'RELEASES.md',
-                'releases.md',
-            ];
-            let changelog = null;
-            for (const file of changelogFiles) {
-                try {
-                    const response = await fetch(`https://raw.githubusercontent.com/${owner}/${repo}/master/${file}`);
-                    if (response.ok) {
-                        changelog = await response.text();
-                        break;
-                    }
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided for changelog analysis.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let name = '';
+            let versionQueried = undefined;
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    name = pkgInput.slice(0, atIdx);
+                    versionQueried = pkgInput.slice(atIdx + 1);
                 }
-                catch (error) {
-                    console.error(`Error fetching ${file}:`, error);
+                else {
+                    name = pkgInput;
                 }
             }
-            // Get release information from GitHub API
-            const githubResponse = await fetch(`https://api.github.com/repos/${owner}/${repo}/releases`, {
-                headers: {
-                    Accept: 'application/vnd.github.v3+json',
-                    'User-Agent': 'MCP-Server',
-                },
-            });
-            const releases = (githubResponse.ok ? await githubResponse.json() : []);
-            let text = `📋 Changelog Analysis for ${pkg}\n\n`;
-            // Analyze version history from npm
-            const versions = Object.keys(npmData.versions || {}).sort((a, b) => {
-                const [aMajor = 0, aMinor = 0] = a.split('.').map(Number);
-                const [bMajor = 0, bMinor = 0] = b.split('.').map(Number);
-                return bMajor - aMajor || bMinor - aMinor;
-            });
-            text += '📦 Version History:\n';
-            text += `• Total versions: ${versions.length}\n`;
-            text += `• Latest version: ${versions[0]}\n`;
-            text += `• First version: ${versions[versions.length - 1]}\n\n`;
-            if (changelog) {
-                text += '📝 Changelog found!\n\n';
-                // Extract and analyze the last few versions from changelog
-                const recentChanges = changelog.split('\n').slice(0, 20).join('\n');
-                text += `Recent changes:\n${recentChanges}\n...\n\n`;
-            }
             else {
-                text += '⚠️ No changelog file found in repository root\n\n';
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    versionQueried: versionQueried,
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            if (!name) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    versionQueried: versionQueried,
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                    message: 'Package name could not be determined from input.',
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmChangelogAnalysis', name);
+            const cachedResult = cacheGet(cacheKey); // Expects the full result object to be cached
+            if (cachedResult) {
+                return {
+                    ...cachedResult,
+                    packageInput: pkgInput, // Ensure these are current for this specific call
+                    packageName: name,
+                    versionQueried: versionQueried,
+                    status: `${cachedResult.status}_cache`,
+                    message: `${cachedResult.message} (from cache)`,
+                };
             }
-            if (releases.length > 0) {
-                text += '🚀 Recent GitHub Releases:\n\n';
-                for (const release of releases.slice(0, 5)) {
-                    text += `${release.tag_name || 'No tag'}\n`;
-                    if (release.name)
-                        text += `Title: ${release.name}\n`;
-                    if (release.published_at)
-                        text += `Published: ${new Date(release.published_at).toLocaleDateString()}\n`;
-                    text += '\n';
+            try {
+                const npmResponse = await fetch(`https://registry.npmjs.org/${name}`);
+                if (!npmResponse.ok) {
+                    const errorResult = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionQueried,
+                        status: 'error',
+                        error: `Failed to fetch npm info for ${name}: ${npmResponse.status} ${npmResponse.statusText}`,
+                        data: null,
+                        message: `Could not retrieve NPM package data for ${name}.`,
+                    };
+                    return errorResult; // Do not cache this type of error
+                }
+                const npmData = await npmResponse.json();
+                if (!isNpmPackageInfo(npmData)) {
+                    const errorResult = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionQueried,
+                        status: 'error',
+                        error: 'Invalid NPM package info data received',
+                        data: null,
+                        message: `Received malformed NPM package data for ${name}.`,
+                    };
+                    return errorResult; // Do not cache this type of error
+                }
+                const repositoryUrl = npmData.repository?.url;
+                if (!repositoryUrl) {
+                    const resultNoRepo = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionQueried,
+                        status: 'no_repo_found',
+                        error: null,
+                        data: null,
+                        message: `No repository URL found in package data for ${name}.`,
+                    };
+                    cacheSet(cacheKey, resultNoRepo, CACHE_TTL_MEDIUM);
+                    return resultNoRepo;
+                }
+                const githubMatch = repositoryUrl.match(/github\.com[:\/]([^\/]+)\/([^\/.]+)/);
+                if (!githubMatch) {
+                    const resultNotGitHub = {
+                        packageInput: pkgInput,
+                        packageName: name,
+                        versionQueried: versionQueried,
+                        status: 'not_github_repo',
+                        error: null,
+                        data: { repositoryUrl: repositoryUrl },
+                        message: `Repository URL (${repositoryUrl}) is not a standard GitHub URL.`,
+                    };
+                    cacheSet(cacheKey, resultNotGitHub, CACHE_TTL_MEDIUM);
+                    return resultNotGitHub;
+                }
+                const [, owner, repo] = githubMatch;
+                const repoNameForUrl = repo.replace(/\.git$/, '');
+                const changelogFiles = [
+                    'CHANGELOG.md',
+                    'changelog.md',
+                    'CHANGES.md',
+                    'changes.md',
+                    'HISTORY.md',
+                    'history.md',
+                    'NEWS.md',
+                    'news.md',
+                    'RELEASES.md',
+                    'releases.md',
+                ];
+                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;
+                        }
+                    }
+                    catch (error) {
+                        console.debug(`Error fetching changelog file ${file} for ${name}: ${error}`);
+                    }
+                }
+                let githubReleases = [];
+                try {
+                    const githubApiResponse = await fetch(`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) {
+                        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,
+                        }));
+                    }
                 }
+                catch (error) {
+                    console.debug(`Error fetching GitHub releases for ${name}: ${error}`);
+                }
+                const versions = Object.keys(npmData.versions || {});
+                const npmVersionHistory = {
+                    totalVersions: versions.length,
+                    latestVersion: npmData['dist-tags']?.latest || (versions.length > 0 ? versions.sort().pop() : null),
+                    firstVersion: versions.length > 0 ? versions.sort()[0] : null,
+                };
+                const status = changelogContent || githubReleases.length > 0 ? 'success' : 'no_changelog_found';
+                const message = status === 'success'
+                    ? `Changelog and release information retrieved for ${name}.`
+                    : status === 'no_changelog_found'
+                        ? `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
+                    packageName: name,
+                    versionQueried: versionQueried,
+                    status: status,
+                    error: null,
+                    data: {
+                        repositoryUrl: repositoryUrl,
+                        changelogSourceUrl: changelogSourceUrl,
+                        changelogContent: changelogContent
+                            ? `${changelogContent.split('\n').slice(0, 50).join('\n')}...`
+                            : null,
+                        hasChangelogFile: hasChangelogFile,
+                        githubReleases: githubReleases,
+                        npmVersionHistory: npmVersionHistory,
+                    },
+                    message: message,
+                };
+                cacheSet(cacheKey, resultToCache, CACHE_TTL_MEDIUM);
+                return resultToCache;
             }
-            else {
-                text += 'ℹ️ No GitHub releases found\n';
+            catch (error) {
+                const errorResult = {
+                    packageInput: pkgInput,
+                    packageName: name,
+                    versionQueried: versionQueried,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while analyzing changelog for ${name}.`,
+                };
+                return errorResult; // Do not cache general errors
             }
-            return { name: pkg, text };
         }));
-        let text = '';
-        for (const result of results) {
-            text += result.text;
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error analyzing changelogs: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error analyzing changelog: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
 export async function handleNpmAlternatives(args) {
     try {
-        const results = await Promise.all(args.packages.map(async (pkg) => {
-            const response = await fetch(`https://registry.npmjs.org/-/v1/search?text=keywords:${pkg}&size=10`);
-            if (!response.ok) {
-                throw new Error(`Failed to search for alternatives: ${response.statusText}`);
+        const packagesToProcess = args.packages || [];
+        if (packagesToProcess.length === 0) {
+            throw new Error('No package names provided to find alternatives.');
+        }
+        const processedResults = await Promise.all(packagesToProcess.map(async (pkgInput) => {
+            let originalPackageName = '';
+            let versionQueried = undefined;
+            if (typeof pkgInput === 'string') {
+                const atIdx = pkgInput.lastIndexOf('@');
+                if (atIdx > 0) {
+                    originalPackageName = pkgInput.slice(0, atIdx);
+                    versionQueried = pkgInput.slice(atIdx + 1);
+                }
+                else {
+                    originalPackageName = pkgInput;
+                }
             }
-            const data = (await response.json());
-            const alternatives = data.objects;
-            const downloadCounts = await Promise.all(alternatives.map(async (alt) => {
+            else {
+                return {
+                    packageInput: JSON.stringify(pkgInput),
+                    packageName: 'unknown_package_input',
+                    status: 'error',
+                    error: 'Invalid package input type',
+                    data: null,
+                    message: 'Package input was not a string.',
+                };
+            }
+            if (!originalPackageName) {
+                return {
+                    packageInput: pkgInput,
+                    packageName: 'empty_package_name',
+                    status: 'error',
+                    error: 'Empty package name derived from input',
+                    data: null,
+                    message: 'Package name could not be determined from input.',
+                };
+            }
+            const cacheKey = generateCacheKey('handleNpmAlternatives', originalPackageName);
+            const cachedResult = cacheGet(cacheKey); // Expects the full result object
+            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
+                    status: `${cachedResult.status}_cache`,
+                    message: `${cachedResult.message} (from cache)`,
+                };
+            }
+            try {
+                const searchResponse = await fetch(`https://registry.npmjs.org/-/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 originalPackageDownloads = 0;
                 try {
-                    const response = await fetch(`https://api.npmjs.org/downloads/point/last-month/${alt.package.name}`);
-                    if (!response.ok)
-                        return 0;
-                    const downloadData = (await response.json());
-                    return downloadData.downloads;
+                    const dlResponse = await fetch(`https://api.npmjs.org/downloads/point/last-month/${originalPackageName}`);
+                    if (dlResponse.ok) {
+                        originalPackageDownloads =
+                            (await dlResponse.json()).downloads || 0;
+                    }
                 }
-                catch (error) {
-                    console.error(`Error fetching download count for ${alt.package.name}:`, error);
-                    return 0;
-                }
-            }));
-            // Get original package downloads for comparison
-            const originalDownloads = await fetch(`https://api.npmjs.org/downloads/point/last-month/${pkg}`)
-                .then((res) => res.json())
-                .then((data) => data.downloads)
-                .catch(() => 0);
-            let text = `🔄 Alternative Packages to ${pkg}\n\n`;
-            text += 'Original package:\n';
-            text += `📦 ${pkg}\n`;
-            text += `Downloads: ${originalDownloads.toLocaleString()}/month\n`;
-            text += `Keywords: ${alternatives[0].package.keywords?.join(', ')}\n\n`;
-            text += 'Alternative packages found:\n\n';
-            alternatives.forEach((alt, index) => {
-                const downloads = downloadCounts[index];
-                const score = alt.score.final;
-                text += `${index + 1}. 📦 ${alt.package.name}\n`;
-                if (alt.package.description)
-                    text += `   ${alt.package.description}\n`;
-                text += `   Downloads: ${downloads.toLocaleString()}/month\n`;
-                text += `   Score: ${(score * 100).toFixed(0)}%\n`;
-                if (alt.package.links?.repository)
-                    text += `   Repo: ${alt.package.links.repository}\n`;
-                if (alt.package.keywords?.length)
-                    text += `   Keywords: ${alt.package.keywords.join(', ')}\n`;
-                text += '\n';
-            });
-            return { name: pkg, text };
+                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 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.`,
+                    };
+                    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) => {
+                    let altDownloads = 0;
+                    try {
+                        const altDlResponse = await fetch(`https://api.npmjs.org/downloads/point/last-month/${alt.package.name}`);
+                        if (altDlResponse.ok) {
+                            altDownloads = (await altDlResponse.json()).downloads || 0;
+                        }
+                    }
+                    catch (e) {
+                        console.debug(`Failed to fetch downloads for alternative ${alt.package.name}: ${e}`);
+                    }
+                    return {
+                        name: alt.package.name,
+                        description: alt.package.description || null,
+                        version: alt.package.version,
+                        monthlyDownloads: altDownloads,
+                        score: alt.score.final,
+                        repositoryUrl: alt.package.links?.repository || null,
+                        keywords: alt.package.keywords || [],
+                    };
+                }));
+                const successResult = {
+                    packageInput: pkgInput,
+                    packageName: originalPackageName,
+                    status: 'success',
+                    error: null,
+                    data: {
+                        originalPackageStats: originalPackageStats,
+                        alternatives: alternativesData,
+                    },
+                    message: `Found ${alternativesData.length} alternative(s) for ${originalPackageName}.`,
+                };
+                cacheSet(cacheKey, successResult, CACHE_TTL_MEDIUM);
+                return successResult;
+            }
+            catch (error) {
+                const errorResult = {
+                    packageInput: pkgInput,
+                    packageName: originalPackageName,
+                    status: 'error',
+                    error: error instanceof Error ? error.message : 'Unknown processing error',
+                    data: null,
+                    message: `An unexpected error occurred while finding alternatives for ${originalPackageName}.`,
+                };
+                return errorResult; // Do not cache general errors
+            }
         }));
-        let text = '';
-        for (const result of results) {
-            text += result.text;
-        }
-        return { content: [{ type: 'text', text }], isError: false };
+        const finalResponse = {
+            queryPackages: args.packages,
+            results: processedResults,
+        };
+        const responseJson = JSON.stringify(finalResponse, null, 2);
+        return { content: [{ type: 'text', text: responseJson }], isError: false };
     }
     catch (error) {
+        const errorResponse = JSON.stringify({
+            queryPackages: args.packages,
+            results: [],
+            error: `General error finding alternatives: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        }, null, 2);
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error finding alternatives: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
+            content: [{ type: 'text', text: errorResponse }],
             isError: true,
         };
     }
 }
 // Create server instance
 const server = new McpServer({
-    name: 'mcp-npm-tools',
-    version: '1.0.0',
+    name: 'npm-sentinel-mcp',
+    version: '1.6.1',
 });
 // Add NPM tools
 server.tool('npmVersions', 'Get all available versions of an NPM package', {
@@ -1867,4 +3198,16 @@ process.on('unhandledRejection', (error) => {
     server.close();
     process.exit(1);
 });
+// Type guard for NpmPackageVersionSchema
+function isNpmPackageVersionData(data) {
+    try {
+        // Use safeParse for type guards to avoid throwing errors on invalid data
+        return NpmPackageVersionSchema.safeParse(data).success;
+    }
+    catch (e) {
+        // This catch block might not be strictly necessary with safeParse but kept for safety
+        // console.error("isNpmPackageVersionData validation failed unexpectedly:", e);
+        return false;
+    }
+}
 //# sourceMappingURL=index.js.map