convez.ai
MCP ServerProdutividadeIntermediário
MCrank

CodeCompress — Índice de Código Inteligente para Agentes IA

MCrank/code-compress

Memória persistente de código para agentes IA — 80% menos tokens

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que cria um índice SQLite persistente da sua codebase, permitindo que agentes IA consultem símbolos, tipos e dependências sem ler arquivos completos. Reduz consumo de tokens em 80-90% e funciona também como CLI standalone, com suporte para .NET 10 e integração nativa com Claude, VS Code, Cursor e Windsurf.

Instalação

$npx convez-ai MCrank/code-compress

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
v1.0.0
Issues abertas
3
Contribuidores
2

Casos de uso

  • Reduzir consumo de contexto em sessões com agentes de código
  • Compartilhar índice de codebase entre múltiplos agentes e ferramentas
  • Indexação incremental de grandes projetos .NET/C#

Veredito

Ferramenta sólida para quem trabalha com agentes IA em codebases .NET. A indexação persistente e redução de tokens é genuinamente útil, mas o escopo é específico para C#/.NET — menos versátil que soluções agnósticas de linguagem.

README

A tradução para o português deste README ainda está na fila.

CodeCompress — MCP Server & CLI

Persistent code index for AI agents. Ask for exactly what you need.

CI Release NuGet NuGet Downloads License: MIT .NET 10


What is CodeCompress?

CodeCompress is a code intelligence tool — available as both an MCP server and a standalone CLI — that gives AI coding agents instant memory of your codebase. Use whichever interface fits your workflow: the MCP server integrates directly with AI tools like Claude Code, while the CLI works anywhere you have a terminal.

Instead of scanning every file at the start of each conversation, agents query a persistent SQLite index to get exactly the symbols, types, and dependencies they need — in a fraction of the tokens.

Without CodeCompressWith CodeCompress
Agent reads 50+ files to understand your projectAgent calls project_outline — gets the full API surface in ~3–8k tokens
30–150k+ tokens wasted per session on context80–90% reduction in context-loading tokens
Sub-agents each scan the same files independentlyAll agents share one persistent index
Bigger codebase = longer wait, every timeIndex time is constant after first run (incremental)

Quick Start

Prerequisites

Option A: MCP Server (recommended for AI tools)

Pick your tool and add the MCP server — that's it.

claude mcp add --transport stdio codecompress -- dnx CodeCompress.Server --yes

Create .vscode/mcp.json in your project:

