@nekzus/mcp-server 1.1.8 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# MCP Server Nekzus
+# @nekzus/mcp-server
 
 [![Github Workflow](https://github.com/nekzus/mcp-server/actions/workflows/publish.yml/badge.svg?event=push)](https://github.com/Nekzus/mcp-server/actions/workflows/publish.yml)
 [![npm-version](https://img.shields.io/npm/v/@nekzus/mcp-server.svg)](https://www.npmjs.com/package/@nekzus/mcp-server)
@@ -8,356 +8,210 @@
 
 <div align="center">
 
-**A Model Context Protocol (MCP) server that provides utility tools for
-development and testing** </br>_This implementation is built on top of the
-official MCP SDK and offers an extensible architecture for adding new tools_
+**A Model Context Protocol (MCP) server for comprehensive NPM package analysis** </br>
+_Built on the MCP SDK, providing real-time insights into package quality, security, dependencies, and metrics_
 
 </div>
 
-## 🌟 Features
+## Features
+
+- **Version Analysis**
+  - List all available package versions
+  - Get latest version details
+  - Track version history
+  - Analyze release patterns
+
+- **Package Analysis**
+  - Check dependencies and devDependencies
+  - Verify TypeScript support
+  - Analyze package size and dependencies
+  - Scan for vulnerabilities
+  - Monitor security updates
+
+- **Metrics Analysis**
+  - Track download trends
+  - Compare package metrics
+  - Evaluate quality scores
+  - Assess maintenance status
+  - Monitor popularity trends
+
+## Tools
+
+### Version Analysis Tools
+
+- **npmVersions**
+  - Get all available versions of a package
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Lists all react versions
+    ```
+
+- **npmLatest**
+  - Get latest version info and changelog
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Latest version details
+    ```
+
+### Package Analysis Tools
+
+- **npmDeps**
+  - Analyze package dependencies
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Dependencies breakdown
+    ```
+
+- **npmTypes**
+  - Check TypeScript support
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> TypeScript support info
+    ```
+
+- **npmSize**
+  - Get package size metrics
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Size and dependency info
+    ```
+
+- **npmVulnerabilities**
+  - Check security vulnerabilities
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Security vulnerabilities
+    ```
+
+### Metrics Analysis Tools
+
+- **npmTrends**
+  - Get download trends
+  - Inputs:
+    - `packageName` (string, required)
+    - `period` (string, optional): "last-week" | "last-month" | "last-year"
+  - Example:
+    ```json
+    {
+      "packageName": "react",
+      "period": "last-month"
+    } -> Download trends data
+    ```
+
+- **npmCompare**
+  - Compare multiple packages
+  - Input: `packages` (string[], required)
+  - Example:
+    ```json
+    {
+      "packages": ["react", "vue", "angular"]
+    } -> Comparative metrics
+    ```
+
+- **npmQuality**
+  - Get quality metrics
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Quality score details
+    ```
+
+- **npmMaintenance**
+  - Get maintenance metrics
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Maintenance status
+    ```
+
+- **npmPopularity**
+  - Get popularity metrics
+  - Input: `packageName` (string, required)
+  - Example:
+    ```json
+    {"packageName": "react"} -> Popularity metrics
+    ```
+
+## Key Features
+
+- Real-time package analysis
+- Comprehensive security scanning
+- Detailed dependency tracking
+- TypeScript support verification
+- Performance metrics monitoring
+- Zero configuration required
+- Type-safe implementations
+- Full TypeScript declarations
+- Docker support
+- ESM support
+
+## Installation
 
-- 🔄 MCP Protocol Implementation with JSON-RPC 2.0
-- 🛠️ Seven Integrated Utility Tools
-- 📝 Input Schema Validation
-- 🚀 ESM Support
-- 🔒 Strict TypeScript Types
-- 🧩 Extensible Tool Architecture
-- 🔍 Detailed Error Handling
-- 🎨 Emoji-Enhanced Output
-- 🔐 Secure Expression Evaluation
-- 📦 NPM Package Support
-
-## 🛠️ Available Tools
-
-### 1. greeting
-
-Generates a personalized greeting message.
-
-**Parameters:**
-
-- `name` (string, required): Recipient's name
-
-**Example:**
-
-```typescript
-// Input
-{
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "greeting",
-    "arguments": {
-      "name": "John"
-    }
-  }
-}
-
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "👋 Hello John! Welcome to the MCP server!"
-    }],
-    "isError": false
-  }
-}
-```
-
-### 2. card
-
-Gets a random card from a standard poker deck.
-
-**Parameters:**
-
-- No parameters required
-
-**Example:**
-
-```typescript
-// Input
-{
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "card",
-    "arguments": {}
-  }
-}
-
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "🎴 You drew: Ace of ♠ Spades"
-    }],
-    "isError": false
-  }
-}
-```
-
-### 3. datetime
-
-Gets the current date and time for a specific timezone.
-
-**Parameters:**
-
-- `timeZone` (string, optional): Timezone identifier (e.g., "America/New_York")
-- `locale` (string, optional): Locale identifier (e.g., "en-US")
-
-**Example:**
-
-```typescript
-// Input
-{
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "datetime",
-    "arguments": {
-      "timeZone": "America/New_York",
-      "locale": "en-US"
-    }
-  }
-}
-
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "🗓️ Date: March 24, 2024\n⏰ Time: 3:25:25 PM\n🌍 Timezone: America/New_York"
-    }],
-    "isError": false
-  }
-}
-```
-
-### 4. calculator
-
-Performs mathematical calculations with support for basic and advanced operations.
-
-**Parameters:**
-
-- `expression` (string, required): Mathematical expression (e.g., "2 + 2 * 3")
-- `precision` (number, optional): Decimal places in the result (default: 2)
-
-**Example:**
+```bash
+# NPM
+npm install @nekzus/mcp-server
 
-```typescript
-// Input
-{
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "calculator",
-    "arguments": {
-      "expression": "2 + 2 * 3",
-      "precision": 2
-    }
-  }
-}
+# Yarn
+yarn add @nekzus/mcp-server
 
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "🧮 Expression: 2 + 2 * 3\n📊 Result: 8.00"
-    }],
-    "isError": false
-  }
-}
+# PNPM
+pnpm add @nekzus/mcp-server
 ```
 
-### 5. passwordGen
+## Configuration
 
-Generates secure passwords with customizable options.
+To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your `claude_desktop_config.json`:
 
-**Parameters:**
+### NPX (Recommended)
 
-- `length` (number, optional): Password length (default: 16)
-- `includeNumbers` (boolean, optional): Include numbers (default: true)
-- `includeSymbols` (boolean, optional): Include special characters (default: true)
-- `includeUppercase` (boolean, optional): Include uppercase letters (default: true)
-
-**Example:**
-
-```typescript
-// Input
+```json
 {
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "passwordGen",
-    "arguments": {
-      "length": 12,
-      "includeNumbers": true,
-      "includeSymbols": true,
-      "includeUppercase": true
+  "mcpServers": {
+    "nekzus": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@nekzus/mcp-server"
+      ]
     }
   }
 }
-
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "🔐 Generated Password:\nKj2$mP9&vN4x\n\n📋 Password Properties:\n• Length: 12\n• Includes Numbers: ✅\n• Includes Symbols: ✅\n• Includes Uppercase: ✅"
-    }],
-    "isError": false
-  }
-}
 ```
 
