Add Advanced Security Alert tools (#270)

We are introducing two new tools---`advsec_get_alerts` and 
`advsec_get_alert_details`---in this change to allow customers to
work with [GHAzDO (GitHub Advanced Security for Azure
DevOps)](https://aka.ms/advanced-security) alerts directly in code 
editor.

## GitHub issue number

N/A

## **Associated Risks**

None

## ✅ **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
- [ ] 🔭 ~~Telemetry added, updated, or N/A~~ N/A
- [x] 📄 Documentation added, updated, or N/A
- [x] 🛡️ Automated tests added, or N/A

## 🧪 **How did you test it?**

  * Automated unit tests run using `npm run test`
  * Manual testing with VS Code Agent Mode in Copilot Chat.

---------

Co-authored-by: Nuthan Munaiah <[email protected]>

Author: nuthanmunaiah

README.md

@@ -119,6 +119,11 @@ Interact with these Azure DevOps services:
 - **release_get_definitions**: Retrieve a list of release definitions for a given project.
 - **release_get_releases**: Retrieve a list of releases for a given project.
 
+### 🔒 Advanced Security
+
+- **advsec_get_alerts**: Retrieve Advanced Security alerts for a repository.
+- **advsec_get_alert_details**: Get detailed information about a specific Advanced Security alert.
+
 ### 🧪 Test Plans
 
 - **testplan_create_test_plan**: Create a new test plan in the project.

src/tools.ts

@@ -1,19 +1,20 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { AccessToken } from "@azure/identity";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebApi } from "azure-devops-node-api";
 
-import { configureCoreTools } from "./tools/core.js";
-import { configureWorkTools } from "./tools/work.js";
+import { configureAdvSecTools } from "./tools/advsec.js";
 import { configureBuildTools } from "./tools/builds.js";
-import { configureRepoTools } from "./tools/repos.js";
-import { configureWorkItemTools } from "./tools/workitems.js";
+import { configureCoreTools } from "./tools/core.js";
 import { configureReleaseTools } from "./tools/releases.js";
-import { configureWikiTools } from "./tools/wiki.js";
-import { configureTestPlanTools } from "./tools/testplans.js";
+import { configureRepoTools } from "./tools/repos.js";
 import { configureSearchTools } from "./tools/search.js";
+import { configureTestPlanTools } from "./tools/testplans.js";
+import { configureWikiTools } from "./tools/wiki.js";
+import { configureWorkTools } from "./tools/work.js";
+import { configureWorkItemTools } from "./tools/workitems.js";
 
 function configureAllTools(server: McpServer, tokenProvider: () => Promise<AccessToken>, connectionProvider: () => Promise<WebApi>, userAgentProvider: () => string) {
   configureCoreTools(server, tokenProvider, connectionProvider);
@@ -25,6 +26,7 @@ function configureAllTools(server: McpServer, tokenProvider: () => Promise<Acces
   configureWikiTools(server, tokenProvider, connectionProvider);
   configureTestPlanTools(server, tokenProvider, connectionProvider);
   configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider);
+  configureAdvSecTools(server, tokenProvider, connectionProvider);
 }
 
 export { configureAllTools };

src/tools/advsec.ts

@@ -0,0 +1,143 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { AccessToken } from "@azure/identity";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebApi } from "azure-devops-node-api";
+import { AlertType, AlertValidityStatus, Confidence, Severity, State } from "azure-devops-node-api/interfaces/AlertInterfaces.js";
+import { z } from "zod";
+import { getEnumKeys, mapStringArrayToEnum, mapStringToEnum } from "../utils.js";
+
+const ADVSEC_TOOLS = {
+  get_alerts: "advsec_get_alerts",
+  get_alert_details: "advsec_get_alert_details",
+};
+
+function configureAdvSecTools(server: McpServer, tokenProvider: () => Promise<AccessToken>, 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();
+
+        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
+        );
+
+        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,
+        };
+      }
+    }
+  );
+
+  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
+        );
+
+        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,
+        };
+      }
+    }
+  );
+}
+
+export { ADVSEC_TOOLS, configureAdvSecTools };

src/utils.ts

@@ -1,12 +1,37 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-import { packageVersion } from "./version.js";
-
 export const apiVersion = "7.2-preview.1";
 export const batchApiVersion = "5.0";
 export const markdownCommentsApiVersion = "7.2-preview.4";
 
+export function createEnumMapping<T extends Record<string, string | number>>(enumObject: T): Record<string, T[keyof T]> {
+  const mapping: Record<string, T[keyof T]> = {};
+  for (const [key, value] of Object.entries(enumObject)) {
+    if (typeof key === "string" && typeof value === "number") {
+      mapping[key.toLowerCase()] = value as T[keyof T];
+    }
+  }
+  return mapping;
+}
+
+export function mapStringToEnum<T extends Record<string, string | number>>(value: string | undefined, enumObject: T, defaultValue?: T[keyof T]): T[keyof T] | undefined {
+  if (!value) return defaultValue;
+  const enumMapping = createEnumMapping(enumObject);
+  return enumMapping[value.toLowerCase()] ?? defaultValue;
+}
+
+/**
+ * Maps an array of strings to an array of enum values, filtering out invalid values.
+ * @param values Array of string values to map
+ * @param enumObject The enum object to map to
+ * @returns Array of valid enum values
+ */
+export function mapStringArrayToEnum<T extends Record<string, string | number>>(values: string[] | undefined, enumObject: T): Array<T[keyof T]> {
+  if (!values) return [];
+  return values.map((value) => mapStringToEnum(value, enumObject)).filter((v): v is T[keyof T] => v !== undefined);
+}
+
 /**
  * Converts a TypeScript numeric enum to an array of string keys for use with z.enum().
  * This ensures that enum schemas generate string values rather than numeric values.