Codebase Context Dumper

🚀 codebase-context-dumper MCP Server

A Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).

🚀 Quick Start

The easiest way to use this tool is via npx, which runs the latest version without needing a local installation. Configure your MCP client (e.g., Claude Desktop, VS Code extensions) to use the following command:

{
  "mcpServers": {
    "codebase-context-dumper": {
      "command": "npx",
      "args": [
        "-y",
        "@lex-tools/codebase-context-dumper"
      ]
    }
  }
}

The MCP client will then be able to invoke the dump_codebase_context tool provided by this server.

✨ Features

Large context windows in LLMs are powerful, but manually selecting and formatting files from a large codebase is tedious. This tool automates the process by:

• Recursively scanning your project directory.
• Including text files from the specified directory tree that are not excluded by .gitignore rules.
• Automatically skipping binary files.
• Concatenating the content with clear file path markers.
• Supporting chunking to handle codebases larger than the LLM's context window.
• Integrating seamlessly with MCP-compatible clients.

💻 Usage Examples

Basic Usage

The recommended way to use this tool is through npx. Here is the configuration for your MCP client:

{
  "mcpServers": {
    "codebase-context-dumper": {
      "command": "npx",
      "args": [
        "-y",
        "@lex-tools/codebase-context-dumper"
      ]
    }
  }
}

Advanced Usage

If you prefer to run a local version (e.g., for development), follow these steps:

1. Clone the repository:

git clone git@github.com:lex-tools/codebase-context-dumper.git
cd codebase-context-dumper

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Configure your MCP client to point to the local build output:

{
  "mcpServers": {
    "codebase-context-dumper": {
      "command": "/path/to/your/local/codebase-context-dumper/build/index.js" // Adjust path
    }
  }
}

📚 Documentation

Tool: dump_codebase_context

Recursively reads text files from a specified directory, respecting .gitignore rules and skipping binary files. Concatenates content with file path headers/footers. Supports chunking the output for large codebases.

Functionality

• Scans the directory provided in base_path.
• Respects .gitignore files at all levels (including nested ones and .git by default).
• Detects and skips binary files.
• Reads the content of each valid text file.
• Prepends a header (--- START: relative/path/to/file ---) and appends a footer (--- END: relative/path/to/file ---) to each file's content.
• Concatenates all processed file contents into a single string.

Input Parameters

• base_path (string, required): The absolute path to the project directory to scan.
• num_chunks (integer, optional, default: 1): The total number of chunks to divide the output into. Must be >= 1.
• chunk_index (integer, optional, default: 1): The 1-based index of the chunk to return. Requires num_chunks > 1 and chunk_index <= num_chunks.

Output

Returns the concatenated (and potentially chunked) text content.

📦 Installation

If you want to run a local version:

1. Clone the repository:

git clone git@github.com:lex-tools/codebase-context-dumper.git
cd codebase-context-dumper

2. Install dependencies:

npm install

3. Build the server:

npm run build

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on development, debugging, and releasing new versions.

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.