feat: add MCP server "domains" (#421)

Add domains

## GitHub issue number
#386

## **Associated Risks**
_Replace_ by possible risks this pull request can bring you might have
thought of

## ✅ **PR Checklist**

- [x] **I have read the [contribution
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CONTRIBUTING.md)**
- [x] **I have read the [code of conduct
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CODE_OF_CONDUCT.md)**
- [x] Title of the pull request is clear and informative.
- [x] 👌 Code hygiene
- [x] 🔭 Telemetry added, updated, or **N/A** -- N/A: tracking domain
enabling will be a follow up
- [ ] 📄 Documentation added, updated, or **N/A** -- N/A: we aligned PM
handling it
- [x] 🛡️ Automated tests added, or N/A

## 🧪 **How did you test it?**
Unit test added
Local run - Inspector
**Post-Update Status:**

- **Wiki + Work Items**  
  Tools loaded reduced from **all tools** to **18 tools**  
<img width="956" height="904" alt="image"
src="https://github.com/user-attachments/assets/3ae7c5ec-2749-4638-8338-284a57b77f84"
/>

   **Repositories + Test Plans**  
  Tools loaded reduced from **all tools** to **23 tools**  
<img width="1000" height="940" alt="image"
src="https://github.com/user-attachments/assets/56e8b811-9df3-4dd8-ad15-7cc504793647"
/>

VS Code 
<img width="1617" height="1204" alt="image"
src="https://github.com/user-attachments/assets/b1cfda6b-fe37-45b4-a8b9-d54b4b4d32b5"
/>

**Note on UI**: Domain selection is not supported in the UI, and VS Code
lacks multi-select for pickString.
Domains are required explicitly; documentation are available to assist..
Workarounds exist but are not prioritized. This UI limitation should be
addressed with Groups and Tags coming.

<img width="471" height="392" alt="image"
src="https://github.com/user-attachments/assets/809b38f2-56c2-44e2-aca1-6e24fec9bcb5"
/>

### Customer Experience
Given We are considering pushing a draft spec generator, the page for
customers would look like:

## Context 

[SEP-993](modelcontextprotocol/modelcontextprotocol#993)
is moving to **Groups and Tags**
We have been discussing with interested parties and authors, Groups is
quite loosely coupled, which can be categorized with:
* Semantic Groups
* Functional Groups

It makes sense for Groups and Tags proposal be as generic as possible.
With domains we introduce a semantic group which in terms of
implementation is just syntax sugar for groups, but it carries more
governance on MCP servers around those.

Some open questions when Groups go to prod: 
* Some other edge case behaviors: e.g. behavior for someone defining
domains and groups
* Standard way to expose and catalog those domains (give viz at
Microsoft for them)

**Important**
* Not all MCP servers necessarily require to have domains. For instance,
if your groups are organized around functional roles rather than strict
semantic boundaries, it may be reasonable not to enforce domain
governance.
* For those servers that do require domain structuring, this capability
is supported through the Groups and Tags SEP. Domains are syntax sugar
for groups, which appear to be the de-facto implementation approach at
the protocol level.


### More info on protocol alignment: Tool Filtering with groups and Tags
More info: [SEP-1300: Tool Filtering with Groups and Tags · Issue #1300
·
modelcontextprotocol/modelcontextprotocol](modelcontextprotocol/modelcontextprotocol#1300)

> Client-side filtering of tools: Agent fetches all the tools with no
filtering, organizes them by groups and tags within the host
application, then provides the appropriate tools to the LLM when needed
via whatever means, e.g., semantic search.

> Server-side filtering of tools: Agent presents a list of groups to the
LLM. When the LLM decides it needs a tool but doesn't have an
appropriate one in its context, it may request the list of tools in a
particular group or set of groups.

---------

Co-authored-by: aaudzei <[email protected]>

Author: Novaes

intTest/domains/mcp.json

@@ -0,0 +1,23 @@
+{
+  "servers": {
+    "ado": {
+      "type": "stdio",
+      "command": "mcp-server-azuredevops",
+      "args": [
+        "${input:ado_org}",
+        "-d",
+        "core",
+        "work",
+        "workitems"
+        // ... any other domain to enable, you can also use 'all' (which is already the default)
+      ]
+    }
+  },
+  "inputs": [
+    {
+      "id": "ado_org",
+      "type": "promptString",
+      "description": "Azure DevOps organization name (e.g. 'contoso')"
+    }
+  ]
+}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "1.3.1",
+  "version": "2.0.0",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
   "author": "Microsoft Corporation",

package.json

@@ -14,18 +14,27 @@ import { configurePrompts } from "./prompts.js";
 import { configureAllTools } from "./tools.js";
 import { UserAgentComposer } from "./useragent.js";
 import { packageVersion } from "./version.js";
+import { DomainsManager } from "./shared/domains.js";
 
 // Parse command line arguments using yargs
 const argv = yargs(hideBin(process.argv))
   .scriptName("mcp-server-azuredevops")
   .usage("Usage: $0 <organization> [options]")
   .version(packageVersion)
-  .command("$0 <organization>", "Azure DevOps MCP Server", (yargs) => {
+  .command("$0 <organization> [options]", "Azure DevOps MCP Server", (yargs) => {
     yargs.positional("organization", {
       describe: "Azure DevOps organization name",
       type: "string",
+      demandOption: true,
     });
   })
+  .option("domains", {
+    alias: "d",
+    describe: "Domain(s) to enable: 'all' for everything, or specific domains like 'repositories builds work'. Defaults to 'all'.",
+    type: "string",
+    array: true,
+    default: "all",
+  })
   .option("tenant", {
     alias: "t",
     describe: "Azure tenant ID (optional, required for multi-tenant scenarios)",
@@ -34,10 +43,14 @@ const argv = yargs(hideBin(process.argv))
   .help()
   .parseSync();
 
-export const orgName = argv.organization as string;
 const tenantId = argv.tenant;
+
+export const orgName = argv.organization as string;
 const orgUrl = "https://dev.azure.com/" + orgName;
 
+const domainsManager = new DomainsManager(argv.domains);
+export const enabledDomains = domainsManager.getEnabledDomains();
+
 async function getAzureDevOpsToken(): Promise<AccessToken> {
   if (process.env.ADO_MCP_AZURE_TOKEN_CREDENTIALS) {
     process.env.AZURE_TOKEN_CREDENTIALS = process.env.ADO_MCP_AZURE_TOKEN_CREDENTIALS;
@@ -84,7 +97,7 @@ async function main() {
 
   configurePrompts(server);
 
-  configureAllTools(server, getAzureDevOpsToken, getAzureDevOpsClient(userAgentComposer), () => userAgentComposer.userAgent);
+  configureAllTools(server, getAzureDevOpsToken, getAzureDevOpsClient(userAgentComposer), () => userAgentComposer.userAgent, enabledDomains);
 
   const transport = new StdioServerTransport();
   await server.connect(transport);

src/index.ts

@@ -4,7 +4,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CORE_TOOLS } from "./tools/core.js";
-import { WORKITEM_TOOLS } from "./tools/workitems.js";
+import { WORKITEM_TOOLS } from "./tools/work-items.js";
 
 function configurePrompts(server: McpServer) {
   server.prompt("Projects", "Lists all projects in the Azure DevOps organization.", {}, () => ({

src/prompts.ts

@@ -0,0 +1,141 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/**
+ * Available Azure DevOps MCP domains
+ */
+export enum Domain {
+  ADVANCED_SECURITY = "advanced-security",
+  BUILDS = "builds",
+  CORE = "core",
+  RELEASES = "releases",
+  REPOSITORIES = "repositories",
+  SEARCH = "search",
+  TEST_PLANS = "test-plans",
+  WIKI = "wiki",
+  WORK = "work",
+  WORK_ITEMS = "work-items",
+}
+
+export const ALL_DOMAINS = "all";
+
+/**
+ * Manages domain parsing and validation for Azure DevOps MCP server tools
+ */
+export class DomainsManager {
+  private static readonly AVAILABLE_DOMAINS = Object.values(Domain);
+
+  private readonly enabledDomains: Set<string>;
+
+  constructor(domainsInput?: string | string[]) {
+    this.enabledDomains = new Set();
+    const normalizedInput = DomainsManager.parseDomainsInput(domainsInput);
+    this.parseDomains(normalizedInput);
+  }
+
+  /**
+   * Parse and validate domains from input
+   * @param domainsInput - Either "all", single domain name, array of domain names, or undefined (defaults to "all")
+   */
+  private parseDomains(domainsInput?: string | string[]): void {
+    if (!domainsInput) {
+      this.enableAllDomains();
+      return;
+    }
+
+    if (Array.isArray(domainsInput)) {
+      this.handleArrayInput(domainsInput);
+      return;
+    }
+
+    this.handleStringInput(domainsInput);
+  }
+
+  private handleArrayInput(domainsInput: string[]): void {
+    if (domainsInput.length === 0 || domainsInput.includes(ALL_DOMAINS)) {
+      this.enableAllDomains();
+      return;
+    }
+
+    if (domainsInput.length === 1 && domainsInput[0] === ALL_DOMAINS) {
+      this.enableAllDomains();
+      return;
+    }
+
+    const domains = domainsInput.map((d) => d.trim().toLowerCase());
+    this.validateAndAddDomains(domains);
+  }
+
+  private handleStringInput(domainsInput: string): void {
+    if (domainsInput === ALL_DOMAINS) {
+      this.enableAllDomains();
+      return;
+    }
+
+    const domains = [domainsInput.trim().toLowerCase()];
+    this.validateAndAddDomains(domains);
+  }
+
+  private validateAndAddDomains(domains: string[]): void {
+    const availableDomainsAsStringArray = Object.values(Domain) as string[];
+    domains.forEach((domain) => {
+      if (availableDomainsAsStringArray.includes(domain)) {
+        this.enabledDomains.add(domain);
+      } else if (domain === ALL_DOMAINS) {
+        this.enableAllDomains();
+      } else {
+        console.error(`Error: Specified invalid domain '${domain}'. Please specify exactly as available domains: ${Object.values(Domain).join(", ")}`);
+      }
+    });
+
+    if (this.enabledDomains.size === 0) {
+      this.enableAllDomains();
+    }
+  }
+
+  private enableAllDomains(): void {
+    Object.values(Domain).forEach((domain) => this.enabledDomains.add(domain));
+  }
+
+  /**
+   * Check if a specific domain is enabled
+   * @param domain - Domain name to check
+   * @returns true if domain is enabled
+   */
+  public isDomainEnabled(domain: string): boolean {
+    return this.enabledDomains.has(domain);
+  }
+
+  /**
+   * Get all enabled domains
+   * @returns Set of enabled domain names
+   */
+  public getEnabledDomains(): Set<string> {
+    return new Set(this.enabledDomains);
+  }
+
+  /**
+   * Get list of all available domains
+   * @returns Array of available domain names
+   */
+  public static getAvailableDomains(): string[] {
+    return Object.values(Domain);
+  }
+
+  /**
+   * Parse domains input from string or array to a normalized array of strings
+   * @param domainsInput - Domains input to parse
+   * @returns Normalized array of domain strings
+   */
+  public static parseDomainsInput(domainsInput?: string | string[]): string[] {
+    if (!domainsInput) {
+      return [];
+    }
+
+    if (typeof domainsInput === "string") {
+      return domainsInput.split(",").map((d) => d.trim().toLowerCase());
+    }
+
+    return domainsInput.map((d) => d.trim().toLowerCase());
+  }
+}

src/shared/domains.ts

@@ -5,28 +5,35 @@ import { AccessToken } from "@azure/identity";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebApi } from "azure-devops-node-api";
 
-import { configureAdvSecTools } from "./tools/advsec.js";
+import { Domain } from "./shared/domains.js";
+import { configureAdvSecTools } from "./tools/advanced-security.js";
 import { configureBuildTools } from "./tools/builds.js";
 import { configureCoreTools } from "./tools/core.js";
 import { configureReleaseTools } from "./tools/releases.js";
-import { configureRepoTools } from "./tools/repos.js";
+import { configureRepoTools } from "./tools/repositories.js";
 import { configureSearchTools } from "./tools/search.js";
-import { configureTestPlanTools } from "./tools/testplans.js";
+import { configureTestPlanTools } from "./tools/test-plans.js";
 import { configureWikiTools } from "./tools/wiki.js";
 import { configureWorkTools } from "./tools/work.js";
-import { configureWorkItemTools } from "./tools/workitems.js";
+import { configureWorkItemTools } from "./tools/work-items.js";
 
-function configureAllTools(server: McpServer, tokenProvider: () => Promise<AccessToken>, connectionProvider: () => Promise<WebApi>, userAgentProvider: () => string) {
-  configureCoreTools(server, tokenProvider, connectionProvider, userAgentProvider);
-  configureWorkTools(server, tokenProvider, connectionProvider);
-  configureBuildTools(server, tokenProvider, connectionProvider, userAgentProvider);
-  configureRepoTools(server, tokenProvider, connectionProvider, userAgentProvider);
-  configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
-  configureReleaseTools(server, tokenProvider, connectionProvider);
-  configureWikiTools(server, tokenProvider, connectionProvider);
-  configureTestPlanTools(server, tokenProvider, connectionProvider);
-  configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider);
-  configureAdvSecTools(server, tokenProvider, connectionProvider);
+function configureAllTools(server: McpServer, tokenProvider: () => Promise<AccessToken>, connectionProvider: () => Promise<WebApi>, userAgentProvider: () => string, enabledDomains: Set<string>) {
+  const configureIfDomainEnabled = (domain: string, configureFn: () => void) => {
+    if (enabledDomains.has(domain)) {
+      configureFn();
+    }
+  };
+
+  configureIfDomainEnabled(Domain.CORE, () => configureCoreTools(server, tokenProvider, connectionProvider, userAgentProvider));
+  configureIfDomainEnabled(Domain.WORK, () => configureWorkTools(server, tokenProvider, connectionProvider));
+  configureIfDomainEnabled(Domain.BUILDS, () => configureBuildTools(server, tokenProvider, connectionProvider, userAgentProvider));
+  configureIfDomainEnabled(Domain.REPOSITORIES, () => configureRepoTools(server, tokenProvider, connectionProvider, userAgentProvider));
+  configureIfDomainEnabled(Domain.WORK_ITEMS, () => configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider));
+  configureIfDomainEnabled(Domain.RELEASES, () => configureReleaseTools(server, tokenProvider, connectionProvider));
+  configureIfDomainEnabled(Domain.WIKI, () => configureWikiTools(server, tokenProvider, connectionProvider));
+  configureIfDomainEnabled(Domain.TEST_PLANS, () => configureTestPlanTools(server, tokenProvider, connectionProvider));
+  configureIfDomainEnabled(Domain.SEARCH, () => configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider));
+  configureIfDomainEnabled(Domain.ADVANCED_SECURITY, () => configureAdvSecTools(server, tokenProvider, connectionProvider));
 }
 
 export { configureAllTools };