Wigo4it Code Conventions MCP

Wigo4it代码指南MCP服务器

一 MCP（模型上下文协议） 服务器，为GitHub Copilot等人工智能助手提供对Wigo4it代码指南、架构决策记录（ADR）、建议、风格指南和项目结构的访问。

� 快速启动-生产安装

先决条件

• .NET 10.0 SDK或更高版本
• MCP兼容客户端（VS Code与GitHub Copilot、Visual Studio、Claude Desktop、Cursor等）

步骤1：安装工具

将MCP服务器作为安装。NET全局工具：

dotnet tool install --global Wigo4it.CodeGuidelines.McpServer

要更新到最新版本：

dotnet tool update --global Wigo4it.CodeGuidelines.McpServer

步骤2：配置IDE

Visual Studio代码（带GitHub副本）

1. 创建或编辑 .vscode/mcp.json 在您的工作区根目录中：

   {
     "servers": {
       "wigo4it-code-guidelines": {
         "command": "wigo4it-code-guidelines"
       }
     }
   }

1. 重新加载VS代码 或重新启动GitHub Copilot扩展

1. 验证连接:

- 打开GitHub Copilot聊天 - MCP工具应自动可用 - 试着问： What ADRs are available?

Visual Studio 2022（使用GitHub Copilot）

1. 打开Visual Studio设置：工具→ 选项→ GitHub Copilot→ MCP服务器

1. 添加MCP服务器:

- 名字: wigo4it-code-guidelines - 命令: wigo4it-code-guidelines

1. 重新启动Visual Studio 激活MCP服务器

1. 验证连接:

- 打开GitHub Copilot聊天 - 问： What documentation is available from Wigo4it?

克劳德桌面

添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json\ macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ Linux: ~/.config/Claude/claude_desktop_config.json

{
  "servers": {
    "wigo4it-code-guidelines": {
      "command": "wigo4it-code-guidelines"
    }
  }
}

重新启动克劳德桌面 保存配置后。

第三步：开始使用！

配置后，您可以向AI助手提出以下问题：

• “有哪些ADR可用？”
• “给我看C#风格指南”
• “对Aspire有什么建议？”
• “显示.NET项目结构准则”

AI将自动使用MCP工具从Wigo4it存储库中获取最新文档。

______________________________________________________________________

�📋 概述

此MCP服务器使Wigo4it的编码标准和文档可以通过模型上下文协议访问AI驱动的开发工具。它公开了三种工具，允许AI助手在开发过程中按需查询和检索文档。

主要特点：

• 🔍 6个MCP工具 用于查询、搜索和发现指南
• 📂 双源支持 -从本地文件系统（开发）或GitHub（生产）加载
• 🤖 AI就绪 -与GitHub Copilot、Claude和其他MCP客户端无缝集成
• 🏷️ 基于类别的组织 -ADR、建议、风格指南、结构
• 🔍 全文检索 -在所有具有相关性评分的文档中搜索
• 🔗 相关文件 -根据内容相似性发现相关文档
• 🏷️ 标签筛选 -按标签跨类别筛选文档
• 🔄 自动发现 -文档是从GitHub或本地文件系统自动发现的
• 🚀 公共存储库 -无需身份验证，开箱即用

�️ 开发安装

对于想要贡献或从源代码运行的开发人员：

克隆和构建

1. 克隆存储库:

   git clone https://github.com/wigo4it/wigo4it-code-conventions-mcp.git
   cd wigo4it-code-conventions-mcp

1. 构建项目:

   dotnet build src/wigo4it-code-conventions-mcp.sln

1. 运行服务器:

   dotnet run --project src/Wigo4it.CodeGuidelines.McpServer

服务器将启动并等待来自MCP客户端的stdio连接。

配置以进行开发

Visual Studio代码（开发模式）

开发时，配置VS Code从源代码运行：

{
  "servers": {
    "wigo4it-code-guidelines": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\absolute\\path\\to\\wigo4it-code-conventions-mcp\\src\\Wigo4it.CodeGuidelines.McpServer"
      ]
    }
  }
}

重要提示： 将路径替换为克隆存储库的绝对路径。

运行测试

运行测试套件以验证一切正常：

# Run all tests
dotnet test src/wigo4it-code-conventions-mcp.sln

# Run tests with code coverage
dotnet test src/wigo4it-code-conventions-mcp.sln /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura

# Run tests with coverage threshold (80% minimum)
dotnet test src/wigo4it-code-conventions-mcp.sln /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura /p:Threshold=80 /p:ThresholdType=line

该项目在23个单元测试中保持了91%以上的测试覆盖率。

______________________________________________________________________

📚 可用的MCP工具

