io.github.Eilodon/calm-mcp MCP Server

CALM — Coding Agent Liveness Map

A live, graph-verified map of your codebase — so an AI coding agent can edit with its eyes open instead of grepping in the dark.

Real call graphs instead of vector-similarity guesses. Compiler-verified edges wherever a compiler is available. Hard safety gates on the write path itself, not just warnings an agent is free to scroll past. Measured claims in this README are tied either to a current CALM snapshot or to benchmark artifacts; repo-specific values change as the codebase changes.

New here? Quick start gets you running in under a minute — no clone, no Rust toolchain, works with Claude Code, VS Code, Cursor, Windsurf/Devin Desktop, Codex, Antigravity, and JetBrains. Comparing tools in this category? Jump straight to Proof, not promises. Want the internals? docs/architecture.md covers multi-tier indexing, the SCIP/LSP overlay system, the concurrency model, and the sanitization layer in full.

Coverage	24 languages parsed · 13 with full call graphs by default (6 zero-config + 7 more via the default tier0-5 bundle) · 12 with a formal/compiler-verified upgrade path when the provider/toolchain is available
Safety	the only one in the published five-server benchmark that refused an unconfirmed edit to a verified hub symbol
Efficiency	task-specific token savings versus a naive read-the-files baseline; see the benchmark artifacts

---

The problem

An AI agent that edits code without knowing who calls the function it's about to change will, sooner or later:

• Delete "dead code" that a dozen other files still call.
• Change a signature and miss half its call sites.
• Refactor a symbol it assumed was minor — and discover, after breaking the build, that it was the hub the whole module leaned on.

None of that is a reasoning failure. It's a visibility failure: the agent never had a map. Give it one, and the guessing stops.

Why "CALM"

Most coding agents operate the way anyone would in an unfamiliar codebase with only grep: no sense of what's wired to what, no way to know if touching this function ripples into fourteen others. That's not confidence — it's fast guessing.

CALM stands for Coding Agent Liveness Map. Liveness, because the map is never a stale snapshot — it watches the filesystem, reindexes incrementally as files change, and reports in every response how fresh it currently is (scanning → parsing → building_edges → ready). Map, because it's an actual graph — call edges, import edges, hub/coreness metrics — not a flat text index pretending to be one. Hand an agent a live, trustworthy map of the terrain, and it stops flailing. It gets calm.

What you get

