Added read-only tool annotations & --read-only CLI flag

README.md

@@ -14,10 +14,11 @@ This TypeScript project provides a **local** MCP server for Azure DevOps, enabli
 3. [⚙️ Supported Tools](#️-supported-tools)
 4. [🔌 Installation & Getting Started](#-installation--getting-started)
 5. [🌏 Using Domains](#-using-domains)
-6. [📝 Troubleshooting](#-troubleshooting)
-7. [🎩 Examples & Best Practices](#-examples--best-practices)
-8. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
-9. [📌 Contributing](#-contributing)
+6. [📖 Read-Only Mode](#-read-only-mode)
+7. [📝 Troubleshooting](#-troubleshooting)
+8. [🎩 Examples & Best Practices](#-examples--best-practices)
+9. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
+10. [📌 Contributing](#-contributing)
 
 ## 📺 Overview
 
@@ -261,6 +262,31 @@ We recommend that you always enable `core` tools so that you can fetch project l
 
 > By default all domains are loaded
 
+## 📖 Read-Only Mode
+
+For environments where you want to prevent any modifications to your Azure DevOps resources, use the `--read-only` flag. This mode exposes only read-only tools (like listing projects, getting work items, viewing pull requests) while hiding all tools that create, update, or delete data.
+
+Add the `--read-only` argument to the server args in your `mcp.json`:
+
+```json
+{
+  "inputs": [
+    {
+      "id": "ado_org",
+      "type": "promptString",
+      "description": "Azure DevOps organization name  (e.g. 'contoso')"
+    }
+  ],
+  "servers": {
+    "ado_readonly": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--read-only"]
+    }
+  }
+}
+```
+
 ## 📝 Troubleshooting
 
 See the [Troubleshooting guide](./docs/TROUBLESHOOTING.md) for help with common issues and logging.

package.json

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

src/index.ts

@@ -54,6 +54,11 @@ const argv = yargs(hideBin(process.argv))
     describe: "Azure tenant ID (optional, applied when using 'interactive' and 'azcli' type of authentication)",
     type: "string",
   })
+  .option("read-only", {
+    describe: "Run the server in read-only mode (no write/update tools exposed)",
+    type: "boolean",
+    default: false,
+  })
   .help()
   .parseSync();
 
@@ -97,7 +102,9 @@ async function main() {
   // removing prompts untill further notice
   // configurePrompts(server);
 
-  configureAllTools(server, authenticator, getAzureDevOpsClient(authenticator, userAgentComposer), () => userAgentComposer.userAgent, enabledDomains);
+  const isReadOnlyMode = argv["read-only"];
+
+  configureAllTools(server, authenticator, getAzureDevOpsClient(authenticator, userAgentComposer), () => userAgentComposer.userAgent, enabledDomains, isReadOnlyMode);
 
   const transport = new StdioServerTransport();
   await server.connect(transport);

src/tools.ts

@@ -15,22 +15,29 @@ import { configureWikiTools } from "./tools/wiki.js";
 import { configureWorkTools } from "./tools/work.js";
 import { configureWorkItemTools } from "./tools/work-items.js";
 
-function configureAllTools(server: McpServer, tokenProvider: () => Promise<string>, connectionProvider: () => Promise<WebApi>, userAgentProvider: () => string, enabledDomains: Set<string>) {
+function configureAllTools(
+  server: McpServer,
+  tokenProvider: () => Promise<string>,
+  connectionProvider: () => Promise<WebApi>,
+  userAgentProvider: () => string,
+  enabledDomains: Set<string>,
+  isReadOnlyMode: boolean
+) {
   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.PIPELINES, () => configurePipelineTools(server, tokenProvider, connectionProvider, userAgentProvider));
-  configureIfDomainEnabled(Domain.REPOSITORIES, () => configureRepoTools(server, tokenProvider, connectionProvider, userAgentProvider));
-  configureIfDomainEnabled(Domain.WORK_ITEMS, () => configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider));
-  configureIfDomainEnabled(Domain.WIKI, () => configureWikiTools(server, tokenProvider, connectionProvider, userAgentProvider));
-  configureIfDomainEnabled(Domain.TEST_PLANS, () => configureTestPlanTools(server, tokenProvider, connectionProvider));
-  configureIfDomainEnabled(Domain.SEARCH, () => configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider));
-  configureIfDomainEnabled(Domain.ADVANCED_SECURITY, () => configureAdvSecTools(server, tokenProvider, connectionProvider));
+  configureIfDomainEnabled(Domain.CORE, () => configureCoreTools(server, tokenProvider, connectionProvider, userAgentProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.WORK, () => configureWorkTools(server, tokenProvider, connectionProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.PIPELINES, () => configurePipelineTools(server, tokenProvider, connectionProvider, userAgentProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.REPOSITORIES, () => configureRepoTools(server, tokenProvider, connectionProvider, userAgentProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.WORK_ITEMS, () => configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.WIKI, () => configureWikiTools(server, tokenProvider, connectionProvider, userAgentProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.TEST_PLANS, () => configureTestPlanTools(server, tokenProvider, connectionProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.SEARCH, () => configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider, isReadOnlyMode));
+  configureIfDomainEnabled(Domain.ADVANCED_SECURITY, () => configureAdvSecTools(server, tokenProvider, connectionProvider, isReadOnlyMode));
 }
 
 export { configureAllTools };

src/tools/advanced-security.ts

@@ -12,131 +12,147 @@ const ADVSEC_TOOLS = {
   get_alert_details: "advsec_get_alert_details",
 };
 
-function configureAdvSecTools(server: McpServer, _: () => Promise<string>, connectionProvider: () => Promise<WebApi>) {
-  server.tool(
-    ADVSEC_TOOLS.get_alerts,
-    "Retrieve Advanced Security alerts for a repository.",
-    {
-      project: z.string().describe("The name or ID of the Azure DevOps project."),
-      repository: z.string().describe("The name or ID of the repository to get alerts for."),
-      alertType: z
-        .enum(getEnumKeys(AlertType) as [string, ...string[]])
-        .optional()
-        .describe("Filter alerts by type. If not specified, returns all alert types."),
-      states: z
-        .array(z.enum(getEnumKeys(State) as [string, ...string[]]))
-        .optional()
-        .describe("Filter alerts by state. If not specified, returns alerts in any state."),
-      severities: z
-        .array(z.enum(getEnumKeys(Severity) as [string, ...string[]]))
-        .optional()
-        .describe("Filter alerts by severity level. If not specified, returns alerts at any severity."),
-      ruleId: z.string().optional().describe("Filter alerts by rule ID."),
-      ruleName: z.string().optional().describe("Filter alerts by rule name."),
-      toolName: z.string().optional().describe("Filter alerts by tool name."),
-      ref: z.string().optional().describe("Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch."),
-      onlyDefaultBranch: z.boolean().optional().default(true).describe("If true, only return alerts found on the default branch. Defaults to true."),
-      confidenceLevels: z
-        .array(z.enum(getEnumKeys(Confidence) as [string, ...string[]]))
-        .optional()
-        .default(["high", "other"])
-        .describe("Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'."),
-      validity: z
-        .array(z.enum(getEnumKeys(AlertValidityStatus) as [string, ...string[]]))
-        .optional()
-        .describe("Filter alerts by validity status. Only applicable for secret alerts."),
-      top: z.number().optional().default(100).describe("Maximum number of alerts to return. Defaults to 100."),
-      orderBy: z.enum(["id", "firstSeen", "lastSeen", "fixedOn", "severity"]).optional().default("severity").describe("Order results by specified field. Defaults to 'severity'."),
-      continuationToken: z.string().optional().describe("Continuation token for pagination."),
-    },
-    async ({ project, repository, alertType, states, severities, ruleId, ruleName, toolName, ref, onlyDefaultBranch, confidenceLevels, validity, top, orderBy, continuationToken }) => {
-      try {
-        const connection = await connectionProvider();
-        const alertApi = await connection.getAlertApi();
+function configureAdvSecTools(server: McpServer, _: () => Promise<string>, connectionProvider: () => Promise<WebApi>, isReadOnlyMode: boolean) {
+  const registeredTools = [
+    server.tool(
+      ADVSEC_TOOLS.get_alerts,
+      "Retrieve Advanced Security alerts for a repository.",
+      {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        repository: z.string().describe("The name or ID of the repository to get alerts for."),
+        alertType: z
+          .enum(getEnumKeys(AlertType) as [string, ...string[]])
+          .optional()
+          .describe("Filter alerts by type. If not specified, returns all alert types."),
+        states: z
+          .array(z.enum(getEnumKeys(State) as [string, ...string[]]))
+          .optional()
+          .describe("Filter alerts by state. If not specified, returns alerts in any state."),
+        severities: z
+          .array(z.enum(getEnumKeys(Severity) as [string, ...string[]]))
+          .optional()
+          .describe("Filter alerts by severity level. If not specified, returns alerts at any severity."),
+        ruleId: z.string().optional().describe("Filter alerts by rule ID."),
+        ruleName: z.string().optional().describe("Filter alerts by rule name."),
+        toolName: z.string().optional().describe("Filter alerts by tool name."),
+        ref: z.string().optional().describe("Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch."),
+        onlyDefaultBranch: z.boolean().optional().default(true).describe("If true, only return alerts found on the default branch. Defaults to true."),
+        confidenceLevels: z
+          .array(z.enum(getEnumKeys(Confidence) as [string, ...string[]]))
+          .optional()
+          .default(["high", "other"])
+          .describe("Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'."),
+        validity: z
+          .array(z.enum(getEnumKeys(AlertValidityStatus) as [string, ...string[]]))
+          .optional()
+          .describe("Filter alerts by validity status. Only applicable for secret alerts."),
+        top: z.number().optional().default(100).describe("Maximum number of alerts to return. Defaults to 100."),
+        orderBy: z.enum(["id", "firstSeen", "lastSeen", "fixedOn", "severity"]).optional().default("severity").describe("Order results by specified field. Defaults to 'severity'."),
+        continuationToken: z.string().optional().describe("Continuation token for pagination."),
+      },
+      {
+        readOnlyHint: true,
+      },
+      async ({ project, repository, alertType, states, severities, ruleId, ruleName, toolName, ref, onlyDefaultBranch, confidenceLevels, validity, top, orderBy, continuationToken }) => {
+        try {
+          const connection = await connectionProvider();
+          const alertApi = await connection.getAlertApi();
 
-        const isSecretAlert = !alertType || alertType.toLowerCase() === "secret";
-        const criteria = {
-          ...(alertType && { alertType: mapStringToEnum(alertType, AlertType) }),
-          ...(states && { states: mapStringArrayToEnum(states, State) }),
-          ...(severities && { severities: mapStringArrayToEnum(severities, Severity) }),
-          ...(ruleId && { ruleId }),
-          ...(ruleName && { ruleName }),
-          ...(toolName && { toolName }),
-          ...(ref && { ref }),
-          ...(onlyDefaultBranch !== undefined && { onlyDefaultBranch }),
-          ...(isSecretAlert && confidenceLevels && { confidenceLevels: mapStringArrayToEnum(confidenceLevels, Confidence) }),
-          ...(isSecretAlert && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }),
-        };
+          const isSecretAlert = !alertType || alertType.toLowerCase() === "secret";
+          const criteria = {
+            ...(alertType && { alertType: mapStringToEnum(alertType, AlertType) }),
+            ...(states && { states: mapStringArrayToEnum(states, State) }),
+            ...(severities && { severities: mapStringArrayToEnum(severities, Severity) }),
+            ...(ruleId && { ruleId }),
+            ...(ruleName && { ruleName }),
+            ...(toolName && { toolName }),
+            ...(ref && { ref }),
+            ...(onlyDefaultBranch !== undefined && { onlyDefaultBranch }),
+            ...(isSecretAlert && confidenceLevels && { confidenceLevels: mapStringArrayToEnum(confidenceLevels, Confidence) }),
+            ...(isSecretAlert && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }),
+          };
 
-        const result = await alertApi.getAlerts(
-          project,
-          repository,
-          top,
-          orderBy,
-          criteria,
-          undefined, // expand parameter
-          continuationToken
-        );
+          const result = await alertApi.getAlerts(
+            project,
+            repository,
+            top,
+            orderBy,
+            criteria,
+            undefined, // expand parameter
+            continuationToken
+          );
 
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          };
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error fetching Advanced Security alerts: ${errorMessage}`,
-            },
-          ],
-          isError: true,
-        };
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error fetching Advanced Security alerts: ${errorMessage}`,
+              },
+            ],
+            isError: true,
+          };
+        }
       }
-    }
-  );
+    ),
+
+    server.tool(
+      ADVSEC_TOOLS.get_alert_details,
+      "Get detailed information about a specific Advanced Security alert.",
+      {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        repository: z.string().describe("The name or ID of the repository containing the alert."),
+        alertId: z.number().describe("The ID of the alert to retrieve details for."),
+        ref: z.string().optional().describe("Git reference (branch) to filter the alert."),
+      },
+      {
+        readOnlyHint: true,
+      },
+      async ({ project, repository, alertId, ref }) => {
+        try {
+          const connection = await connectionProvider();
+          const alertApi = await connection.getAlertApi();
 
-  server.tool(
-    ADVSEC_TOOLS.get_alert_details,
-    "Get detailed information about a specific Advanced Security alert.",
-    {
-      project: z.string().describe("The name or ID of the Azure DevOps project."),
-      repository: z.string().describe("The name or ID of the repository containing the alert."),
-      alertId: z.number().describe("The ID of the alert to retrieve details for."),
-      ref: z.string().optional().describe("Git reference (branch) to filter the alert."),
-    },
-    async ({ project, repository, alertId, ref }) => {
-      try {
-        const connection = await connectionProvider();
-        const alertApi = await connection.getAlertApi();
+          const result = await alertApi.getAlert(
+            project,
+            alertId,
+            repository,
+            ref,
+            undefined // expand parameter
+          );
 
-        const result = await alertApi.getAlert(
-          project,
-          alertId,
-          repository,
-          ref,
-          undefined // expand parameter
-        );
+          return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          };
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
 
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error fetching alert details: ${errorMessage}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+    ),
+  ];
 
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error fetching alert details: ${errorMessage}`,
-            },
-          ],
-          isError: true,
-        };
+  if (isReadOnlyMode) {
+    for (const tool of registeredTools) {
+      if (!tool.annotations?.readOnlyHint) {
+        tool.remove();
       }
     }
-  );
+  }
 }
 
 export { ADVSEC_TOOLS, configureAdvSecTools };