312846230a
Expose Compiler Explorer's compile, list, shortlink and asm-docs APIs
via a Model Context Protocol (MCP) endpoint mounted at `/mcp`. This lets
MCP-aware clients (Claude, etc.) drive CE directly as a tool.
## Tools exposed at `/mcp`
- **`compile`** — compile source and return assembly / stdout / stderr,
with optional execution.
- `compiler` is **optional**; falls back to the language's
`defaultCompiler` from `list_languages` ("compile this hello world in
C++" is one call).
- `libraries[].version` accepts **either** the version id (`"188"`) or
the human form (`"1.88.0"`) — both work.
- When `execute: true` and the build fails,
`buildResult.stdout`/`stderr` carry the real compiler diagnostics with
**ANSI codes stripped** so an LLM caller sees clean text.
- Caps: `maxAsmLines` / `maxStdoutLines` / `maxStderrLines` with
truncation flags + total counts.
- **`list_compilers`** — with `language`, `instructionSet` (closed enum
from `InstructionSetsList`), `match` (case-insensitive AND-of-tokens;
numeric/dotted-version tokens treated as version-prefix), `lean: true`,
`maxResults`, `latestPerMajor: true`, and `includeExperimental: true`.
- Hard cap of 200 entries on lean responses with a refinement hint —
prevents the unfiltered call from overflowing.
- Each entry exposes `releaseTrack` (`stable | nightly | prerelease |
experimental`) and `supportsExecute` / `supportsBinary`.
- **`list_libraries`** — with `match`, `lean`, `maxResults` (same
lean-cap behaviour).
- **`list_languages`** — minimal listing including `defaultCompiler` and
`compilerCount` per language.
- **`generate_short_url`** — returns `{url}`. Library versions are
normalised before saving.
- **`get_shortlink_info`** — returns saved sessions in the **same shape
`compile` accepts** (`{compiler, options, libraries:[{id, version}]}`)
for direct round-tripping. Multi-pane shortlinks (executors,
conformance, CMake trees) are flattened to the basic compile inputs.
- **`lookup_asm_instruction`** — `instruction_set` is a closed enum
derived from the registered providers (no hand-listed enum values; one
source of truth in `lib/asm-docs/`).
## Implementation
- New `lib/mcp/` module wiring `@modelcontextprotocol/sdk` into the
existing Express router via `StreamableHTTPServerTransport` (stateless
mode — one server per request).
- `lib/mcp/utils.ts`: tokenised `match` with version-prefix matching for
numeric/dotted-version tokens (so `"gcc 14.1"` matches `"gcc 14.1"` and
`"gcc 14.1.0"` but NOT `"gcc 14.10"` or `"gcc 14.0.1"`); `applyCap` with
both per-call lean degradation and an absolute hard cap; `truncateLines`
strips ANSI escapes via the existing `filterEscapeSequences` helper from
`lib/utils.ts`.
- `lib/mcp/library-utils.ts`: `normaliseLibraryVersion` and
`normaliseRequestLibraries` — single source of truth for "accept id or
human version" semantics, used by both `compile` and
`generate_short_url`.
- Schema descriptions are tight (LLM context cost matters) and derive
closed-set enums programmatically from `InstructionSetsList`,
`RELEASE_TRACKS`, and a new `availableAsmDocsKeys` export — no
hand-listed values that can rot.
- Refactor `StorageBase` static helpers (`encodeBuffer`, `isCleanText`,
`getSafeHash`) to module-level functions with type-checked input so MCP
tools can build shortlink hashes without instantiating a storage
backend.
- Expose `ApiHandler.compileHandler` and split out
`getAvailableLanguages()` so MCP can reuse the same code paths the REST
API uses; new `ApiHandler.getDefaultCompilerFor()` for the
compile-default-compiler resolution.
- Browser-friendly CORS on `/mcp`: OPTIONS preflight advertises
`Access-Control-Allow-Methods: POST, OPTIONS` (the shared `cors`
middleware doesn't set Methods); 405 responses on other verbs use the
same Allow header.
- `docs/API.md`: clarify that `/api/shortener` requires a JSON object
body (the prior docs implied but didn't state it).
## Tester feedback addressed
A Claude tester drove the staging deployment through several rounds;
full thread in PR comments. Round-by-round refinements:
- Compile diagnostics surfaced on execute-mode build failures (the
original "silent `Build failed` with empty stderr" bug).
- `execute: true` schema description rewritten to reflect the actual
behaviour.
- Library `version` accepts both forms; clean errors when neither
matches with a sample of available versions.
- `latestPerMajor` rebuilt on top of the `releaseTrack` field added in
#8685, with `includeExperimental` opt-in for c++ proposal forks.
- Lean mode (`lean: true`) for catalog browsing, plus a hard 200-item
cap so even unfiltered calls don't overflow the host.
- Tokenised `match` with version-prefix semantics for
numeric/dotted-version tokens. **Behaviour change** vs the old
`/api/compilers?fields=...` text matching: bare numeric tokens are now
treated as version segments — `"2024"` no longer substring-matches
inside `"v2024beta"`, and `"14.1"` no longer wrongly matches `"14.0.1"`.
Strict improvements but worth a release-note line for callers depending
on the prior loose behaviour.
- ANSI escape code stripping from compile output.
- `instructionSet` as a structured filter (instead of relying on `match`
strings).
- `supportsExecute` / `supportsBinary` on `list_compilers` so an agent
knows whether `execute: true` will work without trying.
- `compilerCount` per language so an agent can tell well-stocked vs
niche languages at a glance.
- Compiler-not-found / library-not-found errors point at the right
`list_*` tool.
## Depends on
#8685 (releaseTrack metadata on `CompilerInfo`) — merged.
## Test plan
- [x] `npm run test -- --run mcp release-track` — all pass (78 + 22)
- [x] `npm run test-min` — full minus expensive, all green
- [x] `make pre-commit` — exits 0
- [x] Multi-round driving on staging via the live MCP endpoint,
including: default-compiler hello-world (no compiler arg), human-form
library version (`"1.88.0"`), broken-compile-with-execute (verifies
buildResult), compile+run with stdin, compile+library Boost 1.90,
parallel `-O0` vs `-O3` diff, `list_compilers latestPerMajor` for
c++/rust/go/csharp, `list_libraries match boost/fmt/json`,
`lookup_asm_instruction MOV amd64`, full `generate_short_url` →
`get_shortlink_info` → re-`compile` round-trip with library
normalisation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Matt Godbolt <mattgodbolt@hudson-trading.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: mattgodbolt-molty <mattgodbolt-molty@users.noreply.github.com>
Compiler Explorer
Compiler Explorer is an interactive compiler exploration website. Edit code in C, C++, C#, F#, Rust, Go, D, Haskell, Swift, Pascal, ispc, Python, Java, or any of the other 30+ supported languages, and see how that code looks after being compiled in real time.
Bug Report · Compiler Request · Feature Request · Language Request · Library Request · Report Vulnerability
Overview
Multiple compilers are supported for each language, many different tools and visualizations are available, and the UI layout is configurable (thanks to GoldenLayout).
Try out at godbolt.org, or run your own local instance. An overview of what the site lets you achieve, why it's useful, and how to use it is available here, or in this talk.
Compiler Explorer follows a Code of Conduct which aims to foster an open and welcoming environment.
Compiler Explorer was started in 2012 to show how C++ constructs are translated to assembly code. It started as a
tmux session with vi running in one pane and watch gcc -S foo.cc -o - running in the other.
Since then, it has become a public website serving over 3,000,000 compilations per week.
You can financially support this project on Patreon, GitHub, Paypal, or by buying cool gear on the Compiler Explorer store.
Using Compiler Explorer
FAQ
There is now a FAQ section in the repository wiki. If your question is not present, please contact us as described below, so we can help you. If you find that the FAQ is lacking some important point, please feel free to contribute to it and/or ask us to clarify it.
Videos
Several videos showcase some features of Compiler Explorer:
- Compiler Explorer 2023: What's New?: Presentation for CppNorth 2023.
- Presentation for CppCon 2019 about the project
- Older 2 part series of videos which go into a bit more detail into the more obscure features.
- Just Enough Assembly for Compiler Explorer: Practical introduction to Assembly with a focus on the usage of Compiler Explorer, from CppCon 2021.
- Playlist: Compiler Explorer: A collection of videos discussing Compiler Explorer; using it, installing it, what it's for, etc.
A Road map is available which gives a little insight into the future plans for Compiler Explorer.
Developing
Compiler Explorer is written in TypeScript, on Node.js.
Assuming you have a compatible version of node installed, on Linux simply running make ought to get you up and
running with an Explorer running on port 10240 on your local machine:
http://localhost:10240/. If this doesn't work for you, please contact us, as we consider it
important you can quickly and easily get running. Currently, Compiler Explorer requires
node 22 or higher installed, either on the path or at NODE_DIR (an environment variable or
make parameter).
Running with make EXTRA_ARGS='--language LANG' will allow you to load LANG exclusively, where LANG is one for the
language ids/aliases defined in lib/languages.ts. For example, to only run Compiler Explorer with C++ support,
you'd run make EXTRA_ARGS='--language c++'. You can supply multiple --language arguments to restrict to more than
one language. The Makefile will automatically install all the third-party libraries needed to run; using npm to
install server-side and client-side components.
For development, we suggest using make dev to enable some useful features, such as automatic reloading on file changes
and shorter startup times.
You can also use npm run dev to run if make dev doesn't work on your machine.
When making UI changes, we recommend following the UI Testing Checklist to ensure all components work correctly.
Some languages need extra tools to demangle them, e.g. rust, d, or haskell. Such tools are kept separately in the
tools repo.
Configuring compiler explorer is achieved via configuration files in the etc/config directory. Values are key=value.
Options in a {type}.local.properties file (where {type} is c++ or similar) override anything in the
{type}.defaults.properties file. There is a .gitignore file to ignore *.local.* files, so these won't be checked
into git, and you won't find yourself fighting with updated versions when you git pull. For more information see
Adding a Compiler.
Check CONTRIBUTING.md for detailed information about how you can contribute to Compiler Explorer, and the docs folder for specific details regarding various things you might want to do, such as how to add new compilers or languages to the site.
Running a local instance
If you want to point it at your own GCC or similar binaries, either edit the etc/config/LANG.defaults.properties or
else make a new one with the name LANG.local.properties, substituting LANG as needed. *.local.properties files
have the highest priority when loading properties.
For a quick and easy way to add local compilers, use the CE Properties Wizard which automatically detects and configures compilers for 30+ languages. See Adding a Compiler for more details.
If you want to support multiple compilers and languages like godbolt.org, you can use the
bin/ce_install install compilers command in the infra project to install
all or some of the compilers. Compilers installed in this way can be loaded through the configuration in
etc/config/*.amazon.properties. If you need to deploy in a completely offline environment, you may need to remove some
parts of the configuration that are pulled from www.godbolt.ms@443.
When running in a corporate setting the URL shortening service can be replaced by an internal one if the default storage
driver isn't appropriate for your environment. To do this, add a new module in lib/shortener/myservice.js and set the
urlShortenService variable in configuration. This module should export a single function, see the
tinyurl module for an example.
RESTful API
There's a simple restful API that can be used to do compiles to asm and to list compilers.
You can find the API documentation here.
Contact us
We run a Compiler Explorer Discord, which is a place to discuss using or developing
Compiler Explorer. We also have a presence on the cpplang Slack channel
#compiler_explorer and we have
a public mailing list.
There's a development channel on the discord, and also a development mailing list.
Feel free to raise an issue on github or email Matt directly for more help.
Official domains
Following are the official domains for Compiler Explorer:
The domains allow arbitrary subdomains, e.g., https://foo.godbolt.org/, which is convenient since each subdomain has an independent local state. Also, language subdomains such as https://rust.compiler-explorer.com/ will load with that language already selected.
Credits
Compiler Explorer is maintained by the awesome people listed in the AUTHORS file.
We would like to thank the contributors listed in the CONTRIBUTORS file, who have helped shape Compiler Explorer.
We would also like to especially thank these people for their contributions to Compiler Explorer:
- Gabriel Devillers (while working for Kalray)
- Johan Engelen
- Joshua Sheard
- Andrew Pardoe
Many amazing sponsors, both individuals and companies, have helped fund and promote Compiler Explorer.