• The agent stops guessing who depends on what. callers/callees/edit_context show every known caller before a change ships. Full tree-sitter call graphs cover 13 languages out of the box: Python, TypeScript, JavaScript, Java, Rust, and Go with zero configuration, plus C, C++, C#, Ruby, PHP, Shell, and R via the default tier0-5 grammar bundle. Eleven more (Kotlin, Swift, Scala, Dart, Lua, Elixir, Haskell, OCaml, Zig, PowerShell, Groovy) parse behind opt-in --features lang-X build flags — 24 languages parsed in total (see multi-tier indexing).
• Edits that can't silently break things. Every write is hash-verified against the exact line range and syntax-checked before it ever touches disk. Hub and high-fan-in symbols hard-refuse a write until the agent has reviewed the callers and explicitly confirmed — a policy only a tool with a real dependency graph can enforce, and one the published competitor benchmark found no other server enforcing.
• Every edge tells you how much to trust it. Call edges are confidence-graded (textual → inferred → resolved → formal), and when your compiler can double-check the graph, CALM asks it to: SCIP overlays (rust-analyzer, scip-go — including multi-module go.work workspaces — scip-python, scip-ruby, and more) and live LSP overlays (gopls, clangd) can upgrade best-guess edges to compiler-verified ground truth across 12 supported language integrations when their provider/toolchain is available; unavailable providers sit out without changing the base behavior.
• A codebase that grades itself. fitness_report turns hub concentration, dead code, complexity, and architecture-boundary violations into a queryable, CI-enforceable signal instead of a one-off audit — and remember/recall keep decisions and gotchas available across sessions.
• Plays well with others, and stays on your machine. A cross-process edit lock and single-writer indexing model mean two editor sessions on the same repo don't corrupt each other's writes or double-index — under the shared daemon, sessions can even see each other coming. No code leaves your machine for indexing, search, or editing; the default embedding model is vendored into the binary at build time and needs no runtime network when those weights are valid; if they are unavailable, a runtime fallback download is allowed by default and can be disabled for strict offline operation. MIT-licensed. (One more opt-in exception: building with --features otel and setting OTEL_EXPORTER_OTLP_ENDPOINT exports span attributes — file paths, symbol names, tool names, timing, never source bodies — to your own collector. Off by default; see docs/architecture.md and use https:// collectors only.)

Where CALM fits

"Code intelligence for AI agents" is a real category now, built up by open-source pioneers — Aider, Serena, Sourcegraph/Cody, and others — that proved an agent works better with real code structure under it than with grep and good intentions. CALM builds on that foundation with a different center of gravity: most tools in the category inform the read path — better search, better navigation, better context. CALM also guards the write path. The same graph that answers "who calls this?" enforces "you don't change it until you've looked": hub/high-risk edits require fresh pre-edit context plus explicit confirmation grounded in a real caller; the policy can be widened to every edit, and every write is hash- and syntax-verified before it lands.

The trade-off is stated plainly: CALM's full-call-graph tier out of the box is 13 languages, not the 40+ some pure-LSP tools reach — though with 24 languages parsed and 12 carrying a compiler-verified upgrade path when their providers are available, the gap is narrower than it looks. What the trade buys is the part most distinctly CALM's own: confidence-graded edges, hard pre-edit gates, and a codebase that grades its own health — each backed by a number you can reproduce yourself (Proof, not promises).

Is CALM the right fit?

Good fit: agents that edit code directly, not just answer questions about it · single-repo codebases in a Tier-0/Tier-0.5 language · projects running multiple MCP clients (see supported clients below) against the same repo · local-first users who don't want to depend on an embedding API.

Not the fit today: multi-repo/cross-repo enterprise search — tools purpose-built for that scale (Sourcegraph/Cody among them) will serve you better · a language nowhere in CALM's current 24-language tree-sitter set.

Quick start

Supported clients — CALM works with any MCP client that speaks stdio; these are wired up or documented today:

Client	Modes	Fastest install
Claude Code	CLI · Web · IDE	claude mcp add --transport stdio calm -- npx -y @eilodon/calm-mcp serve
VS Code	IDE (native MCP / Copilot Agent mode)	code --add-mcp '{"name":"calm","command":"npx","args":["-y","@eilodon/calm-mcp","serve"]}'
Cursor	IDE · Cloud (Background Agent)	Add to Cursor →
Windsurf / Devin Desktop	IDE · Cloud	edit ~/.codeium/windsurf/mcp_config.json
Codex (OpenAI)	CLI · IDE	codex mcp add calm -- npx -y @eilodon/calm-mcp serve
Antigravity (Google)	CLI · IDE	edit ~/.gemini/config/mcp_config.json
JetBrains AI Assistant	IDE	via UI settings

Full walkthrough for every client above, including exact global-config snippets for the ones that need one — docs/mcp-client-setup.md. Running inside a devcontainer/Codespace where stdio forwarding doesn't reach? See docs/http-transport.md (advanced, remote-dev only, opt-in, loopback by default).

Using CALM on your own project — no clone, no Rust toolchain:

{
  "mcpServers": {
    "calm": {
      "command": "npx",
      "args": ["-y", "@eilodon/calm-mcp", "serve"]
    }
  }
}

Drop that into .mcp.json (Claude Code/Cursor) or .vscode/mcp.json (VS Code uses a top-level "servers" key instead of "mcpServers", same shape otherwise) at your project root. Claude Code plugin instead: /plugin marketplace add Eilodon/CALM then /plugin install calm@CALM.

Prefer a native binary over npx? curl -fsSL https://raw.githubusercontent.com/Eilodon/CALM/main/scripts/install.sh | sh, then run calm setup from inside your project — it writes the same MCP config automatically, pointing at the binary you just installed. Add calm setup --npx instead to write the portable npx entry (shareable/committable — teammates and CI don't need the binary). It pins to this binary's own version by default for reproducible cold installs; pass --track latest to always resolve npm's newest release instead.

Developing on CALM itself (this repo):

# 1. Build the binary
cargo build --release -p calm-cli

# 2. Initialize config for your project
calm init --project-root .

# 3. Build the index (embeds symbols too, if semantic search is enabled in config.json)
calm index --project-root .

# 4. Run the MCP server over stdio — incremental reindex kicks in automatically if an index already exists
calm serve --project-root .

This repo ships ready-made config for Claude Code (.mcp.json), Cursor (.cursor/mcp.json), and VS Code (.vscode/mcp.json) — all three point at scripts/mcp-launcher.sh, a shared launcher that finds an already-built binary, downloads a checksum-verified prebuilt release if you're on a matching git tag, or builds from source if nothing is available yet. Clone the repo and it just works — no manual build step required first.

Note: calm serve automatically adds .calm/ to .gitignore on startup so the index database never gets committed.

Example: an agent's actual workflow

agent: repo_overview()
  → current files/symbols and `indexing_phase=ready` are reported live

agent: "I need to change getUserByEmail"
  → locate("getUserByEmail")        # find the file + symbol metadata
  → source("getUserByEmail")        # read just the function body, not the whole file
  → edit_context("getUserByEmail")  # MANDATORY before any edit
      → the live caller count and risk assessment determine whether the agent reviews callers before touching the signature
  → edit_symbol("getUserByEmail", expected_hash=..., new_text=...)
      → risk_assessment=high, is_hub=true, no confirm:true → refused, with an explanation
  → edit_symbol(..., confirm=true, reason="checked getUserByToken, still returns the same shape")
      # reason must cite a real caller edit_context returned — writes for real, reindexes immediately
  → diff_impact(staged=true)        # verifies blast radius before commit

Proof, not promises

The table below is a CALM snapshot observed on 2026-08-12 from this checkout. Re-run repo_overview() and fitness_report() to refresh it; repo-specific values change as the codebase changes. Benchmark ratios are task-specific and remain in the benchmark artifacts:

Metric	Measured value
Codebase indexed	366 files, 6,050 symbols — 15 language families present in this repo alone
Hub concentration (hub_pct)	7.38% — 271 hub symbols (gate: ≤ 20%)
Dead-code rate (dead_code_pct, coverage-aware)	5.04% (gate: ≤ 10%)
Hotspot risk (hotspot_risk, churn × complexity, worst file)	0.90 — currently above gate (≤ 0.80), fitness_report() reports FAIL — being investigated rather than hidden or threshold-relaxed; see fitness_report/calm fitness-check
Edge coverage (edge_coverage_pct)	72.39% of symbols have at least one call edge (gate: ≥ 60%)
High-complexity functions (high_complexity_pct)	2.8% (gate: ≤ 15%)
Architecture fit (avg_distance, Martin/OOD)	0.28 average distance from the main sequence (gate: ≤ 1.00)
Ambiguous symbol boundaries (boundary_ambiguous_count)	0 (gate: ≤ 0)
Architecture boundary violations (boundary_violations)	0 (gate: ≤ 0) — the watcher → tools import previously flagged here was fixed by relocating the shared RwLockExt/LockExt traits it needed out of tools/common.rs into their own sync_ext module
Config drift (config_drift_count)	0 (gate: ≤ 0) — the current docs/config path declarations resolve cleanly
Token efficiency vs. a naive read-the-files baseline	Benchmark-specific; see methodology rather than treating one task's ratio as a repo-wide constant
Full test suite (default features)	see Testing below

<details> <summary><strong>Competitor-benchmark methodology and per-language caveats</strong></summary>

Benchmarked against four other live MCP servers

benchmarks/b11_extended_competitor_ab/ installs and calls four established open-source code-intelligence MCP servers — CodeGraph, Semble, grepai, and Serena — against an isolated git worktree of this repo, 5 repeats per task, with a correctness oracle for every task. The goal isn't a leaderboard; it's checking CALM's claims against real, running prior art instead of a marketing page.

What the runs showed: CALM matched the best result on caller-recall and blast-radius tasks, and was the only one of the five servers whose pre-edit safety gate actually refused a risky, unconfirmed edit rather than merely being able to describe the risk after the fact. Not every number flatters: on one token-efficiency task CALM's compression ratio was the lowest of the five — correctness stayed at the ceiling there too, and the number is published as measured. That is this project's standing benchmark policy: unflattering results ship alongside good ones (benchmarks/README.md). Full methodology, every task, and the raw per-tool numbers live in the benchmark's own README.

Language coverage, measured not asserted

benchmarks/resolution/ runs a tier-distribution baseline (resolved / inferred / textual / ambiguous split — no oracle, one real OSS repo per language) across the 19 newly-added or Tier-0.5 languages, reported as-is: Kotlin (89.6%) and OCaml (86.3%) land mostly in the ambiguous tier from common short method-name collisions; Dart produces symbols but zero call edges — a documented limitation of that tree-sitter grammar, not a bug; Tier-2 type inference is wired only for the original Tier-0 languages so far. Full per-language table in the benchmark's own README.

</details>

How CALM works

Full technical detail lives in docs/architecture.md — including the design philosophy behind why every response carries suggested_next and why the risky steps are hard-gated instead of just recommended. Section-by-section summary:

• Multi-tier indexing — 13 languages with full call graphs by default, 11 more parsed behind opt-in grammar features, 24 in total.
• A call graph you can actually trust — every edge is labeled by confidence (resolved/inferred/formal/textual); SCIP and LSP overlays can upgrade edges to compiler-grade ground truth across 12 supported integrations when their providers/toolchains are available; unavailable providers sit out.
• Search that actually finds things — FTS5 + semantic embeddings fused via Reciprocal Rank Fusion, plus real grep/glob straight off disk for files the indexer never parses.
• Editing with an actual safety net — hash-verified writes, syntax validation before anything touches disk, and a three-part gate (fresh edit_context, confirm:true, a grounded reason) on hub/high-risk symbols.
• Concurrency & reliability — a shared daemon, cross-process edit lock, and single-instance indexing lock mean multiple editor sessions on one repo don't corrupt or duplicate work.
• The codebase grading itself — 11 fitness metrics, coverage-aware dead-code detection, declared architecture boundaries, doc-drift detection.
• An agent that remembers, and knows when it's stuck — durable cross-session notes, git co-change mining, a stuck-loop signal.
• Safe by default — credential-shaped content is redacted in source/understand, prompt-injection-shaped content is flagged, and scan_text covers external text; local-first by default with an explicit embedding fallback.

Crate layout

• crates/calm-core/ — the index engine: tree-sitter parsing, SQLite schema, the multi-tier resolver (conservative → inferred → formal/Stack-Graphs, SCIP, or LSP), graph algorithms (coreness, hub detection), FTS5/semantic search, analysis (hotspots, coverage, codeowners, diff-impact, dead-code), fitness metrics, gitignore management.
• crates/calm-server/ — the MCP server (rmcp over stdio or a unix-socket daemon), exposing 40 tools plus the incremental file watcher.
• crates/calm-cli/ — the CLI: calm init, calm index, calm serve, calm connect, calm setup, calm fitness-check, calm guard, calm doctor.

CLI reference

calm init     --project-root .    # writes .calm/config.json with defaults
calm index    --project-root .    # one-shot full index (Scanning → Parsing → BuildingEdges → Ready)
                                 # also embeds symbols+chunks if semantic_search.enabled=true
calm serve    --project-root .    # MCP server over stdio + incremental reindex + file watcher
calm serve    --project-root . --listen unix:/path/to/daemon.sock   # run as a shared daemon (opt-in)
calm connect  --project-root .    # lightweight forwarder to an already-running daemon (opt-in, Unix)
calm serve    --project-root /project --db-path /data/index.db   # separate DB path (container deployment)
calm serve    --project-root . --preset orient   # register only the "orient" phase's tools
calm doctor   --project-root .    # validates config, DB (symbols/files/metrics history), git
calm setup    --project-root .    # writes/merges MCP config (.mcp.json/.cursor/.vscode) pointing at this binary
calm fitness-check --project-root .                             # CI gate, exits 1 on failure
calm fitness-check --project-root . --json                      # JSON output
calm fitness-check --project-root . --config thresholds.toml    # custom thresholds
calm guard    --project-root .    # pre-commit/CI gate on the staged diff, exits 1 if aggregate risk >= --fail-on (default: high)
calm guard    --project-root . --fail-on medium --json   # stricter threshold, machine-readable output
calm guard    --project-root . --base origin/main         # review this branch/PR against a base ref instead of the staged diff
calm guard    --project-root . --commits HEAD~3..HEAD      # raw commit range, passed straight through to git diff
calm value-report --project-root .                        # real counts from .calm/audit.log: risky edits blocked, risk distribution on what was applied
calm value-report --project-root . --json                 # machine-readable output
calm scip-run --project-root . --lang go        # force one SCIP provider to run now, bypassing refresh policy
calm scip-run --project-root .                  # --lang omitted = run every provider ("rust,go,python,javascript,java,csharp,php,ruby,c")
calm index    --project-root . --scip-file build/index.scip --sub-root services/api   # ingest a pre-built SCIP index (CI/sandboxed, no external indexer install needed)

40 MCP tools for AI agents

CLI presets filter tools by workflow phase: orient, trace, edit, compound, full (default) via calm serve --preset or the preset field in config.json — or compose a custom set from toolset (module) names, e.g. --preset "trace,security" or --preset "full,-edit" (see AGENTS.md for the full toolset list). Every response carries suggested_next to point at the next step — full detail on each tool and the complete workflow lives in AGENTS.md.

Group	Tools
Orient	repo_overview, hotspots, fitness_report (health snapshot — same metrics as calm fitness-check, queryable mid-session), indexing_status, test_gap_hotspots (ranks symbols by coreness × dead-code/test-coverage confidence — where test-writing effort pays off most)
Locate	locate, search, file_overview
Inspect	source, symbol_info, understand, symbols_batch (source + callers/callees for several exact qualified_names in one round trip)
Trace	callers, callees (ordered, capped, etag-cacheable on hub symbols), path, dependencies, reference_impact (merges call edges, import edges, and a textual grep into one classified rename/removal reference list — broader but coarser than callers/dependencies alone)
Edit	edit_context (mandatory before any edit), edit_lines/edit_symbol (the one write tool for arbitrary content — hash-verified; a hub/high-risk touch is refused unless edit_context ran for that exact symbol this session, confirm:true is passed, and reason cites a real caller edit_context returned), format_files (rustfmt via stdin only — never a positional file arg, so it can't trigger rustfmt's own crate-wide mod-tree discovery and reformat files outside its own paths list; no confirm/edit_context gate since formatting can't change semantics), pattern_debt_register/pattern_debt_status (anchor a duplicated bug pattern by qualified_name via search(kind="similar"), re-check later for open/resolved/anchor_lost), diff_impact (mandatory before commit) — edit_context and diff_impact are hook-enforced under Claude Code (see .claude/hooks/calm-nudge.sh); session_context's pending_diff_impact is the equivalent signal on any other MCP client
Change (authority)	plan_change/review_change — a reviewable-change facade over the edit gate: plan_change declares a ChangeIntent (what you're about to do, why) as a durable, reviewable record; review_change mints a signed ReviewAuthority for it once approved:true (client self-attestation, sufficient for low/medium risk only) or refuses outright when a real PolicyEngine/RiskVector evaluation classifies the change as needing independent human review — spending the authority via edit_lines/edit_symbol re-verifies it fresh, not just at mint time
Txn (admin)	batch_status (aggregates a caller-supplied list of tx_ids from several edit_lines/edit_symbol/format_files calls into one view — counts by state, whether any failed), edit_transaction_status, maintenance_status, retry_maintenance, repair_consistency, verify_change (WS-6 first slice: on-demand cargo check for an opt-in-verified edit) — transaction/maintenance-outbox diagnostics for the WS-1 durable edit-transaction journal that edit_lines/format_files now write through; registered under their own txn toolset, included in the edit preset (not orient/trace/compound)

| Recover | session_context, remember, recall | | Advanced | scip_refresh, lsp_refresh — force one or every SCIP/LSP provider to run now, bypassing the automatic refresh policy. scan_text — run the same prompt-injection/credential heuristics source/understand use against any text you supply (a WebFetch/WebSearch result, a subagent's report, pasted content) — local and offline, independent of any hosted LLM safety classifier. set_toolset — narrow or reset which tools this session exposes at runtime, without restarting the server (the safety floor — orient+guardrails+recover+edit — is always kept). All four: full preset only, not in the four workflow-phase presets above — deliberate manual/rare-use escape hatches, not steps in the default flow |

MCP Prompts — workflows packaged as slash-commands

Distinct from the tools above — MCP Prompts (prompts/list, prompts/get) return a single ready-made instruction message for a workflow you repeat often; MCP clients surface them as slash-commands:

Prompt	Argument	Packaged workflow
review_symbol	symbol	locate → source → edit_context (mandatory) → risk summary before touching anything
debug_symbol	symbol	understand → callers(max_depth=3) → check test_files/dead_code_confidence
onboard_area	path	repo_overview → file_overview/dependencies → hotspots scoped to that path
review_pr	range	diff_impact(commits=range) → hotspots (overlap check) → fitness_report → aggregate risk summary before merge
calm_workflow	(none)	No-argument orientation to the full Stage 1-8 tool workflow — for a client that never auto-loads AGENTS.md, or a mid-session refresher

One-line CI: the CALM Guard GitHub Action

action.yml wraps calm index + calm guard as a reusable composite action -- one-line adoption for a repo that just wants blast-radius review on every PR, no MCP client involved:

- uses: Eilodon/CALM@main
  with:
    fail-on: high   # default; "low"/"medium" also accepted

On a pull_request event it auto-detects the PR's base branch (fetching just that ref, since a default shallow checkout won't have it) and reviews the merge-base-relative range; on a plain push it reviews before..after. Both are overridable with base/commits inputs matching calm guard's own --base/--commits flags (see CLI reference above) -- set one explicitly for anything the auto-detection doesn't cover (workflow_dispatch, a merge-queue event, etc.). Requires an npm-published @eilodon/calm-mcp release reachable from the runner; nothing else to install.

Fitness check — the CI gate

Run for real in .github/workflows/ci.yml's fitness-check job on every push/PR — calm index first (a fresh checkout has no .calm/index.db yet), then calm fitness-check --project-root . --config thresholds.toml. That --config flag is not optional: without it, [[boundaries]] and [config_drift] are silently treated as "no rules declared" rather than erroring — only the numeric thresholds have a real default.

calm fitness-check measures 11 metrics against thresholds declared in thresholds.toml:

Metric	What it measures	Effective threshold
hub_count	Count of symbols classified as hubs	≤ 1000
hub_pct	% of symbols that are hubs (scale-invariant)	≤ 20.0%
avg_coreness	Average k-core coreness across the graph	≤ 15.0
dead_code_pct	% of symbols with "high" dead-code confidence	≤ 10%
hotspot_risk	Highest hotspot score in the codebase	≤ 0.80 in this repo (thresholds.toml override; built-in default ≤ 0.75)
edge_coverage_pct	% of symbols with at least one call edge	≥ 60%
high_complexity_pct	% of functions/methods with McCabe cyclomatic complexity > 10 (AST-based; Tier-0.5 languages always report complexity 1)	≤ 15.0%
avg_distance	Martin/OOD average distance from the main sequence — how far each file's abstractness sits from the ideal implied by its instability (Ca/Ce)	≤ 1.00
boundary_violations	Count of import_edges violating a declared [[boundaries]] rule	≤ 0
boundary_ambiguous_count	Count of symbols with an ambiguous line boundary (shared with a neighbor) — edit_symbol replace on these is refused until resolved	≤ 0
config_drift_count	Count of doc file-path references (declared via [config_drift].doc_paths) pointing at nothing real	≤ 0

Unless noted above, the table uses built-in numeric defaults; this repo's checked-in thresholds.toml is the effective CI policy. Every calm fitness-check run also snapshots metrics to the DB so edit_context can show a trend (delta versus the previous day).

Architecture boundaries — [[boundaries]]

Declare "module A must not import module B" directly in thresholds.toml (same file as [thresholds]), matched by path prefix (not glob/regex). Note this is for layering Rust's own crate/module boundaries don't already enforce — declaring "calm-core must not import calm-server" would be a no-op, since Cargo's dependency graph makes that structurally impossible already:

[[boundaries]]
from = "crates/calm-core/src/indexer/"
to = "crates/calm-core/src/analysis/"
reason = "indexer (extraction) must stay upstream of analysis (dead-code, hotspots, fitness) — not the other way around"

calm fitness-check reports each violation concretely (the real from/to path, the rule, and the reason) outside --json mode; the default max_boundary_violations = 0 means a rule you bothered to declare is one you actually keep.

This repo's own thresholds.toml currently declares two: the one above, plus crates/calm-server/src/watcher.rs → crates/calm-server/src/tools/ ("the background reindex/watch loop must not depend on the MCP tool-handler layer it runs independently of") — both hold at 0 violations.

Deployment

• cargo build --release → static (musl on Linux) binaries via .github/workflows/release.yml, 5-target matrix with SHA256SUMS + build-provenance attestation for every asset: x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, aarch64-apple-darwin, x86_64-apple-darwin, x86_64-pc-windows-msvc. scripts/mcp-launcher.sh/scripts/install.sh download and checksum-verify the right platform's build automatically on supported targets when checkout is on (or you're installing) a matching git tag; untagged, offline, or unsupported-platform paths fall back to an existing binary or a source build.
• Containerfile, multi-stage (rust:alpine → scratch) — a single static binary, no runtime image needed, published to ghcr.io/eilodon/calm-mcp (tagged by version + latest) on every git tag push.
• compose.yaml ships a hardened example (read_only, cap_drop: ALL, no-new-privileges, pids_limit: 64, mem_limit: 256m).
• The default embedding model's weights are vendored into the binary via include_bytes! — build.rs::ensure_embedding_weights fetches crates/calm-core/assets/potion-code-16m/*.safetensors from Hugging Face Hub and checksum-verifies it once at compile time, so a normal cargo build/release binary needs no network I/O at runtime when those weights are valid. No Git LFS is involved (the repo carries zero LFS content).

<details> <summary>What happens if the build-time fetch fails (offline build, etc.)</summary>

cargo build still compiles successfully — build.rs writes a small placeholder stub in place of the real weights instead of failing the build. Loading that stub at runtime fails ("failed to parse safetensors"), so Embedder::load automatically falls back to a one-time Hugging Face Hub download of the same model (cached locally afterward; the default config allows this fallback, while semantic_search.allow_network_fallback = false keeps the runtime strictly offline). If that fallback is disabled or also unavailable, indexing_status reports embeddings_status: "failed" and search(kind="semantic"/"hybrid") degrades to FTS-only — no crash, just no semantic search until the model is available and you rebuild or re-run.

</details>

Runtime and transport

• Default mode is MCP stdio. The launcher uses the shared Unix daemon when invoked without extra launcher arguments on Unix; custom invocations, CI, and Windows can use one-process calm serve.
• HTTP is opt-in. calm serve --http binds to 127.0.0.1:8787 by default. Non-loopback exposure requires --allow-remote and a non-empty CALM_HTTP_TOKEN sent as a Bearer token.
• Remote HTTP is read-only. CALM forces the effective preset to remote-safe — every tool that declares read_only_hint = true, computed from the tool router itself rather than a hand-maintained list, so it can't silently miss a newly added state-mutating tool; terminate TLS at a reverse proxy. The built-in HTTP transport caps request body size and concurrent requests as defense-in-depth, but has no real rate limiting or per-IP DoS protection, so do not expose it directly to an untrusted network.

Testing

cargo test --workspace                        # unit + integration (embeddings is a default feature, included)
cargo test --test parity_test test_formal_edges   # Stack Graphs regression corpus

Eleven CI jobs run on every PR (verified against .github/workflows/ci.yml's own job list, not hand-counted): verify (fmt/clippy/test/audit), calm-guard-dogfood (dogfoods action.yml against this repo's own PRs — continue-on-error: true, shadow mode while new), stack-graphs-corpus (formal-resolver parity), txn-crash-injection (WS-1's crash-injection suite — kills the process at every reachable TxState transition, real SIGKILL), embeddings (clippy + test with the embeddings feature), no-stack-graphs-formal (clippy + test with stack-graphs-formal off — the only CI coverage of the resolver::formal stub that feature gate compiles to), all-languages (fixture-repo indexing across all 24 parsed languages, plus lsp-overlay), js-client-interop (cross-checks the tool schema against a real JS MCP SDK client, not just Rust's own), otel-http-features (clippy + test with the otel/http features, plus a guard against opentelemetry core version skew), fitness-check (runs calm fitness-check against this repo's own index — see Fitness check below), status-drift (fails the build if docs/status.generated.md is stale, if any hand-authored doc's tool count drifted from it, or if the benchmark claims registry is structurally inconsistent).

The workspace contains 1,000+ tests; the latest CI verify job is the source of truth for pass/fail. A handful of #[ignore]d live-binary integration tests (e.g. rust-analyzer/scip-go/scip-java) need external tools not installed in every environment.

Further reading

• docs/architecture.md — the full technical deep-dive: multi-tier indexing, SCIP/LSP overlays, search internals, the edit safety net, concurrency, self-grading, memory, sanitization, and the design philosophy behind it all.
• docs/comparison.md — methodology-first positioning write-up against other tools in this category.
• docs/what-external-users-get.md — exactly what an npx/npm/MCP-Registry install gives you, as distinct from this repo's own dev checkout: install/distribution mechanics, the full tool and toolset breakdown, the edit safety layer, language coverage, and what never ships externally.
• docs/ — resolver internals, migration plans, and other design notes not covered by docs/architecture.md above.
• docs/adr/ — individual architecture decision records (Stack Graphs scope, the formal-resolver approach, the LSP-optional confidence upgrade, the daemon+forwarder concurrency model).
• docs/mcp-client-setup.md — every MCP client install path in detail, including Windsurf/Devin Desktop and Codex global config.
• docs/http-transport.md — the opt-in remote/HTTP transport (calm serve --http): loopback-by-default, the fail-closed --allow-remote + token requirement, why remote exposure forces a read-only preset, and the TLS/reverse-proxy expectation.
• AGENTS.md — the full tool-by-tool workflow guide this project's own agents follow.
• KNOWN_LIMITATIONS.md — an honest list of what CALM doesn't do yet (single-language unsandboxed verification, no multi-file change-set, no reference-impact tool, risk classification with no change-kind signal, and more), and why each is deliberately deferred rather than half-built.
• benchmarks/ — the measurement suite behind benchmark claims in this README, and a few more: b2_call_graph_quality/ (precision/recall vs. a SCIP oracle), b3_search_quality/ (hybrid RRF vs. FTS-only vs. raw grep, NDCG@10), b4_token_efficiency/ (token cost vs. a naive baseline, per task), b6_tool_call_efficiency/ (round-trips: naive multi-call vs. one MCP call), b7_task_correctness/ (real rename refactors across 6 language corpora — fd/Rust, flask/Python, express/JS, zod/TS, gin/Go, spring-petclinic/Java — checked against an independent pass/fail oracle, not an LLM judge), b11_extended_competitor_ab/ (real calls against 4 other live MCP servers, not self-reported numbers), b12_tier1_tier2_tool_correctness/ (9 tools driven live over JSON-RPC against 6 external OSS repos, ground-truthed against regex/git grep), resolution/ (tier-distribution baseline across 19 real OSS repos, one per language). Unflattering results are published alongside good ones on purpose — benchmarks/README.md states that policy.

License

MIT