服务器提供了6个用于查询和发现文档的工具：

基本查询工具

发现和搜索工具

分类

• 不良反应 -架构决策记录（如ADR-001、ADR-002、ADR-003）
• 建议 -最佳实践和建议（例如，Aspire的使用）
• 风格指南 -编码风格指南（例如C#风格指南）
• 结构 -项目结构和组织指南

💡 用法示例

AI助手的示例查询

当使用GitHub Copilot、Claude或其他MCP客户端进行配置时，您可以询问：

一般问题：

• “有哪些可用的文档？”
• “显示所有ADR”
• “列出所有样式指南”

特定类别：

• “显示所有建议”
• “架构决策存在哪些ADR？”
• “显示所有项目结构”

具体文件：

• “给我看C#风格指南”
• “了解模块化单体的ADR”
• “显示.NET项目结构”
• “显示有关Aspire的推荐”

搜索与发现：

• “搜索有关Aspire的文档”
• “查找与ADR-002相关的文档”
• “显示所有标记为“架构”的文档”
• “哪些文档讨论了微服务？”
• “查找测试指南”

工具使用示例

MCP服务器公开了AI助手自动使用的工具。以下是这些工具如何工作的示例：

GetAll文档

返回包含元数据的所有可用文档的列表：

{
  "tool": "GetAllDocumentation",
  "parameters": {}
}

GetDocumentationByCategory

获取特定类别的文档：

{
  "tool": "GetDocumentationByCategory",
  "parameters": {
    "category": "ADRs"
  }
}

文档内容

检索文档的完整内容：

{
  "tool": "GetDocumentationContent",
  "parameters": {
    "id": "adrs/adr-003-prefer-modular-monoliths"
  }
}

搜索文档

在所有具有相关性评分的文档中搜索：

{
  "tool": "SearchDocumentation",
  "parameters": {
    "searchTerm": "aspire"
  }
}

返回带有相关性得分（0-100）、匹配计数和匹配文本摘录的排名结果。

GetRelated文档

查找与特定文档相关的文档：

{
  "tool": "GetRelatedDocumentation",
  "parameters": {
    "documentId": "adrs/adr-002-adoption-of-aspire-for-distributed-applications",
    "maxResults": 5
  }
}

使用内容相似性、共享标签和类别匹配来识别相关文档。

GetDocumentationByTag

按标签筛选文档：

{
  "tool": "GetDocumentationByTag",
  "parameters": {
    "tags": "architecture,aspire"
  }
}

返回至少有一个指定标记的所有文档。

📖 文档结构

文件按以下结构组织：

docs/
├── ADRs/              # Architecture Decision Records
│   ├── ADR-001-migration-to-dotnet-10.md
│   ├── ADR-002-adoption-of-aspire-for-distributed-applications.md
│   └── ADR-003-prefer-modular-monoliths.md
├── Recommendations/   # Best practices and recommendations
│   └── aspire-embrace.md
├── StyleGuides/       # Coding style guides
│   └── csharp-style-guide.md
└── Structures/        # Project structure guidelines
    └── dotnet-project-structure.md

每个文档都是一个markdown文件，其中可能包含：

• 前言：YAML元数据（可选）
• 标题：摘自第一篇 # Heading
• 内容：完整的降价文档
• 描述：摘自第一段

文档ID格式

文档ID遵循以下格式： category/filename （无 .md 扩展）

示例：

• adrs/adr-001-migration-to-dotnet-10
• styleguides/csharp-style-guide
• structures/dotnet-project-structure
• recommendations/aspire-embrace

🔍 运作原理

双源架构

MCP服务器支持两种加载文档的模式：

1. GitHub模式（默认） -用于生产用途

- 直接从公共GitHub存储库获取文档 - 使用GitHub Contents API列出文件，使用Raw Content API列出内容 - 不需要本地克隆 - 自动将文档缓存在内存中以提高性能 - 速率限制：每小时60个请求（未经身份验证）

1. 本地文件系统模式 -为了发展

- 从本地加载文档 docs/ 文件夹 - 在开发新文档时很有用 - 更快，实现快速迭代 - 无需网络呼叫

配置

该模式由以下方式控制 appsettings.json:

{
  "Documentation": {
    "UseLocalFileSystem": false,  // false = GitHub mode (default)
    "GitHubOwner": "wigo4it",
    "GitHubRepository": "wigo4it-code-conventions-mcp",
    "GitHubBranch": "main",
    "DocsPath": "docs"
  }
}

对于本地开发，set UseLocalFileSystem 到 true.

文档发现

文档会自动被发现：

