@aurracloud/mcp-cli/README.md

A command-line tool to install, manage, and setup MCP (Model Context Protocol) servers with Docker support

# MCP CLI
    ███╗   ███╗ ██████╗██████╗ 
    ████╗ ████║██╔════╝██╔══██╗
    ██╔████╔██║██║     ██████╔╝
    ██║╚██╔╝██║██║     ██╔═══╝ 
    ██║ ╚═╝ ██║╚██████╗██║     
    ╚═╝     ╚═╝ ╚═════╝╚═╝     
    By aurracloud.com
    CLI to install and setup MCP servers
    
[![npm version](https://badge.fury.io/js/@aurracloud%2Fmcp-cli.svg)](https://badge.fury.io/js/@aurracloud%2Fmcp-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A command-line tool to install, manage, and setup MCP (Model Context Protocol) servers with Docker support.

## Features

✨ **Global CLI Tool**: Install once with `npm install -g` and use the `mcp` command anywhere  
🐳 **Docker Support**: Secure, sandboxed execution of MCP servers by default  
🔍 **Multi-Registry Search**: Supports npm, GitHub, and Smithery registries  
📦 **GitHub URL Support**: Install and uninstall directly from GitHub repositories  
🛡️ **Security First**: Docker isolation by default, with optional direct execution  
📋 **Smart Configuration**: Automatic detection and setup of MCP server configurations  
🔧 **Comprehensive Management**: Install, uninstall, list, and get info about servers  
⚡ **Flexible Usage**: Global installation recommended, npx available for one-time use  
🤖 **JSON Mode**: Structured output for automation and programmatic use  
⚙️ **Configuration Arguments**: Non-interactive setup with `--args` flag  
📊 **Multiple Log Levels**: Verbose, debug, and quiet modes for different use cases

## Quick Start

Install globally for the best experience:

```bash
# Install globally (recommended)
npm install -g @aurracloud/mcp-cli

# Now you can use the 'mcp' command anywhere
mcp install @modelcontextprotocol/server-filesystem -c claude
mcp list -c claude
mcp info @modelcontextprotocol/server-filesystem
```

## Global Options

The MCP CLI supports global options that can be used with any command:

```bash
# Verbose output - shows detailed progress information
mcp install package-name -c claude --verbose

# Debug output - shows comprehensive debugging information
mcp install package-name -c claude --debug

# Quiet mode - suppresses all output except errors
mcp install package-name -c claude --quiet

# JSON mode commands automatically use quiet mode
mcp install package-name -c claude --json  # Automatically quiet
mcp info package-name --json              # Automatically quiet
```

**Global Options:**

- **`-v, --verbose`**: Enable verbose output with detailed progress information
- **`-d, --debug`**: Enable debug output with comprehensive debugging details
- **`-q, --quiet`**: Suppress all output except errors (useful for scripting)

**Note:** JSON mode (`--json`) automatically enables quiet mode to prevent logging interference with structured output.

## Installation

### Global Installation (Recommended)

Install once and use everywhere:

```bash
# Install globally from npm
npm install -g @aurracloud/mcp-cli

# Now you can run the command from anywhere
mcp install package-name -c claude
mcp info package-name
mcp list -c claude
mcp uninstall package-name -c claude
```

### One-time Use with npx

For occasional use without installation:

```bash
# Run commands directly without installing
npx @aurracloud/mcp-cli install package-name -c claude
npx @aurracloud/mcp-cli info package-name
npx @aurracloud/mcp-cli list -c claude
npx @aurracloud/mcp-cli uninstall package-name -c claude
```

### Local Development

```bash
# Clone the repository
git clone https://github.com/aurracloud/mcp-cli.git
cd mcp-cli

# Install dependencies
npm install

# Run in development mode
npm run dev

# Or build and run
npm run build
npm start
```

## Usage

### Install an MCP Server

```bash
# Install with default options (uses Docker for security)
mcp install package-name -c claude

# Run the MCP server directly on host (not recommended)
mcp install package-name -c claude -d

# JSON mode for programmatic use
mcp install package-name -c claude --json

# Install with configuration arguments
mcp install package-name -c claude --args API_KEY=secret DEBUG_MODE=true

# JSON mode with configuration (for automation)
mcp install package-name -c claude --json --args API_KEY=secret --verbose=true

# Direct installation with configuration
mcp install package-name -c claude --direct --args FILESYSTEM_ROOT=/tmp

# Or use npx for one-time use
npx @aurracloud/mcp-cli install package-name -c claude
```

**Installation Options:**

- **`-c, --client <client>`** (required): Specify the client (cursor, claude)
- **`-d, --direct`**: Run directly on host instead of Docker (not recommended for security)
- **`-j, --json`**: Output installation result in JSON format for programmatic use
- **`-a, --args <args...>`**: Provide configuration arguments in `key=value` format

**JSON Mode:**

The `--json` flag enables structured output perfect for automation and scripting:

```bash
# Successful installation returns structured data
mcp install @modelcontextprotocol/server-filesystem -c cursor --json --args FILESYSTEM_ROOT=/tmp
```

```json
{
  "success": true,
  "packageName": "@modelcontextprotocol/server-filesystem",
  "serverName": "@modelcontextprotocol/server-filesystem",
  "client": "cursor",
  "installationMode": "docker",
  "runtime": "node",
  "configuration": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "FILESYSTEM_ROOT=/tmp", "node:latest", "npx", "-y", "@modelcontextprotocol/server-filesystem"]
  },
  "environmentVariables": 1
}
```

```bash
# Errors also return structured JSON
mcp install nonexistent-package -c cursor --json
```

```json
{
  "success": false,
  "error": "Package nonexistent-package does not exist on npm registry or PyPI.",
  "packageName": "nonexistent-package"
}
```

**Configuration Arguments:**

Use the `--args` flag to provide configuration without interactive prompts:

```bash
# Environment variables (key=value format)
mcp install server-name -c claude --args API_KEY=secret DATABASE_URL=postgres://...

# Command line arguments (--flag=value format)  
mcp install server-name -c claude --args --port=3000 --host=localhost

# Mixed configuration
mcp install server-name -c claude --args API_KEY=secret --verbose=true DEBUG_MODE=false
```

**How it works:**

The install command:
- By default, runs MCP servers in a Docker container for better security and isolation
- Will display a prominent warning if you choose to install directly with the `-d` flag
- Automatically detects the server's connection type from the Smithery registry
  - For HTTP connections, it will use the deployment URL
  - For StdIO connections, it will use the recommended command and arguments if available
- In JSON mode, automatically sets quiet logging to prevent output interference
- Validates required configuration arguments when MCP server configuration is detected
- Supports both Node.js (npm/npx) and Python (PyPI/uvx) packages

### Uninstall an MCP Server

```bash
# Uninstall from a specific client
mcp uninstall package-name -c claude

# Also works with GitHub URLs (resolves to actual package name)
mcp uninstall https://github.com/owner/repo -c claude
mcp uninstall owner/repo -c claude

# Or use npx for one-time use
npx @aurracloud/mcp-cli uninstall package-name -c claude
```

The uninstall command now intelligently resolves GitHub URLs to the actual package name by:
- Cloning the repository and reading the package.json to get the real package name
- Trying multiple name variations to find the installed server
- Providing helpful feedback about which names were tried if the server isn't found

### List Installed MCP Servers

The `list` command displays all currently installed MCP servers for a specific client:

```bash
# List all MCP servers for Claude
mcp list -c claude

# List all MCP servers for Cursor
mcp list -c cursor

# Or use npx for one-time use
npx @aurracloud/mcp-cli list -c claude
```

**Features:**
- **Comprehensive Overview**: Shows all installed MCP servers with their configurations
- **Installation Type Detection**: Identifies Docker-based (sandboxed) vs direct installations
- **Configuration Details**: Displays commands, arguments, and additional configuration
- **Summary Statistics**: Provides counts by installation type
- **Helpful Tips**: Includes guidance for managing servers
- **Error Handling**: Clear messages for missing or invalid configurations

**What it shows:**
- Server names and types
- Command and arguments used to run each server
- Whether servers run in Docker (safer) or directly on host
- Additional configuration like environment variables, URLs, headers
- Summary of installation types
- Configuration file location and total server count

### Get MCP Server Information

The `info` command provides comprehensive information about MCP servers by checking multiple registries with intelligent fallback:

```bash
# Get information about a server (checks npm, GitHub, and Smithery)
mcp info package-name

# Works with multiple formats
mcp info express                    # npm package
mcp info owner/repo                 # GitHub repository
mcp info @owner/repo               # npm scoped package format
mcp info https://github.com/owner/repo  # full GitHub URL

# JSON mode for programmatic use
mcp info package-name --json

# Or use npx for one-time use
npx @aurracloud/mcp-cli info package-name

# Set your Smithery API token for additional registry information
export SMITHERY_API_TOKEN=your-token
```

**Options:**

- **`-j, --json`**: Output information in structured JSON format for automation

**JSON Mode:**

The `--json` flag provides structured output perfect for automation:

```bash
# Get structured information about a package
mcp info @modelcontextprotocol/server-filesystem --json
```

```json
{
  "packageName": "@modelcontextprotocol/server-filesystem",
  "npm": {
    "found": true,
    "packageInfo": {
      "name": "@modelcontextprotocol/server-filesystem",
      "version": "0.6.2",
      "description": "MCP server for filesystem operations"
    },
    "isExecutable": true,
    "command": "npx -y @modelcontextprotocol/server-filesystem"
  },
  "git": {
    "found": true,
    "repoInfo": {
      "name": "servers",
      "fullName": "modelcontextprotocol/servers"
    },
    "isExecutable": true
  },
  "smithery": {
    "found": true,
    "serverDetails": {
      "qualifiedName": "@modelcontextprotocol/server-filesystem",
      "displayName": "Filesystem Server"
    }
  },
  "summary": {
    "foundInNpm": true,
    "foundInGit": true,
    "foundInSmitery": true,
    "hasMcpConfig": true
  }
}
```

**How it works:**
1. **NPM Registry Check**: First checks if the package exists on npm and is executable
2. **GitHub Fallback**: If not found on npm, searches GitHub repositories (supports all repository formats)
3. **Smithery Registry**: Always checks Smithery registry for additional MCP server information
4. **Comprehensive Results**: Displays information from all available sources with a summary

### Upgrade MCP CLI

Keep your CLI tool up to date with the latest features and bug fixes:

```bash
# Upgrade to the latest version
mcp upgrade

# Or use npx (always gets latest version)
npx @aurracloud/mcp-cli upgrade
```

This command:
- Automatically detects the package name from package.json
- Checks the current version against the latest version on npm
- Downloads and installs the latest version globally
- Provides clear feedback on the upgrade process
- Handles common errors like permission issues

## Automation & Scripting

The MCP CLI is designed for both interactive use and automation. Use JSON mode and configuration arguments for seamless integration into scripts and CI/CD pipelines.

### JSON Mode Examples

```bash
# Install with JSON output for automation
RESULT=$(mcp install @modelcontextprotocol/server-filesystem -c cursor --json --args FILESYSTEM_ROOT=/tmp)
echo $RESULT | jq '.success'  # true

# Check installation status
if echo $RESULT | jq -e '.success' > /dev/null; then
  echo "Installation successful"
  echo $RESULT | jq '.configuration.command'
else
  echo "Installation failed:"
  echo $RESULT | jq '.error'
fi

# Get package information programmatically
INFO=$(mcp info @modelcontextprotocol/server-filesystem --json)
echo $INFO | jq '.summary.foundInNpm'  # true
echo $INFO | jq '.npm.packageInfo.version'  # "0.6.2"
```

### Batch Installation Script

```bash
#!/bin/bash

# List of servers to install
SERVERS=(
  "@modelcontextprotocol/server-filesystem"
  "@modelcontextprotocol/server-brave-search"
  "custom-server"
)

# Configuration for each server
declare -A SERVER_ARGS
SERVER_ARGS["@modelcontextprotocol/server-filesystem"]="FILESYSTEM_ROOT=/home/user"
SERVER_ARGS["@modelcontextprotocol/server-brave-search"]="BRAVE_API_KEY=your-key"
SERVER_ARGS["custom-server"]="API_KEY=secret DEBUG_MODE=true"

# Install each server
for server in "${SERVERS[@]}"; do
  echo "Installing $server..."
  
  args="${SERVER_ARGS[$server]}"
  if [ -n "$args" ]; then
    result=$(mcp install "$server" -c cursor --json --args $args)
  else
    result=$(mcp install "$server" -c cursor --json)
  fi
  
  if echo "$result" | jq -e '.success' > /dev/null; then
    echo "✅ $server installed successfully"
  else
    echo "❌ Failed to install $server:"
    echo "$result" | jq '.error'
  fi
done
```

### CI/CD Integration

```yaml
# GitHub Actions example
name: Install MCP Servers
on: [push]

jobs:
  install-servers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install MCP CLI
        run: npm install -g @aurracloud/mcp-cli
        
      - name: Install MCP Server
        run: |
          result=$(mcp install @modelcontextprotocol/server-filesystem -c cursor --json --args FILESYSTEM_ROOT=/workspace)
          echo "$result" | jq '.success' || exit 1
          
      - name: Verify Installation
        run: |
          info=$(mcp info @modelcontextprotocol/server-filesystem --json)
          echo "Installed version: $(echo "$info" | jq -r '.npm.packageInfo.version')"
```

## Git Repository Integration

The CLI also includes utilities to check if GitHub repositories exist and whether they're executable via npx. This is particularly useful for MCP servers that are not published to npm but are available on GitHub:

```typescript
import { checkGitRepoExistence, getGitNpxCommand, parseGitHubIdentifier } from './git';

// Check if a GitHub repository exists and is executable
const result = await checkGitRepoExistence('owner/repo');

if (result.exists) {
  console.log('Repository exists on GitHub!');
  
  if (result.packageInfo) {
    console.log('Repository has a package.json');
    
    if (result.isExecutable) {
      console.log('Repository is executable via npx');
      console.log(`Executable: ${result.executableName}`);
    }
  }
}

// Get the recommended command to run the repository
const npxCmd = await getGitNpxCommand('owner/repo');
if (npxCmd) {
  console.log(`Run with: ${npxCmd.command} ${npxCmd.args.join(' ')}`);
}
```

### Supported Repository Formats

The git integration supports multiple repository identifier formats:

- `owner/repo` - Simple owner/repository format
- `@owner/repo` - npm scoped package format (@ symbol is automatically removed)
- `https://github.com/owner/repo` - Full GitHub URL
- `https://github.com/owner/repo.git` - Full GitHub URL with .git extension
- `git@github.com:owner/repo.git` - SSH format

### Features

- **Repository Existence Check**: Verifies if a repository exists on GitHub using the GitHub API
- **Automatic Cloning**: Clones repositories to temporary directories for analysis
- **Package.json Detection**: Checks if the repository contains a valid package.json file
- **Executability Analysis**: Determines if the package can be run via npx (has bin entries or start script)
- **Automatic Cleanup**: Removes temporary cloned repositories after analysis
- **Rich Repository Information**: Provides detailed information about the repository including description, language, license, and topics

### Example Usage

```bash
# Check a repository using the example script
npx ts-node examples/check-git-repo.ts facebook/create-react-app
npx ts-node examples/check-git-repo.ts https://github.com/vercel/pkg
npx ts-node examples/check-git-repo.ts @microsoft/vscode
npx ts-node examples/check-git-repo.ts microsoft/vscode
```

See the examples in `examples/check-git-repo.ts` for more details.

## Development

### Building the Project

```bash
npm run build
```

### Adding New Commands

1. Create a new file in the `src/commands/` directory
2. Implement your command function
3. Import and register the command in `src/index.ts`

### Releasing (Maintainers Only)

We use automated releases with GitHub Actions. Use the interactive release script:

```bash
# Interactive release (recommended)
npm run release

# Or quick releases
npm run release:patch    # Bug fixes
npm run release:minor    # New features  
npm run release:major    # Breaking changes
```

This will automatically:
- Update package.json version
- Create a git tag
- Trigger GitHub Actions to create a release and publish to npm

See [RELEASE.md](./RELEASE.md) for detailed instructions.

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Build and test: `npm run build`
5. Commit your changes: `git commit -am 'Add feature'`
6. Push to the branch: `git push origin feature-name`
7. Submit a pull request

## License

MIT