v0.29.0—Sharper bug analysis, reliable resource cleanup, and stronger test and CI checks.See what's new

calor mcp

Start the Model Context Protocol server used by coding agents.

Bash
calor mcp --stdio --root /absolute/project/path

Options

OptionDescription
--stdioUse standard input/output; enabled by default
--verbose, -vWrite debug logs to stderr
--rootConfine project sessions, file writes, and index queries to this directory

Pin --root in harnesses and CI. Without it, write confinement falls back to the server process's working directory, which depends on how the client starts the process.

The Tool Surface

The server registers 19 tools. Several older one-purpose names were folded into action-based tools; clients should discover the live tool list rather than assuming names from pre-consolidation documentation.

ToolPurpose
calor_compileCompile source to C# and return auto-fix suggestions without writing
calor_checkDiagnostics, lint, type checking, or snippet validation
calor_verifySeven-status Z3 contract verification with counterexamples
calor_analyzeBug/security analysis, migration assessment, or interop minimization
calor_convertConvert C# to Calor with issues and validation diagnostics
calor_batchBatch convert, analyze, or compile a project
calor_helpSyntax, support, diagnostic, and example lookup
calor_navigateDefinition, reference, symbol, type, and scope queries
calor_structureOutline, call graph, and change-impact analysis
calor_queryAsk the project index who calls a declaration, what it calls, what a change to it (or to its effects) could break, and what it declares versus what it really does — the same answer calor query gives, from the same index
calor_edit_previewClassify a proposed edit as safe, warning-bearing, or breaking
calor_formatFormat source or check/assign declaration IDs
calor_session_openParse a project and return a session for cross-file checks
calor_session_closeRelease an open project session
calor_file_writeHeal, check, and atomically apply a confined .calr write
calor_refineRefinement obligations, bounds, guards, fixes, and type suggestions
calor_fixReturn non-destructive fixes for common compiler errors
calor_migrateRun the project migration pipeline; this tool can write files
calor_self_testCheck the compiler against embedded golden files

Diagnostic-producing tools use the shared schema 2.0 envelope inside their result DTOs. In particular, verification uses proven, refuted, assumed, unknown, timeout, unsupported, and unavailable.

Conversion Paths in calor_convert, calor_migrate, and calor_batch

The conversion tools report which path kept each member as C#. They use the same vocabulary as calor convert: interop, rescue, passthrough, lossy, and dropped, with a trigger (parse-failure, round-trip-failure, unsupported-construct) and an enabledBy when one applies.

ToolWhere the paths appear
calor_convert (convert, validate, roundtrip modes)lossSummary.locations[] (path, trigger, enabledBy) and lossSummary.paths
calor_migrateperFile[].losses[] and perFile[].conversionPaths
calor_batch (action: "convert")files[].conversionPaths; with summary: true, failedFiles[].conversionPaths and a preservationPaths line; with skipOnError: false, an abort returns error, preservationPaths and files[].conversionPaths

The defaults differ from the command line, on purpose:

  • calor_convert rescues less by default. The CLI turns on automatic rescue of members that fail the C# round trip. calor_convert does not; it returns isError: true with lossSummary.paths.outcome: "refused" and rescueUnusableMembers: false. Pass passthroughOnError: true to have those members kept as §CSHARP. The report then says passthrough, because you asked for it. In the default lossless mode, members whose Calor does not parse are rescued on every surface. Constructs the converter already knows it cannot represent, such as iterator accessors, are preserved as converter interop instead.
  • calor_migrate and calor_batch never rescue round-trip failures, because project migration checks the round trip once for the whole project. calor_migrate has no passthrough option, and calor_batch does not rescue them even with passthroughOnError: true. Such a file fails, and in lossless mode the whole project is refused.

For example, a trailing C# label can survive conversion but fail the C# round trip. calor_convert refuses it by default; passthroughOnError preserves it:

JSON
{ "name": "calor_convert",
  "arguments": { "source": "public class G { static int p; static int P { get { return p; } set { p = value; } } public int M(int x) { P = x; return P; } }",
                 "passthroughOnError": true } }

returns "lossSummary": { …, "paths": { "outcome": "preserved", "passthrough": 1, "triggers": { "round-trip-failure": 1 }, "rescueUnusableMembers": false, "passthroughOnError": true, … } }. Without passthroughOnError the same call returns isError: true and "outcome": "refused".

Before 0.25, a custom moduleName (or an inputPath, from which the module name is derived) stopped the rescue from finding a global-namespace type's original C#, so these calls failed. They now rescue like the others.

Defaults, Counts, and Partial Failures

Every conversion result reports the two options that applied, so you can check the defaults below in paths or conversionPaths:

SurfacerescueUnusableMemberspassthroughOnError
calor_convertfalsefalse (opt in with passthroughOnError: true)
calor_migrate (phase: "convert")falsefalse (no option)
calor_batch (action: "convert")falsefalse (the option exists but does not rescue a round-trip failure)
calor convert (CLI, for comparison)truefalse (--passthrough)

