# Distill

> Open-source MCP server that cuts LLM token usage up to 98% — content-aware compression + AST code reading for Claude Code, Cursor & Windsurf.

- **Type:** MCP server
- **Install:** `agentstack add mcp-arthurdev44-distill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [arthjean](https://agentstack.voostack.com/s/arthjean)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [arthjean](https://github.com/arthjean)
- **Source:** https://github.com/arthjean/distill
- **Website:** https://distill-mcp.com

## Install

```sh
agentstack add mcp-arthurdev44-distill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Distill

  Cut LLM token usage by up to 98% — before the context window ever fills.

  
  
  
  
  
  

  Quick start ·
  The 3 tools ·
  Where it fits ·
  Docs ·
  Discussions

**Distill** is an open-source [MCP](https://modelcontextprotocol.io) 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.

```ts
// 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.

| Problem | Distill tool | How | Savings |
|---------|-------------|-----|---------|
| Large build output, logs, diffs | `auto_optimize` | Auto-detects type, applies the best compressor | 40–95% |
| Reading an entire file for one function | `smart_file_read` | AST extraction across 7 languages | 50–90% |
| Chaining 5–10 tool calls | `code_execute` | A TypeScript SDK in a sandbox — one call | **up 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.

| Approach | What you get | Where Distill fits |
|---|---|---|
| Raw tool calls (`Read` / `Grep` / `Bash`) | Full fidelity, full token cost | Compresses the output *before* it lands in context |
| Claude Code autocompact | Reclaims space *after* the window fills | Distill works *before* — those tokens never enter |
| Manual context trimming | Tedious and error-prone | Content-aware compressors do it automatically |
| A pile of single-purpose MCP tools | Broad surface, ~500 tokens of overhead *each* | 3 always-loaded tools, ~2,000 tokens total |

## Quick Start

```bash
# 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

```bash
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.

| Strategy | Content type | Typical savings |
|----------|-------------|-----------------|
| `build` | Compiler errors (tsc, rustc, webpack) | 95% |
| `logs` | Server / test / build logs | 80–90% |
| `errors` | Repeated error lines | 70–90% |
| `diff` | Git diffs | 60–80% |
| `stacktrace` | Stack traces | 50–80% |
| `code` / `semantic` | Source code (TF-IDF) | 40–60% |
| `config` | JSON / YAML configs | 30–60% |
| `auto` | Auto-detect best strategy | varies |

```
auto_optimize content="" 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:**

```typescript
// 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:**

```typescript
// 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 schemas | Description |
|--|-------------|-------------|
| **Distill** | ~2,000 tokens | 3 always-loaded tools |
| **Equivalent** | ~10,000+ tokens | 20+ individual tools doing the same |

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

## CLI Commands

```bash
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:

```json
{
  "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](.github/SECURITY.md) — please don't open a public issue.

## Development

```bash
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

- **[GitHub Discussions](https://github.com/ArthurDEV44/distill/discussions)** — questions, ideas, feedback
- **[Issues](https://github.com/ArthurDEV44/distill/issues)** — bug reports
- **[Documentation](https://distill-mcp.com)** — full docs site

## Contributing

Contributions welcome — see [CONTRIBUTING.md](./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](LICENSE) © Arthur Jean

---

  npm ·
  GitHub ·
  Documentation ·
  Discussions

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [arthjean](https://github.com/arthjean)
- **Source:** [arthjean/distill](https://github.com/arthjean/distill)
- **License:** MIT
- **Homepage:** https://distill-mcp.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-arthurdev44-distill
- Seller: https://agentstack.voostack.com/s/arthjean
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.