MCP Code Wrapper

⚠️ EXPERIMENTAL: This project is in active development and not production-ready. APIs may change without notice. Use at your own risk. Contributions and feedback welcome!

Transform MCP tool definitions into progressive discovery APIs (96% context savings)

Generate code execution wrappers for Model Context Protocol servers with automatic progressive tool discovery. Reduces context usage by up to 96% while maintaining full MCP functionality.

The Problem

Loading MCP servers directly into Claude Code bloats context with ALL tool definitions:

Chrome DevTools MCP:    17,500 tokens (26 tools)
MSSQL Database (×2):    11,200 tokens (16 tools)
─────────────────────────────────────────────
Total:                  28,700 tokens (14.5% of 200k context)

With 3-4 MCP servers, you easily hit 50k+ tokens before doing any actual work.

The Solution

Progressive Discovery via Filesystem Structure

Instead of loading all tools upfront, present them as a TypeScript API filesystem that Claude explores on-demand:

api-universal/
├── index.ts              # Root discovery (~100 tokens)
├── navigation/           # 6 tools
│   ├── navigate_page.ts  # Load only when needed
│   └── index.ts
├── debugging/            # 5 tools
└── ...

Claude reads only what it needs:

Read root index → discover categories
Explore category → see available tools
Read specific tools → get documentation
Use the APIs → execute via MCP

Result: ~550 tokens for a typical 2-tool task (vs 28,700 tokens)

Quick Start

Install

# Via npx (no install needed)
npx mcp-code-wrapper .                # Current directory
npx mcp-code-wrapper /path/to/project # Specific project
npx mcp-code-wrapper --global         # Global ~/.claude/ MCPs
npx mcp-code-wrapper --help           # Show help

# Or clone and run locally
git clone https://github.com/paddo/mcp-code-wrapper
cd mcp-code-wrapper
pnpm install
pnpm run generate /path/to/project

Usage

Project Mode (converts MCPs in a project):

npx mcp-code-wrapper .                # Current directory (interactive selection)
npx mcp-code-wrapper /path/to/project # Specific directory (interactive selection)
npx mcp-code-wrapper . --all          # Generate all servers without prompting
npx mcp-code-wrapper . --servers mssql-main,chrome-devtools  # Specific servers

Interactive mode (default):

Shows list of available MCP servers
Select which servers to generate wrappers for
Useful when you only want specific MCPs

All mode (--all flag):

Generates wrappers for all MCPs without prompting
Useful for automation/scripts

What it does:

Discovers all MCP servers in .mcp.json
Prompts for server selection (unless --all flag)
Generates code wrappers in .mcp-wrappers/
Creates Claude Code Skills for each MCP
Disables MCPs (keeps config for executor)
Updates .gitignore

Global Mode (explicit flag required):

npx mcp-code-wrapper --global

Looks for ~/.claude/mcp.json and generates wrappers in ~/.claude/.mcp-wrappers/

After Generation

Restart Claude Code to load new Skills:

claude -c

⚠️ Important: When Claude Code restarts and prompts to enable MCPs, decline/toggle them OFF. The Skills use progressive discovery - MCPs stay disabled and are spawned on-demand by the wrapper.

Skills will use .mcp.json config to spawn servers on-demand with progressive discovery.

Verify Skills Are Loaded

After restarting, ask Claude what skills it has:

> what skills do you have?

I have access to three specialized skills:

1. mcp-chrome-devtools - Browser automation and testing
   - Navigate pages, fill forms, take screenshots
   - Inspect network traffic, debug JavaScript

2. mcp-mssql-dev - Database operations on 'app_dev' database
   - Execute SQL queries, read/write data
   - Manage tables and schemas

3. mcp-mssql-prod - Database operations on 'app_prod' database
   - Same SQL capabilities, production database

Token Economics

Real-World Example

Before (Direct MCP):

Chrome DevTools: 26 tools = 17,500 tokens
Database Server 1: 8 tools = 5,600 tokens
Database Server 2: 8 tools = 5,600 tokens
Total: 28,700 tokens (14.5% of context)

After (Progressive Discovery):

Root indexes: ~200 tokens
2 tool definitions: ~350 tokens
Total: ~550 tokens
Savings: 98% (28,150 tokens freed)

Scalability

