MCP Git Commit Generator

Instructions

Implementation Reference

• src/mcp_git_commit_generator/server.py:190-267 (handler)

  The primary handler function for the 'check_git_status' MCP tool. Decorated with @mcp.tool() for automatic registration. Validates repo, fetches git status and branch, parses changes, and formats a user-friendly summary of staged, unstaged, and untracked files.

  @mcp.tool()
  def check_git_status(repo_path: Optional[str] = None) -> str:
      """
      Check the current git repository status.
  
      Args:
          repo_path: Optional path to the target git repository. If not provided, uses the current working directory.
  
      Returns:
          Current git status including staged, unstaged, and untracked files
      """
      try:
          valid_repo_path = _get_valid_repo_path(repo_path)
          if not valid_repo_path:
              return f"Path '{repo_path or os.getcwd()}' is not a valid git repository."
          cwd = valid_repo_path
          # Get full git status
          status_result = subprocess.run(
              ["git", "status", "--porcelain"],
              capture_output=True,
              text=True,
              check=True,
              cwd=cwd,
          )
  
          # Get branch info
          branch_result = subprocess.run(
              ["git", "branch", "--show-current"],
              capture_output=True,
              text=True,
              check=True,
              cwd=cwd,
          )
  
          current_branch = branch_result.stdout.strip()
  
          if not status_result.stdout.strip():
              return f"Repository is clean on branch '{current_branch}'. No changes to commit."
  
          # Parse status using helper
          status_lines = [line for line in status_result.stdout.split("\n") if line]
          staged_files, unstaged_files, untracked_files = _parse_git_status_lines(
              status_lines
          )
  
          status_summary = f"Current branch: {current_branch}\n\n"
  
          if staged_files:
              status_summary += "Staged files (ready to commit):\n"
              status_summary += "\n".join(f"  {file}" for file in staged_files)
              status_summary += "\n\n"
  
          if unstaged_files:
              status_summary += "Unstaged files (need to be added):\n"
              status_summary += "\n".join(f"  {file}" for file in unstaged_files)
              status_summary += "\n\n"
  
          if untracked_files:
              status_summary += "Untracked files:\n"
              status_summary += "\n".join(f"  {file}" for file in untracked_files)
              status_summary += "\n\n"
  
          if staged_files:
              status_summary += "✓ Ready to generate commit message!"
          else:
              status_summary += (
                  "ℹ Stage some files with 'git add' to generate commit messages."
              )
  
          return status_summary
  
      except subprocess.CalledProcessError as e:
          error_msg = e.stderr or e.stdout or str(e)
          return f"Git command failed: {error_msg}"
      except FileNotFoundError:
          return "Git is not installed or not found in PATH"
      except OSError as e:
          return f"OS error occurred: {str(e)}"

• src/mcp_git_commit_generator/server.py:17-32 (helper)

  Helper function to resolve and validate the git repository path from optional input or CWD. Used by check_git_status to ensure a valid repo before running git commands.

  def _get_valid_repo_path(repo_path: Optional[str]) -> Optional[str]:
      """
      Resolve and validate the git repository path.
      Returns the valid repo path if valid, otherwise None.
      """
      logger = logging.getLogger(__name__)
      # Resolve user tilde and symlinks to a canonical path
      resolved = (
          os.path.realpath(os.path.expanduser(repo_path)) if repo_path else os.getcwd()
      )
      logger.info("[get_valid_repo_path] Resolved repository path: %s", resolved)
      if not os.path.isdir(resolved) or not os.path.exists(
          os.path.join(resolved, ".git")
      ):
          return None
      return resolved

• src/mcp_git_commit_generator/server.py:158-172 (helper)

  Parses a single line from 'git status --porcelain' output to categorize files as staged, unstaged, or untracked.

  def _parse_git_status_line(line):
      """
      Helper to parse a single git status line.
      Returns (staged_file, unstaged_file, untracked_file)
      """
      if len(line) < 3:
          return None, None, None
      staged_status = line[0]
      unstaged_status = line[1]
      filename = line[3:]
      if staged_status == "?" and unstaged_status == "?":
          return None, None, filename
      staged_file = filename if staged_status != " " else None
      unstaged_file = filename if unstaged_status != " " else None
      return staged_file, unstaged_file, None

• src/mcp_git_commit_generator/server.py:175-187 (helper)

  Processes multiple git status lines, aggregating files into lists for staged, unstaged, and untracked categories using _parse_git_status_line.

  def _parse_git_status_lines(status_lines):
      staged_files = []
      unstaged_files = []
      untracked_files = []
      for line in status_lines:
          staged_file, unstaged_file, untracked_file = _parse_git_status_line(line)
          if staged_file:
              staged_files.append(staged_file)
          if unstaged_file:
              unstaged_files.append(unstaged_file)
          if untracked_file:
              untracked_files.append(untracked_file)
      return staged_files, unstaged_files, untracked_files