⚠️ 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.
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.
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)
# 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/projectProject 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 serversInteractive 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
--allflag) - 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 --globalLooks for ~/.claude/mcp.json and generates wrappers in ~/.claude/.mcp-wrappers/
Restart Claude Code to load new Skills:
claude -cSkills will use .mcp.json config to spawn servers on-demand with progressive discovery.
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
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)
| 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.
// .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": "***"
}
}
}
}npx mcp-code-wrapper /path/to/projectOutput:
🔍 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
/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
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)
✅ 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
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%Use Chrome DevTools MCP without loading all 26 tools:
# Before: 17.5k tokens
# After (using 2 tools): 650 tokens
# Savings: 96%Convert all your global MCPs once:
npx mcp-code-wrapper --global
# Skills available in all projects
# MCPs disabled globally
# Context savings across all sessionsRemove 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/projectThis 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.
By default, MCPs are disabled after wrapper generation. To keep them enabled:
npx mcp-code-wrapper /path/to/project --no-disableThis generates wrappers but leaves MCPs active in both .mcp.json and .claude/settings.local.json.
To skip interactive server selection and generate all at once:
npx mcp-code-wrapper /path/to/project --allThis is useful for automation, CI/CD, or when you always want all MCPs wrapped.
To generate wrappers for specific servers without prompting:
npx mcp-code-wrapper /path/to/project --servers mssql-main,chrome-devtoolsThis is useful when you:
- Only want specific MCPs wrapped
- Are automating wrapper generation in scripts
- Want to regenerate just one server without interactive prompts
# Traditional command mode (for testing)
pnpm run generate --from-mcp-json /path/to/.mcp.json --server database-serverDB_HOST=your-host DB_NAME=your-database pnpm run generate node /path/to/mcp-server.jsmcp-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
- 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
Session Start
└─ Load all MCP tool definitions (28.7k tokens)
└─ Use 2 tools
└─ 26.7k tokens wasted on unused tools
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)
- Node.js 18+
- Claude Code (for Skills integration)
- Project with
.mcp.jsonor global~/.claude/mcp.json
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
This is an experimental project. See CONTEXT.md for current status and next steps.
MIT
- MCP Context Isolation - Infrastructure-level solution
- Skills Controllability - Why Skills need explicit control
- Stop Speedrunning Claude Code - Context discipline matters
Built by @paddo based on Anthropic's code execution pattern.