Code Understanding MCP Server

This MCP server has been tested on macOS and Linux. Windows support is currently unverified (not yet tested).

If you try Windows and encounter issues, please open an issue so we can improve cross-platform support.

An MCP (Model Context Protocol) server designed to understand codebases and provide intelligent context to AI coding assistants. This server handles both local and remote GitHub repositories and supports standard MCP-compliant operations.

Have an AI coding assistant help you install this server!Copy and paste the contents of ourSetup Assistant Promptto your AI assistant (Claude, ChatGPT, Cursor, etc.) and it will guide you through the entire installation process.

# Install UV (macOS/Linux) curl -sSf https://astral.sh/uv/install.sh | sh # Install UV (Windows PowerShell) irm https://astral.sh/uv/install.ps1 | iex

For more installation options, visit the officialuvinstallation guide atastral.sh/uv.

# Run directly without installing a global binary uvx code-understanding-mcp-server

# Create a dedicated virtual environment uv venv ~/.venvs/mcp-code-understanding # Activate it (macOS/Linux) source ~/.venvs/mcp-code-understanding/bin/activate # Install the package into the venv uv pip install code-understanding-mcp-server # Run the server code-understanding-mcp-server

# Method 1 (uvx): runs via uvx; no persistent binary is installed uvx --version # Method 2 (venv install): verify the binary inside your venv which code-understanding-mcp-server # Expected output example: /Users/username/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server

{ "mcpServers": { "code-understanding": { "command": "uvx", "args": [ "code-understanding-mcp-server" ] } } }

Alternatively, if you installed into a virtual environment, point directly to the binary in that environment:

{ "mcpServers": { "code-understanding": { "command": "/path/to/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server", "args": [] } } }

The MCP Code Understanding Server empowers AI assistants with comprehensive code comprehension capabilities, enabling them to provide more accurate, contextual, and practical assistance with software development tasks. By creating a semantic bridge between repositories and AI systems, this server dramatically reduces the time and friction involved in code exploration, analysis, and implementation guidance.

- Examine external repositories (libraries, dependencies, etc.) to inform current development
- Find implementation patterns and examples in open-source projects
- Understand how specific libraries work internally when documentation is insufficient
- Compare implementation approaches across similar projects
- Identify best practices from high-quality codebases

- Generate comprehensive documentation for poorly documented codebases
- Create architectural overviews and component relationship diagrams
- Develop progressive learning paths for developer onboarding
- Extract business logic and domain knowledge embedded in code
- Identify and document system integration points and dependencies

- Analyze technical debt and prioritize refactoring efforts
- Identify security vulnerabilities and compliance issues
- Assess test coverage and quality
- Detect dead code, duplicated logic, and optimization opportunities
- Evaluate implementation against design patterns and architectural principles

- Recover knowledge from systems with minimal documentation
- Support migration planning by understanding system boundaries
- Analyze complex dependencies before making changes
- Trace feature implementations across multiple components
- Understand historical design decisions and their rationales

- Apply patterns from one project to another
- Bridge knowledge gaps between teams working on related systems
- Identify reusable components across multiple projects
- Understand differences in implementation approaches between teams
- Facilitate knowledge sharing in distributed development environments

For detailed examples of how the MCP Code Understanding Server can be used in real-world scenarios, see ourExample Scenariosdocument. It includes step-by-step walkthroughs of:

