@nekzus/mcp-server 1.1.8 → 1.2.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)
@@ -14,350 +14,220 @@ official MCP SDK and offers an extensible architecture for adding new tools_
 
 </div>
 
-## 🌟 Features
-
-- 🔄 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:**
-
-```typescript
-// Input
-{
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "name": "calculator",
-    "arguments": {
-      "expression": "2 + 2 * 3",
-      "precision": 2
-    }
-  }
-}
-
-// Output
-{
-  "jsonrpc": "2.0",
-  "result": {
-    "content": [{
-      "type": "text",
-      "text": "🧮 Expression: 2 + 2 * 3\n📊 Result: 8.00"
-    }],
-    "isError": false
-  }
-}
-```
-
-### 5. passwordGen
-
-Generates secure passwords with customizable options.
-
-**Parameters:**
-
-- `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
+## Components
+
+### Tools
+
+- **greeting**
+  - Generate personalized greeting messages
+  - Input: `name` (string, required): Name of the recipient
+  - Example:
+    ```json
+    {"name": "John"} -> "👋 Hello John! Welcome to the MCP server!"
+    ```
+
+- **card**
+  - Draw random cards from a standard 52-card poker deck
+  - Input: No parameters required
+  - Example:
+    ```json
+    {} -> "🎴 Drew card: A♠️" (random from 52 cards)
+    ```
+
+- **datetime**
+  - Get formatted date/time for any timezone
+  - Inputs:
+    - `timeZone` (string, optional, default: "UTC"): Timezone identifier
+    - `locale` (string, optional, default: "en-US"): Locale for formatting
+  - Example:
+    ```json
+    {"timeZone": "America/New_York", "locale": "es-ES"} -> 
+    "🕒 domingo, 24 de marzo de 2024, 15:25:25 hora de verano del este"
+    ```
+
+- **calculator**
+  - Perform mathematical calculations
+  - Inputs:
+    - `expression` (string, required): Mathematical expression to evaluate
+    - `precision` (number, optional, default: 2): Number of decimal places
+  - Supported operations: +, -, *, /, %, (), .
+  - Example:
+    ```json
+    {"expression": "2 + 2 * 3", "precision": 2} -> "🔢 Result: 8.00"
+    {"expression": "(15 / 2) % 2", "precision": 3} -> "🔢 Result: 1.500"
+    ```
+
+- **passwordGen**
+  - Generate secure passwords with customizable options
+  - Inputs:
+    - `length` (number, optional, default: 16): Password length
+    - `includeNumbers` (boolean, optional, default: true): Include numbers
+    - `includeSymbols` (boolean, optional, default: true): Include special symbols
+    - `includeUppercase` (boolean, optional, default: true): Include uppercase letters
+  - Example:
+    ```json
+    {"length": 12, "includeSymbols": true} -> "🔐 Generated: Kj2$mP9&vN4x"
+    {"length": 8, "includeNumbers": false} -> "🔐 Generated: KjMpNvXw"
+    ```
+
+- **qrGen**
+  - Generate QR codes for text or URLs
+  - Inputs:
+    - `text` (string, required): Text or URL to encode
+    - `size` (number, optional, default: 200): Size in pixels
+    - `dark` (string, optional, default: "#000000"): Color for dark modules
+    - `light` (string, optional, default: "#ffffff"): Color for light modules
+  - Output: Returns a Data URL containing the QR code image
+  - Example:
+    ```json
+    // Basic Usage
+    {"text": "https://github.com/nekzus"} -> 
+    "📱 QR Code generated successfully!
+     Properties:
+     • Content: https://github.com/nekzus
+     • Size: 200px
+     • Dark Color: #000000
+     • Light Color: #ffffff
+     
+     QR Code (Data URL):
+     data:image/png;base64,..."
+
+    // Custom Size and Colors
+    {
+      "text": "Hello World!",
+      "size": 300,
+      "dark": "#FF0000",
+      "light": "#FFFFFF"
+    } -> 
+    "📱 QR Code generated successfully!
+     Properties:
+     • Content: Hello World!
+     • Size: 300px
+     • Dark Color: #FF0000
+     • Light Color: #FFFFFF
+     
+     QR Code (Data URL):
+     data:image/png;base64,..."
+    ```
+
+  **Note:** The QR code is returned as a Data URL that can be used directly in HTML `<img>` tags or converted to a file.
+
+- **kitchenConvert**
+  - Convert between kitchen measurements
+  - Inputs:
+    - `value` (number, required): Value to convert
+    - `from` (string, required): Source unit
+    - `to` (string, required): Target unit
+    - `ingredient` (string, optional): Ingredient for accurate conversion
+  
+  **Supported Units:**
+  
+  *Volume Units:*
+  ```
+  - ml    (milliliters)
+  - l     (liters)
+  - cup   (US cup = 236.588 ml)
+  - tbsp  (US tablespoon = 14.787 ml)
+  - tsp   (US teaspoon = 4.929 ml)
+  - floz  (US fluid ounce = 29.574 ml)
+  ```
+
+  *Weight Units:*
+  ```
+  - g     (grams)
+  - kg    (kilograms)
+  - oz    (ounces = 28.350 g)
+  - lb    (pounds = 453.592 g)
+  ```
+
+  **Ingredient Densities:**
+  ```
+  - water        (1.000 g/ml)
+  - milk         (1.030 g/ml)
+  - flour        (0.593 g/ml)
+  - sugar        (0.845 g/ml)
+  - brown_sugar  (0.721 g/ml)
+  - salt         (1.217 g/ml)
+  - butter       (0.911 g/ml)
+  - oil          (0.918 g/ml)
+  - honey        (1.420 g/ml)
+  - maple_syrup  (1.370 g/ml)
+  ```
+
+  Examples:
+  ```json
+  // Volume to Volume
+  {"value": 1, "from": "cup", "to": "ml"} -> 
+  "⚖️ 1 cup = 236.59 ml"
+
+  // Weight to Weight
+  {"value": 500, "from": "g", "to": "lb"} -> 
+  "⚖️ 500 g = 1.10 lb"
+
+  // Volume to Weight (requires ingredient)
+  {"value": 1, "from": "cup", "to": "g", "ingredient": "flour"} -> 
+  "⚖️ 1 cup of flour = 140.30 g"
+  ```
+
+## Key Features
+
+- Zero configuration required
+- JSON-RPC 2.0 compliant
+- Type-safe implementations
+- Emoji-enhanced responses
+- Comprehensive error handling
+- ESM support
+- Full TypeScript types
+- Docker support
+
+## Configuration
+
+To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your `claude_desktop_config.json`:
+
+### NPX (Recommended)
+
+```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
-
-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:**
+### Docker
 
