Code Mode for MCP Servers

Description

--- name: code-mode description: > Add a "code mode" tool to an existing MCP server so LLMs can write small processing scripts that run against large API responses in a sandboxed runtime — only the script's compact output enters the LLM context window. Use this skill whenever someone wants to add code mode, context reduction, script execution, sandbox execution, or LLM-generated-code processing to an MCP server. Also trigger when users mention reducing token usage, shrinking API responses, running user-provided code safely, or adding a code execution tool to their MCP server — in any language (TypeScript, Python, Go, Rust, etc.). --- # Code Mode for MCP Servers ## What is Code Mode? When an MCP tool returns a large API response (e.g. listing 500 Kubernetes pods, 200 SCIM users, or thousands of GitHub issues), that entire payload enters the LLM's context window — consuming tokens and degrading performance. Code mode flips the approach: instead of dumping raw data into context, the LLM writes a small processing script. The MCP server runs the script in a **sandboxed runtime** against the raw data, and only the script's stdout enters context. This works especially well with well-known APIs (SCIM, Kubernetes, GitHub, Stripe, Slack, AWS, etc.) because the LLM already knows the response schema from training data — it can write the extraction script in one shot without inspecting the data. **Typical results: 65–99% context reduction.** ### Inspiration - [Cloudflare Code Mode](https://blog.cloudflare.com/code-mode-mcp/) - [claude-context-mode](https://github.com/mksglu/claude-context-mode) --- ## How This Skill Works This is an **interactive planning skill**. Work with the user step-by-step: 1. **Understand** their MCP server (language, framework, what tools return large data) 2. **Select** a sandbox that fits their server language and security needs 3. **Plan** the implementation together 4. **Implement** the code mode tool, sandbox executor, and benchmark 5. **Verify** with benchmarks comparing before/after context sizes Do not jump ahead. Confirm each step with the user before proceeding. --- ## Step 1: Understand the Existing MCP Server Ask the user (or discover by reading their codebase): - **Server language**: TypeScript/JavaScript, Python, Go, Rust, or other? - **MCP framework**: XMCP, FastMCP, mcp-go, custom, etc.? - **Which tools return large responses?** (e.g. list users, get pods, search issues) - **What APIs do they call?** Well-known APIs (SCIM, K8s, GitHub, Stripe) are ideal candidates because the LLM already knows the schema. - **What languages should the sandbox support for script execution?** Usually JavaScript is sufficient. Python is a common second choice. Summarize your understanding back to the user and confirm before moving on. --- ## Step 2: Select a Sandbox The sandbox must be **isolated from the host filesystem and network by default** and **secure by default**. Present the user with options that match their server language, using the reference in `references/sandbox-options.md`. ### Quick Selection Guide **If the server is TypeScript/JavaScript:** | Sandbox | Script Language | Isolation | Size | Notes | |---|---|---|---|---| | `quickjs-emscripten` | JavaScript | WASM (no fs/net) | ~1MB | Lightweight, actively maintained, best default | | `pyodide` | Python | WASM (no fs/net) | ~20MB | Full CPython in WASM, heavier | | `isolated-vm` | JavaScript | V8 isolate (no fs/net) | ~5MB native | Fast, separate V8 heap, not WASM | **If the server is Python:** | Sandbox | Script Language | Isolation | Size | Notes | |---|---|---|---|---| | `RestrictedPython` | Python | AST-restricted compile | Tiny | Compiles to restricted bytecode, no I/O by default | | `pyodide` (in-process WASM) | Python | WASM | ~20MB | Heavier but stronger isolation than RestrictedPython | | `quickjs` (via `quickjs` PyPI) | JavaScript | WASM/native | Small | Run JS from Python | **If the server is Go:** | Sandbox | Script Language | Isolation | Size | Notes | |---|---|---|---|---| | `goja` | JavaScript | Pure Go interpreter | Zero CGO | No fs/net, widely used (used by Grafana) | | `Wazero` | WASM guest (JS/Python compiled to WASM) | WASM runtime, pure Go | Zero CGO | Strongest isolation, runs any WASM module | | `starlark-go` | Starlark (Python dialect) | Pure Go interpreter | Zero CGO | Deterministic, no I/O, used by Bazel | **If the server is Rust:** | Sandbox | Script Language | Isolation | Size | Notes | |---|---|---|---|---| | `boa_engine` | JavaScript | Pure Rust interpreter | No unsafe deps | ES2024 support, embeddable | | `wasmtime` / `wasmer` | WASM guest | WASM runtime | Strong | Run any WASM module, strongest isolation | | `deno_core` | JavaScript/TypeScript | V8-based | Larger | Full V8, powerful but heavier | | `rustpython` | Python | Pure Rust interpreter | Moderate | Less mature but functional | Read `references/sandbox-options.md` for detailed tradeoffs on each option. **Present 2–3 options** to the user (filtered to their server language), explain the tradeoffs briefly, and let them choose. If they're unsure, recommend the lightest WASM-based option for their language. --- ## Step 3: Plan the Implementation Once the sandbox is selected, create a concrete plan with the user. The plan should cover these components: ### 3a. Code Mode Tool A new MCP tool (e.g. `code_mode` or `<domain>_code_mode`) that accepts: - **`command`** or **`args`**: The underlying API call / query to execute (e.g. kubectl args, SCIM endpoint + params, GraphQL query) - **`code`**: The processing script the LLM writes - **`language`** (optional): Script language, defaults to `javascript` The tool handler: 1. Executes the underlying API call (reusing existing logic) 2. Passes the raw response as a `DATA` variable into the sandbox 3. Runs the script in the sandbox 4. Returns only the script's stdout, plus a size measurement line: `[code-mode: 18.0KB -> 6.2KB (65.5% reduction)]` ### 3b. Sandbox Executor A utility module that: - Initializes the chosen sandbox runtime - Injects `DATA` (the raw API response as a string) into the sandbox - Executes the user-provided script - Captures stdout and returns it - Enforces a timeout (e.g. 10 seconds) - Handles errors gracefully (script syntax errors, runtime errors) ### 3c. Wiring - Register the new tool in the MCP server's tool list - Optionally gate behind an env var (ask the user if they want this) ### 3d. Benchmark A benchmark script that compares tool output size vs. code-mode output size across realistic scenarios. See `references/benchmark-pattern.md` for the template. **Present the plan to the user and confirm before implementing.** --- ## Step 4: Implement Follow the confirmed plan. Implement in this order: 1. **Install the sandbox dependency** (e.g. `npm i quickjs-emscripten`) 2. **Create the executor module** — the sandbox wrapper 3. **Create the code mode tool** — the MCP tool handler 4. **Wire it into the server** — register the tool 5. **Create the benchmark script** Keep the implementation minimal — don't over-abstract. The executor and tool can each be a single file. ### Implementation Tips - The `DATA` variable should always be a **string** (JSON-serialized). The script is responsible for parsing it if needed (`JSON.parse(DATA)` in JS, `json.loads(DATA)` in Python). - Include the reduction measurement in every response so the user/LLM can see the savings: `[code-mode: {before}KB -> {after}KB ({pct}% reduction)]` - Set a reasonable default timeout (10s) and memory limit if the sandbox supports it. - Return clear error messages if the script fails — the LLM will use the error to fix its script on the next call. --- ## Step 5: Benchmark and Verify After implementation, run the benchmark to verify code mode actually reduces context size. Read `references/benchmark-pattern.md` for the full template. The benchmark should: 1. **Generate or fetch realistic test data** — use faker/mock data if no live API is available, or hit a real endpoint if the user has one. 2. **Run each scenario through both paths:** - Regular tool response (full JSON) - Code mode with a representative extraction script 3. **Print a comparison table** showing before/after sizes and reduction % 4. **Print a total** across all scenarios Present the benchmark results to the user. Typical expectations: - Simple list extractions: 60–80% reduction - Filtered queries (e.g. "only inactive users"): 90–99% reduction - Aggregations (e.g. "count per department"): 95–99% reduction --- ## Reference Files - `references/sandbox-options.md` — Detailed comparison of all sandbox options by server language, with security analysis and setup instructions - `references/benchmark-pattern.md` — Benchmark script template and methodology

Security Status