Commit Helper MCP

Instructions

Implementation Reference

• src/commit_helper_mcp/server/enhanced_tools.py:141-270 (handler)

  The main handler function for 'get_detailed_diff_analysis' tool. Decorated with @mcp.tool(), it initializes CommitzenService, uses GitPython to get staged/unstaged diffs, analyzes each file's changes (insertions/deletions, binary detection, optional content), computes totals, and returns structured analysis.

  def get_detailed_diff_analysis(
      repo_path: str,
      compare_with: str = "HEAD",
      include_content: bool = False
  ) -> Dict[str, Any]:
      """
      Get detailed diff analysis between working directory and specified commit.
      
      Uses GitPython to provide:
      - File-by-file change analysis
      - Line-level insertion/deletion counts
      - Change type classification (added, modified, deleted, renamed)
      - Binary file detection
      - Optional diff content inclusion
      
      Args:
          repo_path: Path to git repository
          compare_with: Commit/branch to compare with (default: HEAD)
          include_content: Whether to include actual diff content
          
      Returns:
          Dict containing detailed diff analysis
      """
      # Initialize service for the specified repository
      try:
          target_service = CommitzenService(repo_path=repo_path)
      except Exception as e:
          # For backward compatibility with tests
          return {
              "success": False,
              "error": f"Failed to initialize service for repository '{repo_path}': {e}",
              "repository_path": repo_path
          }
      
      if not target_service.git_enabled:
          # For backward compatibility with tests
          return {
              "success": False,
              "error": "Enhanced diff analysis requires GitPython",
              "repository_path": repo_path
          }
      
      try:
          # Get staged and unstaged diffs
          repo = target_service.git_service.repo
          staged_diff = repo.index.diff(compare_with)
          unstaged_diff = repo.index.diff(None)
          
          def analyze_diff_items(diff_items, diff_type):
              analysis = []
              total_insertions = 0
              total_deletions = 0
              
              for item in diff_items:
                  try:
                      # Get diff statistics
                      if item.diff:
                          diff_text = item.diff.decode('utf-8', errors='ignore')
                          insertions = diff_text.count('\n+') - diff_text.count('\n+++')
                          deletions = diff_text.count('\n-') - diff_text.count('\n---')
                      else:
                          insertions = deletions = 0
                      
                      file_analysis = {
                          "file": item.a_path or item.b_path,
                          "change_type": item.change_type,
                          "insertions": max(0, insertions),
                          "deletions": max(0, deletions),
                          "is_binary": item.diff == b'',
                          "old_file": item.a_path,
                          "new_file": item.b_path,
                          "diff_type": diff_type
                      }
                      
                      if include_content and not file_analysis["is_binary"]:
                          file_analysis["diff_content"] = diff_text
                      
                      analysis.append(file_analysis)
                      total_insertions += max(0, insertions)
                      total_deletions += max(0, deletions)
                      
                  except Exception as e:
                      logger.warning(f"Could not analyze diff for {item.a_path}: {e}")
                      analysis.append({
                          "file": item.a_path or item.b_path,
                          "change_type": item.change_type,
                          "error": str(e),
                          "diff_type": diff_type
                      })
              
              return analysis, total_insertions, total_deletions
          
          staged_analysis, staged_insertions, staged_deletions = analyze_diff_items(staged_diff, "staged")
          unstaged_analysis, unstaged_insertions, unstaged_deletions = analyze_diff_items(unstaged_diff, "unstaged")
          
          return create_success_response({
              "repository_path": repo_path,
              "compare_with": compare_with,
              "implementation": target_service.git_implementation,
              "diff_analysis": {
                  "staged_changes": {
                      "files": staged_analysis,
                      "file_count": len(staged_analysis),
                      "total_insertions": staged_insertions,
                      "total_deletions": staged_deletions,
                      "total_changes": staged_insertions + staged_deletions
                  },
                  "unstaged_changes": {
                      "files": unstaged_analysis,
                      "file_count": len(unstaged_analysis),
                      "total_insertions": unstaged_insertions,
                      "total_deletions": unstaged_deletions,
                      "total_changes": unstaged_insertions + unstaged_deletions
                  },
                  "summary": {
                      "total_files_changed": len(staged_analysis) + len(unstaged_analysis),
                      "total_insertions": staged_insertions + unstaged_insertions,
                      "total_deletions": staged_deletions + unstaged_deletions,
                      "has_staged_changes": len(staged_analysis) > 0,
                      "has_unstaged_changes": len(unstaged_analysis) > 0
                  }
              }
          })
      except Exception as e:
          logger.error(f"Failed to get detailed diff analysis: {e}")
          raise ServiceError(
              f"Failed to get detailed diff analysis: {e}",
              service_name="get_detailed_diff_analysis",
              cause=e
          )

• src/commit_helper_mcp/mcp_server.py:54-60 (registration)

  Import statement in the main MCP server file that registers the tool. Importing the @mcp.tool()-decorated function makes it available to the MCP server.

  from .server.enhanced_tools import (
      analyze_repository_health,
      get_detailed_diff_analysis,
      get_branch_analysis,
      smart_commit_suggestion,
      batch_commit_analysis,
  )

• src/commit_helper_mcp/mcp_server.py:93-96 (registration)

  The tool is explicitly listed in __all__ for export and backward compatibility.

  "get_detailed_diff_analysis",
  "get_branch_analysis",
  "smart_commit_suggestion",
  "batch_commit_analysis",