mcp-execution-cli 0.6.4

CLI for MCP progressive loading code generation
Documentation

mcp-execution-cli

Crates.io docs.rs MSRV License

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.89 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)
  • --progressive-output <PATH>: Custom output directory
  • --format <FORMAT>: Output format (json, text, pretty)

Examples:

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

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

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.

stats

View cache statistics:

mcp-execution-cli stats

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

Approach Tokens Savings
Traditional (all tools) ~30,000 -
Progressive (1 tool) ~500-1,500 98%

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:

MSRV Policy

Minimum Supported Rust Version: 1.89

MSRV increases are considered minor version bumps.

License

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