Git Forensics MCP

Instructions

Implementation Reference

• src/index.ts:230-265 (handler)

  The main handler function that executes the get_branch_overview tool logic. It computes last commit info, commit counts, merge bases between branches, generates an overview summary, writes JSON analysis to the output path, and returns a success message.

  private async handleBranchOverview(args: BranchOverviewArgs) {
    const overview = args.branches.map(branch => {
      const lastCommit = this.getLastCommit(args.repoPath, branch);
      const commitCount = this.getCommitCount(args.repoPath, branch);
      const mergeBase = args.branches.map(otherBranch => {
        if (otherBranch === branch) return null;
        return {
          branch: otherBranch,
          base: this.getMergeBase(args.repoPath, branch, otherBranch),
        };
      }).filter((base): base is NonNullable<typeof base> => base !== null);
  
      return {
        branch,
        lastCommit,
        commitCount,
        mergeBase,
      };
    });
  
    const analysis = {
      overview,
      summary: this.generateOverviewSummary(overview),
    };
  
    writeFileSync(args.outputPath, JSON.stringify(analysis, null, 2));
  
    return {
      content: [
        {
          type: 'text',
          text: `Branch analysis written to ${args.outputPath}`,
        },
      ],
    };
  }

• src/index.ts:71-93 (registration)

  Registration of the get_branch_overview tool in the ListTools response, including name, description, and input schema.

  {
    name: 'get_branch_overview',
    description: 'Get high-level overview of branch states and relationships',
    inputSchema: {
      type: 'object',
      properties: {
        repoPath: {
          type: 'string',
          description: 'Path to git repository',
        },
        branches: {
          type: 'array',
          items: { type: 'string' },
          description: 'Branches to analyze',
        },
        outputPath: {
          type: 'string',
          description: 'Path to write analysis output',
        },
      },
      required: ['repoPath', 'branches', 'outputPath'],
    },
  },

• src/index.ts:14-18 (schema)

  TypeScript interface defining the input arguments for the get_branch_overview tool, used for type validation.

  interface BranchOverviewArgs {
    repoPath: string;
    branches: string[];
    outputPath: string;
  }

• src/index.ts:182-188 (registration)

  Dispatch case in CallToolRequestSchema handler that validates input and calls the get_branch_overview handler function.

  case 'get_branch_overview': {
    const args = request.params.arguments as BranchOverviewArgs;
    if (!args?.repoPath || !args?.branches || !args?.outputPath) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required parameters');
    }
    return await this.handleBranchOverview(args);
  }

• src/index.ts:536-548 (helper)

  Helper function called by the handler to generate a summary of branch activity statistics.

  private generateOverviewSummary(overview: Array<{ branch: string; commitCount: number }>) {
    const totalCommits = overview.reduce((sum, { commitCount }) => sum + commitCount, 0);
    const avgCommits = totalCommits / overview.length;
  
    return {
      totalBranches: overview.length,
      totalCommits,
      averageCommitsPerBranch: Math.round(avgCommits),
      mostActiveBranch: overview.reduce((a, b) => 
        a.commitCount > b.commitCount ? a : b
      ).branch,
    };
  }