MCP File Compaction

You run an MCP server that keeps your Claude context lean by auto-summarizing inactive files to their public interfaces while keeping the active file fully available. This helps you work across large codebases without paying for the entire project in every context window.

How to use

Interact with the server through an MCP client to manage files and their context. Read a full file to make it the active file, peek a file’s public interface to review APIs, edit or write files to update your codebase, and check a snapshot of which files are tracked and how much context they save. The server automatically summarizes inactive files when you switch away from them, so Claude only needs the public API surface for those files.

Key actions you can perform include reading files to activate them, peeking at a file’s interface without changing the active file, editing or writing files, and querying the current context savings. These operations keep your context window smaller while preserving the public APIs you rely on.

How to install

Prerequisites: ensure you have a supported runtime environment installed on your machine. Commonly this means Node.js and npm for client-side MCP tools.

From GitHub (recommended): you can start the MCP server directly with a single command.

Local development workflow includes cloning the project, installing dependencies, and building before use.

Configuration and usage examples

{
  "mcpServers": {
    "file-compaction": {
      "command": "npx",
      "args": ["github:YOUR_USERNAME/mcp-file-compaction"]
    }
  }
}

For local development, you can run the server using your local build after you install dependencies and build the project.

{
  "mcpServers": {
    "file-compaction": {
      "command": "node",
      "args": ["/path/to/mcp-file-compaction/dist/index.js"]
    }
  }
}

Add to your Claude Code MCP settings to enable file compaction, and add instructions to your file operation references so teammates understand when to read, peek, edit, or write files.

Additional configuration details

You can review the current tracked files and the savings in context by querying the file status. The active file remains full content while inactive files are summarized to their public interfaces.

License

MIT

Tools and endpoints

The MCP server exposes the following operations to manage files and their context:

• read_file: Read a file and mark it as the active file; auto-summarize the previous active file when you switch to a new one.
• peek_file: Get a summary of a file’s public interface without changing the active file.
• edit_file: Replace a string in a file; the file becomes the active file.
• write_file: Write content to a file, creating it if needed; the file becomes the active file.
• file_status: Show all tracked files with size comparison and context savings.
• forget_file: Remove a file from tracking entirely.

Available 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.

peek_file

Get a summary of a file's public interface without changing the active file.

edit_file

Edit a file by replacing a specific string. The file becomes the active file.

write_file

Write content to a file, creating it if needed. The file becomes the active file.

file_status

Show all tracked files with size comparison and savings.

forget_file

Remove a file from tracking entirely.