mcp-execution-cli

Command-line interface for MCP Code Execution progressive loading. Achieves 98% token savings by generating one TypeScript file per MCP tool.

Installation

Pre-built binaries

Download from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-macos-arm64.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-macos-amd64.tar.gz | tar xz

# Linux (x86_64)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-linux-amd64.tar.gz | tar xz

From crates.io

cargo install mcp-execution-cli

From source

git clone https://github.com/bug-ops/mcp-execution
cd mcp-execution
cargo install --path crates/mcp-cli

[!IMPORTANT] Requires Rust 1.91 or later for building from source.

Usage

Generate Progressive Loading Files

# From config file (recommended)
mcp-execution-cli generate --from-config github

# With manual configuration
mcp-execution-cli generate github-mcp-execution-server --env GITHUB_TOKEN=ghp_xxx

[!TIP] Use --from-config to load server configuration from ~/.claude/mcp.json.

Discover Available Tools

# List available servers
ls ~/.claude/servers/

# List tools in a server
ls ~/.claude/servers/github/

# Load one tool (98% token savings!)
cat ~/.claude/servers/github/createIssue.ts

Shell Completions

# Bash
mcp-execution-cli completions bash > /etc/bash_completion.d/mcp-execution-cli

# Zsh
mcp-execution-cli completions zsh > ~/.zsh/completions/_mcp-execution-cli

# Fish
mcp-execution-cli completions fish > ~/.config/fish/completions/mcp-execution-cli.fish

Commands

generate

Generate TypeScript files with progressive loading:

mcp-execution-cli generate <SERVER> [OPTIONS]

Options:

• --from-config <NAME>: Load config from mcp.json
• --arg <ARG>: Server command argument (repeatable)
• --env <KEY=VALUE>: Environment variable (repeatable)
• --name <NAME>: Custom server name for output directory
• --progressive-output <PATH>: Custom output directory
• --dry-run: Preview files that would be generated without writing to disk
• --format <FORMAT>: Output format (json, text, pretty)

Examples:

# From config
mcp-execution-cli generate --from-config github

# Preview without writing
mcp-execution-cli generate --from-config github --dry-run

# Docker container with custom name
mcp-execution-cli generate docker \
  --arg=run --arg=-i --arg=--rm \
  --arg=ghcr.io/org/server \
  --env=API_KEY=xxx \
  --name=myserver

introspect

Analyze MCP servers and discover capabilities:

mcp-execution-cli introspect <SERVER> [OPTIONS]

Configuration Modes:

1. Load from ~/.claude/mcp.json (recommended):

   mcp-execution-cli introspect --from-config github
   

2. Manual configuration:

   mcp-execution-cli introspect github-mcp-execution-server --arg=stdio
   

Options:

• --from-config <NAME>: Load config from mcp.json
• --arg <ARG>: Server command argument (repeatable)
• --env <KEY=VALUE>: Environment variable (repeatable)
• --detailed: Show full input/output schemas
• --format <FORMAT>: Output format (json, text, pretty)
• --http <URL>: Use HTTP transport
• --sse <URL>: Use SSE transport

Examples:

# From config with detailed schemas
mcp-execution-cli introspect --from-config github --detailed

# Manual with Docker
mcp-execution-cli introspect docker \
  --arg=run --arg=-i --arg=--rm \
  --arg=ghcr.io/github/github-mcp-execution-server \
  --env=GITHUB_TOKEN=ghp_xxx

# HTTP transport
mcp-execution-cli introspect --http https://api.example.com/mcp \
  --header "Authorization=Bearer token"

skill

Generate Claude Code skill files (SKILL.md) from progressive loading tools:

mcp-execution-cli skill --server <SERVER_ID> [OPTIONS]

Options:

• --server, -s <ID>: Server identifier (required)
• --servers-dir <PATH>: Custom servers directory
• --output, -o <PATH>: Custom output path
• --skill-name <NAME>: Custom skill name
• --hint <HINT>: Use case hints (repeatable)
• --overwrite: Overwrite existing SKILL.md

Examples:

# Generate skill for GitHub server
mcp-execution-cli skill --server github

# With custom output and hints
mcp-execution-cli skill --server github \
  --output ~/.claude/skills/github/SKILL.md \
  --hint "managing pull requests" \
  --hint "code review"

# Overwrite existing skill
mcp-execution-cli skill --server github --overwrite

[!TIP] For optimal results, prefer using the MCP server (mcp-execution-server) for skill generation. The MCP server can leverage LLM capabilities to summarize tool descriptions and reduce context size, resulting in more concise and effective skill files.

server

Manage MCP server configurations from ~/.claude/mcp.json:

# List all configured servers
mcp-execution-cli server list

# Show detailed information about a server
mcp-execution-cli server info github

# Validate a server command
mcp-execution-cli server validate docker

setup

Validate the runtime environment for generated MCP tool execution:

mcp-execution-cli setup

# Output:
# ✓ Node.js v20.10.0 detected
# ✓ MCP configuration found
# ✓ Runtime setup complete

Checks that Node.js 18+ is installed, ~/.claude/mcp.json exists, and makes generated TypeScript files executable (Unix only).

completions

Generate shell completions:

mcp-execution-cli completions <SHELL>

[!NOTE] Supported shells: bash, zsh, fish, powershell

Features

• Progressive Loading: One TypeScript file per MCP tool
• Type-Safe: Full TypeScript interfaces from MCP schemas
• Multiple Transports: stdio, HTTP, SSE, Docker
• Shell Completions: bash, zsh, fish, PowerShell
• Fast: ~2-3ms generation time per server

Token Savings

Security

• No Code Execution: Generated TypeScript is for type information only
• Command Injection Prevention: All user input validated
• Path Validation: Rejects malicious paths
• Template Security: Handlebars escapes all user input

[!WARNING] Never pass untrusted input directly to --arg or --env options.

Related Crates

This crate is part of the mcp-execution workspace:

• mcp-execution-core - Foundation types
• mcp-execution-introspector - MCP server analysis
• mcp-execution-codegen - TypeScript code generation
• mcp-execution-files - Virtual filesystem
• mcp-execution-skill - Skill generation
• mcp-execution-server - MCP server

MSRV Policy

Minimum Supported Rust Version: 1.91

MSRV increases are considered minor version bumps.

License

Licensed under either of Apache License 2.0 or MIT license at your option.