https://github.com/bug-ops/mcp-execution
🚀 Generate executable TypeScript tools from MCP servers with 98% token savings. Progressive loading pattern for AI agents. Production-ready.
https://github.com/bug-ops/mcp-execution
ai-agent ai-tools anthropic claude llm-tools mcp rust skills
Last synced: 28 days ago
JSON representation
🚀 Generate executable TypeScript tools from MCP servers with 98% token savings. Progressive loading pattern for AI agents. Production-ready.
- Host: GitHub
- URL: https://github.com/bug-ops/mcp-execution
- Owner: bug-ops
- License: other
- Created: 2025-11-12T14:47:09.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2026-06-02T03:27:54.000Z (about 1 month ago)
- Last Synced: 2026-06-02T05:13:51.412Z (about 1 month ago)
- Topics: ai-agent, ai-tools, anthropic, claude, llm-tools, mcp, rust, skills
- Language: Rust
- Homepage:
- Size: 1.08 MB
- Stars: 45
- Watchers: 0
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-AI-driven-development - MCP Code Execution - Generate executable TypeScript tools from MCP servers with 98% token savings. Progressive loading pattern for AI agents. Production-ready. (MCP Servers & Integrations / Other IDEs)
README
# MCP Code Execution
[](https://crates.io/crates/mcp-execution-cli)
[](https://docs.rs/mcp-execution-core)
[](https://github.com/bug-ops/mcp-execution/actions/workflows/ci.yml)
[](https://codecov.io/gh/bug-ops/mcp-execution)
[](https://blog.rust-lang.org/2025/01/23/Rust-1.91.0.html)
[](LICENSE.md)
Transform any MCP server into executable, type-safe TypeScript tools using progressive loading pattern. Achieve **98% token savings** by loading only what you need.
> [!TIP]
> Inspired by [Anthropic's engineering blog post](https://www.anthropic.com/engineering/code-execution-with-mcp) on Code Execution with MCP.
## The Problem
Traditional MCP integration loads ALL tools from a server (~30,000 tokens), even when you only need one or two. This wastes context window space and slows down AI agents.
## The Solution
Progressive loading generates one TypeScript file per tool (~500-1,500 tokens each). AI agents discover and load only what they need via simple `ls` and `cat` commands.
**Result**: **98% token savings** + **autonomous execution** + **type safety**
## Installation
### From crates.io (recommended)
```bash
cargo install mcp-execution-cli
```
Pre-built binaries
Download from [GitHub Releases](https://github.com/bug-ops/mcp-execution/releases/latest):
```bash
# 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
# Linux (ARM64)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-linux-arm64.tar.gz | tar xz
# Windows (x86_64)
# Download mcp-execution-cli-windows-amd64.zip from releases page
```
From source
```bash
git clone https://github.com/bug-ops/mcp-execution
cd mcp-execution
cargo install --path crates/mcp-cli
```
As a library
Add individual crates to your project:
```bash
cargo add mcp-execution-core # Foundation types
cargo add mcp-execution-introspector # MCP server analysis
cargo add mcp-execution-codegen # TypeScript generation
cargo add mcp-execution-files # Virtual filesystem
cargo add mcp-execution-skill # SKILL.md generation
```
Or add to `Cargo.toml`:
```toml
[dependencies]
mcp-execution-core = "0.7"
mcp-execution-introspector = "0.7"
mcp-execution-codegen = "0.7"
```
> [!IMPORTANT]
> Requires Rust 1.91 or later for building from source.
## Usage
### Generate TypeScript Tools
```bash
# 1. Configure MCP server in ~/.claude/mcp.json
# 2. Generate tools
mcp-execution-cli generate --from-config github
# Output: ~/.claude/servers/github/
# - createIssue.ts
# - updateIssue.ts
# - ... (one file per tool)
```
### Progressive Loading
```bash
# List available tools
ls ~/.claude/servers/github/
# Load only what you need (98% token savings!)
cat ~/.claude/servers/github/createIssue.ts
# Execute autonomously
node ~/.claude/servers/github/createIssue.ts --repo="owner/repo" --title="Bug"
```
> [!NOTE]
> Each tool file is self-contained with full TypeScript interfaces and JSDoc documentation.
## Key Features
| Feature | Description |
|---------|-------------|
| **98% Token Savings** | Load 1 tool (~500 tokens) vs all tools (~30,000 tokens) |
| **Autonomous Execution** | Generated files run directly via Node.js CLI |
| **Type-Safe** | Full TypeScript interfaces from MCP JSON schemas |
| **Lightning Fast** | 526x faster than target (0.19ms for 10 tools) |
| **100% MCP Compatible** | Works with all MCP servers via [rmcp SDK](https://docs.rs/rmcp) |
| **Thoroughly Tested** | 657 tests with 100% pass rate |
## Workspace Crates
| Crate | Description |
|-------|-------------|
| [mcp-execution-core](crates/mcp-core) | Foundation types, traits, and error handling |
| [mcp-execution-introspector](crates/mcp-introspector) | MCP server analysis using rmcp SDK |
| [mcp-execution-codegen](crates/mcp-codegen) | TypeScript code generation with progressive loading |
| [mcp-execution-files](crates/mcp-files) | Virtual filesystem for code organization |
| [mcp-execution-skill](crates/mcp-skill) | SKILL.md generation for Claude Code |
| [mcp-execution-server](crates/mcp-server) | MCP server for progressive loading generation |
| [mcp-execution-cli](crates/mcp-cli) | Command-line interface |
**Dependency Graph**:
```text
mcp-execution-cli → {mcp-execution-codegen, mcp-execution-introspector, mcp-execution-files, mcp-execution-core, mcp-execution-skill}
mcp-execution-server → {mcp-execution-codegen, mcp-execution-introspector, mcp-execution-files, mcp-execution-core, mcp-execution-skill}
mcp-execution-codegen → {mcp-execution-introspector, mcp-execution-core}
mcp-execution-files → mcp-execution-codegen
mcp-execution-introspector → {rmcp, mcp-execution-core}
mcp-execution-skill → mcp-execution-core
```
## CLI Commands
See [mcp-cli README](crates/mcp-cli) for full reference.
```bash
# Generate TypeScript tools from config (recommended)
mcp-execution-cli generate --from-config github
# Preview what would be generated without writing to disk
mcp-execution-cli generate --from-config github --dry-run
# Introspect MCP server from config
mcp-execution-cli introspect --from-config github
# Introspect with detailed schemas
mcp-execution-cli introspect --from-config github --detailed
# Manual configuration (alternative)
mcp-execution-cli introspect docker --arg=run --arg=-i --env=TOKEN=xxx
# Shell completions
mcp-execution-cli completions bash
```
> [!TIP]
> Use `--from-config` to load server settings from `~/.claude/mcp.json` instead of manual arguments.
## Performance
| Metric | Target | Achieved |
|--------|--------|----------|
| 10 tools generation | <100ms | **0.19ms** (526x faster) |
| 50 tools generation | <20ms | **0.97ms** (20.6x faster) |
| VFS export | <10ms | **1.2ms** (8.3x faster) |
| Memory (1000 tools) | <256MB | **~2MB** |
## Documentation
- [Progressive Loading Tutorial](examples/progressive-loading-usage.md) - Complete guide
- [Claude Code Integration](examples/SKILL.md) - Skill setup
- [Architecture Decisions](docs/adr/) - ADRs explaining design choices
## Development
```bash
cargo build --workspace # Build
cargo nextest run --workspace # Test
cargo clippy --workspace # Lint
cargo +nightly fmt --workspace # Format
```
> [!NOTE]
> All development follows [Microsoft Rust Guidelines](https://microsoft.github.io/rust-guidelines/).
## MSRV Policy
Minimum Supported Rust Version: **1.91**
MSRV increases are considered minor version bumps.
## License
Licensed under either of [Apache License 2.0](LICENSE.md) or [MIT license](LICENSE.md) at your option.