code2mcp - Code Mode MCP Server

Execute TypeScript code to call MCP tools instead of using direct tool calls. Based on Cloudflare's revolutionary Code Mode pattern.

What is Code Mode?

Instead of exposing MCP tools directly to the LLM (which wastes tokens and struggles with complex tools), Code Mode:

1. Converts MCP tools into TypeScript APIs with full type definitions
2. Has the LLM write code that calls those APIs
3. Executes code in a secure sandbox with access only to specified MCP servers
4. Returns only the final results to the LLM, not intermediate data

Benefits

• ✅ 98% token reduction for complex multi-tool workflows
• ✅ Better tool understanding: LLMs are trained on millions of TypeScript examples
• ✅ Handle complex tools: Full APIs vs simplified tool schemas
• ✅ Secure execution: Sandboxed code, no network/filesystem access
• ✅ API keys hidden: Keys stored in orchestrator, never exposed to LLM

Installation

# Clone or create project
npm install

# Build (TypeScript compilation only)
npm run build

# Build with API generation (recommended for first-time setup)
npm run build:full

Note: build:full generates TypeScript API files from your MCP servers, which helps Claude understand parameter names and types. See IMPROVEMENTS.md for details.

Configuration

1. Pre-Configured MCP Servers ✅

Already configured and ready to use! Five MCP servers are pre-configured:

1. Context7 - Data storage and context management
2. Playwright - Browser automation and web scraping
3. Bright Data - Proxy network and geo-distributed scraping
4. Chrome DevTools - Chrome DevTools Protocol integration
5. Firecrawl - Advanced web crawling and content extraction

See CONFIGURED_SERVERS.md for details on each server.

To add more servers, edit src/index.ts and modify the MCP_SERVERS array:

const MCP_SERVERS: MCPServerConfig[] = [
  // ... existing 5 servers ...
  {
    name: 'your-server',
    transport: 'stdio',
    command: 'npx',
    args: ['your-mcp-package'],
    env: {},
  },
];

2. Set Environment Variables

cp .env.example .env
# Edit .env with your API keys

3. Register with Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "code2mcp": {
      "command": "node",
      "args": ["/absolute/path/to/code2mcp/build/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "WEATHER_API_KEY": "your_key_here"
      }
    }
  }
}

Usage

Example 1: Simple Tool Call

User: "What's the weather?"

Claude writes:

const weather = await __mcp_call('weather__get_current', { 
  city: 'San Francisco' 
});
console.log(`Temperature: ${weather.temperature}°F`);

Output:

=== Execution Logs ===
Temperature: 65°F

=== Result ===
(undefined)

Execution time: 234ms

Example 2: Multi-Step Workflow (Token Savings!)

User: "Get my Google Doc and update Salesforce"

Claude writes:

// Fetch document (potentially 50,000 tokens)
const doc = await __mcp_call('google_drive__get_document', {
  documentId: 'abc123'
});

// Update Salesforce (large document stays in sandbox!)
await __mcp_call('salesforce__update_record', {
  objectType: 'Lead',
  recordId: 'xyz789',
  data: {
    Notes: doc.content  // 50K tokens never enter Claude's context!
  }
});

console.log('Updated Salesforce with document content');

Key Benefit: The 50,000-token document never enters Claude's context. Only the logs are returned!

Example 3: Complex Orchestration

// Get all files modified in last week
const files = await __mcp_call('google_drive__list_files', {
  modifiedAfter: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()
});

console.log(`Found ${files.length} files`);

// Process each file
for (const file of files) {
  const doc = await __mcp_call('google_drive__get_document', {
    documentId: file.id
  });
  
  // Analyze sentiment (simple keyword matching)
  const sentiment = analyzeSentiment(doc.content);
  
  console.log(`${file.title}: ${sentiment}`);
}

function analyzeSentiment(text) {
  const positive = (text.match(/great|excellent|success/gi) || []).length;
  const negative = (text.match(/issue|problem|failure/gi) || []).length;
  return positive - negative;
}

This kind of complex orchestration would be impossible with standard MCP tool calling!

Architecture

┌─────────────────────────────────────┐
│   Claude Code (MCP Client)          │
│   Sees: ONE tool (execute_code)     │
└──────────────┬──────────────────────┘
               │ Writes TypeScript code
               ▼
    ┌──────────────────────────────────┐
    │   code2mcp Server                │
    │   - Compiles TypeScript          │
    │   - Executes in Node.js VM       │
    │   - Injects __mcp_call binding   │
    └──────────────┬───────────────────┘
                   │ Routes tool calls
                   ▼
    ┌──────────────────────────────────┐
    │   MCP Orchestrator               │
    │   - Manages MCP server conns     │
    │   - Stores API keys              │
    │   - Routes to correct server     │
    └──────────────┬───────────────────┘
                   │
         ┌─────────┴─────────┬──────────┐
         ▼                   ▼          ▼
    ┌─────────┐      ┌──────────┐  ┌─────────┐
    │ Google  │      │Salesforce│  │ Weather │
    │ Drive   │      │          │  │   MCP   │
    │ MCP     │      │   MCP    │  │         │
    └─────────┘      └──────────┘  └─────────┘

Development

# Development mode with hot reload
npm run dev

# Build
npm run build

# Test with MCP Inspector
npm run inspector

# Generate TypeScript APIs manually
npm run generate-apis

Security

The sandbox provides basic isolation:

• ✅ No network access (fetch, XMLHttpRequest, WebSocket blocked)
• ✅ No filesystem access (fs, path blocked)
• ✅ No process access (child_process, process blocked)
• ✅ Only __mcp_call() binding available
• ✅ API keys stored in orchestrator, never in sandbox
• ✅ Timeout enforcement (default 30s)

Note: This uses Node.js built-in vm module, which provides basic isolation but is not as secure as isolated-vm or Deno. For production use, consider:

1. Using Deno with strict permissions
2. Using isolated-vm with older Node.js version (v20)
3. Running in a containerized environment
4. Deploying to Cloudflare Workers (best isolation)

Token Usage Comparison

Standard MCP (Direct Tool Calling)

Tool definitions: 10K tokens (50 tools × 200 tokens)
Intermediate results: 40K tokens (large documents)
Conversation: 50K tokens
────────────────────────────────────────────────
Total: ~100K tokens

Code Mode

Code written by LLM: 2K tokens
Execution logs: 1K tokens
Conversation: 50K tokens
────────────────────────────────────────────────
Total: ~53K tokens

Token Reduction: 47% for simple workflows, 98% for complex workflows!

Documentation

See /DOCS folder for complete architecture documentation:

• DOCS/Architecture/SYSTEM_MAP.md - Complete architecture overview
• DOCS/Architecture/CODE_STRUCTURE.md - File organization
• DOCS/Etc/CODE_MODE_IMPLEMENTATION_PLAN.md - Detailed implementation plan

References

• Cloudflare Code Mode Blog Post
• Anthropic MCP Code Execution
• Model Context Protocol

License

ISC

Contributing

Contributions welcome! This is a reference implementation of the Code Mode pattern.

Roadmap

• Configuration file support (vs hardcoded in src/index.ts)
• Deno sandbox implementation for better security
• TypeScript API browser/explorer
• Support for HTTP/WebSocket MCP transports
• Streaming execution logs
• Code templates library
• Performance optimizations
• Comprehensive test suite

---

Built with ❤️ implementing Cloudflare's Code Mode pattern