cli-mcp-mapper 1.0.1 → 1.0.3

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main", "develop" ]
+  pull_request:
+    branches: [ "main", "develop" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run tests
+        run: npm test
+      
+      - name: Build (if build script exists)
+        run: npm run build --if-present

package/.github/workflows/publish.yml

@@ -41,6 +41,9 @@ jobs:
             echo "✅ Tag v$VERSION does not exist, proceeding..."
           fi
 
+      - run: npm ci
+      - run: npm test
+      
       - name: Create and push tag
         run: |
           VERSION=${{ steps.package-version.outputs.version }}
@@ -50,6 +53,5 @@ jobs:
           git push origin "v$VERSION"
           echo "✅ Created and pushed tag v$VERSION"
 
-      - run: npm ci
       - run: npm run build --if-present
       - run: npm publish

package/README.md

@@ -1,7 +1,8 @@
 # CLI MCP Mapper
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/SteffenBlake/cli-mcp-mapper/refs/heads/main/LICENSE)
 [![npm version](https://img.shields.io/npm/v/cli-mcp-mapper.svg)](https://www.npmjs.com/package/cli-mcp-mapper)
+[![CI](https://github.com/SteffenBlake/cli-mcp-mapper/actions/workflows/ci.yml/badge.svg)](https://github.com/SteffenBlake/cli-mcp-mapper/actions/workflows/ci.yml)
 
 **Transform any CLI command into a Model Context Protocol (MCP) tool with simple JSON configuration.**
 
@@ -66,22 +67,16 @@ The Model Context Protocol (MCP) enables AI assistants to interact with external
 
 ## Installation
 
-Install CLI MCP Mapper globally from GitHub:
+Install CLI MCP Mapper globally from NPM:
 
 ```bash
-npm install -g git+https://github.com/SteffenBlake/cli-mcp-mapper.git
-```
-
-Or install from npm (once published):
-
-```bash
-npm install -g cli-mcp-mapper
+npm i -g cli-mcp-mapper
 ```
 
 Verify the installation:
 
 ```bash
-cli-mcp-mapper --version
+which cli-mcp-mapper
 ```
 
 ## Configuration
@@ -628,26 +623,34 @@ jq -s '{"commands": (map(.commands) | add)}' \
 
 ⚠️ **Important Security Notes:**
 
-1. **Command Injection Risk**: CLI MCP Mapper executes real system commands. Only expose commands you trust.
+1. **Command Injection Protection**: CLI MCP Mapper uses Node.js `spawn` without shell interpretation to prevent command injection attacks. While we have comprehensive tests to validate this protection, **you should always run agents with shell access in containerized or sandboxed environments** (e.g., Docker, VM, or other isolation mechanisms) to minimize potential security risks. This provides an additional layer of defense in case of unforeseen vulnerabilities.
+
+2. **Containerization Best Practice**: When deploying CLI MCP Mapper in production or exposing it to AI agents, strongly consider running it within:
+   - Docker containers with limited privileges
+   - Virtual machines with restricted network access  
+   - Sandboxed environments with filesystem restrictions
+   - Isolated user accounts with minimal permissions
 
-2. **Access Control**: MCP clients that connect to CLI MCP Mapper will have the same permissions as the user running it.
+3. **Access Control**: MCP clients that connect to CLI MCP Mapper will have the same permissions as the user running it. Run the server with the least privileged user account necessary.
 
-3. **Validate Parameters**: Use `enum` to restrict parameter values when possible.
+4. **Validate Parameters**: Use `enum` to restrict parameter values when possible to prevent unexpected inputs.
 
-4. **Avoid Dangerous Commands**: Be cautious about exposing commands like:
+5. **Avoid Dangerous Commands**: Be cautious about exposing commands like:
    - `rm -rf` without proper constraints
    - `chmod` with unrestricted modes
    - Commands that can execute arbitrary code
    - Network commands that could expose sensitive data
+   - System administration commands
 
-5. **Read-Only Operations**: Consider starting with read-only commands (ls, cat, git status) before exposing write operations.
+6. **Read-Only Operations**: Consider starting with read-only commands (ls, cat, git status) before exposing write operations.
 
-6. **Configuration Security**:
+7. **Configuration Security**:
    - Don't commit sensitive configurations to version control
    - Use environment-specific configuration files
    - Review configurations before deploying
+   - Regularly audit which commands are exposed
 
-7. **Least Privilege**: Only grant the minimum necessary commands for your use case.
+8. **Least Privilege**: Only grant the minimum necessary commands for your use case.
 
 **Best Practices:**
 
@@ -702,4 +705,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 **Made with ❤️ for the MCP community**
 
-For issues, questions, or contributions, visit: https://github.com/SteffenBlake/cli-mcp-mapper
+For issues, questions, or contributions, visit: https://github.com/SteffenBlake/cli-mcp-mapper

package/index.js

@@ -3,10 +3,10 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { spawn } from "child_process";
 import { readFile } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
+import { buildInputSchema, buildCommand, executeCommand } from "./lib.js";
 
 // Load config from env variable or default path
 const defaultConfig = join(homedir(), ".config", "cli-mcp-mapper", "commands.json");
@@ -61,82 +61,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
-function buildInputSchema(parameters) {
-  const properties = {};
-  const required = [];
-  
-  for (const [name, param] of Object.entries(parameters || {})) {
-    properties[name] = {
-      type: param.type,
-      description: param.description,
-    };
-    
-    if (param.enum) properties[name].enum = param.enum;
-    if (param.default) properties[name].default = param.default;
-    if (param.required) required.push(name);
-  }
-  
-  return {
-    type: "object",
-    properties,
-    required,
-  };
-}
-
-function buildCommand(commandConfig, args) {
-  const cmd = [commandConfig.command, ...(commandConfig.baseArgs || [])];
-  
-  // Add positional args first
-  const positional = Object.entries(commandConfig.parameters || {})
-    .filter(([_, param]) => param.position !== undefined)
-    .sort(([_, a], [__, b]) => a.position - b.position);
-  
-  for (const [name, param] of positional) {
-    if (args[name] !== undefined) {
-      cmd.push(String(args[name]));
-    }
-  }
-  
-  // Add named args
-  for (const [name, param] of Object.entries(commandConfig.parameters || {})) {
-    if (param.position !== undefined) continue; // Skip positional
-    if (args[name] === undefined) continue; // Skip if not provided
-    
-    if (param.type === "boolean") {
-      if (args[name] === true) {
-        cmd.push(param.argName);
-        if (param.argValue) cmd.push(param.argValue);
-      }
-    } else {
-      cmd.push(param.argName);
-      cmd.push(String(args[name]));
-    }
-  }
-  
-  return cmd;
-}
-
-function executeCommand(cmdArray) {
-  return new Promise((resolve, reject) => {
-    const [command, ...args] = cmdArray;
-    const proc = spawn(command, args, { shell: true });
-    
-    let stdout = "";
-    let stderr = "";
-    
-    proc.stdout.on("data", (data) => (stdout += data));
-    proc.stderr.on("data", (data) => (stderr += data));
-    
-    proc.on("close", (code) => {
-      if (code !== 0) {
-        reject(new Error(`Command failed with code ${code}\n${stderr}`));
-      } else {
-        resolve(stdout || stderr);
-      }
-    });
-  });
-}
-
 // Start server
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/lib.js

@@ -0,0 +1,99 @@
+import { spawn } from "child_process";
+
+/**
+ * Build JSON schema for MCP tool input parameters
+ * @param {Object} parameters - Parameter definitions from config
+ * @returns {Object} JSON schema object
+ */
+export function buildInputSchema(parameters) {
+  const properties = {};
+  const required = [];
+  
+  for (const [name, param] of Object.entries(parameters || {})) {
+    properties[name] = {
+      type: param.type,
+      description: param.description,
+    };
+    
+    if (param.enum) properties[name].enum = param.enum;
+    if (param.default) properties[name].default = param.default;
+    if (param.required) required.push(name);
+  }
+  
+  return {
+    type: "object",
+    properties,
+    required,
+  };
+}
+
+/**
+ * Build command array from config and arguments
+ * @param {Object} commandConfig - Command configuration
+ * @param {Object} args - Arguments passed to the tool
+ * @returns {Array<string>} Command array [command, arg1, arg2, ...]
+ */
+export function buildCommand(commandConfig, args) {
+  const cmd = [commandConfig.command, ...(commandConfig.baseArgs || [])];
+  
+  // Add positional args first
+  const positional = Object.entries(commandConfig.parameters || {})
+    .filter(([_, param]) => param.position !== undefined)
+    .sort(([_, a], [__, b]) => a.position - b.position);
+  
+  for (const [name, param] of positional) {
+    if (args[name] !== undefined) {
+      cmd.push(String(args[name]));
+    }
+  }
+  
+  // Add named args
+  for (const [name, param] of Object.entries(commandConfig.parameters || {})) {
+    if (param.position !== undefined) continue; // Skip positional
+    if (args[name] === undefined) continue; // Skip if not provided
+    
+    if (param.type === "boolean") {
+      if (args[name] === true) {
+        cmd.push(param.argName);
+        if (param.argValue) cmd.push(param.argValue);
+      }
+    } else {
+      cmd.push(param.argName);
+      cmd.push(String(args[name]));
+    }
+  }
+  
+  return cmd;
+}
+
+/**
+ * Execute command safely without shell interpretation
+ * @param {Array<string>} cmdArray - Command array [command, arg1, arg2, ...]
+ * @returns {Promise<string>} Command output
+ */
+export function executeCommand(cmdArray) {
+  return new Promise((resolve, reject) => {
+    const [command, ...args] = cmdArray;
+    // SECURITY FIX: Remove shell: true to prevent command injection
+    // spawn will now execute the command directly without shell interpretation
+    const proc = spawn(command, args);
+    
+    let stdout = "";
+    let stderr = "";
+    
+    proc.stdout.on("data", (data) => (stdout += data));
+    proc.stderr.on("data", (data) => (stderr += data));
+    
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed with code ${code}\n${stderr}`));
+      } else {
+        resolve(stdout || stderr);
+      }
+    });
+    
+    proc.on("error", (err) => {
+      reject(new Error(`Failed to execute command: ${err.message}`));
+    });
+  });
+}

package/lib.test.js

@@ -0,0 +1,611 @@
+import { describe, it, expect } from '@jest/globals';
+import { buildInputSchema, buildCommand, executeCommand } from './lib.js';
+
+describe('buildInputSchema', () => {
+  it('should build schema with string parameter', () => {
+    const params = {
+      name: {
+        type: 'string',
+        description: 'User name',
+        required: true
+      }
+    };
+    
+    const schema = buildInputSchema(params);
+    
+    expect(schema).toEqual({
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'User name'
+        }
+      },
+      required: ['name']
+    });
+  });
+  
+  it('should build schema with boolean parameter', () => {
+    const params = {
+      verbose: {
+        type: 'boolean',
+        description: 'Enable verbose output'
+      }
+    };
+    
+    const schema = buildInputSchema(params);
+    
+    expect(schema).toEqual({
+      type: 'object',
+      properties: {
+        verbose: {
+          type: 'boolean',
+          description: 'Enable verbose output'
+        }
+      },
+      required: []
+    });
+  });
+  
+  it('should build schema with number parameter', () => {
+    const params = {
+      count: {
+        type: 'number',
+        description: 'Number of items',
+        default: 10
+      }
+    };
+    
+    const schema = buildInputSchema(params);
+    
+    expect(schema).toEqual({
+      type: 'object',
+      properties: {
+        count: {
+          type: 'number',
+          description: 'Number of items',
+          default: 10
+        }
+      },
+      required: []
+    });
+  });
+  
+  it('should build schema with enum parameter', () => {
+    const params = {
+      level: {
+        type: 'string',
+        description: 'Log level',
+        enum: ['debug', 'info', 'warn', 'error']
+      }
+    };
+    
+    const schema = buildInputSchema(params);
+    
+    expect(schema).toEqual({
+      type: 'object',
+      properties: {
+        level: {
+          type: 'string',
+          description: 'Log level',
+          enum: ['debug', 'info', 'warn', 'error']
+        }
+      },
+      required: []
+    });
+  });
+  
+  it('should handle empty parameters', () => {
+    const schema = buildInputSchema({});
+    
+    expect(schema).toEqual({
+      type: 'object',
+      properties: {},
+      required: []
+    });
+  });
+  
+  it('should handle undefined parameters', () => {
+    const schema = buildInputSchema(undefined);
+    
+    expect(schema).toEqual({
+      type: 'object',
+      properties: {},
+      required: []
+    });
+  });
+});
+
+describe('buildCommand', () => {
+  it('should build basic command with no args', () => {
+    const config = {
+      command: 'echo',
+      baseArgs: ['hello']
+    };
+    
+    const cmd = buildCommand(config, {});
+    
+    expect(cmd).toEqual(['echo', 'hello']);
+  });
+  
+  it('should build command with positional arguments', () => {
+    const config = {
+      command: 'echo',
+      baseArgs: [],
+      parameters: {
+        message: {
+          type: 'string',
+          description: 'Message to print',
+          position: 0
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { message: 'test message' });
+    
+    expect(cmd).toEqual(['echo', 'test message']);
+  });
+  
+  it('should build command with multiple positional arguments in order', () => {
+    const config = {
+      command: 'cp',
+      baseArgs: [],
+      parameters: {
+        source: {
+          type: 'string',
+          description: 'Source file',
+          position: 0
+        },
+        dest: {
+          type: 'string',
+          description: 'Destination file',
+          position: 1
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { source: 'file1.txt', dest: 'file2.txt' });
+    
+    expect(cmd).toEqual(['cp', 'file1.txt', 'file2.txt']);
+  });
+  
+  it('should build command with named string argument', () => {
+    const config = {
+      command: 'git',
+      baseArgs: ['commit'],
+      parameters: {
+        message: {
+          type: 'string',
+          description: 'Commit message',
+          argName: '-m'
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { message: 'Initial commit' });
+    
+    expect(cmd).toEqual(['git', 'commit', '-m', 'Initial commit']);
+  });
+  
+  it('should build command with boolean flag when true', () => {
+    const config = {
+      command: 'ls',
+      baseArgs: [],
+      parameters: {
+        all: {
+          type: 'boolean',
+          description: 'Show all files',
+          argName: '-a'
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { all: true });
+    
+    expect(cmd).toEqual(['ls', '-a']);
+  });
+  
+  it('should omit boolean flag when false', () => {
+    const config = {
+      command: 'ls',
+      baseArgs: [],
+      parameters: {
+        all: {
+          type: 'boolean',
+          description: 'Show all files',
+          argName: '-a'
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { all: false });
+    
+    expect(cmd).toEqual(['ls']);
+  });
+  
+  it('should build command with mixed positional and named args', () => {
+    const config = {
+      command: 'find',
+      baseArgs: [],
+      parameters: {
+        path: {
+          type: 'string',
+          description: 'Search path',
+          position: 0
+        },
+        name: {
+          type: 'string',
+          description: 'File name pattern',
+          argName: '-name'
+        },
+        type: {
+          type: 'string',
+          description: 'File type',
+          argName: '-type'
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { 
+      path: '/tmp',
+      name: '*.txt',
+      type: 'f'
+    });
+    
+    expect(cmd).toEqual(['find', '/tmp', '-name', '*.txt', '-type', 'f']);
+  });
+  
+  it('should convert number arguments to strings', () => {
+    const config = {
+      command: 'head',
+      baseArgs: [],
+      parameters: {
+        lines: {
+          type: 'number',
+          description: 'Number of lines',
+          argName: '-n'
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { lines: 10 });
+    
+    expect(cmd).toEqual(['head', '-n', '10']);
+  });
+  
+  it('should handle boolean with argValue', () => {
+    const config = {
+      command: 'test-cmd',
+      baseArgs: [],
+      parameters: {
+        flag: {
+          type: 'boolean',
+          description: 'Test flag',
+          argName: '--flag',
+          argValue: 'value'
+        }
+      }
+    };
+    
+    const cmd = buildCommand(config, { flag: true });
+    
+    expect(cmd).toEqual(['test-cmd', '--flag', 'value']);
+  });
+});
+
+describe('Command Injection Security Tests', () => {
+  describe('String parameter injection attempts', () => {
+    it('should safely handle command substitution attempt with $(...)', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: '$(whoami)' });
+      
+      // Command should be built as array, not interpreted by shell
+      expect(cmd).toEqual(['echo', '$(whoami)']);
+      
+      // Execute and verify the literal string is echoed, not evaluated
+      const result = await executeCommand(cmd);
+      expect(result.trim()).toBe('$(whoami)');
+    });
+    
+    it('should safely handle command substitution with backticks', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: '`whoami`' });
+      
+      expect(cmd).toEqual(['echo', '`whoami`']);
+      
+      const result = await executeCommand(cmd);
+      expect(result.trim()).toBe('`whoami`');
+    });
+    
+    it('should safely handle pipe attempts', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: 'test | cat /etc/passwd' });
+      
+      expect(cmd).toEqual(['echo', 'test | cat /etc/passwd']);
+      
+      const result = await executeCommand(cmd);
+      expect(result.trim()).toBe('test | cat /etc/passwd');
+    });
+    
+    it('should safely handle semicolon command chaining', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: 'hello; rm -rf /' });
+      
+      expect(cmd).toEqual(['echo', 'hello; rm -rf /']);
+      
+      const result = await executeCommand(cmd);
+      expect(result.trim()).toBe('hello; rm -rf /');
+    });
+    
+    it('should safely handle && command chaining', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: 'test && cat /etc/passwd' });
+      
+      expect(cmd).toEqual(['echo', 'test && cat /etc/passwd']);
+      
+      const result = await executeCommand(cmd);
+      expect(result.trim()).toBe('test && cat /etc/passwd');
+    });
+    
+    it('should safely handle || command chaining', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: 'test || whoami' });
+      
+      expect(cmd).toEqual(['echo', 'test || whoami']);
+      
+      const result = await executeCommand(cmd);
+      expect(result.trim()).toBe('test || whoami');
+    });
+    
+    it('should safely handle redirection attempts', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: 'test > /tmp/hacked' });
+      
+      expect(cmd).toEqual(['echo', 'test > /tmp/hacked']);
+      
+      const result = await executeCommand(cmd);
+      expect(result.trim()).toBe('test > /tmp/hacked');
+    });
+    
+    it('should safely handle newline injection', async () => {
+      const config = {
+        command: 'echo',
+        baseArgs: [],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Message',
+            position: 0
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: 'test\nwhoami' });
+      
+      expect(cmd).toEqual(['echo', 'test\nwhoami']);
+      
+      const result = await executeCommand(cmd);
+      expect(result).toContain('test\nwhoami');
+    });
+  });
+  
+  describe('Named argument injection attempts', () => {
+    it('should safely handle injection in named string arguments', async () => {
+      const config = {
+        command: 'git',
+        baseArgs: ['commit'],
+        parameters: {
+          message: {
+            type: 'string',
+            description: 'Commit message',
+            argName: '-m'
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { message: '$(whoami) hack' });
+      
+      // Should be separate array elements, not shell-interpreted
+      expect(cmd).toEqual(['git', 'commit', '-m', '$(whoami) hack']);
+    });
+    
+    it('should safely handle injection attempts in number arguments', async () => {
+      const config = {
+        command: 'head',
+        baseArgs: [],
+        parameters: {
+          lines: {
+            type: 'number',
+            description: 'Number of lines',
+            argName: '-n'
+          }
+        }
+      };
+      
+      // Try to inject through number parameter
+      const cmd = buildCommand(config, { lines: '10; whoami' });
+      
+      expect(cmd).toEqual(['head', '-n', '10; whoami']);
+    });
+  });
+  
+  describe('Boolean parameter injection attempts', () => {
+    it('should not allow injection through boolean parameters', () => {
+      const config = {
+        command: 'ls',
+        baseArgs: [],
+        parameters: {
+          all: {
+            type: 'boolean',
+            description: 'Show all',
+            argName: '-a'
+          }
+        }
+      };
+      
+      // Boolean parameters only add the flag when value is exactly true
+      // String values won't trigger the flag even if truthy in JavaScript
+      const cmd = buildCommand(config, { all: '$(whoami)' });
+      
+      // The string '$(whoami)' is truthy but not === true, so flag should be omitted
+      expect(cmd).toEqual(['ls']);
+    });
+  });
+  
+  describe('Multiple parameter injection attempts', () => {
+    it('should safely handle injection across multiple parameters', async () => {
+      const config = {
+        command: 'find',
+        baseArgs: [],
+        parameters: {
+          path: {
+            type: 'string',
+            description: 'Search path',
+            position: 0
+          },
+          name: {
+            type: 'string',
+            description: 'File name',
+            argName: '-name'
+          }
+        }
+      };
+      
+      const cmd = buildCommand(config, { 
+        path: '.; whoami; echo',
+        name: '*.txt && cat /etc/passwd'
+      });
+      
+      // Both should remain as literal strings
+      expect(cmd).toEqual(['find', '.; whoami; echo', '-name', '*.txt && cat /etc/passwd']);
+    });
+  });
+});
+
+describe('Error handling', () => {
+  it('should reject when command fails', async () => {
+    const cmd = ['false']; // 'false' command always returns exit code 1
+    
+    await expect(executeCommand(cmd)).rejects.toThrow('Command failed with code 1');
+  });
+  
+  it('should reject when command does not exist', async () => {
+    const cmd = ['this-command-definitely-does-not-exist-12345'];
+    
+    await expect(executeCommand(cmd)).rejects.toThrow('Failed to execute command');
+  });
+  
+  it('should capture stderr on failure', async () => {
+    // Use a command that writes to stderr
+    const cmd = ['ls', '/this/path/does/not/exist/12345'];
+    
+    await expect(executeCommand(cmd)).rejects.toThrow();
+  });
+});
+
+describe('Normal operation tests', () => {
+  it('should execute simple echo command', async () => {
+    const cmd = ['echo', 'hello world'];
+    const result = await executeCommand(cmd);
+    
+    expect(result.trim()).toBe('hello world');
+  });
+  
+  it('should execute command with multiple arguments', async () => {
+    const cmd = ['echo', 'arg1', 'arg2', 'arg3'];
+    const result = await executeCommand(cmd);
+    
+    expect(result.trim()).toBe('arg1 arg2 arg3');
+  });
+  
+  it('should handle arguments with spaces', async () => {
+    const cmd = ['echo', 'hello world', 'foo bar'];
+    const result = await executeCommand(cmd);
+    
+    expect(result.trim()).toBe('hello world foo bar');
+  });
+  
+  it('should handle arguments with special characters (non-shell)', async () => {
+    const cmd = ['echo', '@#$%^&*()'];
+    const result = await executeCommand(cmd);
+    
+    expect(result.trim()).toBe('@#$%^&*()');
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-mcp-mapper",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "mcp server for mapping cli commands to mcp tools",
   "homepage": "https://github.com/SteffenBlake/cli-mcp-mapper#readme",
   "bugs": {
@@ -16,7 +16,13 @@
     "cli-mcp-mapper": "index.js"
   },
   "type": "module",
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
   }
 }