@nekzus/mcp-server 1.1.2 → 1.1.4

package/README.md

@@ -16,12 +16,16 @@ official MCP SDK and offers an extensible architecture for adding new tools_
 
 ## 🌟 Features
 
-- 🔄 MCP Protocol Implementation
-- 🛠️ Integrated Utility Tools
-- 📝 Schema Validation with Zod
+- 🔄 MCP Protocol Implementation with JSON-RPC 2.0
+- 🛠️ Seven Integrated Utility Tools
+- 📝 Input Schema Validation
 - 🚀 ESM Support
 - 🔒 Strict TypeScript Types
-- 🧩 Extensible Architecture for New Tools
+- 🧩 Extensible Tool Architecture
+- 🔍 Detailed Error Handling
+- 🎨 Emoji-Enhanced Output
+- 🔐 Secure Expression Evaluation
+- 📦 NPM Package Support
 
 ## 🛠️ Available Tools
 
@@ -31,14 +35,33 @@ Generates a personalized greeting message.
 
 **Parameters:**
 
-- `name` (string): Recipient's name
+- `name` (string, required): Recipient's name
 
 **Example:**
 
 ```typescript
-// Result: 👋 Hello John! Welcome to the MCP server!
+// Input
 {
-  name: "John";
+  "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
+  }
 }
 ```
 
@@ -53,8 +76,27 @@ Gets a random card from a standard poker deck.
 **Example:**
 
 ```typescript
-// Result: 🎴 You drew: Ace of ♠️ Spades
-{}
+// 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
@@ -69,13 +111,29 @@ Gets the current date and time for a specific timezone.
 **Example:**
 
 ```typescript
-// Result: 
-// 🗓️ Date: March 20, 2024
-// ⏰ Time: 7:25:25 PM
-// 🌍 Timezone: America/New_York
+// Input
 {
-  timeZone: "America/New_York",
-  locale: "en-US"
+  "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
+  }
 }
 ```
 
@@ -85,15 +143,35 @@ Performs mathematical calculations with support for basic and advanced operation
 
 **Parameters:**
 
-- `expression` (string): Mathematical expression (e.g., "2 + 2 * 3")
+- `expression` (string, required): Mathematical expression (e.g., "2 + 2 * 3")
 - `precision` (number, optional): Decimal places in the result (default: 2)
 
 **Example:**
 
 ```typescript
-// Result: 8
+// Input
+{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "calculator",
+    "arguments": {
+      "expression": "2 + 2 * 3",
+      "precision": 2
+    }
+  }
+}
+
+// Output
 {
-  expression: "2 + 2 * 3"
+  "jsonrpc": "2.0",
+  "result": {
+    "content": [{
+      "type": "text",
+      "text": "🧮 Expression: 2 + 2 * 3\n📊 Result: 8.00"
+    }],
+    "isError": false
+  }
 }
 ```
 
@@ -111,12 +189,31 @@ Generates secure passwords with customizable options.
 **Example:**
 
 ```typescript
-// Result: 4v7&9G8$
+// Input
+{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "passwordGen",
+    "arguments": {
+      "length": 12,
+      "includeNumbers": true,
+      "includeSymbols": true,
+      "includeUppercase": true
+    }
+  }
+}
+
+// Output
 {
-  length: 16,
-  includeNumbers: true,
-  includeSymbols: true,
-  includeUppercase: true
+  "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
+  }
 }
 ```
 
@@ -126,7 +223,7 @@ Generates QR codes for text or URLs.
 
 **Parameters:**
 
-- `text` (string): Text or URL to encode
+- `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")
@@ -134,22 +231,44 @@ Generates QR codes for text or URLs.
 **Example:**
 
 ```typescript
-// Result: QR code for "https://example.com"
+// Input
 {
-  text: "https://example.com"
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "qrGen",
+    "arguments": {
+      "text": "https://www.nekzus.dev",
+      "size": 300,
+      "dark": "#000000",
+      "light": "#ffffff"
+    }
+  }
+}
+
+// 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, including volume-to-weight conversions based on specific ingredients.
+Converts between common kitchen measurements and weights.
 
 **Parameters:**
 
-- `value` (number): Value to convert
-- `from` (string): Source unit (e.g., "cup", "tbsp", "g", "oz", "ml")
-- `to` (string): Target unit (e.g., "cup", "tbsp", "g", "oz", "ml")
-- `ingredient` (string, optional): Ingredient for accurate volume-to-weight conversions
+- `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:**
 
@@ -168,63 +287,61 @@ Converts between common kitchen measurements and weights, including volume-to-we
 - lb (pounds)
 
 **Supported Ingredients:**
-- water
-- milk
-- flour
-- sugar
-- brown sugar
-- salt
-- butter
-- oil
-- honey
-- maple syrup
-
-**Examples:**
+- 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
-// Simple volume conversion
-// Result: 🔄 Conversion Result:
-// • 1 cup = 236.59 ml
+// Input
 {
-  value: 1,
-  from: "cup",
-  to: "ml"
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "kitchenConvert",
+    "arguments": {
+      "value": 1,
+      "from": "cup",
+      "to": "g",
+      "ingredient": "flour"
+    }
+  }
 }
 
