calor mcp

Start the Model Context Protocol server used by coding agents.

Bash

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

Options

Option	Description
`--stdio`	Use standard input/output; enabled by default
`--verbose`, `-v`	Write debug logs to stderr
`--root`	Confine 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 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.

Tool	Purpose
`calor_compile`	Compile source to C# and return auto-fix suggestions without writing
`calor_check`	Diagnostics, lint, type checking, or snippet validation
`calor_verify`	Seven-status Z3 contract verification with counterexamples
`calor_analyze`	Bug/security analysis, migration assessment, or interop minimization
`calor_convert`	Convert C# to Calor with issues and validation diagnostics
`calor_batch`	Batch convert, analyze, or compile a project
`calor_help`	Syntax, support, diagnostic, and example lookup
`calor_navigate`	Definition, reference, symbol, type, and scope queries
`calor_structure`	Outline, call graph, and change-impact analysis
`calor_query`	Ask 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_preview`	Classify a proposed edit as safe, warning-bearing, or breaking
`calor_format`	Format source or check/assign declaration IDs
`calor_session_open`	Parse a project and return a session for cross-file checks
`calor_session_close`	Release an open project session
`calor_file_write`	Heal, check, and atomically apply a confined `.calr` write
`calor_refine`	Refinement obligations, bounds, guards, fixes, and type suggestions
`calor_fix`	Return non-destructive fixes for common compiler errors
`calor_migrate`	Run the project migration pipeline; this tool can write files
`calor_self_test`	Check 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.

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.

Input	Required	Description
`projectDirectory`	Yes	The folder whose `.calr` files the index covers. Must be inside the server's root.
`facet`	Yes	`callers`, `callees`, `impact`, or `effects`
`symbol`	Yes	The name of the declaration you are asking about
`inFile`	No	Which file you meant, when several files declare the same name
`effects`	No	`impact` only: ask which callers would stop compiling if the declaration's effects changed
`row`	No	With `effects: true`: the effects it would have after the change, such as `"cw,fs:w"` (`""` means "no effects"). Defaults to what it declares today.
`noBuild`	No	Refuse an out-of-date index instead of rebuilding it
`indexPath`	No	Read an index from somewhere other than `obj/calor`. Read-only — see below.
`format`	No	`json` (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:

Option	Default	Description
`crossModule`	`false`	Batch 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.
`enforceEffects`	`true`	The command line's `--no-enforce-effects` is `false` here.
`requireDocs`	`false`	The 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.