@azure-devops/mcp 1.2.0 → 1.3.0

package/LICENSE.md

@@ -1,21 +1,21 @@
-    MIT License
-
-    Copyright (c) Microsoft Corporation.
-
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
-
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -15,11 +15,10 @@ This TypeScript project provides a **local** MCP server for Azure DevOps, enabli
 2. [🏆 Expectations](#-expectations)
 3. [⚙️ Supported Tools](#️-supported-tools)
 4. [🔌 Installation & Getting Started](#-installation--getting-started)
-5. [🔦 Usage](#-usage)
-6. [📝 Troubleshooting](#-troubleshooting)
-7. [🎩 Samples & Best Practices](#-samples--best-practices)
-8. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
-9. [📌 Contributing](#-contributing)
+5. [📝 Troubleshooting](#-troubleshooting)
+6. [🎩 Examples & Best Practices](#-samples--best-practices)
+7. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
+8. [📌 Contributing](#-contributing)
 
 ## 📺 Overview
 
@@ -73,12 +72,13 @@ Interact with these Azure DevOps services:
 - **wit_get_query**: Get a query by its ID or path.
 - **wit_get_query_results_by_id**: Retrieve the results of a work item query given the query ID.
 - **wit_update_work_items_batch**: Update work items in batch.
-- **wit_close_and_link_workitem_duplicates**: Close duplicate work items by ID.
 - **wit_work_items_link**: Link work items together in batch.
+- **wit_work_item_unlink**: Unlink one or many links from a work item.
 
 #### Deprecated Tools
 
 - **wit_add_child_work_item**: Replaced by `wit_add_child_work_items` to allow creating one or more child items per call.
+- **wit_close_and_link_workitem_duplicates**: This tool is no longer needed. Finding and marking duplicates can be done with other tools.
 
 ### 📁 Repositories
 
@@ -95,10 +95,12 @@ Interact with these Azure DevOps services:
 - **repo_get_pull_request_by_id**: Get a pull request by its ID.
 - **repo_create_pull_request**: Create a new pull request.
 - **repo_update_pull_request_status**: Update the status of an existing pull request to active or abandoned.
+- **repo_update_pull_request**: Update various fields of an existing pull request (title, description, draft status, target branch).
 - **repo_update_pull_request_reviewers**: Add or remove reviewers for an existing pull request.
-- **repo_reply_to_comment**: Reply to a specific comment on a pull request.
-- **repo_resolve_comment**: Resolve a specific comment thread on a pull request.
-- **repo_search_commits**: Search for commits.
+- **repo_reply_to_comment**: Replies to a specific comment on a pull request.
+- **repo_resolve_comment**: Resolves a specific comment thread on a pull request.
+- **repo_search_commits**: Searches for commits.
+- **repo_create_pull_request_thread**: Creates a new comment thread on a pull request.
 
 ### 🛰️ Builds
 
@@ -117,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.
@@ -134,14 +141,7 @@ Interact with these Azure DevOps services:
 
 ## 🔌 Installation & Getting Started
 
-Clone the repository, install dependencies, and add it to your MCP client configuration.
-
-[VS Code and GitHub Copilot](#%EF%B8%8F-visual-studio-code--github-copilot)<br/>
-[Visual Studio 2022 and GitHub Copilot](#%EF%B8%8F-visual-studio-2022--github-copilot)
-
-### ➡️ Visual Studio Code & GitHub Copilot
-
-For the best experience, use Visual Studio Code and GitHub Copilot.
+For the best experience, use Visual Studio Code and GitHub Copilot. See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, and Cursor.
 
 ### Prerequisites
 
@@ -175,108 +175,7 @@ This installation method is the easiest for all users of Visual Studio Code.
 
 ##### Steps
 
-1. In your project, add a `.vscode\mcp.json` file with the following content:
-
-```json
-{
-  "inputs": [
-    {
-      "id": "ado_org",
-      "type": "promptString",
-      "description": "Azure DevOps organization name  (e.g. 'contoso')"
-    }
-  ],
-  "servers": {
-    "ado": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@azure-devops/mcp", "${input:ado_org}"]
-    }
-  }
-}
-```
-
-2. Save the file, then click 'Start'.
-
-  <img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
-
-3. In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
-4. Click "Select Tools" and choose the available tools.
-5. We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
-
-#### 🛠️ Install from Source (Dev Mode)
-
-This installation method is recommended for advanced users and contributors who want immediate access to the latest updates from the main branch. It is ideal if you are developing new tools, enhancing existing features, or maintaining a custom fork.
-
-> **Note:** For most users, installing from the public feed is simpler and preferred. Use the source installation only if you need the latest changes or are actively contributing to the project.
-
-##### Steps
-
-1. Clone the repository.
-2. Install dependencies:
-
-```sh
-npm install
-```
-
-3. Edit or add `.vscode/mcp.json`:
-
-```json
-{
-  "inputs": [
-    {
-      "id": "ado_org",
-      "type": "promptString",
-      "description": "Azure DevOps organization's name  (e.g. 'contoso')"
-    }
-  ],
-  "servers": {
-    "ado": {
-      "type": "stdio",
-      "command": "mcp-server-azuredevops",
-      "args": ["${input:ado_org}"]
-    }
-  }
-}
-```
-
-4. Start the Azure DevOps MCP Server.
-
-  <img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
-
-5. In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
-6. Click "Select Tools" and choose the available tools.
-7. We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will help you get the best experience using the Azure DevOps MCP Server in GitHub Copilot Chat.
-
-See the [How To](./docs/HOWTO.md) section for details.
-
-### ➡️ Visual Studio 2022 & GitHub Copilot
-
-For the best experience, use Visual Studio Code and GitHub Copilot 👆.
-
-### Prerequisites
-
-1. Install [VS Studio 2022 version 17.14](https://learn.microsoft.com/en-us/visualstudio/releases/2022/release-history) or later
-2. Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)
-3. Open a project in Visual Studio.
-
-### Azure Login
-
-Ensure you are logged in to Azure DevOps via the Azure CLI:
-
-```sh
-az login
-```
-
-#### 🧨 Install from Public Feed (Recommended)
-
-This installation method is the easiest for all users of Visual Studio 2022.
-
-🎥 [Watch this quick start video to get up and running in under two minutes!](https://youtu.be/nz_Gn-WL7j0)
-
-##### Steps
-
-1. Add a `.mcp.json` file to the solution folder with the following content:
+In your project, add a `.vscode\mcp.json` file with the following content:
 
 ```json
 {
@@ -297,45 +196,31 @@ This installation method is the easiest for all users of Visual Studio 2022.
 }
 ```
 
-2. Save the file.
-3. Add your organization name by clicking on the `input` option.
+Save the file, then click 'Start'.
 
-   <img src="./docs/media/start-mcp-server-from-vs.png" alt="start mcp server from visual studio 2022" width="250"/>
+<img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
 
-4. Open Copilot chat and switch to [Agent Mode](https://learn.microsoft.com/en-us/visualstudio/ide/copilot-agent-mode?view=vs-2022).
-5. Click the "Tools" icon and choose the available tools.
+In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
 
-   <img src="./docs/media/set-tools-from-vs.png" alt="set tools to use in visual studio 2022" width="250"/>
+Click "Select Tools" and choose the available tools.
 
-6. We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
+<img src="./docs/media/configure-mcp-server-tools.gif" alt="configure mcp server tools" width="300"/>
 
-## 🔦 Usage
+Open GitHub Copilot Chat and try a prompt like `List ADO projects`.
 
-### Visual Studio Code + GitHub Copilot
+> 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project and copying the contents from this [copilot-instructions.md](./.github/copilot-instructions.md) file. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
 
-1. Open GitHub Copilot in VS Code and switch to Agent mode.
-2. Start the Azure DevOps MCP Server.
-3. The server appears in the tools list.
-4. Try prompts like "List ADO projects".
-
-### Visual Studio + GitHub Copilot
-
-> _Prerequisites:_ Visual Studio 2022 v17.14+, Agent mode enabled in Tools > Options > GitHub > Copilot > Copilot Chat.
-
-1. Switch to Agent mode in the Copilot Chat window.
-2. Enter your Azure DevOps organization name.
-3. Select desired `ado` tools.
-4. Try prompts like "List ADO projects".
-
-For more details, see [Visual Studio MCP Servers documentation](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022) and the [Getting Started Video](https://www.youtube.com/watch?v=oPFecZHBCkg).
+See the [getting started documentation](./docs/GETTINGSTARTED.md) to use our MCP Server with other tools such as Visual Studio 2022, Claude Code, and Cursor.
 
 ## 📝 Troubleshooting
 
 See the [Troubleshooting guide](./docs/TROUBLESHOOTING.md) for help with common issues and logging.
 
-## 🎩 Samples & Best Practices
+## 🎩 Examples & Best Practices
+
+Explore example prompts in our [Examples documentation](./docs/EXAMPLES.md).
 
-Find sample prompts and best practices in our [How-to Guide](./docs/HOWTO.md).
+For best practices and tips to enhance your experience with the MCP Server, refer to the [How-To guide](./docs/HOWTO.md).
 
 ## 🙋‍♀️ Frequently Asked Questions
 

package/dist/shared/tool-validation.js

@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * Validates that a name conforms to Claude API requirements.
+ * Names must match pattern: ^[a-zA-Z0-9_.-]{1,64}$
+ * @param name The name to validate
+ * @returns Object with isValid boolean and error/reason message if invalid
+ */
+export function validateName(name) {
+    // Check length
+    if (name.length === 0) {
+        return { isValid: false, error: "Name cannot be empty", reason: "name cannot be empty" };
+    }
+    if (name.length > 64) {
+        return {
+            isValid: false,
+            error: `Name '${name}' is ${name.length} characters long, maximum allowed is 64`,
+            reason: `name is ${name.length} characters long, maximum allowed is 64`,
+        };
+    }
+    // Check pattern: only alphanumeric, underscore, dot, and hyphen allowed
+    const validPattern = /^[a-zA-Z0-9_.-]+$/;
+    if (!validPattern.test(name)) {
+        return {
+            isValid: false,
+            error: `Name '${name}' contains invalid characters. Only alphanumeric characters, underscores, dots, and hyphens are allowed`,
+            reason: "name contains invalid characters. Only alphanumeric characters, underscores, dots, and hyphens are allowed",
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Validates that a tool name conforms to Claude API requirements.
+ * @param toolName The tool name to validate
+ * @returns Object with isValid boolean and error message if invalid
+ */
+export function validateToolName(toolName) {
+    const result = validateName(toolName);
+    if (!result.isValid) {
+        return { isValid: false, error: result.error?.replace("Name", "Tool name") };
+    }
+    return result;
+}
+/**
+ * Validates that a parameter name conforms to Claude API requirements.
+ * @param paramName The parameter name to validate
+ * @returns Object with isValid boolean and error message if invalid
+ */
+export function validateParameterName(paramName) {
+    const result = validateName(paramName);
+    if (!result.isValid) {
+        return { isValid: false, error: result.error?.replace("Name", "Parameter name") };
+    }
+    return result;
+}
+/**
+ * Extracts tool names from tool constant definitions
+ * @param fileContent - The content of a TypeScript file
+ * @returns Array of tool names found
+ */
+export function extractToolNames(fileContent) {
+    const toolNames = [];
+    // Pattern to match tool constant definitions in tool objects
+    // This looks for patterns like: const SOMETHING_TOOLS = { ... } or const Test_Plan_Tools = { ... }
+    const toolsObjectPattern = /const\s+\w*[Tt][Oo][Oo][Ll][Ss]?\s*=\s*\{([^}]+)\}/g;
+    let toolsMatch;
+    while ((toolsMatch = toolsObjectPattern.exec(fileContent)) !== null) {
+        const objectContent = toolsMatch[1];
+        // Now extract individual tool definitions from within the object
+        const toolPattern = /^\s*[a-zA-Z_][a-zA-Z0-9_]*:\s*"([^"]+)"/gm;
+        let match;
+        while ((match = toolPattern.exec(objectContent)) !== null) {
+            toolNames.push(match[1]);
+        }
+    }
+    return toolNames;
+}
+/**
+ * Extracts parameter names from Zod schema definitions
+ * @param fileContent - The content of a TypeScript file
+ * @returns Array of parameter names found
+ */
+export function extractParameterNames(fileContent) {
+    const paramNames = [];
+    // Pattern to match parameter definitions like: paramName: z.string()
+    const paramPattern = /^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*z\./gm;
+    let match;
+    while ((match = paramPattern.exec(fileContent)) !== null) {
+        paramNames.push(match[1]);
+    }
+    return paramNames;
+}

package/dist/tools/advsec.js

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+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, tokenProvider, connectionProvider) {
+    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))
+            .optional()
+            .describe("Filter alerts by type. If not specified, returns all alert types."),
+        states: z
+            .array(z.enum(getEnumKeys(State)))
+            .optional()
+            .describe("Filter alerts by state. If not specified, returns alerts in any state."),
+        severities: z
+            .array(z.enum(getEnumKeys(Severity)))
+            .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)))
+            .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)))
+            .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 };

package/dist/tools/core.test.js

@@ -0,0 +1 @@
+export {};