-// Volume to weight conversion with ingredient
-// Result: 🔄 Conversion Result:
-// • 1 cup of flour = 140.25 g
+// Output
 {
-  value: 1,
-  from: "cup",
-  to: "g",
-  ingredient: "flour"
+  "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 MCP Server
-
-1. **Global Installation:**
+### As CLI Tool
 
 ```bash
+# Global Installation
 npm install -g @nekzus/mcp-server
-```
 
-2. **Execution:**
-
-```bash
+# Direct Execution
 npx @nekzus/mcp-server
-```
-
-### As a Dependency
-
-```typescript
-import { McpUtilityServer } from "@nekzus/mcp-server";
 
-const server = new McpUtilityServer();
-server.start();
+# Example Usage
+echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greeting","arguments":{"name":"John"}}}' | npx @nekzus/mcp-server
 ```
 
 ## 🔧 Development
@@ -236,48 +353,57 @@ git clone https://github.com/nekzus/mcp-server.git
 # Install dependencies
 npm install
 
-# Development mode
-npm run dev
-
 # Build
 npm run build
 
-# Run
-npm start
+# Run tests
+npm test
+
+# Format code
+npm run format
+
+# Lint code
+npm run lint
+
+# Check code
+npm run check
 ```
 
 ## 📁 Project Structure
 
 ```
-src/
-├── types/          # Type definitions
-│   └── index.ts    # Shared types
-├── utils/          # Utilities
-│   ├── cards.ts    # Card functions
-│   ├── datetime.ts # Date/time functions
-│   └── schema.ts   # Schema conversion
-├── tools/          # Tool implementations
-│   └── index.ts    # Tools registry
-└── index.ts        # Main entry point
+/
+├── 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
 ```
 
 ## 🔍 Technical Details
 
-- **Transport:** Uses `StdioServerTransport` for communication
-- **Validation:** Converts JSON schemas to Zod for input validation
-- **Types:** Fully typed implementation with TypeScript
-- **Error Handling:** Robust error handling and resource cleanup
-- **Signals:** Handles SIGTERM and SIGINT signals for graceful shutdown
+- **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
 
 ## 📄 License
 
-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.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## 👤 Author
 
 **Nekzus**
 
 - GitHub: [@nekzus](https://github.com/nekzus)
+- PayPal: [Donate](https://paypal.me/maseortega)
 
 ## 🌟 Support
 

package/dist/index.js

@@ -485,7 +485,7 @@ async function handleToolCall(name, args) {
 }
 // Server configuration
 const server = new Server({
-    name: 'nekzus-mcp',
+    name: 'mcp-server/nekzus',
     version: '0.1.0',
     description: 'MCP Server implementation for development',
 }, {
@@ -497,18 +497,48 @@ const server = new Server({
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS,
 }));
-server.setRequestHandler(CallToolRequestSchema, async (request) => handleToolCall(request.params.name, request.params.arguments ?? {}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await handleToolCall(request.params.name, request.params.arguments ?? {});
+    return result;
+});
 // Server startup
 async function runServer() {
     try {
         const transport = new StdioServerTransport();
+        // Handle messages directly
+        process.stdin.on('data', async (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                if (message.method === 'tools/call') {
+                    const result = await handleToolCall(message.params.name, message.params.arguments ?? {});
+                    const response = {
+                        jsonrpc: '2.0',
+                        result,
+                        id: message.id,
+                    };
+                    process.stdout.write(`${JSON.stringify(response)}\n`);
+                }
+            }
+            catch (error) {
+                log('[Server] Error processing message:', error);
+            }
+        });
         await server.connect(transport);
         log('[Server] MCP Server is running');
         log('[Server] Available tools:', TOOLS.map((t) => t.name).join(', '));
         // Handle stdin close
-        process.stdin.on('close', () => {
+        process.stdin.on('close', async () => {
             log('[Server] Input stream closed');
-            cleanup();
+            await cleanup();
+        });
+        // Add signal handlers for graceful shutdown
+        process.on('SIGINT', async () => {
+            log('[Server] Received SIGINT signal');
+            await cleanup();
+        });
+        process.on('SIGTERM', async () => {
+            log('[Server] Received SIGTERM signal');
+            await cleanup();
         });
     }
     catch (error) {

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@nekzus/mcp-server",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Personal MCP Server implementation providing extensible utility functions and tools for development and testing purposes",
   "type": "module",
   "bin": {
-    "nekzus-mcp": "dist/index.js"
+    "mcp-server-nekzus": "dist/index.js"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc && shx chmod +x dist/*.js",
+    "build": "tsc && chmod +x dist/index.js",
+    "prepare": "npm run build",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "test": "jest --passWithNoTests",
@@ -19,7 +20,6 @@
     "check": "biome check --apply .",
     "commit": "git-cz",
     "semantic-release": "semantic-release --branches main",
-    "prepare": "npm run build",
     "watch": "tsc --watch"
   },
   "keywords": [