feat(git): add git_clone tool to lean interface (#177) (#179)

Adds first-class git_clone(repo_url, target_path, branch, depth,
single_branch, recurse_submodules) to the lean git domain so multi-repo
standardization flows no longer need the git_init + git_remote_add +
git_fetch + git_checkout workaround.

- Implementation in git/_remote_ops.py using Repo.clone_from with
  multi_options=['--branch=...', '--depth=...', '--single-branch',
  '--recurse-submodules'] (=-form required by GitPython arg handling).
- GitClone Pydantic model in git/models.py mirrors GitInit pattern.
- Re-export through git/operations.py.
- ToolDefinition added to lean/registry_git.py between git_init and
  git_push, using model_json_schema() like git_init (not the inline
  dict form of git_fetch).
- 7 unit tests in tests/unit/git/test_git_clone.py cover happy path,
  branch checkout, shallow depth (via file:// URL since local-path
  clone short-circuits --depth), single-branch flag, rejection of
  non-empty target and missing parent, and GitCommandError handling.
- README.md tool count updated 50 -> 51, git count 25 -> 26.

Closes #177

Author: MementoRC

README.md

@@ -137,15 +137,15 @@ The server provides Azure DevOps integration for monitoring and analyzing Azure
 
 ### Lean MCP Interface (Context-Optimized)
 
-The server provides an alternative **lean interface** that reduces context consumption by ~97% (from ~30k tokens to ~900 tokens). Instead of exposing all 51 tools upfront, it uses a 3-meta-tool pattern:
+The server provides an alternative **lean interface** that reduces context consumption by ~97% (from ~30k tokens to ~900 tokens). Instead of exposing all 52 tools upfront, it uses a 3-meta-tool pattern:
 
 | Meta-Tool | Purpose |
 |-----------|---------|
 | `discover_tools(pattern)` | List available tools with optional filtering |
 | `get_tool_spec(tool_name)` | Get full schema for a specific tool on-demand |
 | `execute_tool(tool_name, params)` | Execute any tool dynamically |
 
-**Tool Coverage**: All 50 tools remain accessible (25 git, 22 GitHub, 3 Azure DevOps).
+**Tool Coverage**: All 51 tools remain accessible (26 git, 22 GitHub, 3 Azure DevOps).
 
 **Usage Example**:
 ```python

src/mcp_server_git/git/_remote_ops.py

@@ -15,6 +15,7 @@
 
 __all__ = [
     "_get_github_token_from_cli",
+    "git_clone",
     "git_push",
     "git_pull",
     "git_remote_list",
@@ -459,6 +460,45 @@ def git_remote_get_url(repo: Repo, name: str) -> str:
         return f"❌ Remote get-url error: {str(e)}"
 
 
+def git_clone(
+    repo_url: str,
+    target_path: str,
+    branch: str | None = None,
+    depth: int | None = None,
+    single_branch: bool = False,
+    recurse_submodules: bool = False,
+) -> str:
+    """Clone a remote repository to a local path"""
+    try:
+        target = Path(target_path)
+        if not target.parent.exists():
+            raise ValueError(f"Parent directory does not exist: {target.parent}")
+        if target.exists() and any(target.iterdir()):
+            raise ValueError(
+                f"Target path already exists and is not empty: {target_path}"
+            )
+
+        multi_options = []
+        if branch:
+            multi_options.append(f"--branch={branch}")
+        if depth is not None:
+            multi_options.append(f"--depth={depth}")
+        if single_branch:
+            multi_options.append("--single-branch")
+        if recurse_submodules:
+            multi_options.append("--recurse-submodules")
+
+        Repo.clone_from(repo_url, target_path, multi_options=multi_options)
+
+        return f"✅ Cloned {repo_url} to {target_path}"
+    except ValueError:
+        raise
+    except GitCommandError as e:
+        return f"❌ Clone failed: {str(e)}"
+    except Exception as e:
+        return f"❌ Clone error: {str(e)}"
+
+
 def git_fetch(
     repo: Repo,
     remote: str = "origin",

src/mcp_server_git/git/models.py

@@ -105,6 +105,15 @@ class GitInit(BaseModel):
     repo_path: str
 
 
+class GitClone(BaseModel):
+    repo_url: str
+    target_path: str
+    branch: str | None = None
+    depth: int | None = None
+    single_branch: bool = False
+    recurse_submodules: bool = False
+
+
 class GitPush(BaseModel):
     repo_path: str
     remote: str = "origin"
@@ -240,12 +249,13 @@ class GitBranchList(BaseModel):
         None, description="commit-ish; only branches containing this commit"
     )
     merged: bool | None = Field(
-        None, description="True=only merged into HEAD, False=only unmerged, None=no filter"
+        None,
+        description="True=only merged into HEAD, False=only unmerged, None=no filter",
     )
     sort: str | None = Field(
         None,
         description="Sort key, e.g. '-committerdate' (most-recent first), 'refname', 'authordate'. "
-                    "Mirrors `git for-each-ref --sort=<key>` semantics. None = no ordering guarantee.",
+        "Mirrors `git for-each-ref --sort=<key>` semantics. None = no ordering guarantee.",
     )
 
 

src/mcp_server_git/git/operations.py

@@ -29,6 +29,7 @@
 )
 from ._init_ops import git_init
 from ._remote_ops import (
+    git_clone,
     git_fetch,
     git_pull,
     git_push,
@@ -68,6 +69,7 @@
 )
 
 __all__ = [
+    "git_clone",
     "git_status",
     "git_diff_unstaged",
     "git_diff_staged",

src/mcp_server_git/lean/registry_git.py

@@ -11,6 +11,7 @@
     GitBranchUpdate,
     GitCheckout,
     GitCherryPick,
+    GitClone,
     GitCommit,
     GitConfigGet,
     GitConfigList,
@@ -168,6 +169,14 @@ def wrapper(repo_path: str, **kwargs):
             domain="git",
             complexity="core",
         ),
+        ToolDefinition(
+            name="git_clone",
+            implementation=git_ops.git_clone,  # git_clone takes no Repo, operates directly
+            description="Clone a remote repository to a local path",
+            schema=GitClone.model_json_schema(),
+            domain="git",
+            complexity="core",
+        ),
         ToolDefinition(
             name="git_push",
             implementation=wrap_repo_op(git_ops.git_push),

tests/unit/git/test_git_clone.py

@@ -0,0 +1,166 @@
+"""Tests for git_clone operation"""
+
+import shutil
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from src.mcp_server_git.utils.git_import import Repo
+
+
+def _make_source_repo(
+    path: Path, num_commits: int = 1, branch: str | None = None
+) -> Repo:
+    """Helper: initialise a bare-ish source repo with commits for use as a local remote."""
+    repo = Repo.init(str(path))
+
+    # Configure a minimal identity so commits work without system config
+    with repo.config_writer() as cw:
+        cw.set_value("user", "name", "Test User")
+        cw.set_value("user", "email", "test@example.com")
+
+    # Write and commit files
+    for i in range(num_commits):
+        dummy = path / f"file_{i}.txt"
+        dummy.write_text(f"content {i}")
+        repo.index.add([str(dummy)])
+        repo.index.commit(f"commit {i}")
+
+    if branch is not None:
+        repo.create_head(branch)
+
+    return repo
+
+
+class TestGitClone:
+    """Test git_clone function"""
+
+    def setup_method(self):
+        self._tmpdirs: list[str] = []
+
+    def teardown_method(self):
+        for d in self._tmpdirs:
+            shutil.rmtree(d, ignore_errors=True)
+
+    def _tmpdir(self) -> Path:
+        d = tempfile.mkdtemp()
+        self._tmpdirs.append(d)
+        return Path(d)
+
+    # ------------------------------------------------------------------
+    # Happy-path tests
+    # ------------------------------------------------------------------
+
+    def test_clone_happy_path(self):
+        """Clone a local source repo into a fresh empty target and verify success."""
+        from src.mcp_server_git.git.operations import git_clone
+
+        src = self._tmpdir()
+        src_repo = _make_source_repo(src)
+        expected_sha = src_repo.head.commit.hexsha
+
+        target = self._tmpdir() / "cloned"
+
+        result = git_clone(str(src), str(target))
+
+        assert "✅" in result
+        assert str(src) in result
+        assert str(target) in result
+
+        cloned_repo = Repo(str(target))
+        assert cloned_repo.head.commit.hexsha == expected_sha
+
+    def test_clone_with_branch(self):
+        """Clone with branch= and verify active branch in cloned repo."""
+        from src.mcp_server_git.git.operations import git_clone
+
+        src = self._tmpdir()
+        _make_source_repo(src, num_commits=1, branch="feature-x")
+
+        target = self._tmpdir() / "cloned"
+
+        result = git_clone(str(src), str(target), branch="feature-x")
+
+        assert "✅" in result
+
+        cloned_repo = Repo(str(target))
+        assert cloned_repo.active_branch.name == "feature-x"
+
+    def test_clone_with_depth(self):
+        """Clone with depth=1 from a 3-commit repo and verify shallow history."""
+        from src.mcp_server_git.git.operations import git_clone
+
+        src = self._tmpdir()
+        _make_source_repo(src, num_commits=3)
+
+        target = self._tmpdir() / "cloned"
+
+        result = git_clone(f"file://{src}", str(target), depth=1)
+
+        assert "✅" in result
+
+        cloned_repo = Repo(str(target))
+        commit_count = cloned_repo.git.rev_list("--count", "HEAD")
+        assert commit_count.strip() == "1"
+
+    def test_clone_single_branch_flag(self):
+        """Clone with single_branch=True succeeds."""
+        from src.mcp_server_git.git.operations import git_clone
+
+        src = self._tmpdir()
+        _make_source_repo(src)
+
+        target = self._tmpdir() / "cloned"
+
+        result = git_clone(str(src), str(target), single_branch=True)
+
+        assert "✅" in result
+
+    # ------------------------------------------------------------------
+    # Validation / rejection tests
+    # ------------------------------------------------------------------
+
+    def test_clone_rejects_existing_nonempty_target(self):
+        """Raise ValueError when target directory already contains files."""
+        from src.mcp_server_git.git.operations import git_clone
+
+        src = self._tmpdir()
+        _make_source_repo(src)
+
+        target = self._tmpdir() / "nonempty"
+        target.mkdir()
+        (target / "existing.txt").write_text("not empty")
+
+        with pytest.raises(ValueError, match="not empty"):
+            git_clone(str(src), str(target))
+
+    def test_clone_rejects_missing_parent(self):
+        """Raise ValueError when the parent of target_path does not exist."""
+        from src.mcp_server_git.git.operations import git_clone
+
+        src = self._tmpdir()
+        _make_source_repo(src)
+
+        nonexistent_parent = self._tmpdir() / "ghost" / "cloned"
+
+        with pytest.raises(ValueError, match="Parent directory does not exist"):
+            git_clone(str(src), str(nonexistent_parent))
+
+    # ------------------------------------------------------------------
+    # Error-path tests
+    # ------------------------------------------------------------------
+
+    def test_clone_bad_url_returns_error_message(self):
+        """Return a '❌' string when repo_url does not point to a valid repo."""
+        from src.mcp_server_git.git.operations import git_clone
+
+        target = self._tmpdir() / "cloned"
+
+        # A path that does not exist is not a valid git repo; GitPython raises
+        # GitCommandError which the implementation catches and returns as "❌ Clone failed: ..."
+        bad_url = "/tmp/this_path_does_not_exist_at_all_xyz123"
+
+        result = git_clone(bad_url, str(target))
+
+        assert "❌" in result