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:

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)

Structural Mutations

Search, Execution, and Runtime

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

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