# Git Analytics MCP Server

🚀 A comprehensive Model Context Protocol (MCP) server that provides detailed Git repository analytics and insights. Perfect for developers who want to understand their codebase better through data-driven insights.

## 📊 Features

### Repository Analytics
- **Comprehensive Stats**: Total commits, authors, branches, and code changes
- **Author Analysis**: Contributor rankings, commit patterns, and activity periods
- **Branch Intelligence**: Branch health, ahead/behind status, and activity metrics
- **File Insights**: Most modified files, author contributions per file
- **Temporal Analysis**: Commit frequency, code churn over time
- **Visual Reports**: Beautifully formatted terminal output with colors and emojis

### Available Tools

1. **`get_repository_overview`** - Executive summary with key metrics and top contributors
2. **`get_repository_stats`** - Detailed repository statistics
3. **`get_author_stats`** - Complete contributor analysis
4. **`get_branch_stats`** - Branch health and comparison metrics
5. **`get_file_stats`** - File modification patterns and hotspots
6. **`get_commit_history`** - Detailed commit timeline with filters
7. **`get_commit_frequency`** - Daily commit patterns over time
8. **`get_code_churn`** - Lines added/removed analysis

## 🛠 Installation

### Prerequisites
- Node.js 18+ 
- npm or yarn
- Git repository to analyze

### Quick Setup

```bash
# Clone or create the project
cd ~/git-analytics-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Test the server (optional)
npm test
```

### Development Mode

```bash
# Run in development with auto-reload
npm run dev
```

## 🚀 Usage

### As MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "git-analytics": {
      "command": "node",
      "args": ["/path/to/git-analytics-mcp-server/dist/index.js"]
    }
  }
}
```

### Direct CLI Usage

```bash
# Install globally
npm install -g .

# Use anywhere
git-analytics-mcp
```

## 📈 Example Analytics

### Repository Overview
```
📊 REPOSITORY SUMMARY REPORT
──────────────────────────────────────────────────
Repository Statistics:
  • Total Commits: 1,247
  • Total Authors: 12
  • Active Branches: 8
  • Code Changes: +45,678 -12,345
  • Repository Age: 2023-01-15 to 2024-06-15

Top Contributors:
  🥇 John Doe - 456 commits
  🥈 Jane Smith - 234 commits
  🥉 Bob Wilson - 189 commits
  🏅 Alice Brown - 145 commits
  🏅 Mike Johnson - 123 commits

Recent Activity:
  • a1b2c3d4 Add new authentication module (John Doe)
  • e5f6g7h8 Fix critical security vulnerability (Jane Smith)
  • i9j0k1l2 Update documentation and examples (Bob Wilson)
```

### Author Analysis
```json
[
  {
    "name": "John Doe",
    "email": "john@example.com",
    "commits": 456,
    "insertions": 12340,
    "deletions": 3456,
    "firstCommit": "2023-01-15T10:30:00Z",
    "lastCommit": "2024-06-15T14:22:00Z"
  }
]
```

### Code Churn Analysis
```json
[
  {
    "date": "2024-06-01",
    "insertions": 234,
    "deletions": 45,
    "net": 189
  },
  {
    "date": "2024-06-02",
    "insertions": 156,
    "deletions": 89,
    "net": 67
  }
]
```

## 🔧 Configuration

### Tool Parameters

Most tools accept these common parameters:

- **`path`** (string): Repository path (default: current directory)
- **`days`** (number): Time range for analysis (default: 30)
- **`limit`** (number): Maximum results to return (default: 50)

### Environment Variables

```bash
# Set default repository path
export GIT_ANALYTICS_DEFAULT_PATH="/path/to/repo"

# Enable debug logging
export GIT_ANALYTICS_DEBUG=true
```

## 🧪 Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Test specific functionality
npm run test -- --grep "author stats"
```

### Test Repository Setup

```bash
# Create test repository
mkdir test-repo && cd test-repo
git init
echo "# Test" > README.md
git add . && git commit -m "Initial commit"

# Test the server
node dist/index.js
```

## 📊 Use Cases

### Development Team Analytics
- **Code Review Insights**: Identify files that need more attention
- **Team Productivity**: Track commit patterns and contribution metrics
- **Technical Debt**: Find files with high churn rates
- **Onboarding**: Understand codebase structure and key contributors

### Project Management
- **Release Planning**: Analyze recent development velocity
- **Resource Allocation**: Identify knowledge silos and areas needing support
- **Quality Metrics**: Track code stability through churn analysis
- **Timeline Analysis**: Understand development patterns and cycles

### Repository Health
- **Branch Management**: Identify stale or problematic branches
- **File Hotspots**: Find files that may need refactoring
- **Contributor Onboarding**: Welcome new team members with context
- **Historical Analysis**: Learn from past development patterns

## 🛠 Advanced Features

### Custom Analytics

Extend the server with custom analytics:

```typescript
// Add to git-analytics.ts
async getCustomMetric(): Promise<CustomMetric> {
  // Your custom analysis logic
}
```

### Integration Examples

```bash
# Use with GitHub CLI
gh repo list | xargs -I {} git-analytics-mcp --path {}

# Batch analysis
find ~/projects -name ".git" -type d | \
  xargs -I {} dirname {} | \
  xargs -I {} git-analytics-mcp --path {}
```

## 🐛 Troubleshooting

### Common Issues

**"Invalid Git repository"**
- Ensure you're in a Git repository or provide correct path
- Check Git installation: `git --version`

**"Permission denied"**
- Verify read access to repository
- Check file permissions on .git directory

**"No commits found"**
- Repository may be empty or newly initialized
- Try with a repository that has commits

### Debug Mode

```bash
# Enable verbose logging
DEBUG=git-analytics:* npm start

# Check server connectivity
echo '{}' | node dist/index.js
```

## 🤝 Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open Pull Request

### Development Setup

```bash
# Install dev dependencies
npm install

# Run in watch mode
npm run dev

# Lint code
npm run lint

# Format code
npm run format
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🌟 Acknowledgments

- [Model Context Protocol](https://github.com/modelcontextprotocol) for the excellent framework
- [simple-git](https://github.com/steveukx/git-js) for Git operations
- [chalk](https://github.com/chalk/chalk) for beautiful terminal output
- [date-fns](https://date-fns.org/) for date manipulation

---

**Happy Analyzing! 📊✨**

For questions, issues, or feature requests, please open an issue on GitHub.

# MCP-Server
# MCP-Server