calor_convert returns its own result object, not the CLI envelope. Its issues[] entries are envelope-style diagnostics: code Calor1343, a severity, and a message that starts with the feature name ([iterator-accessor] …). lossSummary.nativeConversions counts constructs written as Calor, and lossSummary.interopPreservations counts preserved pieces. As on the CLI, the native count still includes constructs of a type that was later rescued, so read lossSummary.paths.outcome to know whether the result is fully native.

Partial results look like this:

  • calor_convert: isError: false with outcome: "preserved" means usable output with some C# kept. isError: true with outcome: "refused" means no usable output. With fidelity: "lossy", isError: true with outcome: "unverified" and paths.roundTrip: "failed" means calorSource is returned (and written to outputPath), but its C# does not compile. issues[] lists the compiler errors. Before 0.26 lossy mode skipped this check and could return such output with isError: false.
  • calor_batch and calor_migrate: in the default lossless mode, one failed file means no file is written. Every file then reports outcome: "refused" with its counts, and the result has isError: true. In the W1-F6-project fixture, a two-file project with one file that needs a rescue, calor_batch reports failedFiles: 2. With skipOnError: false, the response also carries error, naming the first failed file, and a preservationPaths line. Their conversionPaths.roundTrip is deferred: the project-wide compile does the round-trip check, and a failure there refuses the file.

The C# interoperability guide shows, per C# feature, what calor_convert returns with and without passthroughOnError.

The calor_query Tool

New in 0.16. This tool answers questions about how your code fits together by reading the project index — the same file calor index build writes and calor query reads. It never computes a second opinion — it reads the index, rebuilding it first if it is out of date — so an agent and a person at the terminal get the same answer, from the same index.

InputRequiredDescription
projectDirectoryYesThe folder whose .calr files the index covers. Must be inside the server's root.
facetYescallers, callees, impact, or effects
symbolYesThe name of the declaration you are asking about
inFileNoWhich file you meant, when several files declare the same name
effectsNoimpact only: ask which callers would stop compiling if the declaration's effects changed
rowNoWith effects: true: the effects it would have after the change, such as "cw,fs:w" ("" means "no effects"). Defaults to what it declares today.
noBuildNoRefuse an out-of-date index instead of rebuilding it
indexPathNoRead an index from somewhere other than obj/calor. Read-only — see below.
formatNojson (the default) returns the same document calor query … --json prints; text returns the lines calor query prints
JSON
{
  "name": "calor_query",
  "arguments": {
    "projectDirectory": "/work/myapp",
    "facet": "impact",
    "symbol": "Log",
    "effects": true,
    "row": "fs:w"
  }
}

That asks: if Log started writing files, which of the functions that reach it would stop compiling? Ask facet: "callers" for who calls it, "callees" for what it calls, and "effects" for what a declaration says it does next to what the compiler worked out it really does.

The four facets are the four calor query facets that support --json. The CLI has three more — symbol, contracts, and assumptions — and whole-file impact (calor query impact <file> --file) is command-line only.

Where it may look, and what it may write

Answering can mean rebuilding the index, and rebuilding writes to disk. So this tool is confined exactly like calor_file_write:

  • projectDirectory must be inside the folder you started the server on (calor mcp --root /absolute/project/path). The path is resolved first — symlinks and .. are followed — and then checked, so it cannot step outside. Without --root, the root is the server process's working directory, which depends on how your client launched it. Pin it.
  • If the index is missing or out of date, the tool rebuilds it and answers from the fresh one. Pass noBuild: true to have it refuse instead; that setting never writes anything.
  • indexPath is read-only. It lets you point at an index built elsewhere with calor index build --output <dir>, and it must also be inside the root. Nothing is ever written through it: if the index it names is missing or out of date, the tool refuses and tells you to rebuild it yourself rather than writing over a directory you only meant to read.

An out-of-date index is never answered from. Every answer says when it may be incomplete and why — see residuals.

calor_compile Options

calor_compile takes an options object. The ones added in 0.16:

OptionDefaultDescription
crossModulefalseBatch mode only. Compile the whole file set as one project, the way calor -i a.calr -i b.calr does, so effects are checked across files. Without it, batch mode compiles each file on its own with contracts off and effects permissive — useful for triaging a migration, not for judging a project.
enforceEffectstrueThe command line's --no-enforce-effects is false here.
requireDocsfalseThe command line's --require-docs: public functions and types must be documented.

New in 0.16, batch mode returns every diagnostic — warnings included — for each file under that file's diagnostics[], with or without crossModule. Through 0.15 each file in a batch came back with a count of its warnings and a list of its errors as plain sentences; there was no diagnostics[] at all, so nothing carried a code, a position, or a suggested fix.

What crossModule adds is the checking only a whole-project compile can do: effects followed across file boundaries, and contracts, which plain batch mode leaves off. Turn it on when you want the answer calor gives for the project as a whole — not to get warnings, which you now get either way.

Project Configuration

calor init --ai codex, --ai claude, --ai gemini, and --ai github write the client-specific MCP configuration. A direct Codex configuration is:

toml
[mcp_servers.calor]
command = "calor"
args = ["mcp", "--stdio", "--root", "/absolute/project/path"]

Keep human-oriented logging on stderr so the protocol stream stays clean. For write operations, prefer a project session plus calor_file_write; it checks cross-file references and applies the file atomically only after the requested checks pass.