Git MCP

Instructions

Implementation Reference

• src/tools/git-issues.ts:59-106 (handler)

  Main handler function that executes git-issues operations: validates parameters, determines if remote/local, and delegates to provider handler.

  async execute(params: GitIssuesParams): Promise<ToolResult> {
    const startTime = Date.now();
  
    try {
      // Validate basic parameters
      const validation = ParameterValidator.validateToolParams('git-issues', 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-issues', 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-issues.ts:334-431 (schema)

  Static method providing the complete tool schema (name, description, inputSchema) for MCP tool registration.

  static getToolSchema() {
    return {
      name: 'git-issues',
      description: 'Comprehensive issue management tool for Git repositories. Supports create, list, get, update, close, comment, and search operations for issues. 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', 'update', 'close', 'comment', 'search'],
            description: 'The issue operation to perform'
          },
          projectPath: {
            type: 'string',
            description: 'Absolute path to the project directory'
          },
          provider: {
            type: 'string',
            enum: ['github', 'gitea', 'both'],
            description: 'Provider for issue operations (required)'
          },
          repo: {
            type: 'string',
            description: 'Repository name (auto-detected if not provided)'
          },
          issue_number: {
            type: 'number',
            description: 'Issue number (required for get/update/close/comment actions)'
          },
          title: {
            type: 'string',
            description: 'Issue title (required for create, optional for update)'
          },
          body: {
            type: 'string',
            description: 'Issue body/description'
          },
          labels: {
            type: 'array',
            items: { type: 'string' },
            description: 'Issue labels'
          },
          assignees: {
            type: 'array',
            items: { type: 'string' },
            description: 'Issue assignees (usernames)'
          },
          milestone: {
            type: 'number',
            description: 'Milestone number'
          },
          state: {
            type: 'string',
            enum: ['open', 'closed'],
            description: 'Issue state (for update action)'
          },
          state_filter: {
            type: 'string',
            enum: ['open', 'closed', 'all'],
            description: 'Filter issues by state (for list action, default: open)'
          },
          sort: {
            type: 'string',
            enum: ['created', 'updated', 'comments'],
            description: 'Sort criteria (for list action, default: created)'
          },
          direction: {
            type: 'string',
            enum: ['asc', 'desc'],
            description: 'Sort direction (for list action, default: desc)'
          },
          since: {
            type: 'string',
            description: 'Only issues updated after this date (ISO 8601 format, for list action)'
          },
          comment_body: {
            type: 'string',
            description: 'Comment body (required for comment action)'
          },
          query: {
            type: 'string',
            description: 'Search query (required for search action)'
          },
          search_sort: {
            type: 'string',
            enum: ['created', 'updated', 'comments'],
            description: 'Sort for search results (default: created)'
          },
          search_order: {
            type: 'string',
            enum: ['asc', 'desc'],
            description: 'Order for search results (default: desc)'
          }
        },
        required: ['action', 'projectPath']
      }
    };
  }

• src/server.ts:90-90 (registration)

  Instantiation of GitIssuesTool class instance with provider configuration during server initialization.

  this.gitIssuesTool = new GitIssuesTool(providerConfig);

• src/server.ts:476-477 (registration)

  Dispatch case in executeTool method that routes git-issues calls to the tool's execute method.

  case 'git-issues':
    return await this.gitIssuesTool.execute(args);

• src/utils/parameter-validator.ts:386-433 (helper)

  Helper function providing operation-specific parameter validation for git-issues actions.

  private static validateIssuesParams(action: string, params: ToolParams): ValidationResult {
    const result: ValidationResult = {
      isValid: true,
      errors: [],
      warnings: [],
      suggestions: []
    };
  
    switch (action) {
      case 'create':
        if (!params.title) {
          result.errors.push('title is required for issue creation');
          result.suggestions.push('Provide a descriptive title for the issue');
          result.isValid = false;
        }
        break;
      case 'get':
      case 'update':
      case 'close':
        if (params.issue_number === undefined) {
          result.errors.push('issue_number is required for issue operations');
          result.suggestions.push('Provide the issue number');
          result.isValid = false;
        }
        break;
      case 'comment':
        if (params.issue_number === undefined) {
          result.errors.push('issue_number is required for commenting on issues');
          result.suggestions.push('Provide the issue number');
          result.isValid = false;
        }
        if (!params.comment_body) {
          result.errors.push('comment_body is required for commenting on issues');
          result.suggestions.push('Provide the comment text');
          result.isValid = false;
        }
        break;
      case 'search':
        if (!params.query) {
          result.errors.push('query is required for issue search');
          result.suggestions.push('Provide a search query to find issues');
          result.isValid = false;
        }
        break;
    }
  
    return result;
  }