-### 6. qrGen
+### Docker
 
-Generates QR codes for text or URLs.
-
-**Parameters:**
-
-- `text` (string, required): Text or URL to encode
-- `size` (number, optional): Size in pixels (default: 200)
-- `dark` (string, optional): Dark module color (default: "#000000")
-- `light` (string, optional): Light module color (default: "#ffffff")
-
-**Example:**
-
-```typescript
-// Input
+```json
 {
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "qrGen",
-    "arguments": {
-      "text": "https://www.nekzus.dev",
-      "size": 300,
-      "dark": "#000000",
-      "light": "#ffffff"
+  "mcpServers": {
+    "nekzus": {
+      "transport": "stdio",
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "--init", "nekzus/mcp-server"]
     }
   }
 }
-
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "📱 QR Code Properties:\n• Content: https://www.nekzus.dev\n• Size: 300px\n• Dark Color: #000000\n• Light Color: #ffffff\n\n🔄 QR Code generation successful! (Implementation pending)"
-    }],
-    "isError": false
-  }
-}
 ```
 
-### 7. kitchenConvert
-
-Converts between common kitchen measurements and weights.
-
-**Parameters:**
-
-- `value` (number, required): Value to convert
-- `from` (string, required): Source unit
-- `to` (string, required): Target unit
-- `ingredient` (string, optional): Ingredient for volume-to-weight conversions
-
-**Supported Units:**
-
-*Volume:*
-- ml (milliliters)
-- l (liters)
-- cup (US cup)
-- tbsp (tablespoon)
-- tsp (teaspoon)
-- floz (fluid ounce)
-
-*Weight:*
-- g (grams)
-- kg (kilograms)
-- oz (ounces)
-- lb (pounds)
-
-**Supported Ingredients:**
-- water (density: 1.000 g/ml)
-- milk (density: 1.030 g/ml)
-- flour (density: 0.593 g/ml)
-- sugar (density: 0.845 g/ml)
-- brown sugar (density: 0.721 g/ml)
-- salt (density: 1.217 g/ml)
-- butter (density: 0.911 g/ml)
-- oil (density: 0.918 g/ml)
-- honey (density: 1.420 g/ml)
-- maple syrup (density: 1.370 g/ml)
-
-**Example:**
-
-```typescript
-// Input
-{
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "kitchenConvert",
-    "arguments": {
-      "value": 1,
-      "from": "cup",
-      "to": "g",
-      "ingredient": "flour"
-    }
-  }
-}
+The configuration file is typically located at:
+- Windows: `%APPDATA%/claude-desktop/claude_desktop_config.json`
+- macOS: `~/Library/Application Support/claude-desktop/claude_desktop_config.json`
+- Linux: `~/.config/claude-desktop/claude_desktop_config.json`
 
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "🔄 Conversion Result:\n• 1 cup of flour = 140.30 g\n\n📝 Note: Conversion includes ingredient density"
-    }],
-    "isError": false
-  }
-}
-```
-
-## 🚀 Usage
-
-### As CLI Tool
+## Development
 
 ```bash