{
  "servers": {
    "codecompress": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codecompress": {
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "codecompress": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codecompress": {
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

CodeCompress uses stdio transport. Point your client at:

dnx CodeCompress.Server --yes

Commit this file at the root of your repo. Claude Code and VS Code pick it up automatically — every team member gets CodeCompress with zero setup:

{
  "mcpServers": {
    "codecompress": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CodeCompress.Server", "--yes"]
    }
  }
}

Option B: CLI (for terminals, scripts, and agents without MCP)

Install globally as a .NET tool:

dotnet tool install -g CodeCompress

Then use it from any terminal:

codecompress index --path /path/to/project
codecompress outline --path /path/to/project
codecompress search --path /path/to/project --query "MyClass"

The CLI and MCP server share the same index database — you can use both interchangeably. Run codecompress --help for all commands, or codecompress agent-instructions to generate a ready-to-paste instruction block for AI agents.

To update: dotnet tool update -g CodeCompress

2. Index your project

Your AI agent will call index_project automatically when it needs codebase context. You can also trigger it explicitly:

index_project(path: "/path/to/your/project")

First run does a full index — parses every source file and stores symbols in SQLite. Subsequent runs are incremental — only files whose SHA-256 hash changed get re-parsed.

3. Start coding

That's it. Your agent now has instant access to your codebase structure. It will automatically use tools like project_outline, get_symbol, and search_symbols instead of reading raw files.

How It Works

AI Agent  <── MCP (stdio) ──>  CodeCompress Server ──┐
                                                      │
Developer <── Terminal ────>   CodeCompress CLI ──────┤
                                                      │
                                                 Index Engine
                                                   /      \
                                          Language       SQLite Store
                                          Parsers      ~/.code-compress/
                                    (C#, Java, Go, TS,  index.db
                                    Rust, Python, Ruby, …)

Both the MCP server and CLI share the same index database — you can index with one and query with the other.

  1. Index — CodeCompress walks your source files, hashes each one (SHA-256), and extracts symbols (functions, classes, types, constants) and dependencies (imports/requires) using language-specific parsers.

  2. Store — Everything goes into a local SQLite database at .code-compress/index.db in the project directory. The database uses FTS5 virtual tables for fast full-text search.

  3. Query — Agents call MCP tools to get compressed outlines, look up specific symbols by name, search across the codebase, or check what changed since a snapshot.

  4. Stay current — Re-indexing is incremental. Only files whose content hash changed are re-parsed. Call index_project at the start of any session, or after making changes, and it completes in seconds.

Keeping the Index Up to Date

CodeCompress is designed to stay current with minimal effort:

ScenarioWhat to do
Starting a new agent sessionCall index_project — takes seconds if nothing changed
After editing filesCall index_project again — only changed files are re-parsed
Tracking changes across sessionsUse snapshot_create before work, then changes_since to see what's different
Force a clean re-indexCall invalidate_cache then index_project

Tip for CLAUDE.md / system prompts: Add an instruction like "At the start of each session, call index_project to refresh the codebase index, then use project_outline to understand the project structure." This ensures your agent always has a fresh index.

Available MCP Tools

Indexing

ToolWhat it does
index_projectIndex a project directory (incremental by default)
snapshot_createCreate a named snapshot for tracking changes over time
invalidate_cacheForce a full re-index on next index_project call
list_reposList all projects indexed in the global database

Context Assembly

ToolWhat it does
assemble_contextOne-shot context builder — searches symbols, retrieves source code, and builds a structured overview within a token budget. Replaces 5-10 manual tool calls with 1. Provide a query + optional active file, get back Markdown with file tree, source code blocks, and token usage stats. Large symbols auto-summarize.

When to use assemble_context: At the start of a task when you need broad context. For surgical retrieval of a specific symbol, use get_symbol or expand_symbol directly.

Querying

ToolWhat it does
project_outlineCompressed API surface of the entire project — types, functions, signatures
get_symbolRetrieve the full source code of a single symbol by name (supports Parent:Child qualified names)
get_symbolsBatch retrieve multiple symbols in one call (up to 50)
get_module_apiComplete public API of a single file/module
expand_symbolExtract a single method from a large class (~60% fewer tokens than get_symbol)
get_hot_pathReturn only the lines within a symbol that contain specific identifiers plus surrounding context (10–40x fewer tokens than the full body)
search_symbolsFull-text search across symbol names, signatures, parent types, and docs. Auto-retries with contains-match when exact FTS5 returns zero results.
search_textRaw text search across file contents (with glob filtering)
topic_outlineTopic-based search with results grouped in outline format
find_referencesFind all references to a symbol across the codebase

Change Tracking & Navigation

ToolWhat it does
changes_sinceDelta report — what files/symbols changed since a snapshot
file_treeAnnotated project file tree
dependency_graphImport/require dependency graph for a file
project_dependenciesInter-project dependency graph (.NET solutions)

Dependency Analysis

ToolWhat it does
blast_radiusReverse BFS — find all files affected if a given file or symbol changes
find_unused_symbolsBest-effort dead code detection — public symbols with no incoming references

Server Management

ToolWhat it does
stop_serverGracefully shut down the server to release resources and DLL locks

Note: MCP clients like Claude Code automatically restart the server on the next tool call, so stopping it is always safe.

MCP Prompts

CodeCompress ships 4 pre-built workflow prompts. In Claude Code and other MCP clients that support prompts, you can invoke them by name to load step-by-step workflow guidance directly into your context.

PromptWorkflow
explore_codebaseindex_project → project_outline → search_symbols → get_symbol
find_impactindex_project → blast_radius → find_references → dependency_graph
review_changessnapshot_create → [make changes] → index_project → changes_since
debug_symbolsearch_symbols → get_hot_path → get_symbol → find_references

Each prompt returns a ChatRole.User message with the full workflow, token estimates per tool, and guidance on when to prefer one tool over another.

CLI: Run codecompress prompts to list all prompts, or codecompress prompts --name explore_codebase to print the full text of a specific prompt.

Supported Languages

LanguageExtensionsStatusParser
Luau (Roblox).luau, .luaAvailableRegex/pattern-based
C# / .NET.csAvailableTree-sitter AST
Blazor / Razor.razorAvailableDirective extraction + C# delegation
Terraform / HCL.tf, .tfvarsAvailableRegex/pattern-based
Java.javaAvailableTree-sitter AST
Go.goAvailableTree-sitter AST
TypeScript / JavaScript.ts, .tsx, .js, .jsx, .mjs, .cjsAvailableTree-sitter AST
Rust.rsAvailableTree-sitter AST
Python.py, .pyiAvailableTree-sitter AST
Ruby.rbAvailableTree-sitter AST
.NET Project Files.csproj, .fsproj, .propsAvailableXML-based
JSON Config.jsonAvailableTree-sitter AST
YAML Config.yaml, .ymlAvailableStructure-based

Adding a new language requires implementing a single ILanguageParser interface — no changes to storage, indexing, or MCP tools.

Where is my data stored?

All index data is stored in a single global database in your home directory:

~/.code-compress/index.db
  • One SQLite database shared across all indexed projects
  • Contains: file metadata, parsed symbols, dependencies, FTS5 search indexes, snapshots for every indexed project
  • No data leaves your machine — no network calls, no telemetry
  • Nothing is stored in your project directories — no .gitignore entries needed
  • Access is confined to the server's launch directory and its descendants — see Access boundary

To clear the index for a specific project, call invalidate_cache (MCP) or codecompress invalidate-cache --path <root> (CLI). To list all indexed projects, use list_repos (MCP) or codecompress list (CLI).

Security

  • Read-only — never modifies your source files
  • Access boundary — the server is clamped to the directory it was launched from (and its descendants); it cannot index, query, or enumerate repositories outside that boundary (see below)
  • Path traversal prevention — all file paths canonicalized and validated against the project root
  • SQL injection prevention — all queries use parameterized statements
  • Prompt injection safeguards — tool outputs are structured data; raw input is never echoed into freeform text
  • Local only — no network calls, no telemetry, your code stays on your machine

Access boundary

To prevent one project's agent from reaching another repository's code or metadata, the server confines all tools to a boundary root resolved once at startup:

  • Default: the server's launch working directory (where the MCP host started it). Any path at or below this directory is in-bounds — this includes sibling repositories when several repos live under one workspace folder.
  • Override: set CODECOMPRESS_ROOT to pin the boundary explicitly (useful when the host launches the server from an unexpected directory).
  • Allowlist: set CODECOMPRESS_ALLOWED_ROOTS (delimited by the OS path separator — ; on Windows, : elsewhere) to grant additional trusted roots for multi-repo workflows. Filesystem-root entries (/, C:\) are rejected as too broad.

Requests for paths outside the boundary are rejected with a uniform INVALID_PATH error (no information about the out-of-bounds path is leaked), and list_repos returns only repositories within the boundary.

VariablePurposeDefault
CODECOMPRESS_ROOTBoundary root the server may operate at or belowLaunch working directory
CODECOMPRESS_ALLOWED_ROOTSExtra trusted roots, OS-path-separator delimited(none)

Agent Configuration

Paste the following into your CLAUDE.md, .cursorrules, system prompt, or agent configuration file to teach AI agents how to use CodeCompress:

Tip: You can also generate this block by running codecompress agent-instructions if you have the CLI installed.

# CodeCompress — Agent Instructions

CodeCompress is a code intelligence tool that provides compressed, symbol-level access
to the indexed codebase. Use it as your PRIMARY tool for code discovery instead of reading
raw files — it saves 80-90% tokens.

## Access Boundary

All paths are scoped to the server's launch directory (or `CODECOMPRESS_ROOT`). Out-of-bounds
paths are rejected with `INVALID_PATH`. Use `CODECOMPRESS_ALLOWED_ROOTS` for multi-repo workflows.

## Workflow

1. **Index first** — `index_project` (MCP) or `codecompress index --path <root>` (CLI).
   Builds/updates the symbol database. Incremental — only changed files are re-parsed.
2. **Assemble context** — `assemble_context` / `codecompress assemble` for one-shot task context.
   Combines search + source retrieval + overview in a single call — replaces 5-10 round-trips.
3. **Get an overview** — `project_outline` / `codecompress outline` for the full codebase structure.
   `topic_outline` / `codecompress topic-outline` to scope the overview to a specific topic.
4. **Search** — `search_symbols` / `codecompress search` for FTS5 full-text symbol search.
   `search_text` / `codecompress search-text` for raw file content (literals, comments, config).
5. **Read symbols** — `get_symbol` / `codecompress get-symbol` to retrieve exact source code.
   `expand_symbol` / `codecompress expand-symbol` for a single method (~60% fewer tokens).
   `get_hot_path` / `codecompress get-hot-path` for lines matching specific identifiers (10-40x savings).
   `get_symbols` / `codecompress get-symbols` to batch-retrieve up to 50 symbols at once.
   `get_module_api` / `codecompress get-module-api` for the public API surface of a file.
6. **Find references** — `find_references` / `codecompress find-references` to trace usage.
7. **Dependencies** — `dependency_graph` / `codecompress deps` for file import relationships.
   `blast_radius` / `codecompress blast-radius` for reverse impact analysis.
   `project_dependencies` / `codecompress project-deps` for inter-project (.NET solution) deps.
8. **Change tracking** — `snapshot_create` / `codecompress snapshot` to baseline the index.
   `changes_since` / `codecompress changes` for a symbol-level diff since the snapshot.
9. **Registry** — `list_repos` / `codecompress list` to see all indexed projects and their status.

## Tips

- Add `--json` to any CLI command for machine-readable output (snake_case keys).
- The index persists at `~/.code-compress/index.db` (global) — shared between MCP server and CLI.
- PREFER these tools over raw file reading. They are faster, more precise, and dramatically
  reduce token consumption.

Building from Source

git clone https://github.com/MCrank/code-compress.git
cd code-compress
dotnet build CodeCompress.slnx
dotnet test --solution CodeCompress.slnx

To run the MCP server locally:

dotnet run --project src/CodeCompress.Server

To configure a client to use your local build:

claude mcp add --transport stdio codecompress -- dotnet run --project /absolute/path/to/src/CodeCompress.Server

CLI Tool

The CLI provides the same capabilities as the MCP server — use whichever fits your workflow. Both share the same ~/.code-compress/index.db global database.

Installation

dotnet tool install -g CodeCompress

To update to the latest version:

dotnet tool update -g CodeCompress

Usage

# Index a project (must be run first)
codecompress index --path /path/to/project

# Assemble task-relevant context in one call (new!)
codecompress assemble --path /path/to/project --query "authentication" --budget 30000

# Get a compressed codebase overview
codecompress outline --path /path/to/project

# Search for symbols (auto-retries with contains-match on zero results)
codecompress search --path /path/to/project --query "Authentication*"

# Retrieve a specific symbol's source code
codecompress get-symbol --path /path/to/project --name MyClass:MyMethod

# Search raw file contents
codecompress search-text --path /path/to/project --query "TODO"

# Retrieve a nested method without loading the whole class (~60% token savings)
codecompress expand-symbol --path /path/to/project --name MyClass:MyMethod

# Return only lines matching specific identifiers within a symbol (~10-40x fewer tokens)
codecompress get-hot-path --path /path/to/project --name MyClass:MyMethod --identifiers "userId,status"

# Batch retrieve multiple symbols at once
codecompress get-symbols --path /path/to/project --names "Foo,Bar,Baz"

# Get the public API surface of a single file
codecompress get-module-api --path /path/to/project --module src/Core/Foo.cs

# Search by topic — returns results in outline format
codecompress topic-outline --path /path/to/project --topic authentication

# Find all references to a symbol across the codebase
codecompress find-references --path /path/to/project --name ISymbolStore

# View directory structure (no index required)
codecompress file-tree --path /path/to/project

# Show file-level dependency graph
codecompress deps --path /path/to/project

# Show inter-project dependencies (.NET solutions)
codecompress project-deps --path /path/to/project

# Snapshot + change tracking
codecompress snapshot --path /path/to/project --label before-refactor
codecompress changes --path /path/to/project --label before-refactor

# Delete index to force full re-index
codecompress invalidate-cache --path /path/to/project

JSON Output

Add --json to any command for machine-readable JSON output (snake_case keys matching MCP server output):

codecompress search --path /path/to/project --query "Parser" --json

Agent Instructions

Generate a ready-to-paste instruction block for AI agents:

codecompress agent-instructions

This outputs a markdown block you can paste into CLAUDE.md, system prompts, or agent configuration files to teach AI agents how to use the CLI for code discovery.

CLI-to-MCP Equivalence

CLI CommandMCP ToolDescription
indexindex_projectBuild/update the symbol database
assembleassemble_contextOne-shot context assembly within token budget
outlineproject_outlineCompressed codebase overview
get-symbolget_symbolRetrieve symbol source code
expand-symbolexpand_symbolExtract nested symbol (~60% fewer tokens)
get-hot-pathget_hot_pathReturn only lines matching identifiers within a symbol
get-symbolsget_symbolsBatch retrieve multiple symbols
get-module-apiget_module_apiPublic API surface of a file
searchsearch_symbolsFTS5 symbol search (auto contains-match fallback)
search-textsearch_textFTS5 raw content search
topic-outlinetopic_outlineTopic-based search in outline format
find-referencesfind_referencesFind all symbol references
changeschanges_sinceDelta since snapshot
snapshotsnapshot_createCreate index snapshot
file-treefile_treeDirectory tree
depsdependency_graphFile-level dependency graph
project-depsproject_dependenciesInter-project dependencies (.NET)
invalidate-cacheinvalidate_cacheForce full re-index

License

MIT

Ver o original no GitHub

Bom para

Relacionados