Workflow	Tools Used	Direct MCP	Progressive	Savings
Simple task	2 tools	28,700 tokens	550 tokens	98%
Medium task	5 tools	28,700 tokens	950 tokens	97%
Complex task	10 tools	28,700 tokens	1,650 tokens	94%

Even complex workflows save 90%+ of context.

How It Works

1. Add MCPs to Your Project

// .mcp.json
{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "env": {}
    },
    "database-server": {
      "type": "stdio",
      "command": "node",
      "args": [".mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "your-host",
        "DB_NAME": "your-database",
        "DB_USER": "your-user",
        "DB_PASSWORD": "***"
      }
    }
  }
}

2. Generate Wrappers

npx mcp-code-wrapper /path/to/project

Output:

🔍 Discovering MCP servers in /path/to/project
✅ Found .mcp.json

📦 Discovered 2 MCP servers:
   - chrome-devtools
   - database-server

🔧 Generating wrapper for: chrome-devtools
   ✅ 26 tools in 7 categories
🎯 Creating Claude Code Skill wrapper...

🔧 Generating wrapper for: database-server
   ✅ 8 tools in 1 category
🎯 Creating Claude Code Skill wrapper...

✅ Generated wrappers for 2 MCP servers
📁 Output: /path/to/project/.mcp-wrappers/

🔕 Disabled 2 MCP servers in .mcp.json
🔕 Disabled MCPs in settings.local.json
   MCPs stay in .mcp.json for executor reference
   Restore with: npx mcp-code-wrapper --restore

⚠️  IMPORTANT: Restart Claude Code to load new Skills
   Run: claude -c

3. Generated Structure

/path/to/project/
├── .mcp.json                    # MCPs disabled (in-place)
├── .mcp-wrappers/               # Generated code wrappers
│   ├── chrome-devtools/
│   │   ├── navigation/
│   │   │   ├── navigate_page.ts
│   │   │   ├── take_screenshot.ts
│   │   │   └── index.ts
│   │   ├── debugging/
│   │   └── index.ts
│   └── database-server/
│       ├── queries/
│       │   ├── read_data.ts
│       │   ├── insert_data.ts
│       │   └── index.ts
│       └── index.ts
└── .claude/
    ├── settings.local.json      # MCPs disabled (in-place)
    └── skills/                  # Auto-generated Skills
        ├── mcp-chrome-devtools/
        │   ├── skill.json
        │   └── instructions.md
        └── mcp-database-server/
            ├── skill.json
            └── instructions.md

4. Progressive Discovery in Action

When you invoke a Skill:

// Claude reads root index (100 tokens)
import * as db from './.mcp-wrappers/database-server/index.ts';
// Discovers: { queries: {...} }

// Explores category (50 tokens)
import * as queries from './.mcp-wrappers/database-server/queries/index.ts';
// Discovers: { read_data, insert_data, ... }

// Reads specific tool (200 tokens)
import { read_data } from './.mcp-wrappers/database-server/queries/read_data.ts';
// Gets full documentation and API

// Uses tool
const result = await read_data({ query: 'SELECT * FROM users' });

Total: 350 tokens (vs 5,600 tokens loading all tools)

Key Features

✅ Universal: Works with ANY MCP server (npm, Python, binaries, custom) ✅ Auto-discovery: Finds all MCPs in .mcp.json automatically ✅ Skills integration: Auto-generates Claude Code Skills ✅ Config preservation: Disables MCPs but keeps config for executor ✅ Token efficient: 96%+ context savings ✅ Git-safe: Auto-updates .gitignore for generated code ✅ No secrets committed: Env vars stay in .mcp.json (not tracked) ✅ Auto-normalized responses: Runtime executor automatically unwraps MCP response formats

Use Cases

1. Multi-Database Projects

Convert multiple database MCPs without context bloat:

# Project with 3 database connections
npx mcp-code-wrapper /path/to/project

# Before: 3 databases × 5.6k tokens = 16.8k tokens
# After: Root + 3 tools = ~800 tokens
# Savings: 95%

2. Browser Automation

Use Chrome DevTools MCP without loading all 26 tools:

# Before: 17.5k tokens
# After (using 2 tools): 650 tokens
# Savings: 96%

3. Global MCP Management

Convert all your global MCPs once:

npx mcp-code-wrapper --global

# Skills available in all projects
# MCPs disabled globally
# Context savings across all sessions

Advanced Usage

Restore Original MCPs

