From 718e4aedc4821b9e0a088f9134e90318d067f34e Mon Sep 17 00:00:00 2001 From: Copilot Date: Fri, 19 Jun 2026 15:08:28 -0700 Subject: [PATCH 1/4] Add onboarding doc and agent for Azure MCP Server Adds docs/Onboarding.md covering prerequisites, adding a new namespace, adding a new tool, and integrating an external MCP server. Adds a .github/agents/onboarding.agent.md Copilot agent that routes contributors to the guide, links it from CONTRIBUTING.md, and fixes a few pre-existing typos surfaced by cspell. Fixes #2512 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/onboarding.agent.md | 58 +++++ .vscode/cspell.json | 4 + CONTRIBUTING.md | 9 +- docs/Onboarding.md | 354 +++++++++++++++++++++++++++++ 4 files changed, 422 insertions(+), 3 deletions(-) create mode 100644 .github/agents/onboarding.agent.md create mode 100644 docs/Onboarding.md diff --git a/.github/agents/onboarding.agent.md b/.github/agents/onboarding.agent.md new file mode 100644 index 0000000000..a13665727b --- /dev/null +++ b/.github/agents/onboarding.agent.md @@ -0,0 +1,58 @@ +--- +description: Azure MCP Server onboarding assistant - guides new contributors through prerequisites, adding namespaces and tools, and integrating external MCP servers +--- + +# Azure MCP Server Onboarding Agent + +This agent helps **new contributors** get productive in the Azure MCP Server repository. It +orients you, then routes you to the right section of +[`docs/Onboarding.md`](../../docs/Onboarding.md) and the deeper authoritative docs. + +## What This Agent Helps With + +Ask about any of these and the agent will point you to the relevant steps and files: + +- **Prerequisites & setup** — required tooling (.NET, Node.js, PowerShell, Azure CLI/PowerShell, + Bicep), the NuGet feed, and the local build/test quick start. +- **Adding a new namespace (toolset)** — scaffolding `tools/Azure.Mcp.Tools.{Toolset}`, + implementing `IAreaSetup`, registering in `Program.cs` `RegisterAreas()`, solution + AOT steps. +- **Adding a new tool to an existing namespace** — the required files, naming conventions, + option/JSON/AOT rules, and how to validate with unit and recorded live tests. +- **Integrating an external MCP server** — editing + `servers/Azure.Mcp.Server/src/Resources/registry.json`, choosing HTTP/SSE vs stdio transport, + and the authentication considerations. +- **Opening a pull request** — the full PR checklist (format, build, spelling, changelog, + recorded tests, docs). + +## How To Route + +Match the contributor's intent to the matching section of +[`docs/Onboarding.md`](../../docs/Onboarding.md): + +| Intent | Section | Authoritative deep dive | +| --- | --- | --- | +| Set up my machine / build the repo | [Prerequisites](../../docs/Onboarding.md#1-prerequisites), [Quick start](../../docs/Onboarding.md#2-quick-start) | [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | +| Create a brand-new namespace | [Add a new namespace](../../docs/Onboarding.md#3-add-a-new-namespace-toolset) | [`new-command.md`](../../servers/Azure.Mcp.Server/docs/new-command.md) | +| Add one command/tool | [Add a new tool](../../docs/Onboarding.md#4-add-a-new-tool-to-an-existing-namespace) | [`new-command.md`](../../servers/Azure.Mcp.Server/docs/new-command.md) | +| Proxy an external MCP server | [Integrate an external MCP server](../../docs/Onboarding.md#5-integrate-an-external-mcp-server) | [`CONTRIBUTING.md`](../../CONTRIBUTING.md#configuring-external-mcp-servers) | +| Get ready to submit | [PR checklist](../../docs/Onboarding.md#6-pull-request-checklist) | [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | + +## Key Conventions To Reinforce + +When helping with code changes, remind contributors of the repository standards: + +- Use **primary constructors** and **System.Text.Json**; make command classes **sealed**. +- Name commands `{Resource}{Operation}Command` (for example `AccountGetCommand`). +- Use `subscription` / `resourceGroup` (never `subscriptionId` / `resourceGroupName`); singular + resource nouns. +- Register response models in the toolset's `JsonSerializerContext` for **AOT safety**. +- Register new tools in `{Toolset}Setup.cs` and new toolsets **alphabetically** in + `Program.cs` `RegisterAreas()`. +- Azure resource commands require **recorded live tests** — see + [`recorded-tests.md`](../../docs/recorded-tests.md). +- **One tool per pull request** where possible. + +## Source Control + +Contributors work on a branch in **their fork** (for example `RickWinter/mcp`) and open the PR +against `microsoft/mcp:main`. Encourage small, focused PRs. diff --git a/.vscode/cspell.json b/.vscode/cspell.json index f5ce99be80..25ac37cbd8 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -373,6 +373,7 @@ "codesign", "codespace", "cognitiveservices", + "configfile", "containerapp", "containerapps", "contentazurefileconnectionstring", @@ -538,6 +539,7 @@ "ragzrs", "rainfly", "redisearch", + "remotemcp", "requesturl", "resourcegroup", "resourcegroups", @@ -557,6 +559,7 @@ "skillset", "skillsets", "skiptoken", + "slnx", "southafricanorth", "southcentralus", "southeastasia", @@ -595,6 +598,7 @@ "ukwest", "uncompress", "unhex", + "uniqueprefix", "upns", "usersession", "vectorizable", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e39c728cb9..b59a20afd4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,9 @@ After cloning and building the repo, check out the [GitHub project](https://gith >[!IMPORTANT] If you are contributing significant changes, or if the issue is already assigned to a specific milestone, please discuss with the assignee of the issue first before starting to work on the issue. +>[!TIP] +> New to the project? Start with the [Onboarding Guide](docs/Onboarding.md) for a guided walkthrough of prerequisites, adding a new namespace or tool, and integrating an external MCP server. You can also invoke the `@onboarding` agent in GitHub Copilot Chat. + ## Table of Contents - [Contributing to Azure MCP](#contributing-to-azure-mcp) @@ -240,7 +243,7 @@ Requirements: To ensure the product code and unit tests can be cancelled quickly, contributors are required to write async methods (any returning `Task`, `ValueTask`, generic variants of those, etc.) to accept and invoke async methods with a `System.Threading.CancellationToken` parameter. The latter is enforced with the [CA2016 analyzer](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2016). -Mocks created with `NSubstitute.Substitue.For()` and have [methods set up](https://nsubstitute.github.io/help/set-return-value/#for-methods) should be passed `NSubstitute.Arg.Any()` for required `System.Threading.CancellationToken` parameters. The same should be used when [checking for received calls on a mocked object](https://nsubstitute.github.io/help/received-calls/index.html). If the product code is expected to do something interesting with a supplied `System.Threading.CancellationToken` parameter, such as linking with other `System.Threading.CancellationToken`s with [`System.Threading.CancellationTokenSource.CreateLinkedTokenSource`](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtokensource.createlinkedtokensource), then consider testing for that behavior. +Mocks created with `NSubstitute.Substitute.For()` and have [methods set up](https://nsubstitute.github.io/help/set-return-value/#for-methods) should be passed `NSubstitute.Arg.Any()` for required `System.Threading.CancellationToken` parameters. The same should be used when [checking for received calls on a mocked object](https://nsubstitute.github.io/help/received-calls/index.html). If the product code is expected to do something interesting with a supplied `System.Threading.CancellationToken` parameter, such as linking with other `System.Threading.CancellationToken`s with [`System.Threading.CancellationTokenSource.CreateLinkedTokenSource`](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtokensource.createlinkedtokensource), then consider testing for that behavior. Real product code under unit testing must be passed `Xunit.TestContext.Current.CancellationToken` when async methods are invoked. This is to ensure the tests can end to avoid possible issues with the parent process waiting indefinitely for the test runner executable to exit. @@ -700,7 +703,7 @@ The Azure MCP Server implements the [Model Context Protocol specification](https ### Package README -A single package README.md could be used to generate context specific content for different package types (npm, nuget, vsix) using html comment annotations to mark sections for removal or insertion whem processed with script at `.\eng\scripts\Process-PackageReadMe.ps1` +A single package README.md could be used to generate context specific content for different package types (npm, nuget, vsix) using html comment annotations to mark sections for removal or insertion when processed with script at `.\eng\scripts\Process-PackageReadMe.ps1` Supported comment annotations: @@ -780,7 +783,7 @@ The registry structure follows this format: - Use the `url` property to specify the endpoint - Supports HTTP-based communication with automatic transport mode detection - Best for web-based MCP servers and remote endpoints -- Use `title` as the dislay name for the namespace tool (optional) +- Use `title` as the display name for the namespace tool (optional) - Use `description` as the description of the namespace tool for the MCP server - Use `toolPrefix` to assign unique prefix to tools of the MCP server - If the MCP server requires authentication, use `oauthScopes` to specify the Entra client registration representing the MCP server diff --git a/docs/Onboarding.md b/docs/Onboarding.md new file mode 100644 index 0000000000..7071f5b466 --- /dev/null +++ b/docs/Onboarding.md @@ -0,0 +1,354 @@ + + + +# Onboarding Guide: Azure MCP Server + +This guide is the entry point for new contributors to the **Azure MCP Server**. It walks +you through the prerequisites and the most common onboarding tasks: + +1. [Prerequisites](#1-prerequisites) +2. [Quick start](#2-quick-start) +3. [Add a new namespace (toolset) to Azure MCP Server](#3-add-a-new-namespace-toolset) +4. [Add a new tool to an existing namespace](#4-add-a-new-tool-to-an-existing-namespace) +5. [Integrate an external MCP server](#5-integrate-an-external-mcp-server) +6. [Pull request checklist](#6-pull-request-checklist) + +> [!TIP] +> Prefer interactive help? Invoke the `@onboarding` agent (`.github/agents/onboarding.agent.md`) +> in GitHub Copilot Chat. It routes you to the right section of this guide and the deeper docs. + +This document links to the authoritative deep-dive docs rather than duplicating them. The +two most important references are: + +- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — full contribution workflow and standards +- [`servers/Azure.Mcp.Server/docs/new-command.md`](../servers/Azure.Mcp.Server/docs/new-command.md) — the authoritative guide for implementing commands + +--- + +## 1. Prerequisites + +> [!IMPORTANT] +> If you are a **Microsoft employee**, also review the +> [Azure Internal Onboarding Documentation](https://aka.ms/azmcp/intake) for setup. + +Install the following tooling before you build: + +| Tool | Notes | +| --- | --- | +| [VS Code](https://code.visualstudio.com/download) or [Insiders](https://code.visualstudio.com/insiders) | Recommended editor. Insiders is required for some agent-mode features. | +| [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) + [Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) | Used heavily for command scaffolding. | +| [Node.js](https://nodejs.org/en/download) 20 or later | Ensure `node` and `npm` are on your `PATH`. | +| [PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) 7.0 or later | Required for build and test scripts in `eng/scripts`. | +| .NET SDK | Version is pinned in [`global.json`](../global.json). | + +For **live tests** against real Azure resources you also need: + +| Tool | Notes | +| --- | --- | +| [Azure PowerShell](https://learn.microsoft.com/powershell/azure/install-azure-powershell) | `Connect-AzAccount` for live test deployments. | +| [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) | `az login` for authentication. | +| [Azure Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install) | Builds `test-resources.bicep` templates. | + +### NuGet feed + +This repo uses a single Azure DevOps package feed (configured in +[`nuget.config`](../nuget.config)) with an upstream to nuget.org. **External contributors** +cannot authenticate as a feed collaborator; if you add a package that is not already cached, +temporarily add nuget.org as an extra source locally and revert before submitting your PR. +See [CONTRIBUTING.md → Central NuGet Feed](../CONTRIBUTING.md#central-nuget-feed) for details. + +--- + +## 2. Quick start + +```powershell +# 1. Fork microsoft/mcp, then clone your fork +git clone https://github.com//mcp.git +cd mcp + +# 2. Build the solution +dotnet build + +# 3. Verify everything works (build + npx package smoke test) +./eng/scripts/Build-Local.ps1 -UsePaths -VerifyNpx + +# 4. Run unit tests for a specific toolset +./eng/scripts/Test-Code.ps1 -Paths Storage +``` + +### Development workflow + +1. **Fork** `microsoft/mcp` to your account (for example `RickWinter/mcp`). +2. **Create a feature branch** off `main`. +3. **Make your changes** (and write/update tests). +4. **Test locally** with the scripts above. +5. **Open a pull request** from `:` into `microsoft/mcp:main`. + +> [!TIP] +> **Submit one tool per pull request.** Smaller PRs review faster and iterate more easily. +> See [CONTRIBUTING.md → Adding a New Command](../CONTRIBUTING.md#adding-a-new-command). + +### Run the server locally + +Point your `mcp.json` at the freshly built binary: + +```json +{ + "servers": { + "azure-mcp-server": { + "type": "stdio", + "command": "/servers/Azure.Mcp.Server/bin/Debug/net10.0/azmcp.exe", + "args": ["server", "start"] + } + } +} +``` + +Useful `server start` flags: + +- `--namespace storage --namespace keyvault` — expose only specific namespaces. +- `--mode namespace` — group each namespace's tools behind a single proxy tool (helps with + VS Code's tool-count limit). +- `--mode single` — expose one `azure` tool that routes internally. + +--- + +## 3. Add a new namespace (toolset) + +A **namespace** is a top-level command group (for example `storage`, `keyvault`, `sql`), +implemented as a **toolset** project under `tools/Azure.Mcp.Tools.{Toolset}`. Each toolset +provides an `IAreaSetup` implementation that registers its services and commands. + +> The authoritative, end-to-end guide is +> [`new-command.md`](../servers/Azure.Mcp.Server/docs/new-command.md). The steps below are the +> onboarding-level summary of what it takes to stand up a brand-new namespace. + +### Steps + +1. **Create the toolset project** following the standard layout: + + ```text + tools/Azure.Mcp.Tools.{Toolset}/ + ├── src/ + │ ├── Commands/{Resource}/ # Command implementations + │ ├── Services/ # Service interface + implementation + │ ├── Options/ # Option definitions and per-command options + │ ├── Models/ # DTOs / response models + │ ├── {Toolset}JsonContext.cs # AOT-safe JSON serialization context + │ └── {Toolset}Setup.cs # IAreaSetup implementation + └── tests/ + ├── Azure.Mcp.Tools.{Toolset}.Tests/ # Unit + integration tests + ├── test-resources.bicep # Live test infra (Azure services only) + └── test-resources-post.ps1 # Post-deployment script (Azure services only) + ``` + +2. **Add required packages** to [`Directory.Packages.props`](../Directory.Packages.props) first + (central package management), then reference them from the toolset `.csproj`. + +3. **Implement `{Toolset}Setup.cs`** as an `IAreaSetup`. It must expose `Name` (the namespace, + lowercase, no dashes), `Title`, register services in `ConfigureServices`, and build the + command tree in `RegisterCommands`. Use + [`StorageSetup.cs`](../tools/Azure.Mcp.Tools.Storage/src/StorageSetup.cs) as the reference: + + ```csharp + public class WidgetSetup : IAreaSetup + { + public string Name => "widget"; + public string Title => "Manage Azure Widgets"; + + public void ConfigureServices(IServiceCollection services) + { + services.AddSingleton(); + services.AddSingleton(); + } + + public CommandGroup RegisterCommands(IServiceProvider serviceProvider) + { + var widget = new CommandGroup(Name, "Widget operations - ...", Title); + widget.AddCommand(serviceProvider); + return widget; + } + } + ``` + +4. **Register the toolset** in + [`Program.cs`](../servers/Azure.Mcp.Server/src/Program.cs) `RegisterAreas()`, keeping the + list **alphabetically sorted** (excluding the fixed `#if !BUILD_NATIVE` block): + + ```csharp + new Azure.Mcp.Tools.Widget.WidgetSetup(), + ``` + +5. **Add the new projects** to the solution files + [`Microsoft.Mcp.slnx`](../Microsoft.Mcp.slnx) and `Azure.Mcp.Server.slnx`. + +6. **Implement at least one command** in the namespace — follow + [Add a new tool](#4-add-a-new-tool-to-an-existing-namespace). + +7. **Verify AOT compatibility** (required for new toolsets): + + ```powershell + ./eng/scripts/Build-Local.ps1 -BuildNative + ``` + + If AOT fails, follow [`aot-compatibility.md`](aot-compatibility.md) to either fix it or + exclude the toolset from the native build — do **not** edit the fixed exclusion block. + +8. **Add a CODEOWNERS entry** and update docs (see the [PR checklist](#6-pull-request-checklist)). + +--- + +## 4. Add a new tool to an existing namespace + +A **tool** is a single command, named `azmcp ` (for example +`azmcp storage container get`). Adding one to an existing toolset is the most common +contribution. + +> [!TIP] +> The fastest path is Copilot Chat in Agent mode: +> `"create [namespace] [resource] [operation] command using #new-command.md as a reference"`. +> Always review the generated code against [`new-command.md`](../servers/Azure.Mcp.Server/docs/new-command.md). + +### Required files + +For each new command (see +[new-command.md → Required Files](../servers/Azure.Mcp.Server/docs/new-command.md#required-files)): + +1. Option definitions: `src/Options/{Toolset}OptionDefinitions.cs` +2. Per-command options: `src/Options/{Resource}/{Operation}Options.cs` +3. Command class: `src/Commands/{Resource}/{Resource}{Operation}Command.cs` +4. Service interface + implementation: `src/Services/I{Service}Service.cs`, `src/Services/{Service}Service.cs` +5. JSON context entry: register response models in `{Toolset}JsonContext.cs` (AOT requirement) +6. Unit tests: `tests/.../{Resource}/{Resource}{Operation}CommandTests.cs` +7. Live tests: `tests/.../{Toolset}CommandTests.cs` (for Azure resource commands) +8. Command registration: add to `RegisterCommands()` in `{Toolset}Setup.cs` + +### Conventions + +- **Class/command naming:** `{Resource}{Operation}Command` (for example `AccountGetCommand`), + never `GetAccountCommand`. Commands are `sealed` unless designed for inheritance. +- **Use primary constructors** and inject `ILogger` + the service interface. +- **Parameter naming:** use `subscription` (not `subscriptionId`), `resourceGroup` (not + `resourceGroupName`), and singular resource nouns. +- **Use `OptionDefinitions` constants**, not hardcoded option strings. Use `.AsRequired()` / + `.AsOptional()` and bind with `parseResult.GetValueOrDefault(Option)`. +- **Always call `HandleException(context, ex)`** in catch blocks; never log `{@Options}`. +- **System.Text.Json only** (never Newtonsoft). All response models must be in the toolset's + `JsonSerializerContext` for AOT safety. + +### Validate your tool + +```powershell +# Build just your toolset +dotnet build tools/Azure.Mcp.Tools.{Toolset}/src + +# Run unit tests for your command +dotnet test --filter "FullyQualifiedName~{Resource}{Operation}CommandTests" + +# Format and verify +dotnet format --include="tools/Azure.Mcp.Tools.{Toolset}/**/*.cs" +./eng/scripts/Build-Local.ps1 -UsePaths -VerifyNpx +``` + +Azure resource commands additionally **require recorded live tests**. See +[`recorded-tests.md`](recorded-tests.md) for the record/playback workflow and +[CONTRIBUTING.md → Live Tests](../CONTRIBUTING.md#live-tests) for deploying test resources. + +--- + +## 5. Integrate an external MCP server + +The Azure MCP Server can act as a **proxy** that aggregates tools from external MCP servers +into a single interface. External servers are declared in the embedded registry file +[`servers/Azure.Mcp.Server/src/Resources/registry.json`](../servers/Azure.Mcp.Server/src/Resources/registry.json). + +### Steps + +1. **Edit `registry.json`** and add an entry under `servers`, keyed by a unique identifier. +2. **Choose a transport**: + - **HTTP / SSE** — provide a `url`. Optionally add `title`, `toolPrefix` (unique prefix for + the server's tools), and `oauthScopes` if the endpoint requires Entra authentication. + - **stdio** — set `"type": "stdio"` with a `command`, plus optional `args` and `env`. +3. **Include a descriptive `description`** — it is surfaced to agents as the namespace tool + description, so make it clear when the tool should be used. +4. **Rebuild** the project to embed the updated registry. + +```jsonc +{ + "servers": { + "documentation": { + "url": "https://learn.microsoft.com/api/mcp", + "title": "Microsoft Documentation Search", + "description": "Search official Microsoft/Azure documentation..." + }, + "my-stdio-server": { + "type": "stdio", + "command": "path/to/executable", + "args": ["arg1", "arg2"], + "env": { "ENV_VAR": "value" }, + "description": "An external MCP server using stdio transport" + }, + "my-http-server": { + "url": "", + "title": "", + "description": "An external MCP server that offers X, Y, Z", + "toolPrefix": "uniqueprefix_", + "oauthScopes": ["/"] + } + } +} +``` + +### Discovery and filtering + +External servers are discovered automatically at startup and respect the same namespace +filters as built-in commands: + +```bash +# Include only specific external servers +azmcp server start --namespace documentation --namespace my-http-server + +# Group external server tools behind a namespace proxy tool +azmcp server start --mode namespace +``` + +### Authentication notes + +For Entra-protected HTTP endpoints, the external server needs an Entra app registration that +accepts authorization/token requests from common clients (Azure CLI, VS Code). Azure MCP can +pass user-principal tokens (stdio), service-principal tokens (stdio), or On-Behalf-Of tokens +(remote HTTP mode). **Test the app registration** against all supported user types (personal, +organizational, member, guest) and document any unsupported scenarios in the server's entry in +[README.md](../README.md). Full details: +[CONTRIBUTING.md → Configuring External MCP Servers](../CONTRIBUTING.md#configuring-external-mcp-servers). + +--- + +## 6. Pull request checklist + +Before opening your PR from your fork into `microsoft/mcp:main`: + +- [ ] **Format & build:** `dotnet format` and `dotnet build` are clean. +- [ ] **Unit tests** pass and cover your changes. +- [ ] **Live tests** included and **recorded** for Azure resource commands + ([`recorded-tests.md`](recorded-tests.md)). +- [ ] **AOT check** for new toolsets: `./eng/scripts/Build-Local.ps1 -BuildNative`. +- [ ] **Spelling:** `./eng/common/spelling/Invoke-Cspell.ps1` (add new terms to `.vscode/cspell.json`). +- [ ] **Docs updated:** [`azmcp-commands.md`](../servers/Azure.Mcp.Server/docs/azmcp-commands.md) + and test prompts in [`e2eTestPrompts.md`](../servers/Azure.Mcp.Server/docs/e2eTestPrompts.md). +- [ ] **Changelog entry** added for user-facing changes + ([`changelog-entries.md`](changelog-entries.md)). +- [ ] **CODEOWNERS** updated for a new toolset. +- [ ] **One tool per PR** where possible. + +--- + +## More resources + +- [Command reference (`azmcp-commands.md`)](../servers/Azure.Mcp.Server/docs/azmcp-commands.md) +- [Implementing a new command (`new-command.md`)](../servers/Azure.Mcp.Server/docs/new-command.md) +- [Recorded tests guide (`recorded-tests.md`)](recorded-tests.md) +- [AOT compatibility (`aot-compatibility.md`)](aot-compatibility.md) +- [Authentication (`Authentication.md`)](Authentication.md) +- [Changelog entries (`changelog-entries.md`)](changelog-entries.md) +- [Contributing guide (`CONTRIBUTING.md`)](../CONTRIBUTING.md) From ce28c50045ee9fef3342f7d0748bdd8f67dfd837 Mon Sep 17 00:00:00 2001 From: Copilot Date: Fri, 19 Jun 2026 16:31:07 -0700 Subject: [PATCH 2/4] Address PR review: use full GitHub URLs and trim agent - Convert relative file links to full https://github.com/microsoft/mcp/blob/main/ URLs per repo convention (so docs sites resolve them). - Make the onboarding agent reference and Azure.Mcp.Server.slnx clickable links. - Remove implementation-conventions section from the onboarding agent (belongs in AGENTS.md/review agent). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/onboarding.agent.md | 30 ++++---------- CONTRIBUTING.md | 2 +- docs/Onboarding.md | 63 +++++++++++++++--------------- 3 files changed, 41 insertions(+), 54 deletions(-) diff --git a/.github/agents/onboarding.agent.md b/.github/agents/onboarding.agent.md index a13665727b..76f29c6439 100644 --- a/.github/agents/onboarding.agent.md +++ b/.github/agents/onboarding.agent.md @@ -6,7 +6,8 @@ description: Azure MCP Server onboarding assistant - guides new contributors thr This agent helps **new contributors** get productive in the Azure MCP Server repository. It orients you, then routes you to the right section of -[`docs/Onboarding.md`](../../docs/Onboarding.md) and the deeper authoritative docs. +[Onboarding.md](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md) and the deeper +authoritative docs. ## What This Agent Helps With @@ -27,30 +28,15 @@ Ask about any of these and the agent will point you to the relevant steps and fi ## How To Route Match the contributor's intent to the matching section of -[`docs/Onboarding.md`](../../docs/Onboarding.md): +[Onboarding.md](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md): | Intent | Section | Authoritative deep dive | | --- | --- | --- | -| Set up my machine / build the repo | [Prerequisites](../../docs/Onboarding.md#1-prerequisites), [Quick start](../../docs/Onboarding.md#2-quick-start) | [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | -| Create a brand-new namespace | [Add a new namespace](../../docs/Onboarding.md#3-add-a-new-namespace-toolset) | [`new-command.md`](../../servers/Azure.Mcp.Server/docs/new-command.md) | -| Add one command/tool | [Add a new tool](../../docs/Onboarding.md#4-add-a-new-tool-to-an-existing-namespace) | [`new-command.md`](../../servers/Azure.Mcp.Server/docs/new-command.md) | -| Proxy an external MCP server | [Integrate an external MCP server](../../docs/Onboarding.md#5-integrate-an-external-mcp-server) | [`CONTRIBUTING.md`](../../CONTRIBUTING.md#configuring-external-mcp-servers) | -| Get ready to submit | [PR checklist](../../docs/Onboarding.md#6-pull-request-checklist) | [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | - -## Key Conventions To Reinforce - -When helping with code changes, remind contributors of the repository standards: - -- Use **primary constructors** and **System.Text.Json**; make command classes **sealed**. -- Name commands `{Resource}{Operation}Command` (for example `AccountGetCommand`). -- Use `subscription` / `resourceGroup` (never `subscriptionId` / `resourceGroupName`); singular - resource nouns. -- Register response models in the toolset's `JsonSerializerContext` for **AOT safety**. -- Register new tools in `{Toolset}Setup.cs` and new toolsets **alphabetically** in - `Program.cs` `RegisterAreas()`. -- Azure resource commands require **recorded live tests** — see - [`recorded-tests.md`](../../docs/recorded-tests.md). -- **One tool per pull request** where possible. +| Set up my machine / build the repo | [Prerequisites](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#1-prerequisites), [Quick start](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#2-quick-start) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) | +| Create a brand-new namespace | [Add a new namespace](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#3-add-a-new-namespace-toolset) | [new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) | +| Add one command/tool | [Add a new tool](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#4-add-a-new-tool-to-an-existing-namespace) | [new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) | +| Proxy an external MCP server | [Integrate an external MCP server](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#5-integrate-an-external-mcp-server) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md#configuring-external-mcp-servers) | +| Get ready to submit | [PR checklist](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#6-pull-request-checklist) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) | ## Source Control diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b59a20afd4..8bc9135e3c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ After cloning and building the repo, check out the [GitHub project](https://gith If you are contributing significant changes, or if the issue is already assigned to a specific milestone, please discuss with the assignee of the issue first before starting to work on the issue. >[!TIP] -> New to the project? Start with the [Onboarding Guide](docs/Onboarding.md) for a guided walkthrough of prerequisites, adding a new namespace or tool, and integrating an external MCP server. You can also invoke the `@onboarding` agent in GitHub Copilot Chat. +> New to the project? Start with the [Onboarding Guide](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md) for a guided walkthrough of prerequisites, adding a new namespace or tool, and integrating an external MCP server. You can also invoke the `@onboarding` agent in GitHub Copilot Chat. ## Table of Contents diff --git a/docs/Onboarding.md b/docs/Onboarding.md index 7071f5b466..c915a9b9ec 100644 --- a/docs/Onboarding.md +++ b/docs/Onboarding.md @@ -14,14 +14,14 @@ you through the prerequisites and the most common onboarding tasks: 6. [Pull request checklist](#6-pull-request-checklist) > [!TIP] -> Prefer interactive help? Invoke the `@onboarding` agent (`.github/agents/onboarding.agent.md`) +> Prefer interactive help? Invoke the [`@onboarding` agent](https://github.com/microsoft/mcp/blob/main/.github/agents/onboarding.agent.md) > in GitHub Copilot Chat. It routes you to the right section of this guide and the deeper docs. This document links to the authoritative deep-dive docs rather than duplicating them. The two most important references are: -- [`CONTRIBUTING.md`](../CONTRIBUTING.md) — full contribution workflow and standards -- [`servers/Azure.Mcp.Server/docs/new-command.md`](../servers/Azure.Mcp.Server/docs/new-command.md) — the authoritative guide for implementing commands +- [`CONTRIBUTING.md`](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) — full contribution workflow and standards +- [`servers/Azure.Mcp.Server/docs/new-command.md`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) — the authoritative guide for implementing commands --- @@ -39,7 +39,7 @@ Install the following tooling before you build: | [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) + [Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) | Used heavily for command scaffolding. | | [Node.js](https://nodejs.org/en/download) 20 or later | Ensure `node` and `npm` are on your `PATH`. | | [PowerShell](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) 7.0 or later | Required for build and test scripts in `eng/scripts`. | -| .NET SDK | Version is pinned in [`global.json`](../global.json). | +| .NET SDK | Version is pinned in [`global.json`](https://github.com/microsoft/mcp/blob/main/global.json). | For **live tests** against real Azure resources you also need: @@ -52,10 +52,10 @@ For **live tests** against real Azure resources you also need: ### NuGet feed This repo uses a single Azure DevOps package feed (configured in -[`nuget.config`](../nuget.config)) with an upstream to nuget.org. **External contributors** +[`nuget.config`](https://github.com/microsoft/mcp/blob/main/nuget.config)) with an upstream to nuget.org. **External contributors** cannot authenticate as a feed collaborator; if you add a package that is not already cached, temporarily add nuget.org as an extra source locally and revert before submitting your PR. -See [CONTRIBUTING.md → Central NuGet Feed](../CONTRIBUTING.md#central-nuget-feed) for details. +See [CONTRIBUTING.md → Central NuGet Feed](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md#central-nuget-feed) for details. --- @@ -86,7 +86,7 @@ dotnet build > [!TIP] > **Submit one tool per pull request.** Smaller PRs review faster and iterate more easily. -> See [CONTRIBUTING.md → Adding a New Command](../CONTRIBUTING.md#adding-a-new-command). +> See [CONTRIBUTING.md → Adding a New Command](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md#adding-a-new-command). ### Run the server locally @@ -120,7 +120,7 @@ implemented as a **toolset** project under `tools/Azure.Mcp.Tools.{Toolset}`. Ea provides an `IAreaSetup` implementation that registers its services and commands. > The authoritative, end-to-end guide is -> [`new-command.md`](../servers/Azure.Mcp.Server/docs/new-command.md). The steps below are the +> [`new-command.md`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md). The steps below are the > onboarding-level summary of what it takes to stand up a brand-new namespace. ### Steps @@ -142,13 +142,13 @@ provides an `IAreaSetup` implementation that registers its services and commands └── test-resources-post.ps1 # Post-deployment script (Azure services only) ``` -2. **Add required packages** to [`Directory.Packages.props`](../Directory.Packages.props) first +2. **Add required packages** to [`Directory.Packages.props`](https://github.com/microsoft/mcp/blob/main/Directory.Packages.props) first (central package management), then reference them from the toolset `.csproj`. 3. **Implement `{Toolset}Setup.cs`** as an `IAreaSetup`. It must expose `Name` (the namespace, lowercase, no dashes), `Title`, register services in `ConfigureServices`, and build the command tree in `RegisterCommands`. Use - [`StorageSetup.cs`](../tools/Azure.Mcp.Tools.Storage/src/StorageSetup.cs) as the reference: + [`StorageSetup.cs`](https://github.com/microsoft/mcp/blob/main/tools/Azure.Mcp.Tools.Storage/src/StorageSetup.cs) as the reference: ```csharp public class WidgetSetup : IAreaSetup @@ -172,7 +172,7 @@ provides an `IAreaSetup` implementation that registers its services and commands ``` 4. **Register the toolset** in - [`Program.cs`](../servers/Azure.Mcp.Server/src/Program.cs) `RegisterAreas()`, keeping the + [`Program.cs`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/src/Program.cs) `RegisterAreas()`, keeping the list **alphabetically sorted** (excluding the fixed `#if !BUILD_NATIVE` block): ```csharp @@ -180,7 +180,8 @@ provides an `IAreaSetup` implementation that registers its services and commands ``` 5. **Add the new projects** to the solution files - [`Microsoft.Mcp.slnx`](../Microsoft.Mcp.slnx) and `Azure.Mcp.Server.slnx`. + [`Microsoft.Mcp.slnx`](https://github.com/microsoft/mcp/blob/main/Microsoft.Mcp.slnx) and + [`Azure.Mcp.Server.slnx`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/Azure.Mcp.Server.slnx). 6. **Implement at least one command** in the namespace — follow [Add a new tool](#4-add-a-new-tool-to-an-existing-namespace). @@ -191,7 +192,7 @@ provides an `IAreaSetup` implementation that registers its services and commands ./eng/scripts/Build-Local.ps1 -BuildNative ``` - If AOT fails, follow [`aot-compatibility.md`](aot-compatibility.md) to either fix it or + If AOT fails, follow [`aot-compatibility.md`](https://github.com/microsoft/mcp/blob/main/docs/aot-compatibility.md) to either fix it or exclude the toolset from the native build — do **not** edit the fixed exclusion block. 8. **Add a CODEOWNERS entry** and update docs (see the [PR checklist](#6-pull-request-checklist)). @@ -207,12 +208,12 @@ contribution. > [!TIP] > The fastest path is Copilot Chat in Agent mode: > `"create [namespace] [resource] [operation] command using #new-command.md as a reference"`. -> Always review the generated code against [`new-command.md`](../servers/Azure.Mcp.Server/docs/new-command.md). +> Always review the generated code against [`new-command.md`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md). ### Required files For each new command (see -[new-command.md → Required Files](../servers/Azure.Mcp.Server/docs/new-command.md#required-files)): +[new-command.md → Required Files](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md#required-files)): 1. Option definitions: `src/Options/{Toolset}OptionDefinitions.cs` 2. Per-command options: `src/Options/{Resource}/{Operation}Options.cs` @@ -251,8 +252,8 @@ dotnet format --include="tools/Azure.Mcp.Tools.{Toolset}/**/*.cs" ``` Azure resource commands additionally **require recorded live tests**. See -[`recorded-tests.md`](recorded-tests.md) for the record/playback workflow and -[CONTRIBUTING.md → Live Tests](../CONTRIBUTING.md#live-tests) for deploying test resources. +[`recorded-tests.md`](https://github.com/microsoft/mcp/blob/main/docs/recorded-tests.md) for the record/playback workflow and +[CONTRIBUTING.md → Live Tests](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md#live-tests) for deploying test resources. --- @@ -260,7 +261,7 @@ Azure resource commands additionally **require recorded live tests**. See The Azure MCP Server can act as a **proxy** that aggregates tools from external MCP servers into a single interface. External servers are declared in the embedded registry file -[`servers/Azure.Mcp.Server/src/Resources/registry.json`](../servers/Azure.Mcp.Server/src/Resources/registry.json). +[`servers/Azure.Mcp.Server/src/Resources/registry.json`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/src/Resources/registry.json). ### Steps @@ -319,8 +320,8 @@ accepts authorization/token requests from common clients (Azure CLI, VS Code). A pass user-principal tokens (stdio), service-principal tokens (stdio), or On-Behalf-Of tokens (remote HTTP mode). **Test the app registration** against all supported user types (personal, organizational, member, guest) and document any unsupported scenarios in the server's entry in -[README.md](../README.md). Full details: -[CONTRIBUTING.md → Configuring External MCP Servers](../CONTRIBUTING.md#configuring-external-mcp-servers). +[README.md](https://github.com/microsoft/mcp/blob/main/README.md). Full details: +[CONTRIBUTING.md → Configuring External MCP Servers](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md#configuring-external-mcp-servers). --- @@ -331,13 +332,13 @@ Before opening your PR from your fork into `microsoft/mcp:main`: - [ ] **Format & build:** `dotnet format` and `dotnet build` are clean. - [ ] **Unit tests** pass and cover your changes. - [ ] **Live tests** included and **recorded** for Azure resource commands - ([`recorded-tests.md`](recorded-tests.md)). + ([`recorded-tests.md`](https://github.com/microsoft/mcp/blob/main/docs/recorded-tests.md)). - [ ] **AOT check** for new toolsets: `./eng/scripts/Build-Local.ps1 -BuildNative`. - [ ] **Spelling:** `./eng/common/spelling/Invoke-Cspell.ps1` (add new terms to `.vscode/cspell.json`). -- [ ] **Docs updated:** [`azmcp-commands.md`](../servers/Azure.Mcp.Server/docs/azmcp-commands.md) - and test prompts in [`e2eTestPrompts.md`](../servers/Azure.Mcp.Server/docs/e2eTestPrompts.md). +- [ ] **Docs updated:** [`azmcp-commands.md`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/azmcp-commands.md) + and test prompts in [`e2eTestPrompts.md`](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/e2eTestPrompts.md). - [ ] **Changelog entry** added for user-facing changes - ([`changelog-entries.md`](changelog-entries.md)). + ([`changelog-entries.md`](https://github.com/microsoft/mcp/blob/main/docs/changelog-entries.md)). - [ ] **CODEOWNERS** updated for a new toolset. - [ ] **One tool per PR** where possible. @@ -345,10 +346,10 @@ Before opening your PR from your fork into `microsoft/mcp:main`: ## More resources -- [Command reference (`azmcp-commands.md`)](../servers/Azure.Mcp.Server/docs/azmcp-commands.md) -- [Implementing a new command (`new-command.md`)](../servers/Azure.Mcp.Server/docs/new-command.md) -- [Recorded tests guide (`recorded-tests.md`)](recorded-tests.md) -- [AOT compatibility (`aot-compatibility.md`)](aot-compatibility.md) -- [Authentication (`Authentication.md`)](Authentication.md) -- [Changelog entries (`changelog-entries.md`)](changelog-entries.md) -- [Contributing guide (`CONTRIBUTING.md`)](../CONTRIBUTING.md) +- [Command reference (`azmcp-commands.md`)](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/azmcp-commands.md) +- [Implementing a new command (`new-command.md`)](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) +- [Recorded tests guide (`recorded-tests.md`)](https://github.com/microsoft/mcp/blob/main/docs/recorded-tests.md) +- [AOT compatibility (`aot-compatibility.md`)](https://github.com/microsoft/mcp/blob/main/docs/aot-compatibility.md) +- [Authentication (`Authentication.md`)](https://github.com/microsoft/mcp/blob/main/docs/Authentication.md) +- [Changelog entries (`changelog-entries.md`)](https://github.com/microsoft/mcp/blob/main/docs/changelog-entries.md) +- [Contributing guide (`CONTRIBUTING.md`)](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) From a76bb0aac62e7b6575cb3c8351e5e8d663f81152 Mon Sep 17 00:00:00 2001 From: Copilot Date: Mon, 22 Jun 2026 20:33:07 -0700 Subject: [PATCH 3/4] Scope PR to docs only: remove onboarding agent Removes .github/agents/onboarding.agent.md and the references to it in docs/Onboarding.md and CONTRIBUTING.md so this PR only adds the onboarding documentation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/onboarding.agent.md | 44 ------------------------------ CONTRIBUTING.md | 2 +- docs/Onboarding.md | 4 --- 3 files changed, 1 insertion(+), 49 deletions(-) delete mode 100644 .github/agents/onboarding.agent.md diff --git a/.github/agents/onboarding.agent.md b/.github/agents/onboarding.agent.md deleted file mode 100644 index 76f29c6439..0000000000 --- a/.github/agents/onboarding.agent.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -description: Azure MCP Server onboarding assistant - guides new contributors through prerequisites, adding namespaces and tools, and integrating external MCP servers ---- - -# Azure MCP Server Onboarding Agent - -This agent helps **new contributors** get productive in the Azure MCP Server repository. It -orients you, then routes you to the right section of -[Onboarding.md](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md) and the deeper -authoritative docs. - -## What This Agent Helps With - -Ask about any of these and the agent will point you to the relevant steps and files: - -- **Prerequisites & setup** — required tooling (.NET, Node.js, PowerShell, Azure CLI/PowerShell, - Bicep), the NuGet feed, and the local build/test quick start. -- **Adding a new namespace (toolset)** — scaffolding `tools/Azure.Mcp.Tools.{Toolset}`, - implementing `IAreaSetup`, registering in `Program.cs` `RegisterAreas()`, solution + AOT steps. -- **Adding a new tool to an existing namespace** — the required files, naming conventions, - option/JSON/AOT rules, and how to validate with unit and recorded live tests. -- **Integrating an external MCP server** — editing - `servers/Azure.Mcp.Server/src/Resources/registry.json`, choosing HTTP/SSE vs stdio transport, - and the authentication considerations. -- **Opening a pull request** — the full PR checklist (format, build, spelling, changelog, - recorded tests, docs). - -## How To Route - -Match the contributor's intent to the matching section of -[Onboarding.md](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md): - -| Intent | Section | Authoritative deep dive | -| --- | --- | --- | -| Set up my machine / build the repo | [Prerequisites](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#1-prerequisites), [Quick start](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#2-quick-start) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) | -| Create a brand-new namespace | [Add a new namespace](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#3-add-a-new-namespace-toolset) | [new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) | -| Add one command/tool | [Add a new tool](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#4-add-a-new-tool-to-an-existing-namespace) | [new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) | -| Proxy an external MCP server | [Integrate an external MCP server](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#5-integrate-an-external-mcp-server) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md#configuring-external-mcp-servers) | -| Get ready to submit | [PR checklist](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#6-pull-request-checklist) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) | - -## Source Control - -Contributors work on a branch in **their fork** (for example `RickWinter/mcp`) and open the PR -against `microsoft/mcp:main`. Encourage small, focused PRs. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8bc9135e3c..51346cd250 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ After cloning and building the repo, check out the [GitHub project](https://gith If you are contributing significant changes, or if the issue is already assigned to a specific milestone, please discuss with the assignee of the issue first before starting to work on the issue. >[!TIP] -> New to the project? Start with the [Onboarding Guide](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md) for a guided walkthrough of prerequisites, adding a new namespace or tool, and integrating an external MCP server. You can also invoke the `@onboarding` agent in GitHub Copilot Chat. +> New to the project? Start with the [Onboarding Guide](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md) for a guided walkthrough of prerequisites, adding a new namespace or tool, and integrating an external MCP server. ## Table of Contents diff --git a/docs/Onboarding.md b/docs/Onboarding.md index c915a9b9ec..e632df9c89 100644 --- a/docs/Onboarding.md +++ b/docs/Onboarding.md @@ -13,10 +13,6 @@ you through the prerequisites and the most common onboarding tasks: 5. [Integrate an external MCP server](#5-integrate-an-external-mcp-server) 6. [Pull request checklist](#6-pull-request-checklist) -> [!TIP] -> Prefer interactive help? Invoke the [`@onboarding` agent](https://github.com/microsoft/mcp/blob/main/.github/agents/onboarding.agent.md) -> in GitHub Copilot Chat. It routes you to the right section of this guide and the deeper docs. - This document links to the authoritative deep-dive docs rather than duplicating them. The two most important references are: From 8883dfa8f6b0ce26259451492e08f5aa3a0fa0cb Mon Sep 17 00:00:00 2001 From: Copilot Date: Tue, 23 Jun 2026 11:56:14 -0700 Subject: [PATCH 4/4] Fix onboarding guide links Ensure the onboarding contribution guidance points at the current new-command documentation so PR link validation does not resolve removed skill documentation paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 51346cd250..9430852640 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -165,10 +165,10 @@ Do not assume the Pull Request pipeline will always ingest a missing package aut ```txt Execute in Copilot Chat: - "create [namespace] [resource] [operation] command using #new-command.md as a reference" + "create [namespace] [resource] [operation] command using servers/Azure.Mcp.Server/docs/new-command.md as a reference" ``` -4. **Follow implementation guidelines** in [docs/new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) +4. **Follow the implementation guidelines** in [servers/Azure.Mcp.Server/docs/new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) 5. **Update documentation**: - Add the new command to [/servers/Azure.Mcp.Server/docs/azmcp-commands.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/azmcp-commands.md) @@ -890,7 +890,7 @@ We're building this in the open. Your feedback is much appreciated, and will he ### Additional Resources - [Azure MCP Documentation](https://github.com/microsoft/mcp/blob/main/README.md) -- [Command Implementation Guide](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) +- [Command implementation guide](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) - [VS Code Insiders Download](https://code.visualstudio.com/insiders/) - [GitHub Copilot Documentation](https://docs.github.com/en/copilot)