{ "mcpServers": { "code-understanding": { "command": "/path/to/code-understanding-mcp-server", "args": [], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here" } } } }

For advanced users, the server supports several configuration options:

{ "mcpServers": { "code-understanding": { "command": "/path/to/code-understanding-mcp-server", "args": [ "--cache-dir", "~/custom-cache-dir", // Override repository cache location "--max-cached-repos", "20", // Override maximum number of cached repos "--transport", "stdio", // Transport type (stdio or sse) "--port", "3001" // Port for SSE transport (only used with sse) ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here" } } } }

- --cache-dir: Override the repository cache directory location (default: ~/.cache/mcp-code-understanding)
- --max-cached-repos: Set maximum number of cached repositories (default: 10)
- --transport: Choose transport type (stdio or sse, default: stdio)
- --port: Set port for SSE transport (default: 3001, only used with sse transport)

- Withuvx, no persistent binary is installed; no PATH changes are required
- With a virtual environment, ensure you activate it or reference the full path to the venv binary

- Withuvx, no persistent binary is installed; no PATH changes are required
- With a virtual environment, you may prefer adding a helper alias or activating the venv before use

- Not currently supported- Windows support is planned for a future release
- Development work is ongoing to enable Windows compatibility

If you encounter dependency conflicts when usinguvx, create an isolated environment and install the package there:

# Create a dedicated virtual environment uv venv ~/.venvs/mcp-code-understanding # Activate it (macOS/Linux) source ~/.venvs/mcp-code-understanding/bin/activate # Install the package uv pip install code-understanding-mcp-server # Run the server code-understanding-mcp-server

# macOS/Linux find ~/.local -name "code-understanding-mcp-server" 2>/dev/null

# Add to ~/.bashrc, ~/.zshrc, or appropriate shell config export PATH="$HOME/.local/bin:$PATH"

Use the absolute path to your venv binary in MCP configuration if not activating the venv

The server uses aconfig.yamlfile for base configuration. This file is automatically created in the standard configuration directory (~/.config/mcp-code-understanding/config.yaml) when the server first runs. You can also place aconfig.yamlfile in your current directory to override the default configuration.

Here's the default configuration structure:

name: "Code Understanding Server" log_level: "debug" repository: cache_dir: "~/.cache/mcp-code-understanding" max_cached_repos: 10 documentation: include_tags: - markdown - rst - adoc include_extensions: - .md - .markdown - .rst - .txt - .adoc - .ipynb format_mapping: tag:markdown: markdown tag:rst: restructuredtext tag:adoc: asciidoc ext:.md: markdown ext:.markdown: markdown ext:.rst: restructuredtext ext:.txt: plaintext ext:.adoc: asciidoc ext:.ipynb: jupyter category_patterns: readme: - readme api: - api documentation: - docs - documentation examples: - examples - sample

- Python 3.11 or 3.12: Required for both development and usage

# Verify your Python version python --version # or python3 --version

# Install UV curl -sSf https://astral.sh/uv/install.sh | sh

To contribute or run this project locally:

# 1. Clone the repository git clone https://github.com/yourusername/mcp-code-understanding.git cd mcp-code-understanding # 2. Create virtual environment uv venv # 3. Activate the virtual environment # Choose the command appropriate for your operating system and shell: # Linux/macOS (bash/zsh): source .venv/bin/activate # Windows (Command Prompt - cmd.exe): .venv\\Scripts\\activate.bat # Windows (PowerShell): # Note: You might need to adjust your execution policy first. # Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process .venv\\Scripts\\Activate.ps1 # 4. Install dependencies (editable mode with dev extras) # (Ensure your virtual environment is activated first!) uv pip install -e ".[dev]" # 5. Set up pre-commit hooks pre-commit install # 6. Run tests uv run pytest # 7. Test the server using MCP inspector # Without GitHub authentication: uv run mcp dev src/code_understanding/mcp/server/app.py # With GitHub authentication (for testing private repos): GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here uv run mcp dev src/code_understanding/mcp/server/app.py

This will launch an interactive console where you can test all MCP server endpoints directly.

The following development tools are available after installing with dev extras (.[dev]):

# Format with black uv run black . # Sort imports uv run isort .

All tools are configured via pyproject.toml with settings optimized for this project.

When you're ready to publish a new version to PyPI, follow these steps:
-

Update the version number inpyproject.toml:

# Edit pyproject.toml and change the version field # For example: version = "0.1.1"

# Remove previous distribution packages and build directories rm -rf dist/ 2>/dev/null || true rm -rf build/ 2>/dev/null || true rm -rf src/.egg-info/ 2>/dev/null || true

# Install twine if you haven't already uv pip install twine # For PyPI release: uv run python -m twine upload dist/

You'll need PyPI credentials configured or you'll be prompted to enter them during upload.

- Dependency Fix: Explicitly pinnedconfigargparse==1.7to resolve installation issues caused by the yanked version in PyPI
- This ensures clean installation withuvxand other package managers by preventing dependency resolution failures
- No functional changes to the server capabilities

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Create crafted UI components inspired by the best 21st.dev design engineers.

Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server