Git MCP

Instructions

Implementation Reference

• src/tools/git-branches.ts:47-97 (handler)

  Main execute method of GitBranchesTool that validates parameters and routes to local or remote branch operations (create, list, get, delete, merge, compare). All logic is implemented in this class's private methods.

  /**
   * Execute git-branches operation
   */
  async execute(params: GitBranchesParams): Promise<ToolResult> {
    const startTime = Date.now();
  
    try {
      // Validate basic parameters
      const validation = ParameterValidator.validateToolParams('git-branches', params);
      if (!validation.isValid) {
        return OperationErrorHandler.createToolError(
          'VALIDATION_ERROR',
          `Parameter validation failed: ${validation.errors.join(', ')}`,
          params.action,
          { validationErrors: validation.errors },
          validation.suggestions
        );
      }
  
      // Validate operation-specific parameters
      const operationValidation = ParameterValidator.validateOperationParams('git-branches', params.action, params);
      if (!operationValidation.isValid) {
        return OperationErrorHandler.createToolError(
          'VALIDATION_ERROR',
          `Operation validation failed: ${operationValidation.errors.join(', ')}`,
          params.action,
          { validationErrors: operationValidation.errors },
          operationValidation.suggestions
        );
      }
  
      // Route to appropriate handler
      const isRemoteOperation = this.isRemoteOperation(params.action);
      
      if (isRemoteOperation) {
        return await this.executeRemoteOperation(params, startTime);
      } else {
        return await this.executeLocalOperation(params, startTime);
      }
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      return OperationErrorHandler.createToolError(
        'EXECUTION_ERROR',
        `Failed to execute ${params.action}: ${errorMessage}`,
        params.action,
        { error: errorMessage },
        ['Check the error details and try again']
      );
    }
  }

• src/tools/git-branches.ts:600-703 (schema)

  Tool schema definition including input schema, error codes, warnings, and usage examples for MCP registration.

  static getToolSchema() {
    return {
      name: 'git-branches',
      description: 'Git branch management tool for branch lifecycle operations. Supports create, list, get, delete, merge, and compare operations. Includes safety warnings for destructive operations like branch deletion. In universal mode (GIT_MCP_MODE=universal), automatically executes on both GitHub and Gitea providers.',
      inputSchema: {
        type: 'object',
        properties: {
          action: {
            type: 'string',
            enum: ['create', 'list', 'get', 'delete', 'merge', 'compare'],
            description: 'The branch operation to perform. WARNING: delete operation permanently removes branches and their commit history.'
          },
          projectPath: {
            type: 'string',
            description: 'Absolute path to the project directory'
          },
          provider: {
            type: 'string',
            enum: ['github', 'gitea', 'both'],
            description: 'Provider for remote operations (if supported)'
          },
          branchName: {
            type: 'string',
            description: 'Name of the branch (required for create, get, delete, merge)'
          },
          sourceBranch: {
            type: 'string',
            description: 'Source branch to create from (for create action)'
          },
          targetBranch: {
            type: 'string',
            description: 'Target branch to merge into (for merge action)'
          },
          baseBranch: {
            type: 'string',
            description: 'Base branch for comparison (required for compare action)'
          },
          compareBranch: {
            type: 'string',
            description: 'Branch to compare against base (required for compare action)'
          },
          force: {
            type: 'boolean',
            description: 'Force operation (for delete, merge actions)'
          },
          remote: {
            type: 'string',
            description: 'Remote name (default: origin)'
          },
          checkout: {
            type: 'boolean',
            description: 'Checkout branch after creation (for create action)'
          },
          repo: {
            type: 'string',
            description: 'Repository name (for remote operations)'
          }
        },
        required: ['action', 'projectPath'],
        additionalProperties: false
      },
      errorCodes: {
        'VALIDATION_ERROR': 'Parameter validation failed - check required parameters and format',
        'BRANCH_EXISTS': 'Branch already exists - use different name or delete existing branch',
        'BRANCH_NOT_FOUND': 'Branch not found - check branch name and remote configuration',
        'MERGE_CONFLICT': 'Merge conflicts detected - resolve conflicts before completing merge',
        'DIRTY_WORKING_TREE': 'Working directory has uncommitted changes - commit or stash first',
        'NOT_A_GIT_REPOSITORY': 'Directory is not a Git repository - use git init first',
        'PERMISSION_DENIED': 'Permission denied - check access rights and credentials'
      },
      warnings: {
        'delete': 'Branch deletion is permanent and cannot be undone. Ensure branch is merged or no longer needed.',
        'force': 'Force operations can cause data loss. Use with extreme caution.'
      },
      examples: [
        {
          description: 'List all branches',
          input: {
            action: 'list',
            projectPath: '/path/to/project'
          }
        },
        {
          description: 'Create new feature branch',
          input: {
            action: 'create',
            projectPath: '/path/to/project',
            branchName: 'feature/new-feature',
            sourceBranch: 'main',
            checkout: true
          }
        },
        {
          description: 'Compare two branches',
          input: {
            action: 'compare',
            projectPath: '/path/to/project',
            baseBranch: 'main',
            compareBranch: 'feature/new-feature'
          }
        }
      ]
    };
  }

• src/server.ts:88-89 (registration)

  Instantiation of GitBranchesTool instance during server initialization.

  this.gitBranchesTool = new GitBranchesTool(providerConfig);
  this.gitFilesTool = new GitFilesTool(providerConfig);

• src/server.ts:474-475 (registration)

  Tool execution dispatch in the MCP CallToolRequest handler switch statement.

  case 'git-branches':
    return await this.gitBranchesTool.execute(args);

• src/server.ts:125-127 (registration)

  Tool schema registration in the MCP ListToolsRequest handler.

  GitWorkflowTool.getToolSchema(),
  GitFilesTool.getToolSchema(),
  GitBranchesTool.getToolSchema(),

• src/utils/parameter-validator.ts:54-55 (helper)

  Parameter validation configuration for git-branches tool operations in ParameterValidator.

  'git-branches': [], // All branch operations are local for now
  'git-issues': ['create', 'list', 'get', 'update', 'close', 'comment', 'search'],