Gitrules MCP Server

Git规则MCP服务器

使用AI编码助手强制执行Git工作流规则并防止违反存储库。

一个模型上下文协议（MCP）服务器，根据可配置的存储库规则验证Git命令，提供工作流指导，并在使用AI编码助手时防止常见的Git错误。

______________________________________________________________________

🚀 它做什么

• 🛡️ 分支保护：防止直接提交/推送到受保护的分支（main、master等）
• 📋 工作流验证：根据存储库的工作流规则验证Git命令
• 🔄 聪明的建议：在命令被阻止时提供替代工作流
• 📝 承诺标准：强制使用常规提交消息格式
• 🧹 存储库运行状况：分析存储库是否符合工作流规则
• 🤖 人工智能集成：与Claude Code、Cursor、GitHub Copilot和其他AI助手无缝协作

______________________________________________________________________

🎯 为什么你需要这个

问题

AI编码助手可能会意外地：

• 直接推送到受保护的分支
• 创建消息质量差的提交
• 绕过团队的Git工作流
• 使存储库管理混乱

解决方案

此MCP服务器充当 守门人 即：

• ✅ 验证每个Git操作 执行前
• ✅ 强制执行团队的工作流程规则 一贯地
• ✅ 指导人工智能助手 遵循正确的Git实践
• ✅ 防止违反存储库 在它们发生之前

______________________________________________________________________

📦 快速安装

⚠️ 重要：大多数用户在默认npm配置下都会遇到权限错误。使用 推荐设置 下面是为了避免问题。

🎯 推荐设置（防止权限错误）

将整个块复制并粘贴到您的终端中：

# Setup npm user directory and install in one go:
mkdir -p ~/.npm-global && \
npm config set prefix ~/.npm-global && \
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && \
source ~/.zshrc && \
npm install -g @fraqtiv/git-rules-mcp && \
echo "🎉 Installation complete! Testing..." && \
mcp-git-rules --test

对于Bash用户，替换 ~/.zshrc 随着 ~/.bashrc:

# Bash version:
mkdir -p ~/.npm-global && \
npm config set prefix ~/.npm-global && \
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc && \
source ~/.bashrc && \
npm install -g @fraqtiv/git-rules-mcp && \
echo "🎉 Installation complete! Testing..." && \
mcp-git-rules --test

运行上述操作后的预期输出：

🎉 Installation complete! Testing...
🔍 Testing git-rules-mcp installation...
✅ MCP Server: Initialized successfully
✅ Git Repository: Detected (or Not found)
✅ Configuration: Loaded (X protected branches)
🎉 Installation test passed! The MCP server is ready to use.

🔧 替代方案：全系统安装（可能需要Sudo）

如果您更喜欢全系统安装并遇到权限错误：

# Only if you get EACCES permission errors:
sudo npm install -g @fraqtiv/git-rules-mcp

# Then test (no sudo needed for testing):
mcp-git-rules --test

🚨 常见问题的快速修复

仍然出现权限错误？ 使用上面的单行命令，而不是 npm install -g 直接。

❌ 安装后“找不到命令：mcp-git-rules”？ 你错过了将npm bin添加到PATH中。 立即修复：

# Quick fix (copy-paste this):
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc && mcp-git-rules --test

# Or for Bash:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc && source ~/.bashrc && mcp-git-rules --test

# Alternative - run with full path once:
~/.npm-global/bin/mcp-git-rules --test

要验证安装状态吗？

npm list -g @fraqtiv/git-rules-mcp  # Check if installed
which mcp-git-rules                 # Check if in PATH
mcp-git-rules --help               # Show available options

⚡ 通过AI助手快速设置

选择您的AI编码助手以获取特定的设置说明：

💡 快速开始：大多数用户应该从 克劳德代码指南 为了获得最流畅的体验。

______________________________________________________________________

🛠️ 基本配置

创建 .gitrules.yaml 在您的存储库根目录中：

# Protected branches that cannot be directly modified
protectedBranches:
  - main
  - master

# Integration branch where features are merged first  
integrationBranch: dev

# Branch naming conventions
featureBranchPrefix: feature/
hotfixBranchPrefix: hotfix/

# Workflow enforcement
requireCleanWorkingTree: true
allowDirectPush: false
enforceCommitMessageFormat: true

# Conventional commit types
allowedCommitTypes:
  - feat      # New features
  - fix       # Bug fixes  
  - docs      # Documentation
  - style     # Formatting
  - refactor  # Code restructuring
  - test      # Adding tests
  - chore     # Maintenance

🎮 运作原理

1.存储库状态检查

# The MCP server analyzes your repository
Current Branch: feature/user-auth
Status: Clean ✅
Protected: No ✅
Integration Branch: dev

2.命令验证