1. GitHub模式：使用GitHub Contents API扫描存储库
2. 本地模式：递归扫描 docs/ 目录 *.md 文件
3. 解析：从第一个标题中提取标题 # Heading 以及第一段的描述
4. 缓存：文档缓存在内存中，以便快速访问

无需手动维护索引。

� 添加新文档

1. 创建markdown文件 在适当的 docs/ 子文件夹：

- docs/ADRs/ -架构决策记录 - docs/Recommendations/ -最佳做法和建议 - docs/StyleGuides/ -编码风格指南 - docs/Structures/ -项目结构指南

1. 撰写您的文档 以markdown格式：

   ---
   title: My New Guideline
   category: StyleGuide
   status: Active
   ---

   # My New Guideline

   This is the introduction paragraph that will be used as the description.

   ## Section 1
   ...

1. 本地测试:

- 集 UseLocalFileSystem: true 在 appsettings.json - 运行服务器并验证您的文档是否显示

1. 承诺并推动 到 main 分支：

   git add docs/
   git commit -m "docs: add new guideline"
   git push

推送后，该文档将通过GitHub模式自动可用。

项目结构

src/
├── Wigo4it.CodeGuidelines.Server/        # Core library
│   ├── Models/                           # DocumentationMetadata, Category, Content
│   ├── Configuration/                    # DocumentationOptions
│   ├── Services/                         # IDocumentationService implementations
│   │   ├── GitHubDocumentationService.cs       # GitHub API implementation
│   │   └── LocalFileSystemDocumentationService.cs  # Local file implementation
│   └── Tools/                            # DocumentationTools (MCP tools)
│
├── Wigo4it.CodeGuidelines.McpServer/     # MCP Server host
│   ├── Program.cs                        # Entry point & DI configuration
│   └── appsettings.json                  # Configuration
│
└── Wigo4it.CodeGuidelines.Tests/         # Unit tests (23 tests, 91%+ coverage)

📦 出版

该项目配置为。NET全局工具，可以发布到NuGet或GitHub包。

软件包配置

• 包ID: Wigo4it.CodeGuidelines.McpServer
• 工具命令名称: wigo4it-code-guidelines
• 目标框架: .净值10.0
• 许可证：MIT

带有GitHub操作的CI/CD

该项目使用GitHub Actions进行自动化构建和测试：

• 触发：推到 main 分支或拉取请求
• 工作：构建、测试、覆盖
• 测试覆盖率：91%+（20次通过测试，3次跳过集成测试）

手动构建和打包

要在本地创建NuGet包，请执行以下操作：

# Build the solution
dotnet build src/wigo4it-code-conventions-mcp.sln --configuration Release

# Pack the tool
dotnet pack src/Wigo4it.CodeGuidelines.McpServer/Wigo4it.CodeGuidelines.McpServer.csproj --configuration Release

# The .nupkg file will be in src/Wigo4it.CodeGuidelines.McpServer/nupkg/

版本控制

版本可以通过项目属性或GitVersion进行控制：

  1.0.0

🤝 贡献

欢迎投稿！请遵循以下指南：

1. 分叉存储库
2. 创建要素分支: git checkout -b feature/my-new-guideline
3. 添加您的文档 适当的 docs/ 文件夹（ADR、建议、样式指南或结构）
4. 本地测试 随着 UseLocalFileSystem: true
5. 提交您的更改: git commit -m "docs: add new guideline"
6. 推你的叉子: git push origin feature/my-new-guideline
7. 创建拉取请求

文件编制指南

• 使用清晰简洁的语言
• 遵循现有文档结构和格式
• 在适当的地方包括代码示例
• 添加带有标题、类别和状态的封面
• 通过MCP工具测试文档是否正确加载

📄 许可证

该项目根据MIT许可证获得许可。看 许可证 文件以获取详细信息。

🔗 相关链接

• 模型上下文协议文档
• 克劳德桌面
• 光标IDE

💬 支持

如有疑问、问题或建议：

• 问题:
• 讨论:
• 内部：联系Wigo4it开发团队

📊 项目状态

• ✅ .NET 10.0与C#14
• ✅ 3个用于文档访问的MCP工具
• ✅ 双源代码支持（GitHub+本地文件系统）
• ✅ 23个单元测试，代码覆盖率超过91%
• ✅ GitHub和本地文档服务
• ✅ 公共存储库（无需身份验证）
• ✅ 配置为。NET全局工具
• ✅ 完整的XML文档
• 🚧 发布到NuGet.org（即将推出）

当前文档

• 3 ADR: .NET 10迁移、Aspire采用、模块化单体
• 1建议：完全拥抱Aspire
• 1风格指南：C#代码风格指南（微软惯例）
• 1结构: .NET项目结构指南

______________________________________________________________________

由以下材料制成❤️ 作者：Wigo4it