ArchGuard（架构守护者）MCP服务器 / GitHub应用
A.提供C#验证检查的.NET 9应用程序 通过AI代理工具（MCP）和自动化的GitHub webhook检查。 当前的实现仅包含2个简单的规则验证，仅供演示之用。 关键在于，基于模板的规则系统可以轻松扩展，以处理任何所需的验证操作，从而使得 确保你的架构指南得到了妥善遵循（参见TEMPLATE_SYSTEM.md）。
请在我的LinkedIn帖子中查看更多信息：\ https://www.linkedin.com/feed/update/urn:li:activity:7370622737263894528/ （该链接为LinkedIn上的一个动态更新页面，直接翻译为中文无实际意义，保持原样即可）\ https://www.linkedin.com/feed/update/urn:li:activity:7371608592623312896/ 的中文翻译可以是：“领英（LinkedIn）动态更新链接：urn:li:activity:7371608592623312896/”。不过，通常我们不会直接翻译URL地址，因为它们在中文环境中通常保持原样，但这里为了符合翻译要求，给出了一个意译版本。实际上，在中文语境中，我们更可能直接使用该URL，或者简单描述为“领英上的某条动态更新链接”\ https://www.linkedin.com/feed/update/urn:li:activity:7373155482225647616/（该链接翻译为中文仍为原链接形式，因为链接本身是网址，无需翻译。但若仅就链接内容或意图进行描述，可表述为：“这是一个LinkedIn（领英）上的更新链接，指向特定的活动ID为7373155482225647616的帖子。”）\ https://www.linkedin.com/feed/update/urn:li:activity:7374811981289103360/ （该链接为LinkedIn上的特定更新页面，直接翻译为中文无实际意义，保持原样）\ https://www.linkedin.com/feed/update/urn:li:activity:7378160986584670208/（该链接为LinkedIn上的一个动态更新页面，直接翻译为中文无实际意义，可表述为“LinkedIn上的一个动态更新链接”）
概述
ArchGuard 以两种模式运行：
- MCP 服务器模式AI代理（如Visual Studio和VS Code中的GitHub Copilot）可以直接调用验证工具
- GitHub Webhook 模式由GitHub事件（推送、拉取请求、检查运行）触发的自动化验证
两种模式都使用相同的核心验证逻辑，该逻辑会启动一个AI代理（ClaudeCode、GeminiCLI、LocalFoundry或GitHubModels）来分析C#项目，以 依赖注入问题或任何其他定义的规则。
关键特性
- 双操作模式 - MCP工具 + GitHub Webhook自动化
- 动态仓库克隆 - 按需分析任何GitHub仓库
- 背景清理 - 自动删除临时克隆的仓库
- 私有仓库支持 - GitHub 应用程序认证用于私有仓库
建筑学
这个项目扩展了一个OAuth保护的MCP服务器架构，增加了与GitHub的集成功能。
基于之前的项目
关于OAuth 2.0服务器、MCP基础设施、ngrok设置以及基本配置详情，请参阅：\ Enphase MCP服务器项目原始README文件
OAuth/MCP基础设施（端点、JWT令牌、客户端注册、ngrok配置）与原始实现保持不变。
ArchGuard的不同之处在哪里
新的GitHub集成：
- 动态仓库克隆系统
- 针对私有仓库的GitHub应用认证
- 用于推送、拉取请求和检查运行的Webhook处理程序
- 背景仓库清理服务
快速入门
1. GitHub 应用配置
创建并安装一个具有以下权限的GitHub应用程序：
- 仓库权限：
- 内容：阅读 - 元数据：读取 - 拉取请求：阅读 - 支票：填写
配置webhook事件：
- 推动；推送
- 拉取请求
- 检查运行情况
- 检查套件
2. 应用程序配置
更新 appsettings.json:
{
"GitHub": {
"AppId": "your-github-app-id",
"PrivateKeyFilePath": "path/to/private-key.pem"
},
"RepositoryCloning": {
"CodingAgent": "ClaudeCode", // Options: "ClaudeCode", "GeminiCLI", "LocalFoundry" (not recommended), "GitHubModels"
"CleanupIntervalMinutes": 60,
"MaxRetentionHours": 2,
"CleanupAfterValidation": true
},
"GitHub": {
"Models": {
"PAT": "", // GitHub Personal Access Token (required for GitHubModels agent)
"ModelId": "openai/gpt-4o",
"Endpoint": "https://models.github.ai/inference"
}
}
}3. OAuth/MCP 设置
遵循原始项目的设置：
- ngrok URL 配置
- OAuth客户端注册
- MCP终端保护
4. 运行应用程序
# Start ngrok tunnel (see original project for details)
ngrok http 7071 --domain=your-static-domain.ngrok-free.app
# Run the application
dotnet runArchGuard验证工具
它验证的内容
- 构造函数依赖项 - 确保所有通过构造函数注入的服务都已注册
- 实体/数据传输对象（DTO）属性映射 - 验证实体与数据传输对象（DTO）之间的属性映射
- 易于扩展 - 基于模板的规则系统，用于添加新的验证规则（见
TEMPLATE_SYSTEM.md)
它是如何运作的
- 仓库访问克隆GitHub仓库到临时目录（基于文件的代理），通过GitHub API提取文件（基于API的代理），或在通过MCP调用时访问本地目录。
- 分析使用AI代理（ClaudeCode、GeminiCLI、LocalFoundry或GitHubModels）来分析项目
- 结果返回包含验证结果、违规项及解释的JSON数据
- 清理删除基于文件的代理的临时存储库（立即或后台）
工具输入模式（或工具输入架构）
{
"contextFiles": [
{ "filePath": "src/Services/SomeService.cs" }
],
"diffs": ["git diff output lines..."]
}操作模式
MCP模式（AI代理）
AI代理调用验证工具：
ValidateDependencyRegistration（模板规则）ValidateEntityDtoPropertyMapping（生成的规则）- 工具使用MCP服务器的root访问权限克隆仓库或访问本地目录
- 返回结构化的验证结果
GitHub Webhook 模式
由GitHub事件触发的自动化验证：
推送事件验证推送提交中的更改 拉取请求（或合并请求）在合并前验证拉取请求（PR）的更改\ 检查运行（或“验证执行”）按需重新运行验证 检查套件全面的验证套件
工作流程：
- GitHub发送webhook → ArchGuard接收事件
- 仓库已克隆到临时目录
- 针对特定提交/分支的验证运行
- 结果以检查运行的形式发布回GitHub
- 仓库已清理（立即或后台进行）
GitHub 集成详情
动态仓库克隆
- 任何仓库不限于特定项目
- 私有仓库使用GitHub应用程序身份验证
- 特定的提交（或提交记录）从webhook精确克隆提交
- 临时存储使用系统临时目录并进行清理
- 跨平台路径Windows存储 → 用于Claude Code的WSL路径
Webhook 安全性
- 签名验证验证GitHub webhook签名
- 安装ID用于身份验证的webhook有效载荷提取内容
- 事件过滤仅处理相关的GitHub事件
后台服务
- 仓库清理自动删除旧的临时存储库
- 可配置的保留策略为临时存储库设置最大年龄
- 磁盘空间监控空间不足时的紧急清理
- 立即清理验证后立即清理的选项
故障排除
GitHub Webhook 问题
- 403 禁止访问检查GitHub应用程序的权限和安装情况
- 空的JSON响应通常表示仓库克隆失败
- 权限被拒绝错误Git 打包文件可能是只读的（自动处理）
仓库克隆问题
- 认证失败验证GitHub应用的私钥和应用ID
- 路径转换错误检查WSL（Windows Subsystem for Linux）的安装和路径格式
- 清理失败可能需要手动清理临时目录
MCP/OAuth 问题
OAuth 参数兼容性：
- Gemini 命令行界面 (CLI)需要
audience参数支持（同时发送两者）audience和resource) - 其他客户可使用
resource参数（RFC 8707 资源指示器） - 服务器支持ArchGuard 支持这两种参数，并遵循 OAuth 规范的优先级（
audience>resource）
“invalid_target”的认证错误：
- 验证客户端是否在发送正确的MCP终端URL
audience或者resource参数 - 预期的URL格式：
https://your-ngrok-domain/mcp/（带尾部斜杠）
请参阅原始的Enphase MCP服务器项目README文件，以获取有关OAuth服务器和MCP故障排除的更多信息。
已知的局限性
- Gemini CLI 可靠性在验证过程中，输出可能会偶尔消失
- 本地晶圆厂整合由于精度有限，不建议用于生产环境（见下文LocalFoundry部分）
- 调试日志记录在积极开发期间，控制台输出大量信息
- 上下文/差异当前已登录但未在验证逻辑中积极使用
- DI规则范围仅验证构造函数依赖项（不包括属性注入等）
有关详细的技术问题和开发说明，请参阅 KNOWN_ISSUES.md 翻译为中文是：“已知问题.md” 或 “已知问题列表.md”.
本地晶圆厂整合讨论
状态可用但不推荐。（详见KNOWN_ISSUES.md）
LocalFoundry（微软的本地AI运行时）已被整合为继ClaudeCode和GeminiCLI之后的第三个AI代理选项。详见 KNOWN_ISSUES.md 翻译为中文是：“已知问题.md” 关于详细的技术限制和准确性问题。
设置（如果使用LocalFoundry）
如果您想尝试使用LocalFoundry：
- 安装LocalFoundry遵循微软的 开始使用LocalFoundry 指南；引导；导游
- 预先下载模型 （建议在运行 ArchGuard 之前进行）
foundry model run qwen2.5-0.5b这会将模型下载到本地，首次运行时可能需要较长时间。先运行此命令可以避免ArchGuard启动时出现超时问题。
- 测试你的设置使用LocalFoundry命令行聊天机器人或 VS Code 的 AI Studio 插件 直接与模型聊天以测试其性能。
GitHub模型集成
状态适用于且建议使用基于云的验证。
GitHub Models 通过 GitHub 的基础设施提供对云端 AI 模型（包括 GPT-4）的访问。这是推荐的基于 API 的代理选项。
优势
- 更高的准确性云模型（尤其是GPT-4）在遵循指令方面优于本地模型
- 无硬件要求没有本地GPU或CPU的限制
- 可靠的JSON输出与较小的本地模型相比，解析问题极少
- 提供免费套餐速率受限，但基本访问无使用费用
- 未初始化无需下载本地模型，即时可用
设置
- 生成GitHub个人访问令牌（PAT）：
- 访问 https://github.com/settings/tokens - 创建一个具有适当权限的新令牌，以便访问GitHub Models - 请参阅：https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens（管理您的个人访问令牌）
- 配置 ArchGuard：
- 设置 CodingAgent to "GitHubModels" 在 appsettings.json - 添加您的PAT（个人访问令牌/个人密码等，具体根据上下文确定）到 GitHub:Models:PAT 在 appsettings.json 中，或者 - 设定；套装 GITHUB_MODELS_PAT 环境变量（出于安全考虑，建议使用）
- 可选定制：
- 改变 ModelId 使用不同的模型（默认： "openai/gpt-4o") - 终端已预配置为 https://models.github.ai/inference
局限性
- 网络依赖需要互联网连接
- 速率限制免费套餐对API调用有速率限制
- 延迟网络往返执行与本地执行
如需详细的实施信息，请参阅 .
版权和许可
代码
版权所有 (©) 2025 Jzuras
这个程序是自由软件：你可以对其进行传播和/或修改 它根据由（版权持有者）发布的GNU通用公共许可证（条款）进行许可 自由软件基金会，采用其许可证的第三版，或 （由您选择）任何后续版本。
这个程序的分发是出于希望它能有所用处， 但没有任何保证；甚至没有暗示性的保证 商品的适销性或特定用途的适用性。请参阅 GNU通用公共许可证（GNU General Public License）中有关于此的更多详细信息。
商标
所有商标均为其各自所有者的财产。 本项目中使用的任何商标均仅为描述性使用，且用于说明兼容性。