Skip to content

SuperCodeMode

SuperCodeMode logo

SuperCodeMode is an optimization framework for Code Mode style client behavior.

It helps MCP and HTTP tool users improve quality by tuning client side instruction text and routing policy.

What This Project Solves

Many tool systems fail because the client logic is weak, even when tools are good.

Typical failures:

  • execute tool used too early
  • discovery step skipped
  • weak execution instructions
  • unstable or noisy final answers

SuperCodeMode gives you a repeatable loop to improve these behaviors.

Who This Is For

  • Cloudflare Code Mode MCP users
  • MCP users running search and execute style tools
  • platform engineers and evaluation teams

What Is Included

  • MCP stdio runner for local workflows
  • MCP streamable HTTP runner for direct Cloudflare MCP
  • HTTP runner for Cloudflare or bridge endpoints
  • local, Docker, and Monty execution backend options in demo MCP server
  • doctor checks for setup confidence
  • artifacts for run outputs and best candidates
  • observability output in JSONL and OTLP modes

How GEPA Changes Work

This repo demonstrates the GEPA adapter approach where:

  • GEPA optimizes client text policy
  • runners execute tools on MCP or HTTP runtimes
  • transport can switch without rewriting adapter logic

Read guides/gepa-adapter.md for the exact behavior and commands.

What Is Not Included By Default

  • automatic server code mutation
  • automatic server deploy workflows

Expected Benefits

  • better tool routing quality
  • better final answer consistency
  • fewer unnecessary tool calls
  • easier comparison of baseline vs tuned behavior
  • easier debugging with traces and telemetry

Left Menu Section Guide

Use the left menu in this order:

  1. Getting Started for install and first run
  2. Examples for runnable scenarios
  3. CLI and Config for all flags and environment settings
  4. Operations for checks, observability, and troubleshooting

Quick Start

pip install -e .
scm doctor
scm showcase --runner mcp-http
scm showcase --runner mcp-stdio

scm optimize --runner mcp-stdio --max-metric-calls 10 --save-artifact
scm --obs-backend jsonl --obs-jsonl-path artifacts/obs.jsonl showcase --runner mcp-stdio

Useful Pages

  • install: getting-started/install.md
  • first run: getting-started/first-run.md
  • examples: guides/examples.md
  • gepa adapter: guides/gepa-adapter.md
  • cloudflare http: guides/cloudflare-http.md
  • cli reference: reference/cli.md
  • observability: operations/observability.md