MCP Git Server

Instructions

Implementation Reference

• src/mcp_server_git/git/operations.py:788-817 (handler)

  Core handler function that performs git checkout: switches to local branch if exists, or creates tracking branch from remote if available.

  def git_checkout(repo: Repo, branch_name: str) -> str:
      """Switch to a branch"""
      try:
          # Check if branch exists locally
          local_branches = [branch.name for branch in repo.branches]
  
          if branch_name in local_branches:
              # Switch to local branch
              repo.git.checkout(branch_name)
              return f"✅ Switched to branch '{branch_name}'"
          else:
              # Check if branch exists on remote
              try:
                  remote_branches = [
                      ref.name.split("/")[-1] for ref in repo.remote().refs
                  ]
                  if branch_name in remote_branches:
                      # Create local tracking branch
                      repo.git.checkout("-b", branch_name, f"origin/{branch_name}")
                      return f"✅ Created and switched to branch '{branch_name}' (tracking origin/{branch_name})"
                  else:
                      return f"❌ Branch '{branch_name}' not found locally or on remote"
              except Exception:
                  return f"❌ Branch '{branch_name}' not found"
  
      except GitCommandError as e:
          return f"❌ Checkout failed: {str(e)}"
      except Exception as e:
          return f"❌ Checkout error: {str(e)}"

• src/mcp_server_git/git/models.py:72-75 (schema)

  Pydantic schema/model defining input parameters: repo_path and branch_name.

  class GitCheckout(BaseModel):
      repo_path: str
      branch_name: str

• src/mcp_server_git/core/handlers.py:101-103 (registration)

  Tool registration in the git handlers dictionary, wrapping the core git_checkout function with error handling and repo creation.

  "git_checkout": self._create_git_handler(
      git_checkout, requires_repo=True, extra_args=["branch_name"]
  ),

• src/mcp_server_git/core/tools.py:246-253 (registration)

  Tool definition registration in the central ToolRegistry with schema and metadata.

  ToolDefinition(
      name=GitTools.CHECKOUT,
      category=ToolCategory.GIT,
      description="Switch branches",
      schema=GitCheckout,
      handler=placeholder_handler,
      requires_repo=True,
  ),

• src/mcp_server_git/protected_git_operations.py:305-310 (helper)

  Protected wrapper that adds repository binding validation before calling the core git_checkout.

  async def protected_git_checkout(self, repo_path: str, branch_name: str) -> str:
      """Git checkout with repository binding protection."""
      validated_path = await self._validate_and_prepare_operation(repo_path)
      repo = Repo(validated_path)
      return git_checkout(repo, branch_name)