# Before: git push origin main
❌ BLOCKED: Direct push to protected branch 'main'
💡 Suggestion: Merge to 'dev' first, then create PR to main

# Proper workflow:
✅ git checkout dev
✅ git merge feature/user-auth  
✅ git push origin dev
✅ Create PR: dev → main

3.工作流程指导

# AI Assistant asks: "How do I start a new feature?"
# MCP Server responds:

🚀 Starting New Feature:
1. git checkout dev
2. git pull origin dev  
3. git checkout -b feature/your-feature-name

✅ Ready to begin development!

______________________________________________________________________

🔧 可用工具

MCP服务器为AI助手提供以下工具：

______________________________________________________________________

🌟 主要特点

分支保护

• 受保护的分支：防止直接提交到main/master
• 集成工作流程：强制执行适当的合并模式
• 清洁工作树：需要干净状态才能进行受保护的操作

承诺标准

• 常规承诺：强制执行 type: description 格式
• 类型验证：只允许配置的提交类型
• 消息质量：确保有意义的提交消息

工作流程自动化

• 聪明的建议：命令被阻止时的替代路径
• 分步指导：完整的工作流程说明
• 安全检查：每次操作前进行验证

AI助手集成

• 通用兼容性：可与任何启用MCP的AI助手配合使用
• 实时验证：Git操作的即时反馈
• 教育的：教授正确的Git工作流程

______________________________________________________________________

📖 示例工作流

受保护的分支工作流

main (protected) ← PR ← dev ← merge ← feature/new-auth
                                   ↑
                              You work here

功能开发流程

# 1. Start new feature (validated by MCP)
git checkout dev
git pull origin dev
git checkout -b feature/user-authentication

# 2. Development work
git add .
git commit -m "feat: add user login form"
git commit -m "test: add login form tests"

# 3. Feature complete (validated by MCP)  
git checkout dev
git merge feature/user-authentication
git push origin dev

# 4. Production release
# Create PR: dev → main (only way to update main)

______________________________________________________________________

🏗️ 高级用法

自定义规则

# .gitrules.yaml - Advanced configuration
protectedBranches:
  - main
  - staging
  - release/*

workflowRules:
  requirePullRequest: true
  requireCodeReview: true
  requireStatusChecks: true
  
branchNaming:
  feature: "feature/JIRA-123-description"
  hotfix: "hotfix/JIRA-456-critical-fix"
  
commitRules:
  maxLength: 72
  requireJiraTicket: true
  allowedScopes: ["auth", "api", "ui", "docs"]

CI/CD集成

# .github/workflows/validate-git-rules.yml
name: Git Rules Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup npm global directory
        run: |
          mkdir -p ~/.npm-global
          npm config set prefix ~/.npm-global
          echo "$HOME/.npm-global/bin" >> $GITHUB_PATH
      - run: npm install -g @fraqtiv/git-rules-mcp
      - run: mcp-git-rules --test

______________________________________________________________________

🔍 高级故障排除

安装问题

⚠️ 最常见的问题：参见 快速安装 以上部分介绍了主动解决方案。

高级路径配置

# For different shells:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc   # Bash
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc    # Zsh
echo 'set -gx PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.fish  # Fish

# Check current npm prefix:
npm config get prefix

# Check if PATH includes npm global bin:
echo $PATH | grep -q "$(npm config get prefix)/bin" && echo "✅ PATH configured" || echo "❌ PATH missing npm global bin"

软件包安装问题

# Check installation
npm list -g @fraqtiv/git-rules-mcp

# Reinstall if needed
npm install -g @fraqtiv/git-rules-mcp

规则未被执行

• 看 克劳德代码警告
• 确保项目有适当的工作流程文档
• AI助手需要明确的指导才能使用MCP工具

配置未加载

# Test configuration
mcp-git-rules --config-check

# Validate YAML syntax
mcp-git-rules --validate-config .gitrules.yaml

______________________________________________________________________

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发设置

git clone https://github.com/FRAQTIV/gitrules-mcp-server.git
cd gitrules-mcp-server
npm install
npm run build
npm test

______________________________________________________________________

📋 路线图

• \[ \] Web仪表板 -可视化存储库合规性仪表板
• \[ \] 团队分析 -工作流合规性指标和报告
• \[ \] 定制挂钩 -可扩展验证系统
• \[ \] 集成模板 -针对流行工作流的预构建配置
• \[ \] 企业功能 -高级合规性和审计日志记录

______________________________________________________________________

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙋 支持与社区

• 📖 文档: 完整文档和集成指南
• 🐛 问题:
• 💬 讨论:
• 🔗 网站:

______________________________________________________________________

⭐ 如果此仓库有助于保持Git工作流程的整洁，请将其标记为星号！ ⭐

由以下材料制成❤️ 靠近 FRAQTIV