Clone a repository into MCP server's cache and prepare it for analysis.

    This tool must be called before using analysis endpoints like get_source_repo_map
    or get_repo_documentation. It copies the repository into MCP's cache and
    automatically starts building a repository map in the background.

    IMPORTANT - BEFORE CLONING:
        1. CHECK IF ALREADY CACHED: Use list_cached_repository_branches(url) first to avoid
           redundant clone attempts. Returns empty list if not cached, or existing branches if cached.

        2. VERIFY DEFAULT BRANCH NAME: Many repositories use "master", "develop", or other names
           instead of "main". If branch is not specified and clone fails:
           - Use list_remote_branches(url) to discover available branches
           - Look for "main", "master", "develop", or check repo documentation
           - Explicitly specify the correct branch parameter

        3. AFTER CLONING: The cached repository can become stale over time. Before analysis,
           consider using refresh_repo() to ensure you're working with the latest code.

    Args:
        url (str): URL of remote repository or path to local repository to analyze
        branch (str, optional): Specific branch to clone for analysis. Defaults to "main" if not
            specified, but many repositories use "master" or other names - verify first!
        cache_strategy (str, optional): Cache strategy - "shared" (default) or "per-branch"
            - "shared": One cache entry per repo, switch branches in place
            - "per-branch": Separate cache entries for each branch (useful for PR reviews)

    Returns:
        dict: Response with format:
            {
                "status": "pending" | "already_cloned" | "switched_branch" | "error",
                "path": str,  # Cache location where repo is being cloned
                "message": str,  # Status message about clone and analysis
                "cache_strategy": str,  # Strategy used for caching
                "current_branch": str,  # (if applicable) Current active branch
                "previous_branch": str,  # (if switched) Previous branch name
            }

    Recommended Workflow:
        1. Check cache: cached = list_cached_repository_branches(url)
        2. If not cached, discover branches: branches = list_remote_branches(url)
        3. Clone with correct branch: clone_repo(url, branch=discovered_branch)
        4. Before analysis, refresh if needed: refresh_repo(url)
        5. Perform analysis: get_source_repo_map(url, ...)

    Note:
        - This is a setup operation for MCP analysis only
        - Does not modify the source repository
        - Repository map building starts automatically after clone completes
        - Use get_source_repo_map to check analysis status and retrieve results
        - Per-branch strategy allows simultaneous access to different branches
    

    Analyze and identify the most structurally significant files in a codebase.

    Uses code complexity metrics to calculate importance scores, helping identify
    files that are most critical for understanding the system's structure.

    Args:
        repo_path: Path/URL matching what was provided to clone_repo
        files: Optional list of specific files to analyze
        directories: Optional list of specific directories to analyze
        limit: Maximum number of files to return (default: 50)
        include_metrics: Include detailed metrics in response (default: True)

    Returns:
        dict: {
            "status": str,  # "success", "error"
            "files": [{
                "path": str,
                "importance_score": float,
                "metrics": {  # Only if include_metrics=True
                    "total_ccn": int,
                    "max_ccn": int,
                    "function_count": int,
                    "nloc": int
                }
            }],
            "total_files_analyzed": int
        }
    

    Retrieve and analyze repository documentation files.

    Searches for and analyzes documentation within the repository, including:
    - README files
    - API documentation
    - Design documents
    - User guides
    - Installation instructions
    - Other documentation files

    Args:
        repo_path (str): Path or URL matching what was originally provided to clone_repo

    Returns:
        dict: Documentation analysis results with format:
            {
                "status": str,  # "success", "error", or "waiting"
                "message": str,  # Only for error/waiting status
                "documentation": {  # Only for success status
                    "files": [
                        {
                            "path": str,      # Relative path in repo
                            "category": str,  # readme, api, docs, etc.
                            "format": str     # markdown, rst, etc.
                        }
                    ],
                    "directories": [
                        {
                            "path": str,
                            "doc_count": int
                        }
                    ],
                    "stats": {
                        "total_files": int,
                        "by_category": dict,
                        "by_format": dict
                    }
                }
            }
    

    Retrieve file contents or directory listings from a repository.

    Args:
        repo_path (str): Path or URL to the repository
        resource_path (str, optional): Path to the target file or directory within the repository. Defaults to the repository root if not provided.
        branch (str, optional): Specific branch to read from (only used with per-branch cache strategy)
        cache_strategy (str, optional): Cache strategy - "shared" (default) or "per-branch"

    Returns:
        dict: For files:
            {
                "type": "file",
                "path": str,  # Relative path within repository
                "content": str,  # Complete file contents
                "branch": str,  # Current branch name
                "cache_strategy": str  # Cache strategy used
            }
            For directories:
            {
                "type": "directory",
                "path": str,  # Relative path within repository
                "contents": List[str],  # List of immediate files and subdirectories
                "branch": str,  # Current branch name
                "cache_strategy": str  # Cache strategy used
            }

    Note:
        Directory listings are not recursive - they only show immediate contents.
        To explore subdirectories, make additional calls with the subdirectory path.
    

    Get repository structure information with optional file listings.

    Args:
        repo_path: Path/URL matching what was provided to clone_repo
        directories: Optional list of directories to limit results to
        include_files: Whether to include list of files in response

    Returns:
        dict: {
            "status": str,
            "message": str,
            "directories": [{
                "path": str,
                "analyzable_files": int,
                "extensions": {
                    "py": 10,
                    "java": 5,
                    "ts": 3
                },
                "files": [str]  # Only present if include_files=True
            }],
            "total_analyzable_files": int
        }
    

    Retrieve a semantic analysis map of the repository's code structure.

    Returns a detailed map of the repository's structure, including file hierarchy,
    code elements (functions, classes, methods), and their relationships. Can analyze
    specific files/directories or the entire repository.

    Args:
        repo_path (str): Path or URL matching what was originally provided to clone_repo
        files (List[str], optional): Specific files to analyze. If None, analyzes all files
        directories (List[str], optional): Specific directories to analyze. If None, analyzes all directories
        max_tokens (int, optional): Limit total tokens in analysis. Useful for large repositories
        branch (str, optional): Specific branch to analyze (only used with per-branch cache strategy)
        cache_strategy (str, optional): Cache strategy - "shared" (default) or "per-branch"

    Returns:
        dict: Response with format:
            {
                "status": str,  # "success", "building", "waiting", or "error"
                "content": str,  # Hierarchical representation of code structure
                "metadata": {    # Analysis metadata
                    "excluded_files_by_dir": dict,
                    "is_complete": bool,
                    "max_tokens": int
                },
                "message": str,  # Present for "building"/"waiting" status
                "error": str     # Present for "error" status
            }

    Note:
        - Repository must be previously cloned using clone_repo
        - Initial analysis happens in background after clone
        - Returns "building" status while analysis is in progress
        - Content includes file structure, code elements, and their relationships
        - For large repos, consider using max_tokens or targeting specific directories
    

    Check if a repository is already cached and list all cached branch versions.

    USE THIS FIRST before calling clone_repo to avoid redundant clone attempts.
    If the repository is already cached, you can proceed directly to refresh_repo
    and analysis instead of cloning again.

    This tool scans the MCP cache to find all entries for a given repository URL,
    showing both shared and per-branch cache entries. Useful for understanding
    what branches are available and their current status.

    Args:
        repo_url (str): Repository URL to search for (must match exact URL used in clone_repo)

    Returns:
        dict: Response with format:
            {
                "status": "success" | "error",
                "repo_url": str,  # Repository URL searched
                "cached_branches": [  # List of cached branch entries (empty if not cached)
                    {
                        "requested_branch": str,  # Branch that was requested during clone
                        "current_branch": str,    # Current active branch in the cache
                        "cache_path": str,        # File system path to cached repository
                        "cache_strategy": str,    # "shared" or "per-branch"
                        "last_access": str,       # ISO timestamp of last access
                        "clone_status": dict,     # Clone operation status
                        "repo_map_status": dict   # Repository map build status
                    }
                ],
                "total_cached": int  # Total number of cached entries (0 if not cached)
            }

    Typical Workflow:
        1. Check cache first: result = list_cached_repository_branches(url)
        2. If result["total_cached"] > 0:
           - Repository is cached, skip clone
           - Use refresh_repo(url) to update cached code
        3. If result["total_cached"] == 0:
           - Repository not cached yet
           - Use list_remote_branches(url) to discover branch names
           - Use clone_repo(url, branch=correct_branch)

    Note:
        - Only returns repositories that have been cloned via clone_repo
        - Empty cached_branches list means repository is NOT cached
        - Useful for PR review workflows to see all available branch versions
        - Shows both active and completed cache entries
        - Helps identify which cache strategy was used for each entry
    

    Discover all available branches in a remote repository without cloning.

    CRITICAL USE CASE: Many repositories use "master", "develop", or other names instead
    of "main" as their default branch. Use this tool BEFORE clone_repo to discover the
    actual default branch name and avoid clone failures.

    This tool uses git ls-remote --heads to query the remote repository, which is fast
    and does not require cloning the entire repository.

    Args:
        repo_url (str): Remote repository URL (e.g., https://github.com/user/repo)

    Returns:
        dict: Response with format:
            {
                "status": "success" | "error",
                "repo_url": str,  # Repository URL queried
                "remote_branches": [str],  # List of branch names (e.g., ["main", "develop", "feature-x"])
                "total_remote": int,  # Total number of branches found
                "error": str  # (Only on error) Error message
            }

    Common Default Branch Names to Look For:
        - "main" (modern GitHub default)
        - "master" (traditional Git default)
        - "develop" or "development" (common for dev workflows)
        - Check repository documentation if unclear

    Typical Workflow:
        1. Discover branches: branches = list_remote_branches(url)
        2. Identify default branch from branches["remote_branches"]
           - Look for "main", "master", or "develop"
           - If unsure, check the repository's web page
        3. Clone with correct branch: clone_repo(url, branch=identified_branch)

    Note:
        - Fast operation, does not clone the repository
        - Requires network access to the remote repository
        - Works with any Git repository (GitHub, GitLab, Bitbucket, etc.)
    

    Update a previously cloned repository in MCP's cache and refresh its analysis.

    CRITICAL: Cached repositories become stale over time. ALWAYS refresh before analysis
    to ensure you're working with the latest code. Failure to refresh means your analysis
    may be based on outdated code that could be days, weeks, or months old.

    For Git repositories, performs a git pull to get latest changes.
    For local directories, copies the latest content from the source.
    Then triggers a new repository map build to ensure all analysis is based on
    the updated code.

    RECOMMENDED WORKFLOW:
        1. Check if repository is cached: list_cached_repository_branches(url)
        2. If cached, ALWAYS refresh first: refresh_repo(url)
        3. Wait a moment for refresh to complete
        4. Then perform analysis: get_source_repo_map(url, ...)

        This ensures your analysis reflects current code, not stale cached data.

    Args:
        repo_path (str): Path or URL matching what was originally provided to clone_repo
        branch (str, optional): Specific branch to switch to during refresh
        cache_strategy (str, optional): Cache strategy - must match original clone strategy

    Returns:
        dict: Response with format:
            {
                "status": str,  # "pending", "switched_branch", "error"
                "path": str,    # (On pending) Cache location being refreshed
                "message": str, # (On pending) Status message
                "error": str    # (On error) Error message
                "cache_strategy": str  # Strategy used for caching
            }

    Note:
        - Repository must be previously cloned and have completed initial analysis
        - Updates MCP's cached copy, does not modify the source repository
        - Automatically triggers rebuild of repository map with updated files
        - If branch is specified, switches to that branch after pulling latest changes
        - cache_strategy should match the strategy used during original clone
        - Operation runs in background, check get_repo_map_content for status