Distill

Extract the essence. Compress the context. Save tokens.

Distill is an open-source MCP server that optimizes LLM token usage through intelligent context compression. Works with Claude Code, Cursor, and Windsurf.

Why Distill?

| Problem | Distill Solution | Savings | |---------|------------------|---------| | Large build outputs | Auto-compress errors | 80-95% | | Reading entire files | AST-based extraction | 50-70% | | Multiple tool calls | TypeScript SDK execution | 98% | | Verbose logs | Smart summarization | 80-90% |

Quick Start

# Run directly with npx
npx distill-mcp

# Or install globally
npm install -g distill-mcp

# Configure your IDE
distill-mcp setup

Add to Claude Code

claude mcp add distill -- npx distill-mcp

Features

• Smart File Reading - Extract functions, classes, or signatures without loading entire files
• Auto Compression - Detects content type and applies optimal compression
• Code Execution SDK - Write TypeScript instead of chaining tool calls
• Lazy Loading - Only loads tools when needed (85% token overhead reduction)
• 7 Languages - TypeScript, JavaScript, Python, Go, Rust, PHP, Swift

MCP Tools

Core Tools (Always Loaded)

| Tool | Purpose | Savings | |------|---------|---------| | auto_optimize | Auto-detect and compress content | 40-95% | | smart_file_read | Read code with AST extraction | 50-70% | | code_execute | Execute TypeScript with SDK | 98% | | discover_tools | Browse/load additional tools | - |

On-Demand Tools

| Tool | Purpose | Savings | |------|---------|---------| | semantic_compress | TF-IDF based compression | 40-60% | | summarize_logs | Summarize server/test/build logs | 80-90% | | analyze_build_output | Parse build errors | 95%+ | | deduplicate_errors | Group repeated errors | 80-95% | | diff_compress | Compress git diffs | 50-80% | | context_budget | Pre-flight token estimation | - | | session_stats | Usage analytics | - |

Usage Examples

Smart File Reading

# Get file structure overview
mcp__distill__smart_file_read filePath="src/server.ts"

# Extract specific function
mcp__distill__smart_file_read filePath="src/server.ts" target={"type":"function","name":"createServer"}

# Get skeleton (signatures only)
mcp__distill__smart_file_read filePath="src/server.ts" skeleton=true

Compress Build Output

# After a failed build, compress the output
mcp__distill__auto_optimize content="<paste npm/tsc/webpack output>"

Code Execution SDK

The code_execute tool provides 98% token savings by letting LLMs write TypeScript:

mcp__distill__code_execute code="return ctx.compress.auto(ctx.files.read('logs.txt'))"

SDK API:

// File operations
ctx.files.read(path)
ctx.files.glob(pattern)
ctx.files.exists(path)

// Code analysis
ctx.code.skeleton(content, lang)
ctx.code.extract(content, lang, {type, name})
ctx.code.parse(content, lang)

// Compression
ctx.compress.auto(content, hint?)
ctx.compress.logs(logs)
ctx.compress.diff(diff)
ctx.compress.semantic(content, ratio?)

// Git operations
ctx.git.diff(ref?)
ctx.git.log(limit?)
ctx.git.blame(file, line?)

// Search
ctx.search.grep(pattern, glob?)
ctx.search.symbols(query)

// Analysis
ctx.analyze.dependencies(file)
ctx.analyze.callGraph(fn)

Discover Tools

# Browse available tools (metadata only)
mcp__distill__discover_tools category="compress"

# Load tools when needed
mcp__distill__discover_tools category="compress" load=true

# TOON format for compact output
mcp__distill__discover_tools format="toon"

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 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 automatically added to the appropriate settings file.

Token Overhead

Distill uses lazy loading to minimize overhead:

| Mode | Tokens | Description | |------|--------|-------------| | Core only | 264 | Default (4 tools) | | All tools | 1,108 | Full suite (21 tools) | | Savings | 76% | Lazy vs eager loading |

Security

Code execution runs in a sandboxed environment:

• Blocked: eval, require, import(), process, global
• File access restricted to working directory
• Sensitive files blocked (.env, credentials, keys)
• Memory limit: 128MB, Timeout: 30s

Development

# Install dependencies
bun install

# Run tests
bun run test

# Build
bun run build

# Start dev server
bun run dev

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Priority areas:

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

License

MIT

npm · GitHub · Documentation