Simple MCP Runner

A production-ready Model Context Protocol (MCP) server that provides Language Learning Models (LLMs) with a safe interface to discover and execute system commands on the local machine.

Features

Command Discovery: Pattern-based discovery of available system commands
Safe Execution: Configurable security policies, timeouts, and resource limits
Structured Configuration: YAML-based configuration with validation
Production Logging: Structured logging with multiple output formats
Graceful Shutdown: Proper signal handling and cleanup
Comprehensive Testing: Unit and integration tests for critical functionality
Clean Architecture: Modular design with separation of concerns

Installation

From Source

go install github.com/mjmorales/simple-mcp-runner@latest

Building Locally

git clone https://github.com/mjmorales/simple-mcp-runner.git
cd simple-mcp-runner
go build -o simple-mcp-runner

Quick Start

Run with default configuration:

simple-mcp-runner run

Run with custom configuration:

simple-mcp-runner run --config config.yaml

Run with debug logging:

simple-mcp-runner run --log-level debug

Configuration

Create a config.yaml file to customize the server behavior:

app: my-mcp-server
transport: stdio

# Define custom commands
commands:
  - name: list_files
    description: List files in current directory
    command: ls
    args: ["-la"]
    
  - name: show_date
    description: Show current date and time
    command: date

# Security settings
security:
  # Maximum command length
  max_command_length: 1000
  
  # Disable shell expansion for safety
  disable_shell_expansion: true
  
  # Block dangerous commands
  blocked_commands:
    - rm
    - dd
    - mkfs
    - shutdown
    - reboot
    
  # Or use a whitelist approach
  # allowed_commands:
  #   - echo
  #   - ls
  #   - cat
  
  # Restrict execution to specific paths
  # allowed_paths:
  #   - /home/user/projects
  #   - /tmp

# Execution limits
execution:
  default_timeout: 30s
  max_timeout: 5m
  max_concurrent: 10
  max_output_size: 10485760  # 10MB
  kill_timeout: 5s

# Logging configuration
logging:
  level: info  # debug, info, warn, error
  format: text # text, json
  output: stderr
  include_source: false

# Command discovery settings
discovery:
  max_results: 100
  common_commands:
    - ls
    - cat
    - grep
    - find
    - git
    - npm
    - go
    - python
    - node

Usage

CLI Commands

Run the MCP Server

simple-mcp-runner run [flags]

Flags:
  -c, --config string       Path to configuration file
      --log-level string    Log level (debug, info, warn, error) (default "info")
      --log-format string   Log format (text, json) (default "text")
  -h, --help               Help for run

Validate Configuration

simple-mcp-runner validate --config config.yaml

Show Version

simple-mcp-runner version

MCP Tools

The server exposes the following tools via the Model Context Protocol:

1. Command Discovery

Name: discover_commands
Description: Discover available system commands
Parameters:
- pattern (optional): Filter pattern (e.g., "git*", "npm")
- max_results (optional): Limit number of results
- include_desc (optional): Include command descriptions

2. Command Execution

Name: execute_command
Description: Execute a system command
Parameters:
- command (required): Command to execute
- args (optional): Command arguments
- workdir (optional): Working directory
- timeout (optional): Execution timeout

3. Configured Commands

Custom commands defined in the configuration file are exposed as individual tools.

Security Considerations

This tool is designed for local development use only. Security features include:

Command Blocking: Dangerous commands are blocked by default
Shell Expansion Protection: Prevents shell injection attacks
Path Restrictions: Limit execution to specific directories
Resource Limits: Prevent resource exhaustion
Timeout Protection: Commands have configurable timeouts
Output Limits: Prevent memory exhaustion from large outputs

Architecture

The project follows clean architecture principles:

.
├── cmd/                    # CLI commands
│   ├── root.go
│   ├── run.go
│   ├── validate.go
│   └── version.go
├── internal/              # Private packages
│   ├── config/           # Configuration management
│   ├── discovery/        # Command discovery
│   ├── errors/          # Error handling
│   ├── executor/        # Command execution
│   ├── logger/          # Structured logging
│   └── server/          # MCP server implementation
├── pkg/                  # Public packages
│   └── types/           # Shared types
├── config.yaml          # Example configuration
├── go.mod
├── go.sum
└── main.go

Development

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./internal/executor

Building with Version Info

VERSION=$(git describe --tags --always --dirty)
COMMIT=$(git rev-parse --short HEAD)
BUILD_TIME=$(date -u '+%Y-%m-%d %H:%M:%S')

go build -ldflags "-X 'github.com/mjmorales/simple-mcp-runner/cmd.Version=$VERSION' \
  -X 'github.com/mjmorales/simple-mcp-runner/cmd.Commit=$COMMIT' \
  -X 'github.com/mjmorales/simple-mcp-runner/cmd.BuildTime=$BUILD_TIME'" \
  -o simple-mcp-runner

Code Quality

The codebase follows Go best practices:

Comprehensive error handling with context
Structured logging for debugging
Proper resource cleanup and timeouts
Thread-safe operations
Extensive test coverage

Contributing

Contributions are welcome! Please ensure:

Code follows Go conventions
Tests are included for new functionality
Documentation is updated as needed
Security implications are considered

License

MIT License

Acknowledgments

Built using:

Cobra for CLI
Model Context Protocol SDK for MCP support
Go standard library for robust system interaction