## MCP Tool Usage Guidelines

Use Distill MCP tools for token-efficient operations:

### Rule 1: Smart File Reading

When reading source code files for **exploration or understanding**:

\`\`\`
mcp__distill__smart_file_read filePath="path/to/file.ts"
\`\`\`

**When to use native Read instead:**
- Before editing a file (Edit requires Read first)
- Configuration files: `.json`, `.yaml`, `.toml`, `.md`, `.env`

### Rule 2: Compress Large Outputs

After Bash commands that produce large output (>500 chars):

\`\`\`
mcp__distill__auto_optimize content="<paste the large output>"
\`\`\`

### Rule 3: Code Execution SDK for Complex Operations

For multi-step operations, use `code_execute` instead of multiple tool calls (**98% token savings**):

\`\`\`
mcp__distill__code_execute code="<typescript code>"
\`\`\`

**SDK API (`ctx`):**

*Compression:*
- `ctx.compress.auto(content, hint?)` - Auto-detect and compress
- `ctx.compress.logs(logs)` - Summarize log output
- `ctx.compress.diff(diff)` - Compress git diff
- `ctx.compress.semantic(content, ratio?)` - TF-IDF compression

*Code:*
- `ctx.code.parse(content, lang)` - Parse to AST structure
- `ctx.code.extract(content, lang, {type, name})` - Extract element
- `ctx.code.skeleton(content, lang)` - Get signatures only

*Files:*
- `ctx.files.read(path)` - Read file content
- `ctx.files.exists(path)` - Check if file exists
- `ctx.files.glob(pattern)` - Find files by pattern

*Git:*
- `ctx.git.diff(ref?)` - Get git diff
- `ctx.git.log(limit?)` - Get commit history
- `ctx.git.status()` - Get repo status
- `ctx.git.branch()` - Get branch info
- `ctx.git.blame(file, line?)` - Git blame for a file

*Search:*
- `ctx.search.grep(pattern, glob?)` - Search for pattern in files
- `ctx.search.symbols(query, glob?)` - Search for symbols (functions, classes)
- `ctx.search.files(pattern)` - Search files by pattern
- `ctx.search.references(symbol, glob?)` - Find references to a symbol

*Analyze:*
- `ctx.analyze.dependencies(file)` - Analyze imports/exports
- `ctx.analyze.callGraph(fn, file, depth?)` - Build call graph
- `ctx.analyze.exports(file)` - Get file exports
- `ctx.analyze.structure(dir?, depth?)` - Directory structure with analysis

*Utilities:*
- `ctx.utils.countTokens(text)` - Count tokens
- `ctx.utils.detectType(content)` - Detect content type
- `ctx.utils.detectLanguage(path)` - Detect language from path

**Examples:**

\`\`\`typescript
// Get skeletons of all TypeScript files
const files = ctx.files.glob("src/**/*.ts").slice(0, 5);
return files.map(f => ({
  file: f,
  skeleton: ctx.code.skeleton(ctx.files.read(f), "typescript")
}));

// Compress and analyze logs
const logs = ctx.files.read("server.log");
return ctx.compress.logs(logs);

// Extract a specific function
const content = ctx.files.read("src/api.ts");
return ctx.code.extract(content, "typescript", { type: "function", name: "handleRequest" });
\`\`\`

### Quick Reference

| Action | Use |
|--------|-----|
| Read code for exploration | `mcp__distill__smart_file_read filePath="file.ts"` |
| Get function/class | `mcp__distill__smart_file_read filePath="file.ts" target={"type":"function","name":"myFunc"}` |
| Compress build errors | `mcp__distill__auto_optimize content="..."` |
| Summarize logs | `mcp__distill__auto_optimize content="..."` |
| Multi-step operations | `mcp__distill__code_execute code="return ctx.files.glob('src/**/*.ts')"` |
| Before editing | Use native `Read` tool |

## MCP Tools

Use Distill for token optimization:
- Code exploration: `mcp__distill__smart_file_read filePath="file.ts"`
- Large outputs: `mcp__distill__auto_optimize content="..."`
- Multi-step ops: `mcp__distill__code_execute code="return ctx.files.glob('**/*.ts')"`
- Before editing: Use native `Read` tool

/init

distill-mcp setup

distill-mcp setup --hooks