Remove all generated wrappers and Skills, re-enable MCPs:

# Restore current directory
npx mcp-code-wrapper --restore

# Restore specific project
npx mcp-code-wrapper --restore /path/to/project

This will:

Remove .mcp-wrappers/ directory
Remove all mcp-* Skills from .claude/skills/
Re-enable MCPs in .mcp.json (removes "disabled": true)
Re-enable MCPs in .claude/settings.local.json

No backup files created - operates on config in-place to avoid accidentally committing secrets.

Keep MCPs Enabled

By default, MCPs are disabled after wrapper generation. To keep them enabled:

npx mcp-code-wrapper /path/to/project --no-disable

This generates wrappers but leaves MCPs active in both .mcp.json and .claude/settings.local.json.

Generate All Without Prompting

To skip interactive server selection and generate all at once:

npx mcp-code-wrapper /path/to/project --all

This is useful for automation, CI/CD, or when you always want all MCPs wrapped.

Generate Specific Servers

To generate wrappers for specific servers without prompting:

npx mcp-code-wrapper /path/to/project --servers mssql-main,chrome-devtools

This is useful when you:

Only want specific MCPs wrapped
Are automating wrapper generation in scripts
Want to regenerate just one server without interactive prompts

Generate for Specific MCP

# Traditional command mode (for testing)
pnpm run generate --from-mcp-json /path/to/.mcp.json --server database-server

Generate with Custom Environment

DB_HOST=your-host DB_NAME=your-database pnpm run generate node /path/to/mcp-server.js

Project Structure

mcp-code-wrapper/
├── src/
│   ├── cli.ts                    # npx entry point
│   ├── generator-universal.ts    # Universal MCP generator
│   ├── executor.ts               # MCP client & code executor
│   ├── measure-tokens.ts         # Token comparison tool
│   └── index.ts                  # Demo workflow
├── USAGE.md                      # Detailed usage guide
├── FINDINGS.md                   # Experiment analysis
├── CONTEXT.md                    # Project context
└── UNIVERSAL_GENERATOR.md        # Technical details

Documentation

USAGE.md - Complete usage guide with examples
FINDINGS.md - Experiment results and analysis
CONTEXT.md - Project overview and next steps
UNIVERSAL_GENERATOR.md - How the generator works

Workflow Comparison

Without Code Wrapper

Session Start
└─ Load all MCP tool definitions (28.7k tokens)
   └─ Use 2 tools
      └─ 26.7k tokens wasted on unused tools

With Code Wrapper

Session Start
└─ Load Skills (50 tokens)
   └─ Read root index (100 tokens)
      └─ Navigate to category (50 tokens)
         └─ Read 2 tool files (350 tokens)
            └─ Use tools
Total: 550 tokens (98% savings)

Requirements

Node.js 18+
Claude Code (for Skills integration)
Project with .mcp.json or global ~/.claude/mcp.json

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

This is an experimental project. See CONTEXT.md for current status and next steps.

License

MIT

Related Work

MCP Context Isolation - Infrastructure-level solution
Skills Controllability - Why Skills need explicit control
Stop Speedrunning Claude Code - Context discipline matters

Credits

Built by @paddo based on Anthropic's code execution pattern.

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.github		.github
src		src
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTEXT.md		CONTEXT.md
CONTRIBUTING.md		CONTRIBUTING.md
FINDINGS.md		FINDINGS.md
LICENSE		LICENSE
README.md		README.md
UNIVERSAL_GENERATOR.md		UNIVERSAL_GENERATOR.md
USAGE.md		USAGE.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

MCP Code Wrapper

The Problem

The Solution

Quick Start

Install

Usage

After Generation

Verify Skills Are Loaded

Token Economics

Real-World Example

Scalability

How It Works

1. Add MCPs to Your Project

2. Generate Wrappers

3. Generated Structure

4. Progressive Discovery in Action

Key Features

Use Cases

1. Multi-Database Projects

2. Browser Automation

3. Global MCP Management

Advanced Usage

Restore Original MCPs

Keep MCPs Enabled

Generate All Without Prompting

Generate Specific Servers

Generate for Specific MCP

Generate with Custom Environment

Project Structure

Documentation

Workflow Comparison

Without Code Wrapper

With Code Wrapper

Requirements

Contributing

License

Related Work

Credits

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 1

Languages

Packages