npm package: @mileschou/shell-proxy-mcp
Description: A Model Context Protocol (MCP) server that provides shell proxy functionality
Author: Miles Chou
Latest version: 0.3.0

# shell-proxy-mcp

A Model Context Protocol (MCP) server that provides shell proxy functionality. Define your shell tools in YAML and expose them to LLMs through MCP.

## Features

- **YAML Configuration**: Define shell tools with parameters, types, and descriptions in a simple YAML format
- **Type Validation**: Automatic runtime parameter validation using Zod schemas (string, number, boolean)
- **Template Support**: Use Mustache templates (`{{param}}`) for dynamic command generation
- **Security**: Built-in parameter validation, configurable timeouts, and error handling
- **Cross-platform**: Works on Linux, macOS, and Windows with platform-specific shell support
- **Flexible Execution**: Configure shell type and timeout per tool or globally
- **Rich Output**: Optional output prefixes and structured error reporting

## Requirements

- Node.js 20.x or 22.x

## Installation

### Using npx (Recommended)

The easiest way to use shell-proxy-mcp is with npx - no installation required:

```bash
npx @mileschou/shell-proxy-mcp path/to/your/tools.yaml
```

### From npm

Install globally:

```bash
npm install -g @mileschou/shell-proxy-mcp
shell-proxy-mcp path/to/your/tools.yaml
```

### From Source

For development or customization:

```bash
git clone https://github.com/MilesChou/shell-proxy-mcp.git
cd shell-proxy-mcp
npm install
npm run build
node dist/index.js path/to/your/tools.yaml
```

## Usage with Claude Desktop

### Using npx (Recommended)

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "shell-proxy": {
      "command": "npx",
      "args": [
        "-y",
        "@mileschou/shell-proxy-mcp",
        "/path/to/your/tools.yaml"
      ]
    }
  }
}
```

**Note**: The `-y` flag automatically confirms the installation prompt.

### Using Global Installation

If you installed globally with npm:

```json
{
  "mcpServers": {
    "shell-proxy": {
      "command": "shell-proxy-mcp",
      "args": [
        "/path/to/your/tools.yaml"
      ]
    }
  }
}
```

### Using Local Build

If building from source:

```json
{
  "mcpServers": {
    "shell-proxy": {
      "command": "node",
      "args": [
        "/path/to/shell-proxy-mcp/dist/index.js",
        "/path/to/your/tools.yaml"
      ]
    }
  }
}
```

## Configuration

Create a `tools.yaml` file to define your shell tools:

```yaml
mcp:
  description: My shell tools
  run:
    shell: /bin/bash
    timeout: 30000  # milliseconds

  tools:
    - name: list_files
      description: List files in a directory
      params:
        directory:
          type: string
          description: Directory path to list
          required: true
        pattern:
          type: string
          description: File pattern to match
          required: false
          default: "*"
      run:
        command: ls -la "{{directory}}" | grep "{{pattern}}"
      output:
        prefix: "Files in {{directory}}:"

    - name: disk_usage
      description: Show disk usage
      params:
        directory:
          type: string
          required: true
        max_depth:
          type: number
          required: false
          default: 1
      run:
        command: du -h --max-depth={{max_depth}} "{{directory}}"
```

### Configuration Reference

**Parameter Types:**
- `string`: Text values
- `number`: Numeric values
- `boolean`: true/false values

**Parameter Options:**
- `required`: Whether the parameter is mandatory
- `default`: Default value if not provided
- `description`: Parameter description for LLMs

**Tool Options:**
- `run.command`: Shell command with Mustache templates
- `run.shell`: Override default shell (optional)
- `run.timeout`: Override default timeout in ms (optional)
- `output.prefix`: Add prefix to command output (optional)

## Environment Variables

The following environment variables can be used to customize server behavior:

- `SHELL_PROXY_MCP_TIMEOUT_MS` - Default command timeout in milliseconds (default: `30000`)
- `SHELL_PROXY_MCP_MAX_BUFFER` - Maximum output buffer size in bytes (default: `10485760`)
- `SHELL_PROXY_MCP_TIMEOUT_EXIT_CODE` - Exit code for timeout errors (default: `124`)
- `SHELL_PROXY_MCP_UNIX_SHELL` - Default shell for Unix/Linux/macOS (default: `/bin/bash`)
- `SHELL_PROXY_MCP_WIN32_SHELL` - Default shell for Windows (default: `cmd.exe`)

**Example:**

```bash
# Set custom timeout (60 seconds)
export SHELL_PROXY_MCP_TIMEOUT_MS=60000