-# Global Installation
-npm install -g @nekzus/mcp-server
-
-# Direct Execution
-npx @nekzus/mcp-server
-
-# Example Usage
-echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greeting","arguments":{"name":"John"}}}' | npx @nekzus/mcp-server
-```
-
-## 🔧 Development
-
-```bash
-# Clone repository
-git clone https://github.com/nekzus/mcp-server.git
-
 # Install dependencies
 npm install
 
-# Build
-npm run build
-
-# Run tests
-npm test
+# Run in development mode
+npm run dev
 
 # Format code
 npm run format
@@ -365,46 +219,30 @@ npm run format
 # Lint code
 npm run lint
 
-# Check code
-npm run check
-```
-
-## 📁 Project Structure
+# Run tests
+npm run test
 
-```
-/
-├── index.ts           # Main server implementation
-├── package.json       # Project configuration
-├── tsconfig.json     # TypeScript configuration
-├── biome.json        # Biome configuration
-├── jest.config.js    # Jest configuration
-├── .github/          # GitHub workflows
-│   └── workflows/    # CI/CD configuration
-└── dist/            # Compiled JavaScript
+# Build
+npm run build
 ```
 
-## 🔍 Technical Details
+## Docker
 
-- **Transport:** Uses `StdioServerTransport` for JSON-RPC communication
-- **Input Validation:** Schema validation for tool arguments
-- **Error Handling:** Comprehensive error handling with detailed messages
-- **Security:** Safe expression evaluation in calculator tool
-- **Types:** Full TypeScript type coverage
-- **Testing:** Jest test framework integration
-- **CI/CD:** Automated publishing with semantic-release
-- **Formatting:** Biome for code formatting and linting
+Build and run the Docker image:
 
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+```bash
+# Build the image
+docker build -t nekzus/mcp-server .
 
-## 👤 Author
+# Run the container
+docker run -i --rm --init nekzus/mcp-server
+```
 
-**Nekzus**
+## Requirements
 
-- GitHub: [@nekzus](https://github.com/nekzus)
-- PayPal: [Donate](https://paypal.me/maseortega)
+- Node.js >= 18
+- npm >= 9
 
-## 🌟 Support
+## License
 
-Give a ⭐️ if this project helped you!
+MIT © [nekzus](https://github.com/nekzus)

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+declare function handleNpmVersions(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmLatest(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmDeps(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmTypes(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmSize(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmVulnerabilities(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmTrends(args: {
+    packageName: string;
+    period?: string;
+}): Promise<CallToolResult>;
+declare function handleNpmCompare(args: {
+    packages: string[];
+}): Promise<CallToolResult>;
+declare function handleNpmQuality(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmMaintenance(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+declare function handleNpmPopularity(args: {
+    packageName: string;
+}): Promise<CallToolResult>;
+export { handleNpmCompare, handleNpmDeps, handleNpmLatest, handleNpmMaintenance, handleNpmPopularity, handleNpmQuality, handleNpmSize, handleNpmTrends, handleNpmTypes, handleNpmVersions, handleNpmVulnerabilities, };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,EAAE,cAAc,EAAQ,MAAM,oCAAoC,CAAC;AAiT/E,iBAAe,iBAAiB,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAwCvF;AAED,iBAAe,eAAe,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAyDrF;AAED,iBAAe,aAAa,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAqDnF;AAED,iBAAe,cAAc,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAwCpF;AAED,iBAAe,aAAa,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAuCnF;AAED,iBAAe,wBAAwB,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CA6D9F;AAED,iBAAe,eAAe,CAAC,IAAI,EAAE;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,cAAc,CAAC,CA8B1B;AAED,iBAAe,gBAAgB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAoDrF;AAGD,iBAAe,gBAAgB,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CA4CtF;AAGD,iBAAe,oBAAoB,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CA4C1F;AAGD,iBAAe,mBAAmB,CAAC,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CA4CzF;AAGD,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACxB,CAAC"}