# 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

```bash
# 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](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](CONFIGURED_SERVERS.md) for details on each server.

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

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

### 2. Set Environment Variables

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

### 3. Register with Claude Code

Add to `~/.claude.json`:

```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:**
```typescript
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:**
```typescript
// 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

```typescript
// 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

```bash
# 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](https://blog.cloudflare.com/code-mode/)
- [Anthropic MCP Code Execution](https://www.anthropic.com/news/mcp-code-execution)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## 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