This project implements an MCP (Model Context Protocol) server that exposes tools to explore and understand a codebase. The server provides various tools that can be used by an agent to retrieve information from a codebase.

The server implements the following tools:

1. read_file - Read a file with optional line range

   • Parameters: path, optional from, optional to

2. read_dir - Read a directory and list its contents

   • Parameters: path, optional max_results (default: 100)

3. search_file_contents_regex - Search file contents using regex pattern

   • Parameters: regex, optional subdir, optional max_results (default: 25), optional context (default: 5)

4. search_file_contents_fuzzy - Search file contents using fuzzy matching

   • Parameters: query, optional subdir, optional max_results (default: 25), optional context (default: 5)

5. search_dir - Search for files and directories using a regex matched against the full path

   • Parameters: regex, optional subdir, optional max_results (default: 50)

6. search_dir_fuzzy - Search for files and directories by name using fuzzy matching

   • Parameters: query, optional subdir, optional max_results (default: 50)

All file operations are restricted to a configurable base directory for security:

• Set MCP_BASE_DIR environment variable to define the allowed base directory
• Defaults to current working directory if not set
• All file paths are validated to prevent directory traversal attacks

npm install
# ripgrep is installed automatically as part of the dependencies

You can build the Docker image yourself or pull the prebuilt image from the GitHub Container Registry.

docker build -t mcp-codebase-explorer .

docker pull ghcr.io/alexw00/mcp-codebase-explorer:latest

An updated image is published automatically whenever the main branch is updated.

# Build the project
npm run build

# Start the server
npm start

# Or run in development mode with hot reload
npm run dev

Run the MCP server in a Docker container with your codebase mounted:

# Run with a mounted directory (use quotes for paths with spaces)
docker run -it --rm \
  -v "/path/to/your/codebase:/workspace" \
  -e MCP_BASE_DIR=/workspace \
  ghcr.io/alexw00/mcp-codebase-explorer:latest

# Example: Mount current directory (properly quoted)
docker run -it --rm \
  -v "$(pwd):/workspace" \
  -e MCP_BASE_DIR=/workspace \
  ghcr.io/alexw00/mcp-codebase-explorer:latest

# Example: Mount a specific directory with spaces
docker run -it --rm \
  -v "/aw/Developer/Buffertab:/workspace" \
  -e MCP_BASE_DIR=/workspace \
  ghcr.io/alexw00/mcp-codebase-explorer:latest

To use this MCP server with VS Code and Claude, add the following configuration to your VS Code settings:

Add to your VS Code settings.json:

{
	"mcp.mcpServers": {
		"codebase-explorer": {
			"command": "node",
			"args": ["/path/to/mcp-codebase-explorer/dist/server.js"],
			"env": {
				"MCP_BASE_DIR": "/path/to/your/codebase"
			}
		}
	}
}

Add to your VS Code settings.json:

{
	"mcp.mcpServers": {
		"codebase-explorer": {
			"command": "docker",
			"args": [
				"run",
				"-i",
				"--rm",
				"-v",
				"/path/to/your/codebase:/workspace",
				"-e",
                                "MCP_BASE_DIR=/workspace",
                                "ghcr.io/alexw00/mcp-codebase-explorer:latest"
			]
		}
	}
}

Note: For paths with spaces, escape them properly or use the full absolute path without spaces if possible.

For Claude Desktop, add to your claude_desktop_config.json:

{
	"mcpServers": {
		"codebase-explorer": {
			"command": "docker",
			"args": [
				"run",
				"-i",
				"--rm",
				"-v",
				"/aw/Developer/Buffertab:/workspace",
				"-e",
                                "MCP_BASE_DIR=/workspace",
                                "ghcr.io/alexw00/mcp-codebase-explorer:latest"
			]
		}
	}
}

Important: The volume mount path must be properly quoted when running Docker commands manually. In JSON configuration files, the paths are automatically handled correctly.

If you encounter errors like "includes invalid characters for a local volume name", ensure your paths are properly quoted:

# ✅ Correct - paths with spaces are quoted
docker run -it --rm \
  -v "/path/with spaces:/workspace" \
  -e MCP_BASE_DIR=/workspace \
  ghcr.io/alexw00/mcp-codebase-explorer:latest

# ❌ Incorrect - unquoted paths with spaces
docker run -it --rm \
  -v /path/with spaces:/workspace \
  -e MCP_BASE_DIR=/workspace \
  ghcr.io/alexw00/mcp-codebase-explorer:latest

If you encounter permission issues when accessing files, you may need to run the container with your user ID:

docker run -it --rm \
  -v "$(pwd):/workspace" \
  -e MCP_BASE_DIR=/workspace \
  --user "$(id -u):$(id -g)" \
  ghcr.io/alexw00/mcp-codebase-explorer:latest

• Uses performant tools like find and ripgrep for searching
• Implements fuzzy search using the fuzzysort library
• All tools are implemented as TypeScript modules for maintainability
• Error handling is implemented for all tools
• Built with MCP TypeScript SDK v1.12.0
• Uses ES modules and modern TypeScript features
• Includes path validation and security restrictions

• src/tools/ - Individual tool implementations
• src/tools.ts - Tool definitions and MCP SDK integration
• src/server.ts - MCP server setup and configuration