# Set custom buffer size (20MB)
export SHELL_PROXY_MCP_MAX_BUFFER=20971520

# Use zsh as default shell on Unix
export SHELL_PROXY_MCP_UNIX_SHELL=/bin/zsh

# Run the server
npx @mileschou/shell-proxy-mcp tools.yaml
```

**Using with Claude Desktop:**

You can set environment variables in the Claude Desktop configuration:

```json
{
  "mcpServers": {
    "shell-proxy": {
      "command": "npx",
      "args": ["-y", "@mileschou/shell-proxy-mcp", "/path/to/tools.yaml"],
      "env": {
        "SHELL_PROXY_MCP_TIMEOUT_MS": "60000",
        "SHELL_PROXY_MCP_UNIX_SHELL": "/bin/zsh"
      }
    }
  }
}
```

## Examples

The [examples](./examples) directory contains comprehensive tool configurations:

- **[examples/tools.yaml](./examples/tools.yaml)**: 6 ready-to-use tools demonstrating different patterns:
  - `list_files`: Directory listing with pattern filtering
  - `disk_usage`: Disk space analysis with configurable depth
  - `find_large_files`: Find files above a size threshold
  - `system_info`: System information gathering
  - `git_status`: Git repository status checker
  - `count_lines`: Code line counting by file extension

- **[examples/README.md](./examples/README.md)**: Detailed documentation including:
  - Complete parameter reference for each tool
  - Usage examples with different parameter combinations
  - Best practices for creating custom tools
  - Security considerations
  - Cross-platform compatibility tips
  - Testing and debugging guide

### Quick Example

Try the example tools:

**Using npx (no installation required):**
```bash
npx @mileschou/shell-proxy-mcp examples/tools.yaml
```

**Or build from source:**
```bash
# Clone and build
git clone https://github.com/MilesChou/shell-proxy-mcp.git
cd shell-proxy-mcp
npm install
npm run build

# Run with example configuration
node dist/index.js examples/tools.yaml
```

Then configure in Claude Desktop to start using the tools with your LLM.

## CLI Usage

**Using npx (no installation):**
```bash
# With config file
npx @mileschou/shell-proxy-mcp path/to/tools.yaml

# Show help
npx @mileschou/shell-proxy-mcp --help
```

**If installed globally:**
```bash
# Use tools.yaml in current directory
shell-proxy-mcp

# Specify configuration file
shell-proxy-mcp path/to/config.yaml

# Show help
shell-proxy-mcp --help
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run watch

# Run tests (32 tests covering config, validator, executor)
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Generate coverage report
npm run test:coverage
```

### Project Structure

```
src/
├── config.ts      # YAML configuration parser
├── validator.ts   # Parameter validation with Zod
├── executor.ts    # Command execution with Mustache templates
├── server.ts      # MCP server implementation
└── index.ts       # CLI entry point

tests/
├── config.test.ts    # Configuration tests
├── validator.test.ts # Validation tests
├── executor.test.ts  # Execution tests
└── fixtures/         # Test YAML files

examples/
├── tools.yaml    # Example tool configurations
└── README.md     # Detailed examples documentation
```

## Use Cases

This MCP server enables LLMs to safely execute system commands for various tasks:

- **System Administration**: Check disk usage, list files, monitor processes
- **Development**: Git operations, line counting, file searching
- **Data Analysis**: Log parsing, file statistics, directory analysis
- **Automation**: Create custom tools for repetitive shell tasks
- **Monitoring**: System information, resource usage, service status

## Supported Operating Systems

Tested and working on:
- **Ubuntu** (latest) - Full support
- **macOS** (latest) - Full support
- **Windows** (latest) - Full support with cmd.exe or PowerShell

CI/CD runs tests on Node.js 20.x and 22.x across all platforms.

## Inspiration

This project is inspired by [MCPShell](https://github.com/inercia/MCPShell) (Go implementation) and provides a Node.js/TypeScript alternative with:
- Native TypeScript support
- Zod-based validation
- Vitest testing framework
- Cross-platform compatibility

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Areas for improvement:

- Additional example tools
- Enhanced security features (CEL-like constraints)
- Better error messages
- Platform-specific optimizations
- Documentation improvements

Please feel free to submit a Pull Request or open an issue.

## Support

- **Documentation**: Check [examples/README.md](./examples/README.md) for detailed guides
- **Issues**: Report bugs at [GitHub Issues](https://github.com/MilesChou/shell-proxy-mcp/issues)
- **MCP Resources**: Visit [Model Context Protocol](https://modelcontextprotocol.io/) for more information