{"id":28903787,"url":"https://github.com/alexw00/mcp-codebase-explorer","last_synced_at":"2025-10-03T14:00:10.334Z","repository":{"id":296732224,"uuid":"992618876","full_name":"AlexW00/mcp-codebase-explorer","owner":"AlexW00","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-04T17:20:49.000Z","size":164,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-21T05:53:29.765Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexW00.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-29T12:54:14.000Z","updated_at":"2025-06-04T17:20:51.000Z","dependencies_parsed_at":"2025-06-02T02:23:01.382Z","dependency_job_id":"d2a208ec-dacf-47a8-a975-68a4aee8b8ca","html_url":"https://github.com/AlexW00/mcp-codebase-explorer","commit_stats":null,"previous_names":["alexw00/mcp-codebase-explorer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AlexW00/mcp-codebase-explorer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexW00%2Fmcp-codebase-explorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexW00%2Fmcp-codebase-explorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexW00%2Fmcp-codebase-explorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexW00%2Fmcp-codebase-explorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexW00","download_url":"https://codeload.github.com/AlexW00/mcp-codebase-explorer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexW00%2Fmcp-codebase-explorer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278173366,"owners_count":25942293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-21T12:06:34.996Z","updated_at":"2025-10-03T14:00:10.313Z","avatar_url":"https://github.com/AlexW00.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Codebase Explorer\n\nThis 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.\n\n## Features\n\nThe server implements the following tools:\n\n1. **read_file** - Read a file with optional line range\n\n   - Parameters: `path`, optional `from`, optional `to`\n\n2. **read_dir** - Read a directory and list its contents\n\n   - Parameters: `path`, optional `max_results` (default: 100)\n\n3. **search_file_contents_regex** - Search file contents using regex pattern\n\n   - Parameters: `regex`, optional `subdir`, optional `max_results` (default: 25), optional `context` (default: 5)\n\n4. **search_file_contents_fuzzy** - Search file contents using fuzzy matching\n\n   - Parameters: `query`, optional `subdir`, optional `max_results` (default: 25), optional `context` (default: 5)\n\n5. **search_dir** - Search for files and directories using a regex matched against the full path\n\n   - Parameters: `regex`, optional `subdir`, optional `max_results` (default: 50)\n\n6. **search_dir_fuzzy** - Search for files and directories by name using fuzzy matching\n   - Parameters: `query`, optional `subdir`, optional `max_results` (default: 50)\n\n## Security\n\nAll file operations are restricted to a configurable base directory for security:\n\n- Set `MCP_BASE_DIR` environment variable to define the allowed base directory\n- Defaults to current working directory if not set\n- All file paths are validated to prevent directory traversal attacks\n\n## Installation\n\n### Local Development\n\n```bash\nnpm install\n# ripgrep is installed automatically as part of the dependencies\n```\n\n### Docker\n\nYou can build the Docker image yourself or pull the prebuilt image from the GitHub Container Registry.\n\n#### Local build\n\n```bash\ndocker build -t mcp-codebase-explorer .\n```\n\n#### Pull from GitHub\n\n```bash\ndocker pull ghcr.io/alexw00/mcp-codebase-explorer:latest\n```\n\nAn updated image is published automatically whenever the `main` branch is updated.\n\n## Usage\n\n### Local Development\n\n```bash\n# Build the project\nnpm run build\n\n# Start the server\nnpm start\n\n# Or run in development mode with hot reload\nnpm run dev\n```\n\n### Docker\n\nRun the MCP server in a Docker container with your codebase mounted:\n\n```bash\n# Run with a mounted directory (use quotes for paths with spaces)\ndocker run -it --rm \\\n  -v \"/path/to/your/codebase:/workspace\" \\\n  -e MCP_BASE_DIR=/workspace \\\n  ghcr.io/alexw00/mcp-codebase-explorer:latest\n\n# Example: Mount current directory (properly quoted)\ndocker run -it --rm \\\n  -v \"$(pwd):/workspace\" \\\n  -e MCP_BASE_DIR=/workspace \\\n  ghcr.io/alexw00/mcp-codebase-explorer:latest\n\n# Example: Mount a specific directory with spaces\ndocker run -it --rm \\\n  -v \"/aw/Developer/Buffertab:/workspace\" \\\n  -e MCP_BASE_DIR=/workspace \\\n  ghcr.io/alexw00/mcp-codebase-explorer:latest\n```\n\n## VS Code Configuration\n\nTo use this MCP server with VS Code and Claude, add the following configuration to your VS Code settings:\n\n### Option 1: Local Installation\n\nAdd to your VS Code `settings.json`:\n\n```json\n{\n\t\"mcp.mcpServers\": {\n\t\t\"codebase-explorer\": {\n\t\t\t\"command\": \"node\",\n\t\t\t\"args\": [\"/path/to/mcp-codebase-explorer/dist/server.js\"],\n\t\t\t\"env\": {\n\t\t\t\t\"MCP_BASE_DIR\": \"/path/to/your/codebase\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### Option 2: Docker Container\n\nAdd to your VS Code `settings.json`:\n\n```json\n{\n\t\"mcp.mcpServers\": {\n\t\t\"codebase-explorer\": {\n\t\t\t\"command\": \"docker\",\n\t\t\t\"args\": [\n\t\t\t\t\"run\",\n\t\t\t\t\"-i\",\n\t\t\t\t\"--rm\",\n\t\t\t\t\"-v\",\n\t\t\t\t\"/path/to/your/codebase:/workspace\",\n\t\t\t\t\"-e\",\n                                \"MCP_BASE_DIR=/workspace\",\n                                \"ghcr.io/alexw00/mcp-codebase-explorer:latest\"\n\t\t\t]\n\t\t}\n\t}\n}\n```\n\n**Note**: For paths with spaces, escape them properly or use the full absolute path without spaces if possible.\n\n### Claude Desktop Configuration\n\nFor Claude Desktop, add to your `claude_desktop_config.json`:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"codebase-explorer\": {\n\t\t\t\"command\": \"docker\",\n\t\t\t\"args\": [\n\t\t\t\t\"run\",\n\t\t\t\t\"-i\",\n\t\t\t\t\"--rm\",\n\t\t\t\t\"-v\",\n\t\t\t\t\"/aw/Developer/Buffertab:/workspace\",\n\t\t\t\t\"-e\",\n                                \"MCP_BASE_DIR=/workspace\",\n                                \"ghcr.io/alexw00/mcp-codebase-explorer:latest\"\n\t\t\t]\n\t\t}\n\t}\n}\n```\n\n**Important**: The volume mount path must be properly quoted when running Docker commands manually. In JSON configuration files, the paths are automatically handled correctly.\n\n## Troubleshooting\n\n### Docker Volume Mount Issues\n\nIf you encounter errors like \"includes invalid characters for a local volume name\", ensure your paths are properly quoted:\n\n```bash\n# ✅ Correct - paths with spaces are quoted\ndocker run -it --rm \\\n  -v \"/path/with spaces:/workspace\" \\\n  -e MCP_BASE_DIR=/workspace \\\n  ghcr.io/alexw00/mcp-codebase-explorer:latest\n\n# ❌ Incorrect - unquoted paths with spaces\ndocker run -it --rm \\\n  -v /path/with spaces:/workspace \\\n  -e MCP_BASE_DIR=/workspace \\\n  ghcr.io/alexw00/mcp-codebase-explorer:latest\n```\n\n### Permission Issues\n\nIf you encounter permission issues when accessing files, you may need to run the container with your user ID:\n\n```bash\ndocker run -it --rm \\\n  -v \"$(pwd):/workspace\" \\\n  -e MCP_BASE_DIR=/workspace \\\n  --user \"$(id -u):$(id -g)\" \\\n  ghcr.io/alexw00/mcp-codebase-explorer:latest\n```\n\n## Implementation Details\n\n- Uses performant tools like `find` and `ripgrep` for searching\n- Implements fuzzy search using the `fuzzysort` library\n- All tools are implemented as TypeScript modules for maintainability\n- Error handling is implemented for all tools\n- Built with MCP TypeScript SDK v1.12.0\n- Uses ES modules and modern TypeScript features\n- Includes path validation and security restrictions\n\n## Project Structure\n\n- `src/tools/` - Individual tool implementations\n- `src/tools.ts` - Tool definitions and MCP SDK integration\n- `src/server.ts` - MCP server setup and configuration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexw00%2Fmcp-codebase-explorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexw00%2Fmcp-codebase-explorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexw00%2Fmcp-codebase-explorer/lists"}