JSdotNet.Project.Guidelines.McpServer 1.0.2

JSdotNet Project Guidelines

Design, architecture, style and structure guidelines for modern .NET (C#) projects, organized as ADRs, designs, recommendations and structures under guide/. An MCP Server in src/ exposes these documents for tools/agents.

Credits: This project builds on the original HexMaster Design Guidelines work by Eduard Keilholz (GitHub: nikneem) and contributors. Original repository: https://github.com/nikneem/hexmaster-design-guidelines

MCP Server (C#, .NET 10)

An MCP (Model Context Protocol) server implementing the official Microsoft MCP SDK. Exposes design guideline documents as tools that AI assistants can call.

Requirements

• .NET 10 SDK

MCP Protocol

The server implements the Model Context Protocol using the official ModelContextProtocol NuGet package. It exposes tools for:

1. ListDocuments - Lists all available design guideline documents (ADRs, designs, recommendations, structures)
2. GetDocument - Retrieves the content of a specific document by its ID
3. SearchDocuments - Searches documents by keyword or phrase

Documents are served from the local filesystem when available, with automatic fallback to GitHub repository content.

Run Standalone (for testing)

From the repository root:

dotnet run --project .\src\JSdotNet.Project.Guidelines.McpServer\JSdotNet.Project.Guidelines.McpServer.csproj

The server uses stdio transport for MCP communication. Logs are written to stderr, JSON-RPC messages to stdout.

Install as GitHub Copilot MCP Tool

The MCP Server can be integrated with GitHub Copilot to provide AI agents with access to design guidelines during code generation.

There are two usage scenarios:

1. Standard Installation (Recommended) - Install from NuGet, documents fetched from GitHub
2. Local Development - Run from source with local documents for testing changes

Scenario 1: Standard Installation (NuGet Global Tool)

This is the recommended approach for general use. Documents are automatically fetched from the GitHub repository, so no local clone is needed.

VS Code Setup

1. Install the package:

   dotnet tool install --global JSdotNet.Project.Guidelines.McpServer
   

2. Configure VS Code MCP settings:

   Create or edit .vscode/mcp.json in your user profile or workspace:

   {
     "inputs": [],
     "servers": {
       "jsdotnet-coding-guidelines": {
         "type": "stdio",
         "command": "jsdotnet-project-guidelines-mcpserver",
         "args": []
       }
     }
   }
   

   Location options:

   • User-level (all workspaces): %USERPROFILE%\.vscode\mcp.json (Windows) or ~/.vscode/mcp.json (Mac/Linux)
   • Workspace-level (specific project): .vscode/mcp.json in your project root

3. Restart VS Code to apply changes

4. Verify the connection:

   • Open the Output panel: View → Output
   • Select "MCP" from the dropdown
   • You should see server startup logs
   • Open GitHub Copilot Chat
   • Ask Copilot: "What ADRs are available in the design guidelines?"

Visual Studio Setup

1. Install the package:

   dotnet tool install --global JSdotNet.Project.Guidelines.McpServer
   

2. Configure Copilot MCP settings:

   • Go to Tools → Options
   • Navigate to GitHub → Copilot → MCP Servers
   • Click "Add Server"
   • Configure:
     • Name: jsdotnet-coding-guidelines
     • Command: jsdotnet-project-guidelines-mcpserver

3. Restart Visual Studio to apply changes

4. Verify the connection:

   • Open GitHub Copilot Chat window
   • The MCP server should be listed as an active tool
   • Ask Copilot: "Show me the ADR for .NET version adoption"

How it works: When installed as a global tool, the server automatically fetches documents from the GitHub repository (https://github.com/JSdotNet/Project-Guidelines-MCP). No local clone is required, and you'll always get the latest published content from the main branch.

Update:

dotnet tool update --global JSdotNet.Project.Guidelines.McpServer

Uninstall:

dotnet tool uninstall --global JSdotNet.Project.Guidelines.McpServer

Scenario 1b: GitHub Copilot CLI Setup

Copilot CLI reads .mcp.json from your project root automatically. This repo ships a ready-to-use .mcp.json — you only need to install the global tool first.

1. Install the package (if not already installed):

   dotnet tool install --global JSdotNet.Project.Guidelines.McpServer
   

2. Copy .mcp.json to your project root (or add the server entry to an existing .mcp.json):

   {
     "mcpServers": {
       "jsdotnet-coding-guidelines": {
         "type": "stdio",
         "command": "jsdotnet-project-guidelines-mcpserver",
         "args": [],
         "tools": ["*"]
       }
     }
   }
   

3. Start Copilot CLI in your project folder:

   copilot
   

   The MCP server is picked up automatically — no restart needed.

4. Verify by running /mcp show jsdotnet-coding-guidelines inside the CLI session.

Alternatively, add the server at the user level (available in all projects):

# Inside a Copilot CLI session
/mcp add

Follow the prompts: type stdio, command jsdotnet-project-guidelines-mcpserver, tools *.

Update:

dotnet tool update --global JSdotNet.Project.Guidelines.McpServer

Then inside an active Copilot CLI session, run /mcp show to confirm the updated server version is loaded.

Uninstall:

dotnet tool uninstall --global JSdotNet.Project.Guidelines.McpServer

Then remove the entry from .mcp.json or run /mcp delete jsdotnet-coding-guidelines inside a Copilot CLI session to remove the user-level entry.

Scenario 2: Local Development (Run from Source)

For contributors testing local changes before publishing to NuGet. This allows you to work with unpublished ADRs, recommendations, or structural changes.

VS Code Setup

1. Clone the repository:

   git clone https://github.com/JSdotNet/Project-Guidelines-MCP.git
   cd Project-Guidelines-MCP
   

2. Create or edit .vscode/mcp.json in the repository root with your actual path:

   {
     "inputs": [],
     "servers": {
       "jsdotnet-project-guidelines-local": {
         "type": "stdio",
         "command": "dotnet",
         "args": [
           "run",
           "--project",
           "D:/projects/github.com/JSdotNet/Project-Guidelines-MCP/src/JSdotNet.Project.Guidelines.McpServer/JSdotNet.Project.Guidelines.McpServer.csproj"
         ]
       }
     }
   }
   

3. Restart VS Code - The MCP server will run directly from your local source code

How it works: When running from source with dotnet run, the server automatically discovers and reads documents from your local guide/ folder. This allows you to test changes immediately without publishing.

Testing Local NuGet Packages (Advanced)

If you want to test the packaged tool locally before publishing to NuGet.org:

# Pack the project
dotnet pack src/JSdotNet.Project.Guidelines.McpServer/JSdotNet.Project.Guidelines.McpServer.csproj -o ./local-packages

# Install from local package
dotnet tool install --global --add-source ./local-packages JSdotNet.Project.Guidelines.McpServer

Troubleshooting

Server doesn't appear in Copilot

• Check Output panel (View → Output) and select "MCP" from dropdown
• Verify the command path is correct (use full path if needed)
• Ensure .NET 10 SDK is installed: dotnet --version
• Try restarting VS Code

Documents not loading

• For NuGet installation: Check internet connectivity (docs fetched from GitHub)
• For local development: Verify JSDOTNET_REPO_ROOT points to repository root
• Check server logs in MCP Output panel

Global tool not found

• Verify installation: dotnet tool list --global
• Check PATH includes .NET tools directory
  • Windows: %USERPROFILE%\.dotnet\tools
  • Mac/Linux: ~/.dotnet/tools

Registering new documents

This repository uses guide/index.json as the canonical registry for MCP document discovery.

When you add, rename, edit, or remove markdown files in guide/, also update guide/index.json so metadata and paths stay in sync.

Repo structure

guide/
 adrs/
 designs/
 recommendations/
 structures/
src/
 Project.Guidelines.guide/
 Project.Guidelines.McpServer/
tests/
 Project.Guidelines.McpServer.Tests/
JSdotNet.Project.Guidelines.slnx
.github/
 copilot-instructions.md

ADRs

• 0001: Adopt .NET 10 as Target Framework (Accepted)
• 0002: Central Package Management for .NET Solutions (Accepted)
• 0003: .NET Aspire Recommendation for ASP.NET Services (Accepted)
• 0004: Standardize Result Objects for Expected Application Outcomes (Accepted)
• 0005: Modular Monolith Project Structure (Accepted)
• 0006: CQRS Recommendation for ASP.NET API (Accepted)
• 0007: Minimal APIs Over Controller-Based APIs (Accepted)
• 0008: Adopt Vertical Slice Architecture for Feature Organization (Accepted)
• 0009: Feature Slices Within Module Projects (Accepted)
• 0010: Adopt OpenTelemetry for Comprehensive Observability (Accepted)
• 0011: Centralized Frontend Styling Variables (Accepted)

Designs

• Modular Monolith Architecture Design
• Pragmatic Domain-Driven Design Approach

Recommendations

• Blazor Frontend Framework Guidance
• C# Coding Style
• Object Calisthenics for Domain Code
• Specification Pattern for Business Rules
• Architecture Testing for Layer and Module Boundaries
• End-to-End Testing
• Integration Testing
• Testing Shared Instructions
• Unit Testing with xUnit, Moq, and Bogus

Structures

• Feature Slices Module Structure
• Folder Structure Reference
• Minimal API Endpoint Organization
• Modular Solution Structure Template
• Simple Solution Structure Design

Development

Building and Testing

# Build the solution
dotnet build JSdotNet.Project.Guidelines.slnx

# Run all tests
dotnet test tests/JSdotNet.Project.Guidelines.McpServer.Tests/JSdotNet.Project.Guidelines.McpServer.Tests.csproj

# Run tests with coverage
dotnet test tests/JSdotNet.Project.Guidelines.McpServer.Tests/JSdotNet.Project.Guidelines.McpServer.Tests.csproj --collect:"XPlat Code Coverage" --results-directory ./coverage --settings coverlet.runsettings

# Generate coverage report
reportgenerator -reports:"coverage/**/coverage.cobertura.xml" -targetdir:"coverage/report" -reporttypes:"Html"

Code Coverage Requirements

• Core Library (JSdotNet.Project.Guidelines.Docs): ≥80% line coverage
• Tests: All tests must pass
• Coverage reports are automatically generated in CI/CD

CI/CD Workflows

Build and Publish Workflow

Workflow: .github/workflows/publish-nuget.yml

Triggers on push to main branch when files in src/ change.

Steps:

1. Versioning – GitVersion generates semantic version
2. Build – Compiles solution in Release configuration with version info
3. Test – Runs all unit tests with 80% coverage enforcement
4. Coverage Report – Generates coverage summary
5. Package – Creates NuGet package for the MCP Server
6. Publish – Pushes package to NuGet.org
7. Release – Creates GitHub release with version tag and artifacts

Semantic Versioning Strategy (GitHubFlow):

• Main branch: 1.0.0, 1.0.1, 1.0.2... (patch increments)
• Feature branches (feature/*): 1.1.0-alpha.1, 1.1.0-alpha.2... (minor with alpha pre-release)
• Release branches (release/*): 1.0.0-beta.1, 1.0.0-beta.2... (beta pre-release)

Configuration: GitVersion.yml at repository root.

NuGet Package

Published to NuGet.org:

• JSdotNet.Project.Guidelines.McpServer – MCP Server .NET global tool

Package features:

• .NET 10 global tool
• Automatic document discovery from filesystem or GitHub
• ModelContextProtocol SDK integration
• MIT license

Setup Requirements

To enable automated publishing, add the following GitHub secret:

• NUGET_API_KEY – NuGet.org API key with push permissions

Navigate to: Repository Settings → Secrets and variables → Actions → New repository secret

Local Version Testing

To check what version GitVersion would generate locally:

# Install GitVersion tool
dotnet tool install --global GitVersion.Tool

# Run in repository root
dotnet-gitversion

Notes

• All code and examples target .NET 10.
• The MCP Server uses the FileSystemDocumentCatalog for local development and GitHubDocumentCatalog for published scenarios.
• Coverage threshold is enforced at 80% for core library code.
• CI/CD pipeline only triggers on changes to src/ folder when pushed to main branch.