Sign inSign up

rafadotel/mcp-shell

By rafadotel

•Updated 10 months ago

Image
0

1.9K

rafadotel/mcp-shell repository overview

⁠MCP Shell

CI Main CI Dev Container Build Documentation Go Report Card Coverage

Last release Docker Pulls Docker Image Size License: GPL v3 Documentation

MCP Shell Server for serving shell AI models

⁠Installation

⁠Using Nix (Recommended)
# With flakes enabled
nix run github:rafa-dot-el/mcp-shell

# Or install to profile
nix profile install github:rafa-dot-el/mcp-shell
⁠GitHub Releases

Download the latest binary from the releases page⁠:

# Linux/macOS
curl -L https://github.com/rafa-dot-el/mcp-shell/releases/latest/download/mcp-shell_linux_amd64.tar.gz | tar xz
sudo mv mcp-shell /usr/local/bin/

# Verify installation
mcp-shell version
⁠Container
# Run with Docker/Podman (Docker Hub)
docker run --rm rafadotel/mcp-shell:latest --help

# Run from GitHub Container Registry
docker run --rm ghcr.io/rafa-dot-el/mcp-shell:latest --help

# Pull specific version
docker pull rafadotel/mcp-shell:v0.1.0
docker pull ghcr.io/rafa-dot-el/mcp-shell:v0.1.0

# Run development version
docker run --rm rafadotel/mcp-shell:dev --help
⁠Build from Source
# Clone and build
git clone https://github.com/rafa-dot-el/mcp-shell.git
cd mcp-shell
go build -o mcp-shell ./cmd/mcp-shell

⁠Quick Start

# Basic usage
mcp-shell --help

# Show version
mcp-shell version

# Configuration help
mcp-shell --config /path/to/config.yaml

# Enable verbose output
mcp-shell --verbose

⁠Configuration

MCP Shell supports multiple configuration methods with the following precedence (highest to lowest):

  1. Command line flags (highest priority)
  2. Environment variables (MCP-SHELL_*)
  3. Configuration files
  4. Default values (lowest priority)
⁠Configuration Files

Configuration files are searched in the following order:

  1. --config flag path (if specified)
  2. ~/.config/mcp-shell/config.yaml
  3. ./mcp-shell.yaml (current directory)
  4. /etc/mcp-shell/config.yaml

Example configuration file:

# ~/.config/mcp-shell/config.yaml
verbose: false
debug: false
log_level: info
⁠Environment Variables

All configuration options can be set via environment variables:

export MCP-SHELL_VERBOSE=true
export MCP-SHELL_DEBUG=false
export MCP-SHELL_LOG_LEVEL=debug

⁠Development

⁠Prerequisites
⁠Setup
# Clone repository
git clone https://github.com/rafa-dot-el/mcp-shell.git
cd mcp-shell

# Enter development environment (with direnv)
direnv allow

# Or manually
nix develop

# Install dependencies and build
task deps
task build
⁠Available Tasks

Use task to see all available development tasks:

task                    # List all tasks
task build             # Build the binary
task test              # Run all tests
task lint              # Run linters
task vuln              # Security scans
task clean             # Clean artifacts
task dev-setup         # Setup development environment
⁠Development Helpers

The project includes helpful development functions in functions.sh:

# Available after entering nix develop
build-watch            # Watch for changes and rebuild
test-watch             # Watch for changes and retest
go-coverage            # Generate coverage report
security-scan          # Run security scanners
dev-help               # Show all available helpers
⁠Testing
# Run all tests
task test

# Run specific test types
task test-unit
task test-integration
task test-e2e

# Run with coverage
go-coverage
⁠Release Process
  1. Update VERSION file
  2. Create and push tag: 
    task version-bump-minor  # or patch/major
task version-tag
git push origin v$(cat VERSION)
  3. GitHub Actions will automatically build and publish the release

⁠Documentation

Full documentation is available at: https://rafa-dot-el.github.io/mcp-shell⁠

⁠Building Documentation
task docs-build         # Build Hugo site
task docs-serve         # Serve locally
task docs-test          # Test documentation

⁠Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes following the coding standards
  4. Run tests: task test
  5. Run linting: task lint
  6. Commit changes: git commit -am 'Add feature'
  7. Push to branch: git push origin feature-name
  8. Submit a Pull Request
⁠Code Standards
  • Follow Go conventions and best practices
  • All functions must have 100% test coverage
  • Use GPL3-compatible dependencies only
  • Include proper GPL3 license headers
  • Document all public functions and types

⁠Security

Security issues should be reported privately to <>.

For general vulnerabilities:

  • Run task vuln to check for known vulnerabilities
  • Security scans are run automatically in CI/CD

⁠License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE⁠ file for details.

⁠Support

⁠Acknowledgments

Built with:

Copyright (C) 2025 Rafael. Licensed under GPL-3.0.

Tag summary

Content type

Image

Digest

sha256:7cfeda703…

Size

2.7 MB

Last updated

12 months ago

docker pull rafadotel/mcp-shell