convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
ArthurDEV44

Distill

ArthurDEV44/distill

Comprima contexto na origem — reduz tokens antes da janela encher

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que reduz o uso de tokens em LLMs até 98% através de compressão consciente de conteúdo e leitura de AST de código. Funciona com Claude Code, Cursor e Windsurf, processando outputs, logs, diffs e leituras de arquivo inteiras de forma eficiente.

Instalação

$npx convez-ai ArthurDEV44/distill

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
6
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 3 meses
Versão
v0.11.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Comprimir outputs de build, logs e diffs automaticamente
  • Extrair funções específicas de arquivos grandes (7 linguagens)
  • Executar múltiplas operações em um único call via TypeScript sandbox

Veredito

Distill resolve um problema real de custo operacional em agentic workflows — compressão de contexto *antes* do window encher, não depois. Para times que usam Claude Code/Cursor/Windsurf e trabalham com grandes codebases ou outputs, o ROI em tokens é significativo.

README

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

Distill is an open-source MCP server that compresses context at the source. Build output, logs, diffs, and whole-file reads get distilled down to the tokens that actually matter — so your agent reads more, spends less, and stays sharp deeper into a session. Three always-loaded tools, present from turn 1, replace dozens of individual calls. Works with Claude Code, Cursor, and Windsurf.

// Before Distill — 7 tool calls, ~2,500 tokens of overhead:
//   Read ×3  →  Grep  →  Read  →  Read  →  compress

// With Distill — 1 call, ~500 tokens:
code_execute(`
  const files = ["server.ts", "registry.ts", "executor.ts"];
  return ctx.compress.auto(
    files.map(f => ctx.code.skeleton(ctx.files.read(f), "typescript")).join("\n")
  );
`)
//                                              ▲  ~80% less overhead, same answer

Why Distill?

Claude Code already compresses context after it enters the window (autocompact). Distill compresses before — catching large outputs at the source, so the expensive tokens never land in context at all.

ProblemDistill toolHowSavings
Large build output, logs, diffsauto_optimizeAuto-detects type, applies the best compressor40–95%
Reading an entire file for one functionsmart_file_readAST extraction across 7 languages50–90%
Chaining 5–10 tool callscode_executeA TypeScript SDK in a sandbox — one callup to 98%

Where it fits

Distill doesn't replace your tools — it sits between their output and your context window and keeps the noise out.

ApproachWhat you getWhere Distill fits
Raw tool calls (Read / Grep / Bash)Full fidelity, full token costCompresses the output before it lands in context
Claude Code autocompactReclaims space after the window fillsDistill works before — those tokens never enter
Manual context trimmingTedious and error-proneContent-aware compressors do it automatically
A pile of single-purpose MCP toolsBroad surface, ~500 tokens of overhead each3 always-loaded tools, ~2,000 tokens total

Quick Start

# Run directly with npx
npx distill-mcp

# Or install globally
npm install -g distill-mcp

# Auto-configure your IDE (Claude Code, Cursor, Windsurf)
distill-mcp setup

Add to Claude Code

claude mcp add distill -- npx distill-mcp

All 3 tools are available immediately — no discovery step, no loading modes.

The 3 Tools

auto_optimize — compress any content

Auto-detects content type and applies the optimal compression strategy.

StrategyContent typeTypical savings
buildCompiler errors (tsc, rustc, webpack)95%
logsServer / test / build logs80–90%
errorsRepeated error lines70–90%
diffGit diffs60–80%
stacktraceStack traces50–80%
code / semanticSource code (TF-IDF)40–60%
configJSON / YAML configs30–60%
autoAuto-detect best strategyvaries
auto_optimize content="<large build output>" strategy="auto"

smart_file_read — AST-powered code reading

Read code with precision — extract exactly what you need.

5 modes:

  • skeleton — function / class signatures only (depth 1–3)
  • extract — pull a specific function, class, or interface by name
  • search — find elements matching a query
  • full — complete file structure overview
  • auto — detect mode from params

7 languages: TypeScript, JavaScript, Python, Go, Rust, PHP, Swift

smart_file_read filePath="src/server.ts" mode="skeleton"
smart_file_read filePath="src/server.ts" mode="extract" target={"type":"function","name":"createServer"}
smart_file_read filePath="src/server.ts" mode="search" query="register"

code_execute — TypeScript SDK in a sandbox

Write TypeScript instead of chaining tool calls. Access files, git, search, and compression through the ctx.* SDK.

