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:
- 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
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 resultsinclude_desc (optional): Include command descriptions
2. Command Execution
- Name:
execute_command - Description: Execute a system command
- Parameters:
command (required): Command to executeargs (optional): Command argumentsworkdir (optional): Working directorytimeout (optional): Execution timeout
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: