Git File Forensics MCP

Instructions

Implementation Reference

• src/index.ts:323-342 (handler)

  The primary handler function for the 'analyze_file_diff' tool. It retrieves the git diff between two versions, detects moved code blocks, generates a summary, writes the analysis to the specified output path, and returns a success message.

  private async handleFileDiff(args: FileDiffArgs) {
    const diff = this.getFileDiff(args.repoPath, args.file, args.versions);
    const movedBlocks = this.findMovedBlocks(diff);
    
    const analysis = {
      diff,
      movedBlocks,
      summary: this.generateDiffSummary(diff),
    };
  
    writeFileSync(args.outputPath, JSON.stringify(analysis, null, 2));
  
    return {
      content: [
        {
          type: 'text',
          text: `File diff analysis written to ${args.outputPath}`,
        },
      ],
    };

• src/index.ts:168-197 (registration)

  Tool registration in the ListTools response, including name, description, and complete input schema definition.

  {
    name: 'analyze_file_diff',
    description: 'Analyze specific changes between any two versions of a file',
    inputSchema: {
      type: 'object',
      properties: {
        repoPath: {
          type: 'string',
          description: 'Path to git repository',
        },
        file: {
          type: 'string',
          description: 'File to analyze',
        },
        versions: {
          type: 'object',
          properties: {
            from: { type: 'string' },
            to: { type: 'string' },
          },
          required: ['from', 'to'],
        },
        outputPath: {
          type: 'string',
          description: 'Path to write analysis output',
        },
      },
      required: ['repoPath', 'file', 'versions', 'outputPath'],
    },
  },

• src/index.ts:260-266 (registration)

  Dispatch handler in the CallToolRequestSchema that validates input using isFileDiffArgs and invokes the main handleFileDiff method.

  case 'analyze_file_diff': {
    const args = request.params.arguments as unknown;
    if (!this.isFileDiffArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required parameters');
    }
    return await this.handleFileDiff(args);
  }

• src/index.ts:73-90 (schema)

  Type guard function for validating the input arguments against the FileDiffArgs interface used in the tool.

  private isFileDiffArgs(args: unknown): args is FileDiffArgs {
    return (
      typeof args === 'object' &&
      args !== null &&
      'repoPath' in args &&
      'file' in args &&
      'versions' in args &&
      'outputPath' in args &&
      typeof (args as FileDiffArgs).repoPath === 'string' &&
      typeof (args as FileDiffArgs).file === 'string' &&
      typeof (args as FileDiffArgs).outputPath === 'string' &&
      typeof (args as FileDiffArgs).versions === 'object' &&
      (args as FileDiffArgs).versions !== null &&
      'from' in (args as FileDiffArgs).versions &&
      'to' in (args as FileDiffArgs).versions &&
      typeof (args as FileDiffArgs).versions.from === 'string' &&
      typeof (args as FileDiffArgs).versions.to === 'string'
    );

• src/index.ts:422-431 (helper)

  Helper function that executes the git diff command to retrieve the raw diff between two file versions.

  private getFileDiff(
    repoPath: string,
    file: string,
    versions: { from: string; to: string }
  ) {
    return execSync(
      `cd "${repoPath}" && git diff ${versions.from} ${versions.to} -- "${file}"`,
      { encoding: 'utf8' }
    );
  }