{"id":38721901,"url":"https://github.com/jonmatum/git-metrics-mcp-server","last_synced_at":"2026-01-20T17:52:47.576Z","repository":{"id":327623142,"uuid":"1101483285","full_name":"jonmatum/git-metrics-mcp-server","owner":"jonmatum","description":"MCP server for understanding team health through git metrics. A mirror for reflection, not a microscope for surveillance.","archived":false,"fork":false,"pushed_at":"2026-01-01T21:34:55.000Z","size":984,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-03T22:41:52.325Z","etag":null,"topics":["amazon-q","bus-factor","code-quality","collaboration","developer-experience","git-metrics","kiro-cli","knowledge-sharing","mcp","process-improvement","retrospectives","sustainable-development","team-health","team-productivity","technical-debt"],"latest_commit_sha":null,"homepage":"https://jonmatum.github.io/git-metrics-mcp-server/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonmatum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T18:32:46.000Z","updated_at":"2025-12-04T18:02:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jonmatum/git-metrics-mcp-server","commit_stats":null,"previous_names":["jonmatum/git-metrics-mcp-server"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/jonmatum/git-metrics-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fgit-metrics-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fgit-metrics-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fgit-metrics-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fgit-metrics-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonmatum","download_url":"https://codeload.github.com/jonmatum/git-metrics-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fgit-metrics-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28506613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T10:25:30.148Z","status":"ssl_error","status_checked_at":"2026-01-17T10:25:29.718Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-q","bus-factor","code-quality","collaboration","developer-experience","git-metrics","kiro-cli","knowledge-sharing","mcp","process-improvement","retrospectives","sustainable-development","team-health","team-productivity","technical-debt"],"created_at":"2026-01-17T11:10:00.405Z","updated_at":"2026-01-17T11:10:01.000Z","avatar_url":"https://github.com/jonmatum.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Git Metrics MCP Server\n\nMCP server for analyzing git repository metrics and understanding team health. Built for Kiro CLI (Amazon Q CLI) and other MCP clients.\n\n## Overview\n\nThis server provides tools to extract meaningful metrics from git repositories, helping teams understand their development patterns, identify risks early, and have better conversations about code quality and team health.\n\n**This is a mirror, not a microscope.** Use it to reflect on team health and process quality, not to surveil individual behavior.\n\n## Features\n\n- **Commit Statistics**: Track commits, additions, deletions, and files changed\n- **Author Metrics**: Per-developer performance breakdown\n- **File Churn Analysis**: Identify frequently modified files (quality indicators)\n- **Team Summaries**: Comprehensive team performance reports\n- **Commit Patterns**: Analyze when people commit (burnout detection)\n- **Code Ownership**: Bus factor and knowledge distribution analysis\n- **Velocity Trends**: Week/month productivity tracking\n- **Collaboration Metrics**: Team interaction patterns\n- **Quality Metrics**: Commit size, reverts, and fix rates\n- **Technical Debt**: Stale files and complexity hotspots\n- **Conventional Commits**: Analyze commit types, scopes, and release frequency\n\n### Production Features\n\n- **Input Sanitization**: Protection against command injection attacks\n- **Structured Logging**: JSON-formatted logs with timestamps for monitoring\n- **Configurable Timeouts**: Set `GIT_TIMEOUT` env var (default: 30s)\n- **Error Boundaries**: Graceful error handling with detailed logging\n- **CI/CD**: Automated testing on pull requests via GitHub Actions\n\n\n## Installation\n\n### From npm (Recommended)\n\n```bash\nnpm install -g @jonmatum/git-metrics-mcp-server\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/jonmatum/git-metrics-mcp-server.git\ncd git-metrics-mcp-server\nnpm install\nnpm run build\n```\n\n## Kiro CLI Configuration\n\nAdd to `~/.kiro/settings/mcp.json`:\n\n**If installed globally:**\n```json\n{\n  \"mcpServers\": {\n    \"git-metrics\": {\n      \"command\": \"git-metrics-mcp-server\",\n      \"args\": []\n    }\n  }\n}\n```\n\n**If using npx:**\n```json\n{\n  \"mcpServers\": {\n    \"git-metrics\": {\n      \"command\": \"npx\",\n      \"args\": [\"@jonmatum/git-metrics-mcp-server\"]\n    }\n  }\n}\n```\n\n**If running from source:**\n```json\n{\n  \"mcpServers\": {\n    \"git-metrics\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/path/to/git-metrics-mcp-server/src/git-metrics.ts\"]\n    }\n  }\n}\n```\n\n## Usage with Kiro CLI\n\nStart Kiro CLI:\n```bash\nkiro-cli chat\n```\n\nThen ask natural language questions:\n\n```\nGet commit stats for /home/user/myproject since 2025-11-01\nShow me team summary and velocity trends for the last 2 weeks\nWhat's our bus factor? Who are single points of failure?\nShow me commit patterns - are people committing late at night?\nWhat files have the most churn since October?\nIdentify technical debt and complexity hotspots\n```\n\nFor comprehensive analysis, see the [Analysis Prompt](docs/git-metrics-analysis-prompt.md).\n\n## Available Tools\n\n\u003e **Note on Date Ranges**: The `until` parameter is **inclusive** - commits on the end date are included in results. For example, `since=\"2025-11-01\" until=\"2025-11-30\"` includes all commits from November 1st through November 30th.\n\n### get_commit_stats\n\nGet overall commit statistics for a time period.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD), inclusive\n- `author` (optional): Filter by author\n\n**Returns:**\n```json\n{\n  \"commits\": 45,\n  \"additions\": 1250,\n  \"deletions\": 380,\n  \"filesChanged\": 67,\n  \"netChange\": 870\n}\n```\n\n### get_author_metrics\n\nDetailed metrics per contributor.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD)\n\n**Returns:**\n```json\n{\n  \"John Doe \u003cjohn@example.com\u003e\": {\n    \"commits\": 23,\n    \"additions\": 650,\n    \"deletions\": 120,\n    \"files\": 34\n  }\n}\n```\n\n### get_file_churn\n\nFiles with most changes (indicates complexity or issues).\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD), inclusive\n- `limit` (optional): Number of files, default 10\n\n**Returns:**\n```json\n[\n  { \"file\": \"src/main.ts\", \"changes\": 15 },\n  { \"file\": \"src/utils.ts\", \"changes\": 12 }\n]\n```\n\n### get_team_summary\n\nComprehensive team performance report.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD)\n\n**Returns:**\n```json\n{\n  \"period\": { \"since\": \"2025-11-01\", \"until\": \"now\" },\n  \"team\": {\n    \"totalCommits\": 45,\n    \"totalAdditions\": 1250,\n    \"totalDeletions\": 380,\n    \"contributors\": 3\n  },\n  \"contributors\": { ... }\n}\n```\n\n### get_commit_patterns\n\nAnalyze when people commit (burnout detection).\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD)\n\n**Returns:**\n```json\n{\n  \"byDay\": { \"Mon\": 45, \"Tue\": 38, ... },\n  \"byHour\": { \"09\": 12, \"14\": 18, ... },\n  \"patterns\": {\n    \"weekendPercentage\": \"15.2%\",\n    \"lateNightPercentage\": \"8.3%\"\n  }\n}\n```\n\n\u003e **Note:** Hours are shown in the author's local timezone at the time of commit.\n\n### get_code_ownership\n\nBus factor and knowledge distribution.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD), inclusive\n\n**Returns:**\n```json\n{\n  \"totalFiles\": 150,\n  \"sharedFiles\": 80,\n  \"soloFiles\": 70,\n  \"busFactor\": [\n    { \"author\": \"John \u003cjohn@example.com\u003e\", \"exclusiveFiles\": 25 }\n  ]\n}\n```\n\n### get_velocity_trends\n\nTrack velocity over time.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD), inclusive\n- `interval` (optional): \"week\" or \"month\", default \"week\"\n\n**Returns:**\n```json\n{\n  \"interval\": \"week\",\n  \"trends\": [\n    { \"period\": \"2025-11-01\", \"commits\": 45, \"additions\": 1250, \"deletions\": 380 }\n  ]\n}\n```\n\n### get_collaboration_metrics\n\nTeam interaction patterns.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD), inclusive\n\n**Returns:**\n```json\n{\n  \"collaborativeFiles\": 80,\n  \"topCollaborations\": [\n    { \"pair\": \"John \u003c-\u003e Jane\", \"sharedFiles\": 25 }\n  ]\n}\n```\n\n### get_quality_metrics\n\nCode quality indicators.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD), inclusive\n\n**Returns:**\n```json\n{\n  \"averageCommitSize\": 125,\n  \"medianCommitSize\": 85,\n  \"revertRate\": \"2.3%\",\n  \"fixRate\": \"18.5%\"\n}\n```\n\n### get_technical_debt\n\nIdentify technical debt.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `stale_days` (optional): Days to consider stale, default 90\n\n**Returns:**\n```json\n{\n  \"staleFiles\": [\n    { \"file\": \"old-module.js\", \"daysSinceLastChange\": 180 }\n  ],\n  \"complexityHotspots\": [\n    { \"file\": \"big-file.js\", \"churn\": 25 }\n  ]\n}\n```\n\n### get_conventional_commits\n\nAnalyze conventional commit usage and release patterns.\n\n**Parameters:**\n- `repo_path` (required): Path to git repository\n- `since` (required): Start date (YYYY-MM-DD)\n- `until` (optional): End date (YYYY-MM-DD), inclusive\n\n**Returns:**\n```json\n{\n  \"totalCommits\": 25,\n  \"conventionalCommits\": 25,\n  \"conventionalPercentage\": \"100.0%\",\n  \"commitTypes\": [\n    { \"type\": \"feat\", \"count\": 5 },\n    { \"type\": \"fix\", \"count\": 5 }\n  ],\n  \"topScopes\": [\n    { \"scope\": \"main\", \"count\": 8 }\n  ],\n  \"breakingChanges\": 0,\n  \"recentReleases\": [\n    { \"tag\": \"v2.0.1\", \"date\": \"2025-11-24\" }\n  ],\n  \"releaseFrequency\": \"8 releases since 2025-11-01\"\n}\n```\n\n## Real-World Use Case: Team Health Analysis\n\nHere's how a real engineering team used this tool to understand their development patterns across 5 repositories with 83 contributors:\n\n### The Challenge\nA team needed to understand their development health across multiple repositories without manually parsing git logs. They wanted to identify risks, improve collaboration, and ensure sustainable work practices.\n\n### What They Discovered\n\n**Team Health Insights:**\n- ✅ Excellent work-life balance: Only 1.3% weekend commits\n- ✅ Strong release discipline: 114 releases with 86.3% conventional commit adoption\n- ⚠️ Bus factor risk: Two developers owned 61% of exclusive files in one repo\n- ⚠️ High fix rate (36.3%) indicated reactive development in one project\n\n**Collaboration Patterns:**\n- Best practice: One repo had 88.9% shared files (excellent knowledge distribution)\n- Needs improvement: Another repo had only 30.5% shared files\n- Identified top collaboration pairs for knowledge sharing\n\n**Code Quality Indicators:**\n- Found complexity hotspots: Files with 66+ changes needing refactoring\n- Identified technical debt: Stale files and high-churn areas\n- Discovered optimal commit patterns: Median 17 lines (focused commits)\n\n### Actions Taken\n1. **Immediate:** Scheduled knowledge transfer sessions for high bus factor areas\n2. **Process:** Implemented pair programming to increase file sharing\n3. **Quality:** Added pre-commit hooks to reduce fix rate\n4. **Culture:** Replicated best practices from high-performing repos\n\n**Time Saved:** What would have taken days of manual analysis was completed in minutes with natural language queries.\n\n**Read the full analysis:** [team-activity-analysis.md](team-activity-analysis.md)\n\n---\n\n## Use Cases\n\n### ✅ Good Use Cases\n\n**Sprint Retrospectives**\n```\nShow me team summary and velocity trends for the last 2 weeks\nWhat's our commit pattern? Are we burning out?\n```\n\n**Risk Management**\n```\nWhat's our bus factor? Who are single points of failure?\nShow me code ownership - where do we have knowledge concentration?\n```\n\n**Code Quality Reviews**\n```\nShow me quality metrics and technical debt\nWhat files have high churn and need refactoring?\n```\n\n**Team Health Checks**\n```\nAre people committing late at night or on weekends?\nShow me collaboration metrics - is the team working together?\n```\n\n**Onboarding Support**\n```\nGet commit stats for new-dev@example.com since their start date\nShow their velocity trend over the first 3 months\n```\n\n### ❌ What This Is NOT For\n\n- ❌ Micromanagement or surveillance\n- ❌ Comparing developers against each other\n- ❌ Performance review ammunition\n- ❌ Daily productivity tracking\n\n## Team Health Indicators You Can Track\n\n### Risk Management\n- **Bus Factor**: Knowledge concentration risk - who are single points of failure?\n- **Code Ownership**: File sharing patterns - is knowledge distributed?\n- **Technical Debt**: Stale files, complexity hotspots needing attention\n\n### Team Well-being\n- **Burnout Indicators**: Weekend/late-night commits - is the team overworked?\n- **Work Patterns**: When people commit - are boundaries healthy?\n- **Velocity Trends**: Sustainable pace or sprint-and-crash cycles?\n\n### Code Quality\n- **Churn**: Files changed repeatedly (quality indicator)\n- **Commit Size**: Focused commits vs. large dumps\n- **Revert Rate**: How often do we undo work?\n- **Fix Rate**: Reactive (high fixes) vs. proactive development\n\n### Collaboration Health\n- **File Sharing**: How much code is touched by multiple people?\n- **Collaboration Pairs**: Who works together most often?\n- **Contribution Balance**: Even distribution or bottlenecks?\n\n### Process Maturity\n- **Conventional Commits**: Adoption rate of commit standards\n- **Release Frequency**: How often do we ship?\n- **Breaking Changes**: How disruptive are our releases?\n\n## Tips for Responsible Usage\n\n### How to Use This Tool Well\n\n1. **Use natural language**: Kiro understands context, so ask questions naturally\n2. **Focus on trends, not snapshots**: Weekly/monthly patterns matter more than daily counts\n3. **Combine metrics**: Ask for multiple analyses to get the full picture\n4. **Start conversations, don't end them**: Use data to ask \"why?\" not to judge\n5. **Look for patterns**: Team health indicators, not individual performance scores\n6. **Regular reviews**: Weekly health checks (5 min), sprint retrospectives (15 min), monthly trends (30 min)\n\n### Red Flags (Don't Do This)\n\n- ❌ Checking metrics more than once per day\n- ❌ Creating leaderboards or rankings\n- ❌ Setting commit quotas or targets\n- ❌ Using metrics in performance reviews without context\n- ❌ Comparing developers directly\n\n### Green Flags (Good Usage)\n\n- ✅ You check trends weekly/monthly, not daily\n- ✅ You ask \"what does this tell us about our process?\"\n- ✅ You use it to start conversations, not end them\n- ✅ You focus on team health, not individual performance\n- ✅ You look for patterns, not outliers\n- ✅ You use it to help, not judge\n\n**Remember:** The best teams are built on trust, not metrics. Use this tool to support your team, not surveil them.\n\n## Development\n\n```bash\nnpm run dev    # Run in development mode\nnpm run build  # Build for production\nnpm start      # Run built version\n```\n\n## Testing\n\n```bash\nnpm test              # Run tests\nnpm run test:watch    # Run tests in watch mode\nnpm run test:coverage # Run tests with coverage report\n```\n\nThe test suite covers:\n- Date validation\n- Repository path validation\n- Git command execution\n- Commit data parsing\n- Core git operations (stats, metrics, churn, velocity)\n\n\n## License\n\nMIT - See [LICENSE](LICENSE) file\n\n## Author\n\nJonatan Mata ([@jonmatum](https://github.com/jonmatum))\n\n## Contributing\n\nIssues and PRs welcome at https://github.com/jonmatum/git-metrics-mcp-server\n\n## Support\n\n- GitHub Issues: https://github.com/jonmatum/git-metrics-mcp-server/issues\n- MCP Documentation: https://modelcontextprotocol.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonmatum%2Fgit-metrics-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonmatum%2Fgit-metrics-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonmatum%2Fgit-metrics-mcp-server/lists"}