# MCP File Compaction
An MCP server that reduces Claude context window costs by automatically summarizing files to their public interfaces.
## The Problem
When Claude works on large tasks across multiple files, the context window grows continuously. Each API request costs based on the **full size** of the context, not just new tokens. This leads to quadratic cost growth:
1. Implement `ptr.rs` (2KB) → Context: 2KB
2. Implement `raw_page.rs` using `ptr.rs` (3KB) → Context: 5KB
3. Implement `paged_pool.rs` using both (4KB) → Context: 9KB
After finishing a file, Claude doesn't need the full implementation—just the public interface (structs, functions, traits).
## The Solution
This MCP server:
- **Tracks the "active" file** — the one you're currently editing (full contents)
- **Auto-summarizes inactive files** — when you switch files, the previous one is summarized to just its public API
- **Uses AST parsing** — deterministic, fast, no LLM calls for summarization
- **Handles unsupported languages gracefully** — returns full contents without tracking
## Installation
### From GitHub (recommended)
```bash
npx github:YOUR_USERNAME/mcp-file-compaction
```
### Local development
```bash
git clone https://github.com/YOUR_USERNAME/mcp-file-compaction.git
cd mcp-file-compaction
npm install
npm run build
```
## Configuration
Add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"file-compaction": {
"command": "npx",
"args": ["github:YOUR_USERNAME/mcp-file-compaction"]
}
}
}
```
Or for local development:
```json
{
"mcpServers": {
"file-compaction": {
"command": "node",
"args": ["/path/to/mcp-file-compaction/dist/index.js"]
}
}
}
```
Add to your `CLAUDE.md`:
```markdown
## File Operations
Use the file-compaction MCP server for file operations:
- `read_file` instead of `Read` when you need full file contents
- `peek_file` when you only need to check interfaces
- `edit_file` instead of `Edit` for modifications
- `write_file` instead of `Write` for new files
- `file_status` to see tracked files and context savings
This reduces context window size by keeping only summaries of inactive files.
```
## Tools
### read_file
Read a file and mark it as the active file. When you switch to a different file, the previous file is automatically summarized.
```json
{ "path": "src/lib.rs" }
```
### peek_file
Get a summary of a file's public interface without changing the active file. Useful for checking APIs.
```json
{ "path": "src/ptr.rs" }
```
### edit_file
Edit a file by replacing a specific string. The file becomes (or remains) the active file.
```json
{
"path": "src/lib.rs",
"old_string": "fn old_name(",
"new_string": "fn new_name("
}
```
### write_file
Write content to a file, creating it if needed. The file becomes the active file.
```json
{
"path": "src/new_module.rs",
"content": "//! New module\n\npub fn hello() {}\n"
}
```
### file_status
Show all tracked files with size comparison and savings.
```
Context Status
==============
Active: src/paged_pool.rs (full, 4.2 KB)
Cached Summaries:
src/ptr.rs 312 B (was 2.1 KB, saved 1.8 KB)
src/raw_page.rs 428 B (was 3.4 KB, saved 3.0 KB)
Total Context: 5.2 KB
Without Compaction: 11.5 KB
Savings: 6.3 KB (55%)
```
### forget_file
Remove a file from tracking entirely.
```json
{ "path": "src/old_file.rs" }
```
## Supported Languages
Currently supported for summarization:
- **Rust** (.rs) — extracts public structs, enums, traits, functions, type aliases, constants, and re-exports
Unsupported file types are read/edited normally without tracking—they won't interfere with compaction.
## How Summaries Work
For a Rust file like:
```rust
//! Type-safe pointer wrappers.
use std::marker::PhantomData;
#[derive(Debug, Clone)]
pub struct Ptr<T> {
raw: *mut T,
_marker: PhantomData<T>,
}
impl<T> Ptr<T> {
pub fn new(raw: *mut T) -> Self {
Self { raw, _marker: PhantomData }
}
pub fn is_null(&self) -> bool {
self.raw.is_null()
}
// Private helper
fn internal_check(&self) -> bool {
!self.raw.is_null()
}
}
```
The summary becomes:
```rust
// Purpose: Type-safe pointer wrappers.
#[derive(Debug, Clone)]
pub struct Ptr<T> { ... }
impl<T> Ptr<T> {
pub fn new(raw: *mut T) -> Self;
pub fn is_null(&self) -> bool;
}
```
Private items, implementation details, and doc comments are condensed—only the public interface remains.
## License
MIT
