Git MCP

Instructions

Implementation Reference

• src/tools/git-analytics.ts:67-128 (handler)

  Main execute() method in GitAnalyticsTool class that handles all git-analytics operations: validation, routing to local/remote handlers, error handling.

  async execute(params: GitAnalyticsParams): Promise<ToolResult> {
    const startTime = Date.now();
  
    try {
      // Validate basic parameters
      const validation = ParameterValidator.validateToolParams('git-analytics', 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-analytics', 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) {
        if (!params.provider) {
          if (configManager.isUniversalMode()) {
            params.provider = 'both';
            console.error(`[Universal Mode] Auto-applying both providers for ${params.action}`);
          } else {
            return OperationErrorHandler.createToolError(
              'PROVIDER_REQUIRED',
              'Provider parameter is required for remote analytics operations',
              params.action,
              {},
              ['Specify provider as: github, gitea, or both']
            );
          }
        }
        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-analytics.ts:914-1016 (schema)

  Static getToolSchema() method providing the complete input schema for git-analytics tool registration in MCP.

  static getToolSchema() {
    return {
      name: 'git-analytics',
      description: 'Git analytics and statistics tool for repository analysis. Supports stats, commits, and contributors operations. Provides comprehensive analytics for Git repositories.',
      inputSchema: {
        type: 'object',
        properties: {
          action: {
            type: 'string',
            enum: ['stats', 'commits', 'contributors'],
            description: 'The analytics operation to perform'
          },
          projectPath: {
            type: 'string',
            description: 'Absolute path to the project directory'
          },
          provider: {
            type: 'string',
            enum: ['github', 'gitea', 'both'],
            description: 'Provider for enhanced remote analytics (optional)'
          },
          since: {
            type: 'string',
            description: 'Start date for analysis (ISO date or relative like "1 week ago")'
          },
          until: {
            type: 'string',
            description: 'End date for analysis (ISO date or relative like "yesterday")'
          },
          branch: {
            type: 'string',
            description: 'Specific branch to analyze (default: current branch)'
          },
          ref: {
            type: 'string',
            description: 'Specific ref to analyze (commit, tag, etc.)'
          },
          author: {
            type: 'string',
            description: 'Filter commits by author (for commits operation)'
          },
          committer: {
            type: 'string',
            description: 'Filter commits by committer (for commits operation)'
          },
          grep: {
            type: 'string',
            description: 'Search in commit messages (for commits operation)'
          },
          minCommits: {
            type: 'number',
            description: 'Minimum commits threshold (for contributors operation)'
          },
          sortBy: {
            type: 'string',
            enum: ['commits', 'additions', 'deletions', 'name'],
            description: 'Sort contributors by field (for contributors operation)'
          },
          format: {
            type: 'string',
            enum: ['json', 'csv', 'summary'],
            description: 'Output format for results'
          },
          limit: {
            type: 'number',
            description: 'Maximum number of results to return'
          },
          includeStats: {
            type: 'boolean',
            description: 'Include file change statistics (for commits operation)'
          },
          includeMerges: {
            type: 'boolean',
            description: 'Include merge commits in analysis'
          },
          repo: {
            type: 'string',
            description: 'Repository name (for remote operations)'
          },
          groupBy: {
            type: 'string',
            enum: ['day', 'week', 'month', 'year'],
            description: 'Group statistics by time period (for stats operation)'
          },
          includeFileTypes: {
            type: 'boolean',
            description: 'Include file type analysis (for stats operation)'
          },
          includePaths: {
            type: 'array',
            items: { type: 'string' },
            description: 'Specific paths to include in analysis'
          },
          excludePaths: {
            type: 'array',
            items: { type: 'string' },
            description: 'Paths to exclude from analysis'
          }
        },
        required: ['action', 'projectPath']
      }
    };
  }

• src/server.ts:502-503 (registration)

  Registration in server executeTool switch: routes 'git-analytics' calls to this.gitAnalyticsTool.execute()

  case 'git-analytics':
    return await this.gitAnalyticsTool.execute(args);

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

  Tool instance initialization in GitMCPServer constructor with provider config.

  this.gitAnalyticsTool = new GitAnalyticsTool(providerConfig);

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

  Tool schema included in ListToolsRequestHandler response for MCP tool discovery.

  GitAnalyticsTool.getToolSchema(),

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

  TOOL_OPERATIONS definition listing supported actions for git-analytics validation.

  'git-analytics': ['stats', 'commits', 'contributors'],

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

  REMOTE_OPERATIONS definition indicating git-analytics uses local operations by default.

  'git-analytics': [], // All analytics operations are local by default