code_execute code="return ctx.compress.auto(ctx.files.read('build.log'))"

Batch multiple operations in one call:

// Read 3 files, extract key signatures, compress the result — 1 tool call instead of 7
const files = ["src/server.ts", "src/registry.ts", "src/executor.ts"];
const skeletons = files.map(f => ctx.code.skeleton(ctx.files.read(f), "typescript"));
return ctx.compress.auto(skeletons.join("\n---\n"));

SDK API:

// File operations
ctx.files.read(path)         // Read file content
ctx.files.glob(pattern)      // Find files by pattern
ctx.files.exists(path)       // Check if file exists

// Code analysis
ctx.code.parse(content, lang)                  // Parse to structure
ctx.code.extract(content, lang, {type, name})  // Extract element
ctx.code.skeleton(content, lang)               // Signatures only

// Compression
ctx.compress.auto(content, hint?)    // Auto-detect and compress
ctx.compress.logs(logs)              // Log summarization
ctx.compress.diff(diff)              // Diff compression
ctx.compress.semantic(content, ratio?) // TF-IDF compression

// Git
ctx.git.diff(ref?)         // Get diff
ctx.git.log(limit?)        // Commit history
ctx.git.blame(file, line?) // Blame info
ctx.git.status()           // Working tree status
ctx.git.branch()           // Current branch info

// Search
ctx.search.grep(pattern, glob?)       // Search file contents
ctx.search.symbols(query, glob?)      // Find code symbols
ctx.search.files(pattern)             // Find files by pattern
ctx.search.references(symbol, glob?)  // Find symbol references

// Analysis
ctx.analyze.dependencies(file)           // File dependencies
ctx.analyze.callGraph(fn, file, depth?)  // Call graph
ctx.analyze.exports(file)               // Exported symbols
ctx.analyze.structure(dir, depth?)       // Directory structure

// Pipeline
ctx.pipeline(steps)                  // Run step array
ctx.pipeline.codebaseOverview(dir?)  // Quick overview
ctx.pipeline.findUsages(symbol)      // Find all usages
ctx.pipeline.analyzeDeps(file)       // Dependency analysis

// Utilities
ctx.utils.countTokens(text)      // Count tokens
ctx.utils.detectType(content)    // Detect content type
ctx.utils.detectLanguage(path)   // Detect language from path

Token Overhead

Distill's 3 tools add minimal overhead to every API call:

Tool schemasDescription
Distill~2,000 tokens3 always-loaded tools
Equivalent~10,000+ tokens20+ individual tools doing the same

All 3 tools use _meta['anthropic/alwaysLoad'] — present from turn 1 with zero discovery friction.

CLI Commands

distill-mcp setup          # Auto-configure detected IDEs
distill-mcp setup --claude # Configure Claude Code only
distill-mcp setup --cursor # Configure Cursor only
distill-mcp doctor         # Verify installation
distill-mcp serve          # Start the MCP server
distill-mcp analyze        # Analyze codebase token usage
distill-mcp --help         # Show help

IDE Configuration

Claude Code

After running distill-mcp setup, your config will include:

{
  "mcpServers": {
    "distill": {
      "command": "npx",
      "args": ["distill-mcp", "serve"]
    }
  }
}

Cursor / Windsurf

Configuration is added to the appropriate settings file automatically.

Security

code_execute runs in a sandboxed environment with 7 security layers:

  • Static analysis blocks eval, require, import(), process, Reflect, Proxy
  • QuickJS WASM isolation — no fetch, no fs, no host access
  • File access restricted to the working directory (symlinks resolved)
  • Sensitive files blocked (.env, credentials, keys)
  • Git commands allowlisted (no push, fetch, clone)
  • Memory limit 128 MB · timeout 30 s · output cap 4,000 tokens (auto-compressed)

Found a vulnerability? See SECURITY.md — please don't open a public issue.

Development

bun install          # Install dependencies
bun run build        # Build all packages
bun run test         # Run tests
bun run dev          # Start dev mode (watch)
bun run check-types  # TypeScript type check
bun run lint         # ESLint

Built with Bun workspaces + Turborepo. The published package lives in packages/mcp-server/.

Community

Contributing

Contributions welcome — see CONTRIBUTING.md.

Priority areas:

  • New language parsers for smart_file_read (Java, C#, Kotlin)
  • SDK extensions for code_execute
  • Documentation

If Distill saves you tokens, a ⭐ helps other people find it.

License

MIT © Arthur Jean


Ver o original no GitHub

Bom para

Relacionados