@azure-devops/mcp 1.2.1 → 1.3.1-nightly.20250807

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
 
@@ -74,6 +73,7 @@ Interact with these Azure DevOps services:
 - **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_work_items_link**: Link work items together in batch.
+- **wit_work_item_unlink**: Unlink one or many links from a work item.
 
 #### Deprecated Tools
 
@@ -95,6 +95,7 @@ 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**: Replies to a specific comment on a pull request.
 - **repo_resolve_comment**: Resolves a specific comment thread on a pull request.
@@ -118,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.
@@ -135,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
 
@@ -176,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
 {
@@ -298,45 +196,32 @@ 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. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
+> To start, just include "`This project uses Azure DevOps. Always check to see if the Azure DevOps MCP server has a tool relevant to the user's request`" in your copilot instructions file.
 
-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/repos.js

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
-import { PullRequestStatus, GitVersionType, GitPullRequestQueryType, } from "azure-devops-node-api/interfaces/GitInterfaces.js";
+import { PullRequestStatus, GitVersionType, GitPullRequestQueryType, CommentThreadStatus, } from "azure-devops-node-api/interfaces/GitInterfaces.js";
 import { z } from "zod";
 import { getCurrentUserDetails } from "./auth.js";
 import { getEnumKeys } from "../utils.js";
@@ -16,7 +16,7 @@ const REPO_TOOLS = {
     get_branch_by_name: "repo_get_branch_by_name",
     get_pull_request_by_id: "repo_get_pull_request_by_id",
     create_pull_request: "repo_create_pull_request",
-    update_pull_request_status: "repo_update_pull_request_status",
+    update_pull_request: "repo_update_pull_request",
     update_pull_request_reviewers: "repo_update_pull_request_reviewers",
     reply_to_comment: "repo_reply_to_comment",
     create_pull_request_thread: "repo_create_pull_request_thread",
@@ -82,10 +82,18 @@ function configureRepoTools(server, tokenProvider, connectionProvider) {
         description: z.string().optional().describe("The description of the pull request. Optional."),
         isDraft: z.boolean().optional().default(false).describe("Indicates whether the pull request is a draft. Defaults to false."),
         workItems: z.string().optional().describe("Work item IDs to associate with the pull request, space-separated."),
-    }, async ({ repositoryId, sourceRefName, targetRefName, title, description, isDraft, workItems }) => {
+        forkSourceRepositoryId: z.string().optional().describe("The ID of the fork repository that the pull request originates from. Optional, used when creating a pull request from a fork."),
+    }, async ({ repositoryId, sourceRefName, targetRefName, title, description, isDraft, workItems, forkSourceRepositoryId }) => {
         const connection = await connectionProvider();
         const gitApi = await connection.getGitApi();
         const workItemRefs = workItems ? workItems.split(" ").map((id) => ({ id: id.trim() })) : [];
+        const forkSource = forkSourceRepositoryId
+            ? {
+                repository: {
+                    id: forkSourceRepositoryId,
+                },
+            }
+            : undefined;
         const pullRequest = await gitApi.createPullRequest({
             sourceRefName,
             targetRefName,
@@ -93,20 +101,44 @@ function configureRepoTools(server, tokenProvider, connectionProvider) {
             description,
             isDraft,
             workItemRefs: workItemRefs,
+            forkSource,
         }, repositoryId);
         return {
             content: [{ type: "text", text: JSON.stringify(pullRequest, null, 2) }],
         };
     });
-    server.tool(REPO_TOOLS.update_pull_request_status, "Update status of an existing pull request to active or abandoned.", {
+    server.tool(REPO_TOOLS.update_pull_request, "Update a Pull Request by ID with specified fields.", {
         repositoryId: z.string().describe("The ID of the repository where the pull request exists."),
-        pullRequestId: z.number().describe("The ID of the pull request to be published."),
-        status: z.enum(["Active", "Abandoned"]).describe("The new status of the pull request. Can be 'Active' or 'Abandoned'."),
-    }, async ({ repositoryId, pullRequestId, status }) => {
+        pullRequestId: z.number().describe("The ID of the pull request to update."),
+        title: z.string().optional().describe("The new title for the pull request."),
+        description: z.string().optional().describe("The new description for the pull request."),
+        isDraft: z.boolean().optional().describe("Whether the pull request should be a draft."),
+        targetRefName: z.string().optional().describe("The new target branch name (e.g., 'refs/heads/main')."),
+        status: z.enum(["Active", "Abandoned"]).optional().describe("The new status of the pull request. Can be 'Active' or 'Abandoned'."),
+    }, async ({ repositoryId, pullRequestId, title, description, isDraft, targetRefName, status }) => {
         const connection = await connectionProvider();
         const gitApi = await connection.getGitApi();
-        const statusValue = status === "Active" ? PullRequestStatus.Active.valueOf() : PullRequestStatus.Abandoned.valueOf();
-        const updatedPullRequest = await gitApi.updatePullRequest({ status: statusValue }, repositoryId, pullRequestId);
+        // Build update object with only provided fields
+        const updateRequest = {};
+        if (title !== undefined)
+            updateRequest.title = title;
+        if (description !== undefined)
+            updateRequest.description = description;
+        if (isDraft !== undefined)
+            updateRequest.isDraft = isDraft;
+        if (targetRefName !== undefined)
+            updateRequest.targetRefName = targetRefName;
+        if (status !== undefined) {
+            updateRequest.status = status === "Active" ? PullRequestStatus.Active.valueOf() : PullRequestStatus.Abandoned.valueOf();
+        }
+        // Validate that at least one field is provided for update
+        if (Object.keys(updateRequest).length === 0) {
+            return {
+                content: [{ type: "text", text: "Error: At least one field (title, description, isDraft, targetRefName, or status) must be provided for update." }],
+                isError: true,
+            };
+        }
+        const updatedPullRequest = await gitApi.updatePullRequest(updateRequest, repositoryId, pullRequestId);
         return {
             content: [{ type: "text", text: JSON.stringify(updatedPullRequest, null, 2) }],
         };
@@ -375,10 +407,11 @@ function configureRepoTools(server, tokenProvider, connectionProvider) {
     server.tool(REPO_TOOLS.get_pull_request_by_id, "Get a pull request by its ID.", {
         repositoryId: z.string().describe("The ID of the repository where the pull request is located."),
         pullRequestId: z.number().describe("The ID of the pull request to retrieve."),
-    }, async ({ repositoryId, pullRequestId }) => {
+        includeWorkItemRefs: z.boolean().optional().default(false).describe("Whether to reference work items associated with the pull request."),
+    }, async ({ repositoryId, pullRequestId, includeWorkItemRefs }) => {
         const connection = await connectionProvider();
         const gitApi = await connection.getGitApi();
-        const pullRequest = await gitApi.getPullRequest(repositoryId, pullRequestId);
+        const pullRequest = await gitApi.getPullRequest(repositoryId, pullRequestId, undefined, undefined, undefined, undefined, undefined, includeWorkItemRefs);
         return {
             content: [{ type: "text", text: JSON.stringify(pullRequest, null, 2) }],
         };
@@ -416,6 +449,11 @@ function configureRepoTools(server, tokenProvider, connectionProvider) {
         content: z.string().describe("The content of the comment to be added."),
         project: z.string().optional().describe("Project ID or project name (optional)"),
         filePath: z.string().optional().describe("The path of the file where the comment thread will be created. (optional)"),
+        status: z
+            .enum(getEnumKeys(CommentThreadStatus))
+            .optional()
+            .default(CommentThreadStatus[CommentThreadStatus.Active])
+            .describe("The status of the comment thread. Defaults to 'Active'."),
         rightFileStartLine: z.number().optional().describe("Position of first character of the thread's span in right file. The line number of a thread's position. Starts at 1. (optional)"),
         rightFileStartOffset: z
             .number()
@@ -429,7 +467,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider) {
             .number()
             .optional()
             .describe("Position of last character of the thread's span in right file. The character offset of a thread's position inside of a line. Must only be set if rightFileEndLine is also specified. (optional)"),
-    }, async ({ repositoryId, pullRequestId, content, project, filePath, rightFileStartLine, rightFileStartOffset, rightFileEndLine, rightFileEndOffset }) => {
+    }, async ({ repositoryId, pullRequestId, content, project, filePath, status, rightFileStartLine, rightFileStartOffset, rightFileEndLine, rightFileEndOffset }) => {
         const connection = await connectionProvider();
         const gitApi = await connection.getGitApi();
         const threadContext = { filePath: filePath };
@@ -460,7 +498,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider) {
                 threadContext.rightFileEnd.offset = rightFileEndOffset;
             }
         }
-        const thread = await gitApi.createThread({ comments: [{ content: content }], threadContext: threadContext }, repositoryId, pullRequestId, project);
+        const thread = await gitApi.createThread({ comments: [{ content: content }], threadContext: threadContext, status: CommentThreadStatus[status] }, repositoryId, pullRequestId, project);
         return {
             content: [{ type: "text", text: JSON.stringify(thread, null, 2) }],
         };

package/dist/tools/testplans.js

@@ -79,7 +79,7 @@ function configureTestPlanTools(server, tokenProvider, connectionProvider) {
     server.tool(Test_Plan_Tools.create_test_case, "Creates a new test case work item.", {
         project: z.string().describe("The unique identifier (ID or name) of the Azure DevOps project."),
         title: z.string().describe("The title of the test case."),
-        steps: z.string().optional().describe("The steps to reproduce the test case. Make sure to format each step as '1. Step one\\n2. Step two' etc."),
+        steps: z.string().optional().describe("The steps to reproduce the test case. Make sure to format each step as '1. Step one|Expected result one\n2. Step two|Expected result two"),
         priority: z.number().optional().describe("The priority of the test case."),
         areaPath: z.string().optional().describe("The area path for the test case."),
         iterationPath: z.string().optional().describe("The iteration path for the test case."),
@@ -165,17 +165,21 @@ function configureTestPlanTools(server, tokenProvider, connectionProvider) {
  * Helper function to convert steps text to XML format required
  */
 function convertStepsToXml(steps) {
+    // Accepts steps in the format: '1. Step one|Expected result one\n2. Step two|Expected result two'
     const stepsLines = steps.split("\n").filter((line) => line.trim() !== "");
     let xmlSteps = `<steps id="0" last="${stepsLines.length}">`;
     for (let i = 0; i < stepsLines.length; i++) {
         const stepLine = stepsLines[i].trim();
         if (stepLine) {
-            const stepMatch = stepLine.match(/^(\d+)\.\s*(.+)$/);
-            const stepText = stepMatch ? stepMatch[2] : stepLine;
+            // Split step and expected result by '|', fallback to default if not provided
+            const [stepPart, expectedPart] = stepLine.split("|").map((s) => s.trim());
+            const stepMatch = stepPart.match(/^(\d+)\.\s*(.+)$/);
+            const stepText = stepMatch ? stepMatch[2] : stepPart;
+            const expectedText = expectedPart || "Verify step completes successfully";
             xmlSteps += `
                 <step id="${i + 1}" type="ActionStep">
                     <parameterizedString isformatted="true">${escapeXml(stepText)}</parameterizedString>
-                    <parameterizedString isformatted="true">Verify step completes successfully</parameterizedString>
+                    <parameterizedString isformatted="true">${escapeXml(expectedText)}</parameterizedString>
                 </step>`;
         }
     }

package/dist/tools/workitems.js

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+import { WorkItemExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { QueryExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { z } from "zod";
 import { batchApiVersion, markdownCommentsApiVersion, getEnumKeys, safeEnumConvert } from "../utils.js";
@@ -21,6 +22,7 @@ const WORKITEM_TOOLS = {
     get_query_results_by_id: "wit_get_query_results_by_id",
     update_work_items_batch: "wit_update_work_items_batch",
     work_items_link: "wit_work_items_link",
+    work_item_unlink: "wit_work_item_unlink",
 };
 function getLinkTypeFromName(name) {
     switch (name.toLowerCase()) {
@@ -46,6 +48,8 @@ function getLinkTypeFromName(name) {
             return "Microsoft.VSTS.Common.Affects-Forward";
         case "affected by":
             return "Microsoft.VSTS.Common.Affects-Reverse";
+        case "artifact":
+            return "ArtifactLink";
         default:
             throw new Error(`Unknown link type: ${name}`);
     }
@@ -92,11 +96,26 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
     server.tool(WORKITEM_TOOLS.get_work_items_batch_by_ids, "Retrieve list of work items by IDs in batch.", {
         project: z.string().describe("The name or ID of the Azure DevOps project."),
         ids: z.array(z.number()).describe("The IDs of the work items to retrieve."),
-    }, async ({ project, ids }) => {
+        fields: z.array(z.string()).optional().describe("Optional list of fields to include in the response. If not provided, a hardcoded default set of fields will be used."),
+    }, async ({ project, ids, fields }) => {
         const connection = await connectionProvider();
         const workItemApi = await connection.getWorkItemTrackingApi();
-        const fields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.Parent", "System.Tags"];
-        const workitems = await workItemApi.getWorkItemsBatch({ ids, fields }, project);
+        const defaultFields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.Parent", "System.Tags", "Microsoft.VSTS.Common.StackRank", "System.AssignedTo"];
+        // If no fields are provided, use the default set of fields
+        const fieldsToUse = !fields || fields.length === 0 ? defaultFields : fields;
+        const workitems = await workItemApi.getWorkItemsBatch({ ids, fields: fieldsToUse }, project);
+        // Format the assignedTo field to include displayName and uniqueName
+        // Removing the identity object as the response. It's too much and not needed
+        if (workitems && Array.isArray(workitems)) {
+            workitems.forEach((item) => {
+                if (item.fields && item.fields["System.AssignedTo"] && typeof item.fields["System.AssignedTo"] === "object") {
+                    const assignedTo = item.fields["System.AssignedTo"];
+                    const name = assignedTo.displayName || "";
+                    const email = assignedTo.uniqueName || "";
+                    item.fields["System.AssignedTo"] = `${name} <${email}>`.trim();
+                }
+            });
+        }
         return {
             content: [{ type: "text", text: JSON.stringify(workitems, null, 2) }],
         };
@@ -279,13 +298,15 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
         repositoryId: z.string().describe("The ID of the repository containing the pull request. Do not use the repository name here, use the ID instead."),
         pullRequestId: z.number().describe("The ID of the pull request to link to."),
         workItemId: z.number().describe("The ID of the work item to link to the pull request."),
-    }, async ({ projectId, repositoryId, pullRequestId, workItemId }) => {
+        pullRequestProjectId: z.string().optional().describe("The project ID containing the pull request. If not provided, defaults to the work item's project ID (for same-project linking)."),
+    }, async ({ projectId, repositoryId, pullRequestId, workItemId, pullRequestProjectId }) => {
         try {
             const connection = await connectionProvider();
             const workItemTrackingApi = await connection.getWorkItemTrackingApi();
             // Create artifact link relation using vstfs format
             // Format: vstfs:///Git/PullRequestId/{project}/{repositoryId}/{pullRequestId}
-            const artifactPathValue = `${projectId}/${repositoryId}/${pullRequestId}`;
+            const artifactProjectId = pullRequestProjectId && pullRequestProjectId.trim() !== "" ? pullRequestProjectId : projectId;
+            const artifactPathValue = `${artifactProjectId}/${repositoryId}/${pullRequestId}`;
             const vstfsUrl = `vstfs:///Git/PullRequestId/${encodeURIComponent(artifactPathValue)}`;
             // Use the PATCH document format for adding a relation
             const patchDocument = [
@@ -573,5 +594,69 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
+    server.tool(WORKITEM_TOOLS.work_item_unlink, "Remove one or many links from a single work item", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        id: z.number().describe("The ID of the work item to remove the links from."),
+        type: z
+            .enum(["parent", "child", "duplicate", "duplicate of", "related", "successor", "predecessor", "tested by", "tests", "affects", "affected by", "artifact"])
+            .default("related")
+            .describe("Type of link to remove. Options include 'parent', 'child', 'duplicate', 'duplicate of', 'related', 'successor', 'predecessor', 'tested by', 'tests', 'affects', 'affected by', and 'artifact'. Defaults to 'related'."),
+        url: z.string().optional().describe("Optional URL to match for the link to remove. If not provided, all links of the specified type will be removed."),
+    }, async ({ project, id, type, url }) => {
+        try {
+            const connection = await connectionProvider();
+            const workItemApi = await connection.getWorkItemTrackingApi();
+            const workItem = await workItemApi.getWorkItem(id, undefined, undefined, WorkItemExpand.Relations, project);
+            const relations = workItem.relations ?? [];
+            const linkType = getLinkTypeFromName(type);
+            let relationIndexes = [];
+            if (url && url.trim().length > 0) {
+                // If url is provided, find relations matching both rel type and url
+                relationIndexes = relations.map((relation, idx) => (relation.url === url ? idx : -1)).filter((idx) => idx !== -1);
+            }
+            else {
+                // If url is not provided, find all relations matching rel type
+                relationIndexes = relations.map((relation, idx) => (relation.rel === linkType ? idx : -1)).filter((idx) => idx !== -1);
+            }
+            if (relationIndexes.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No matching relations found for link type '${type}'${url ? ` and URL '${url}'` : ""}.\n${JSON.stringify(relations, null, 2)}` }],
+                    isError: true,
+                };
+            }
+            // Get the relations that will be removed for logging
+            const removedRelations = relationIndexes.map((idx) => relations[idx]);
+            // Sort indexes in descending order to avoid index shifting when removing
+            relationIndexes.sort((a, b) => b - a);
+            const apiUpdates = relationIndexes.map((idx) => ({
+                op: "remove",
+                path: `/relations/${idx}`,
+            }));
+            const updatedWorkItem = await workItemApi.updateWorkItem(null, apiUpdates, id, project);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Removed ${removedRelations.length} link(s) of type '${type}':\n` +
+                            JSON.stringify(removedRelations, null, 2) +
+                            `\n\nUpdated work item result:\n` +
+                            JSON.stringify(updatedWorkItem, null, 2),
+                    },
+                ],
+                isError: false,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error unlinking work item: ${error instanceof Error ? error.message : "Unknown error occurred"}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
 }
 export { WORKITEM_TOOLS, configureWorkItemTools };

package/dist/tools.js

@@ -1,14 +1,15 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
-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, tokenProvider, connectionProvider, userAgentProvider) {
     configureCoreTools(server, tokenProvider, connectionProvider);
     configureWorkTools(server, tokenProvider, connectionProvider);
@@ -19,5 +20,6 @@ function configureAllTools(server, tokenProvider, connectionProvider, userAgentP
     configureWikiTools(server, tokenProvider, connectionProvider);
     configureTestPlanTools(server, tokenProvider, connectionProvider);
     configureSearchTools(server, tokenProvider, connectionProvider, userAgentProvider);
+    configureAdvSecTools(server, tokenProvider, connectionProvider);
 }
 export { configureAllTools };

package/dist/utils.js

@@ -3,6 +3,32 @@
 export const apiVersion = "7.2-preview.1";
 export const batchApiVersion = "5.0";
 export const markdownCommentsApiVersion = "7.2-preview.4";
+export function createEnumMapping(enumObject) {
+    const mapping = {};
+    for (const [key, value] of Object.entries(enumObject)) {
+        if (typeof key === "string" && typeof value === "number") {
+            mapping[key.toLowerCase()] = value;
+        }
+    }
+    return mapping;
+}
+export function mapStringToEnum(value, enumObject, defaultValue) {
+    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(values, enumObject) {
+    if (!values)
+        return [];
+    return values.map((value) => mapStringToEnum(value, enumObject)).filter((v) => 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.

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "1.2.1";
+export const packageVersion = "1.3.1-nightly.20250807";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "1.2.1",
+  "version": "1.3.1-nightly.20250807",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
   "author": "Microsoft Corporation",
@@ -23,6 +23,7 @@
   "scripts": {
     "preinstall": "npm config set registry https://registry.npmjs.org/",
     "prebuild": "node -p \"'export const packageVersion = ' + JSON.stringify(require('./package.json').version) + ';\\n'\" > src/version.ts && prettier --write src/version.ts",
+    "validate-tools": "tsc --noEmit && node scripts/build-validate-tools.js",
     "build": "tsc && shx chmod +x dist/*.js",
     "prepare": "npm run build",
     "watch": "tsc --watch",
@@ -37,7 +38,7 @@
   },
   "dependencies": {
     "@azure/identity": "^4.10.0",
-    "@modelcontextprotocol/sdk": "1.16.0",
+    "@modelcontextprotocol/sdk": "1.17.0",
     "azure-devops-extension-api": "^4.252.0",
     "azure-devops-extension-sdk": "^4.0.2",
     "azure-devops-node-api": "^15.1.0",
@@ -51,6 +52,7 @@
     "@types/node": "^22",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-header": "^3.1.1",
+    "glob": "^11.0.3",
     "jest": "^30.0.2",
     "jest-extended": "^6.0.0",
     "prettier": "3.6.2",

package/dist/http.js

@@ -1,52 +0,0 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT License.
-import express from "express";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { serverBuildAndConnect } from "./server.js";
-import { packageVersion } from "./version.js";
-const app = express();
-app.use(express.json());
-app.post('/mcp/:orgName', async (req, res) => {
-    // In stateless mode, create a new instance of transport and server for each request
-    // to ensure complete isolation. A single instance would cause request ID collisions
-    // when multiple clients connect concurrently.
-    try {
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined,
-        });
-        const server = await serverBuildAndConnect(req.params.orgName, transport);
-        res.on('close', () => {
-            transport.close();
-            server.close();
-        });
-        await transport.handleRequest(req, res, req.body);
-    }
-    catch (error) {
-        console.error('Error handling MCP request:', error);
-        if (!res.headersSent) {
-            res.status(500).json({
-                jsonrpc: '2.0',
-                error: {
-                    code: -32603,
-                    message: 'Internal server error',
-                },
-                id: null,
-            });
-        }
-    }
-});
-app.get('/mcp/:orgName', async (req, res) => {
-    console.log('Received GET MCP request');
-    res.writeHead(405).end(JSON.stringify({
-        jsonrpc: "2.0",
-        error: {
-            code: -32000,
-            message: "Method not allowed."
-        },
-        id: null
-    }));
-});
-const PORT = 3000;
-app.listen(PORT, () => {
-    console.log(`Azure DevOps MCP Server with http transport listening on port ${PORT}. Version: ${packageVersion}`);
-});

package/dist/server.js

@@ -1,36 +0,0 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT License.
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import * as azdev from "azure-devops-node-api";
-import { DefaultAzureCredential } from "@azure/identity";
-import { configurePrompts } from "./prompts.js";
-import { configureAllTools } from "./tools.js";
-import { userAgent } from "./utils.js";
-import { packageVersion } from "./version.js";
-async function getAzureDevOpsToken() {
-    process.env.AZURE_TOKEN_CREDENTIALS = "dev";
-    const credential = new DefaultAzureCredential(); // CodeQL [SM05138] resolved by explicitly setting AZURE_TOKEN_CREDENTIALS
-    const token = await credential.getToken("499b84ac-1321-427f-aa17-267ca6975798/.default");
-    return token;
-}
-async function getAzureDevOpsClient(orgUrl) {
-    const token = await getAzureDevOpsToken();
-    const authHandler = azdev.getBearerHandler(token.token);
-    const connection = new azdev.WebApi(orgUrl, authHandler, undefined, {
-        productName: "AzureDevOps.MCP",
-        productVersion: packageVersion,
-        userAgent: userAgent
-    });
-    return connection;
-}
-export async function serverBuildAndConnect(orgName, transport) {
-    const server = new McpServer({
-        name: "Azure DevOps MCP Server",
-        version: packageVersion,
-    });
-    const orgUrl = "https://dev.azure.com/" + orgName;
-    configurePrompts(server);
-    configureAllTools(server, () => orgName, getAzureDevOpsToken, () => getAzureDevOpsClient(orgUrl));
-    await server.connect(transport);
-    return server;
-}