⚠️ Platform Support Notice

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.

Code Understanding MCP Server

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.

🤖 AI Assistant Installation

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

Features

• Clone and analyze GitHub repositories or local codebases
• Get repository structure and file organization
• Identify critical files based on complexity metrics and code structure
• Generate detailed repository maps showing:
  • Function signatures and relationships
  • Class definitions and hierarchies
  • Code structure and dependencies
• Retrieve and analyze repository documentation
• Target analysis to specific files or directories
• Keep analysis up-to-date with repository changes via refresh

Quick Start: MCP Client Configuration

Prerequisites

Required: `uv` Installation

This server requires `uv`, a modern Python package manager. If you don't already have `uv` installed:

# 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 official `uv` installation guide at astral.sh/uv.

Installation Methods

Method 1: Direct execution with uvx (Recommended)

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

This launches the server in an isolated environment managed by UV each time.

Method 2: Virtual environment install (Optional)

If you prefer a persistent binary inside a dedicated virtual environment:

# 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

Verify Installation

Depending on your chosen method:

# 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

Configure Your MCP Client

Use one of the following configurations for your MCP client:

{
  "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": []
    }
  }
}

Why Use this MCP Server?

MCP Code Understanding Server

Value Proposition

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.

Common Use Cases

Reference Repository Analysis

• 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

Knowledge Extraction and Documentation

• 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

Codebase Assessment and Improvement

• 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

Legacy System Understanding

• 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

Cross-Project Knowledge Transfer

• 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 our Example Scenarios document. It includes step-by-step walkthroughs of:

• Accelerating developer onboarding to a complex codebase
• Planning and executing API migrations
• Conducting security vulnerability assessments

How It Works

The MCP Code Understanding Server processes repositories through a series of analysis steps:

1. Repository Cloning: The server clones the target repository into its cache

2. Structure Analysis: Analysis of directories, files, and their organization

3. Critical File Identification: Determination of structurally significant components

4. Documentation Retrieval: Collection of all documentation files

5. Semantic Mapping: Creation of a detailed map showing relationships between components

6. Content Analysis: Examination of specific files as needed for deeper understanding

AI assistants integrate with the server by making targeted requests for each analytical stage, building a comprehensive understanding of the codebase that can be used to address specific user questions and needs.

Recommended Workflow for AI Assistants

When working with repositories, AI assistants should follow this workflow for optimal results:

1. Check Cache First: Use `list_cached_repository_branches` to see if the repository is already cached

2. Discover Branch Names: Many repositories use "master", "develop", or other names instead of "main"

3. Refresh Before Analysis: Cached repositories become stale over time

4. Perform Analysis: Once repository is current, use analysis tools

This workflow prevents common issues like clone failures from incorrect branch names, redundant clone attempts, and analysis based on stale cached data.

Design Considerations for Large Codebases

The server employs several strategies to maintain performance and usability even with enterprise-scale repositories:

• Asynchronous Processing: Repository cloning and analysis occur in background threads, providing immediate feedback while deeper analysis continues
• Progressive Analysis: Initial quick analysis enables immediate interaction, with more detailed understanding building over time
• Scope Control: Parameters for `max_tokens`, `files`, and `directories` enable targeted analysis of specific areas of interest
• Threshold Management: Automatic detection of repository size with appropriate guidance for analysis strategies
• Hierarchical Understanding: Repository structure is analyzed first, enabling intelligent prioritization of critical components for deeper semantic analysis

These design choices ensure that developers can start working immediately with large codebases while the system builds a progressively deeper understanding in the background, striking an optimal balance between analysis depth and responsiveness.

GitHub Authentication (Optional)

If you need to access private repositories or want to avoid GitHub API rate limits, add your GitHub token to the configuration:

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

Advanced Configuration Options

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"
      }
    }
  }
}

Available options:

• `--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)

Platform-Specific Notes

macOS

• With `uvx`, 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

Linux

• With `uvx`, 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

Windows

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

Troubleshooting

Dependency Conflicts

If you encounter dependency conflicts when using `uvx`, 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

Binary Not Found

If the installed binary is not found:

1. Check installation location:

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

2. Add to PATH if needed:

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

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

Server Configuration

The server uses a `config.yaml` file 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 a `config.yaml` file 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

For Developers

Prerequisites

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

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

• UV Package Manager: The modern Python package installer

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

Development Setup

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.

Development Tools

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

Run tests with coverage:

uv run pytest

Format code (using black and isort):

# Format with black
uv run black .

# Sort imports
uv run isort .

Type checking with mypy:

uv run mypy .

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

Publishing to PyPI

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

1. Update the version number in `pyproject.toml`:

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

2. Clean previous build artifacts:

# 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

3. Build the distribution packages:

uv run python -m build

4. Verify the built packages:

ls dist/

5. Upload to PyPI (use TestPyPI first if unsure):

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

Version History

v0.1.6 (Latest)

• Dependency Fix: Explicitly pinned `configargparse==1.7` to resolve installation issues caused by the yanked version in PyPI
• This ensures clean installation with `uvx` and other package managers by preventing dependency resolution failures
• No functional changes to the server capabilities

License

MIT