shell-mcp

Shell MCP (Model Control Protocol)

A lightweight Bash implementation of an MCP server that allows creating and using custom command-line tools via a JSON-RPC interface.

Overview

Shell MCP provides a simple framework to create, manage, and use custom command-line tools. The server loads tools from the tools directory and makes them available through a standardized interface.

Getting Started

Running the Server

To start the MCP server with the default configuration:

./mcp-server.sh

The server will load all tools from the tools directory and begin listening for commands via stdin.

Adding New Tools

Shell MCP includes a CLI option to easily create new tools.

Command Line Options

# Create a new tool
./mcp-server.sh --add-tool NAME DESCRIPTION "PARAM1:TYPE,PARAM2:TYPE"

# Show help information
./mcp-server.sh --help

Example: Creating a New Tool

# Create a new multiplication tool
./mcp-server.sh --add-tool multiply "Multiplies two numbers" "num1:int,num2:int"

This will generate a new tool file at tools/multiply.tool.sh with a basic implementation template.

Contributing Your Own Tools

We welcome contributions from the community! You can create your own general-purpose tools and submit them as pull requests.

Guidelines for contributing tools:

1. Tools should be general-purpose and useful to a wide audience
2. Follow the existing pattern for tool implementation
3. Include clear documentation within your tool file
4. Make sure your tool works correctly before submitting
5. Submit a pull request with your tool added to the tools directory

Tool Structure

Each tool consists of:

1. A function that implements the tool's logic
2. A call to register_tool to make the tool available to the server

Here's an example of a simple tool implementation:

#!/usr/bin/env bash

# Addition tool implementation

# Function that performs the addition
addition_impl() {
    local num1=$1
    local num2=$2
    
    # Calculate the sum
    local sum=$((num1 + num2))
    echo "sum of two numbers is $sum"
}

# Register the tool with the server
register_tool \
    "addition" \
    "addition of two numbers" \
    "num1:int,num2:int" \
    "addition_impl"

Important Notes for Tool Development

1. Each tool function should accept parameters in the order they are defined
2. Tools must use a single echo statement at the end to return their result
3. Parameter types are for documentation only - all parameters are passed as strings
4. Make the tool file executable with chmod +x after creating it manually

Project Structure

shell-mcp/
├── mcp-server.sh       # Main server script
├── tools/              # Directory containing all tools
│   ├── addition.tool.sh    # Example tool
│   ├── bmi_calculator.tool.sh  # Example tool
│   └── pokemon_fetcher.tool.sh # Example tool
└── mcp_server.log     # Server log file (created when server runs)

Protocol

The server implements a simplified JSON-RPC interface with the following methods:

• initialize: Initializes the server and returns its capabilities
• tools/list: Lists all available tools with their descriptions and parameters
• tools/call: Calls a specific tool with the provided arguments
• resources/list: Lists available resources (not implemented)
• prompts/list: Lists available prompts (not implemented)

Requirements

• Bash 4.0 or higher
• jq for JSON processing

License

This project is open source and available under the MIT License.