mcp: Instructions file for GitHub Copilot

Coding Instructions for GitHub Copilot

• Always use primary constructors in C#
• Always run dotnet build after making a change
• Always use System.Text.Json over Newtonsoft
• Always put new classes and interfaces in separate files
• Always make members static if they can be
• All generated code needs to be AOT safe
• Never expose RetryPolicyOptions through tool options or service contracts; use Azure SDK retry defaults
• Always review your own code for consistency, maintainability, and testability
• Always ask for clarifications if the request is ambiguous or lacks sufficient context.

Engineering System

• Use ./eng/scripts/Build-Local.ps1 -VerifyNpx to verify changes to powershell, c# project files and npm packages
• Don't run local builds to check pipeline YAML files (e.g., files in eng/pipelines/ with .yml extension)

Pull Request Guidelines

• Ensure all tests pass
• Follow the contribution guidelines
• Include appropriate documentation
• Include tests that cover your changes
• Update CHANGELOG.md with your changes
• Run .\eng\common\spelling\Invoke-Cspell.ps1
• Create the auto-generated PR body as normal, but copilot should add an additional section after all of its regular PR body content. The contents should be:

  ## Invoking Livetests
  
  Copilot submitted PRs are not trustworthy by default. Users with `write` access to the repo need to validate the contents of this PR before leaving a comment with the text `/azp run mcp - pullrequest - live`. This will trigger the necessary livetest workflows to complete required validation.
  

Transitioning Live Tests to Recorded Tests

• Always convert tool services to inject IHttpClientFactory into its clients and use IHttpClientFactory.CreateClient method to instantiate the HttpClient for usage in the tool classes' methods.
  • If IHttpClientFactory is already injected into the client, ensure that IHttpClientFactory.CreateClient is used to instantiate the HttpClient. If this is done, then no further action is needed.
• Always re-parent test classes parented by CommandTestsBase to RecordedCommandTestsBase. This will require minor fixture adjustments.
• In test classes extending RecordedCommandTestsBase, every test for a LocalRequired = true tool must call AssertLocalToolIsUnavailableInHttpMode(toolName) and return early when it returns true. This verifies that remote HTTP mode does not expose the local-only tool.
• Always generate a new assets.json file alongside the livetest csproj file if one does not exist. This file should contain the following content:

  {
    "AssetsRepo": "Azure/azure-sdk-assets",
    "AssetsRepoPrefixPath": "",
    "TagPrefix": "<TestCsProjFileNameWithoutExtension>", // e.g., "Azure.Mcp.Tools.KeyVault.Tests"
    "Tag": ""
  }
  

• Copilot should utilize the recorded test documentation in docs/recorded-tests.md for more details on how to convert and validate recorded tests.