# 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
