cortex-works (minimal)

One binary. 13 tools. Built to make AI agents faster, cheaper, and more precise.

cortex-works-minimal is a lean MCP server for AI-powered IDEs. It replaces slow, token-hungry IDE tooling with a disciplined surface of 13 surgical tools — covering repo mapping, symbol analysis, structural editing, filesystem work, and bounded shell execution.

✅ Cross-platform tested: macOS, Windows, and Ubuntu (other Linux distros may work too).

Setup

Before building on macOS, make sure the Rust toolchain, Apple command line tools, and CMake are installed:

rustup update
xcode-select --install
brew install cmake

If you already have the Apple command line tools, you can skip the install step. This repository now uses the default macOS linker, so you do not need a Homebrew-specific lld path to build the release binary.

cargo build --release -p cortex-mcp
./target/release/cortex-mcp   # wire to your IDE via MCP stdio

---

Why Agents Perform Better Here

Standard IDE tools expose the filesystem as a flat text surface. Agents waste tokens reading full files to find the three lines they need, burning context on boilerplate and build artifacts that should never appear in a prompt.

cortex-works is designed around the opposite principle: return exactly what the agent needs, nothing more.

Token Efficiency by Design

The stack enforces a layered, progressive-disclosure model:

Stage	Tool	What the agent learns
L1 — Discover	workspace_topology	Roots, manifests, language hints — <500 tokens
L2 — Map	map_overview / skeleton	File tree + symbol list for selected dirs only
L3 — Read	read_source / deep_slice	Exact symbol body or focused file slice

An agent that follows this pattern typically spends 5–10× fewer tokens on codebase orientation than one using raw file reads.

Structure-Aware Edits, Not Line Patches

Line-number-based edits break as soon as another tool touches the same file. cortex-works edits by name:

• cortex_act_edit_ast — replace a Rust/TS/Python function or struct by symbol name
• cortex_act_edit_data_graph — update a JSON or YAML key by JSONPath target
• cortex_act_edit_markup — rewrite a Markdown section by heading or HTML node by tag/id
• cortex_act_sql_surgery — swap a DDL statement by type and object name

The agent supplies the new content; the tool handles byte offsets, bottom-up ordering, and post-edit validation automatically.

Fail-Safe AST Editing

cortex_act_edit_ast validates syntax after edits and aborts safely if the output is invalid. This avoids writing broken code to disk.

Multi-Root Path Routing, Built-In

VS Code multi-root workspaces, Zed multi-project, and JetBrains polyrepo sessions all work transparently via prefixed path convention: [FolderName]/path/to/file. No manual path juggling required.

One Round-Trip for Sequential Workflows

cortex_act_batch_execute collapses multi-step workflows — explore → checkpoint → edit → verify — into a single MCP call, cutting back-and-forth latency by up to an order of magnitude.

---

The 13 Active Tools

Intelligence (read-only)

Tool	Use when
cortex_code_explorer	First look at an unfamiliar repo; topology, maps, deep slices
cortex_symbol_analyzer	You already know the symbol; read source, find usages, blast radius
cortex_chronos	Save a rollback point before risky refactors; compare before/after
cortex_manage_ast_languages	A non-core parser is missing (Go, PHP, Ruby, Java, C, C++, C#, Dart)

Structural Mutations

Tool	Use when
cortex_act_edit_ast	Editing a Rust, TypeScript, or Python symbol by name
cortex_act_edit_data_graph	Updating JSON or YAML keys structurally
cortex_act_edit_markup	Rewriting Markdown sections, HTML/XML nodes by heading/tag/id
cortex_act_sql_surgery	Replacing a DDL statement (CREATE TABLE, CREATE INDEX, …)
cortex_fs_manage	Creating, copying, moving, deleting files and dirs; patching .env/.ini

Search, Execution, and Runtime

Tool	Use when
cortex_search_exact	A literal string, regex, or identifier you know exactly
cortex_act_shell_exec	Short diagnostic commands; manifest-aware run_diagnostics mode
cortex_act_batch_execute	Collapsing a sequential workflow (explore → edit → verify) into one call
cortex_mcp_hot_reload	After rebuilding, reload the worker on the same stdio channel without restarting the IDE

---

Quick Start

# 1. Clone and build
git clone https://github.com/cortex-works/cortex-works-minimal
cd cortex-works-minimal
cargo build --release -p cortex-mcp

# 2. Wire to VS Code (add to mcp.json)
{
  "cortex-works": {
    "type": "stdio",
    "command": "/absolute/path/to/target/release/cortex-mcp"
  }
}

---

Recommended Agent Workflow

1. cortex_code_explorer(workspace_topology, repoPath="/abs/path")
   ← discover workspace roots cheaply (always pass repoPath)

2. cortex_code_explorer(map_overview, target_dirs=["crates/my-crate/src"])
   ← inspect only the dirs that matter

3. cortex_symbol_analyzer(read_source, path="crates/my-crate/src/lib.rs", symbol_name="MyStruct")
   ← read exact code before editing (use `path`, not `file`)

4. cortex_chronos(save_checkpoint, path="...", symbol_name="...", semantic_tag="pre-refactor")
   ← rollback point before risky changes

5. cortex_act_edit_ast / edit_data_graph / edit_markup / …
   ← narrowest structural edit matching the file type

6. cortex_act_shell_exec(run_diagnostics=true, cwd=".")
   ← verify the change compiled

---

Common Pitfalls

Wrong	Correct
cortex_symbol_analyzer(read_source, file="...")	path="..." (not file)
cortex_symbol_analyzer(find_usages, path="...")	target_dir="." (not path)
cortex_chronos(compare_checkpoint, semantic_tag="...")	tag_a="before" + tag_b="after" (or tag_b="__live__")
cortex_fs_manage(action=read, ...)	No read action — use cortex_symbol_analyzer or deep_slice
cortex_fs_manage(action=delete, paths=["/tmp/..."])	Delete is workspace-guarded; use workspace-relative paths
cortex_act_edit_data_graph(edits=[..., value=..., code=...])	Field is value, not code
cortex_code_explorer(workspace_topology) without repoPath	Always pass repoPath (absolute) — omitting it triggers a safety block

---

Runtime Layout

cortex-mcp  (IDE gateway — MCP stdio transport)
    │
    ├── cortex-ast  (intelligence: topology, slices, symbols, checkpoints, grammar loading)
    │
    ├── cortex-act  (mutations: AST edits, data/markup/SQL edits, search, shell exec, batching)
    │
    └── cortex-db   (persistence: local checkpoint storage)

All four crates compile into one binary (cortex-mcp). The IDE talks only to that binary.

---

Documentation

Doc	Content
docs/ARCH.md	Architecture, component roles, multi-root routing, progressive disclosure model
docs/USAGE.md	Workflow patterns, path conventions, batch examples, JSON vs YAML rules
docs/DEVELOPING.md	Build commands, test suite, schema source-of-truth, dependency management