-```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"
-    }
-  }
-}
-
-// 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
-
-```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
-```
+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`
 
-## 🔧 Development
+## 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 +235,43 @@ npm run format
 # Lint code
 npm run lint
 
-# Check code
-npm run check
+# Run tests
+npm run test
+
+# Build
+npm run build
 ```
 
-## 📁 Project Structure
+## Docker
 
-```
-/
-├── 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 the Docker image:
+
+```bash
+# Build the image
+docker build -t nekzus/mcp-server .
+
+# Run the container
+docker run -i --rm --init nekzus/mcp-server
 ```
 
-## 🔍 Technical Details
+## Contributing
 
-- **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
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes using commitizen (`npm run commit`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-## 📄 License
+## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
 
-## 👤 Author
+## Author
 
-**Nekzus**
+👤 **nekzus**
 
-- GitHub: [@nekzus](https://github.com/nekzus)
-- PayPal: [Donate](https://paypal.me/maseortega)
+* GitHub: [@Nekzus](https://github.com/Nekzus)
 
-## 🌟 Support
+## Show your support
 
 Give a ⭐️ if this project helped you!

package/dist/index.js

@@ -2,7 +2,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import 'dotenv/config';
+import QRCode from 'qrcode';
 // Logger function that uses stderr - only for critical errors
 const log = (...args) => {
     // Filter out server status messages
@@ -250,15 +250,38 @@ async function handlePasswordGen(args) {
     };
 }
 async function handleQRGen(args) {
-    return {
-        content: [
-            {
-                type: 'text',
-                text: 'QR code generation is not implemented yet',
+    try {
+        const { text, size = 200, dark = '#000000', light = '#ffffff' } = args;
+        // Generate QR code as Data URL
+        const qrDataUrl = await QRCode.toDataURL(text, {
+            width: size,
+            margin: 1,
+            color: {
+                dark,
+                light,
             },
-        ],
-        isError: true,
-    };
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `📱 QR Code generated successfully!\n\nProperties:\n• Content: ${text}\n• Size: ${size}px\n• Dark Color: ${dark}\n• Light Color: ${light}\n\nQR Code (Data URL):\n${qrDataUrl}`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error generating QR code: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
 }
 async function handleKitchenConvert(args) {
     // Simplified conversion logic
@@ -350,7 +373,7 @@ async function runServer() {
     });
     await server.connect(transport);
 }
-runServer().catch(console.error);
+runServer().catch(log);
 process.stdin.on('close', () => {
     server.close();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nekzus/mcp-server",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "Personal MCP Server implementation providing extensible utility functions and tools for development and testing purposes",
   "type": "module",
   "bin": {
@@ -10,9 +10,9 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
+    "build": "tsc && shx chmod +x dist/*.js",
     "prepare": "npm run build",
-    "dev": "tsx src/index.ts",
+    "dev": "tsx watch index.ts",
     "start": "node dist/index.js",
     "test": "jest --passWithNoTests",
     "format": "biome format --write .",
@@ -42,7 +42,7 @@
   "homepage": "https://github.com/Nekzus/mcp-server#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.7.0",
-    "dotenv": "16.4.7"
+    "qrcode": "1.5.4"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
@@ -52,11 +52,13 @@
     "@semantic-release/npm": "12.0.1",
     "@semantic-release/release-notes-generator": "14.0.3",
     "@types/jest": "29.5.14",
-    "@types/node": "22.13.11",
+    "@types/node": "22.13.13",
+    "@types/qrcode": "1.5.5",
     "cz-conventional-changelog": "3.3.0",
     "jest": "29.7.0",
     "semantic-release": "24.2.3",
-    "ts-jest": "29.2.6",
+    "shx": "0.4.0",
+    "ts-jest": "29.3.0",
     "tsx": "4.19.3",
     "typescript": "5.8.2"
   },