Merge branch 'microsoft:main' into main

ShriHumrudha · web-flow · commit f6870b144213 · 2025-08-13T22:35:11.000+05:30
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ 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. [📝 Troubleshooting](#-troubleshooting)
-6. [🎩 Examples & Best Practices](#-samples--best-practices)
+6. [🎩 Examples & Best Practices](#-examples--best-practices)
 7. [🙋‍♀️ Frequently Asked Questions](#️-frequently-asked-questions)
 8. [📌 Contributing](#-contributing)
 
@@ -198,13 +198,13 @@ In your project, add a `.vscode\mcp.json` file with the following content:
 
 Save the file, then click 'Start'.
 
-<img src="./docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
+![start mcp server](./docs/media/start-mcp-server.gif)
 
 In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
 
 Click "Select Tools" and choose the available tools.
 
-<img src="./docs/media/configure-mcp-server-tools.gif" alt="configure mcp server tools" width="300"/>
+![configure mcp server tools](./docs/media/configure-mcp-server-tools.gif)
 
 Open GitHub Copilot Chat and try a prompt like `List ADO projects`.
 
diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md
@@ -1,16 +1,19 @@
+# Azure DevOps MCP Server: Example Usage
+
 This guide offers step-by-step examples for using the Azure DevOps MCP Server to interact with your Azure DevOps organization. For additional tips and best practices, see the [How To guide](./HOWTO.md).
 
 > 📝 These examples have been tested and validated only in English. If you encounter issues when using a different language, please open an issue in the repository so we can investigate.
 
-[Get List of Projects](#get-list-of-projects)<br/>
-[Get List of Teams](#get-list-of-teams)<br/>
-[Get My Work Items](#get-my-work-items)<br/>
-[Get Work Items in a Backlog](#get-all-work-items-in-a-backlog)<br/>
-[Retrieve and Edit Work Items](#retrieve-and-edit-work-items)<br/>
-[Create and Link Test Cases](#create-and-link-test-cases)<br/>
-[Triage Work](#triage-work)<br/>
-[Using Markdown Format](#adding-and-updating-work-items-using-the-format-paramater)<br/>
-[Remove Links from a Work Item](#remove-one-or-more-links-from-a-work-item)
+- [Get List of Projects](#get-list-of-projects)
+- [Get List of Teams](#get-list-of-teams)
+- [Get My Work Items](#get-my-work-items)
+- [Get Work Items in a Backlog](#get-all-work-items-in-a-backlog)
+- [Retrieve and Edit Work Items](#retrieve-and-edit-work-items)
+- [Create and Link Test Cases](#create-and-link-test-cases)
+- [Triage Work](#triage-work)
+- [Using Markdown Format](#adding-and-updating-work-items-using-the-format-paramater)
+- [Remove Links from a Work Item](#remove-one-or-more-links-from-a-work-item)
+- [Adding Artifact Links](#adding-artifact-links)
 
 ## 🙋‍♂️ Projects and Teams
 
@@ -149,3 +152,36 @@ Next, remove a specific link to a work item, pull request, etc. or remove links
 ```plaintext
 Remove link 5678 and 91011 from work item 1234. Also remove any related links and links to pull request 121314
 ```
+
+## 🔗 Adding Artifact Links
+
+### Add Artifact Links to Work Items
+
+Use this tool to associate work items with repository artifacts such as branches, commits, and pull requests.
+
+You have two options for linking artifacts:
+
+Supply the complete artifact `vstfs` URI in the required format. For example:
+
+**Branch**:
+`vstfs:///Git/Ref/{projectId}%2F{repositoryId}%2FGB{branchName}`
+
+**Commit**:
+`vstfs:///Git/Commit/{projectId}%2F{repositoryId}%2F{commitId}`
+
+**Pull Request**:
+`vstfs:///Git/PullRequestId/{projectId}%2F{repositoryId}%2F{pullRequestId}`
+
+```text
+Add a branch artifact link to work item 1234 in project "Contoso" with URI "vstfs:///Git/Ref/12341234-1234-1234-1234-123412341234%2F12341234-1234-1234-1234-123412341234%2FGBmain" and link type "Branch" with comment "Linked to main branch for GitHub Copilot integration"
+```
+
+Alternatively, you can simply provide the branch, commit, pull request, or build identifiers directly, and the tool will automatically construct the required artifact URI for you.
+
+For example:
+
+```text
+Get me the list of pull requests for Constoso project and Frabrikam repo. Then link the first pull request to work item 12345.
+```
+
+📽️ [Azure Devops MCP Server: Adding artifact links](https://youtu.be/t8HqEt8cZtY)
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -1,13 +1,15 @@
+# Frequently Asked Questions
+
 Before you get started, ensure you follow the steps in the `README.md` file. This will help you get up and running and connected to your Azure DevOps organization.
 
-### Does the MCP Server support both Azure DevOps Services and on-premises deployments?
+## Does the MCP Server support both Azure DevOps Services and on-premises deployments?
 
 Currently, the MCP Server supports only Azure DevOps Services. Several required API endpoints are not yet available for on-premises deployments. Additionally, focusing on Azure DevOps Services during the public preview makes it easier to debug and deliver fixes.
 
-### Can I connect to more than one organization at a time?
+## Can I connect to more than one organization at a time?
 
 No, you can connect to only one organization at a time. However, you can switch organizations as needed.
 
-### Can I set a default project instead of fetching the list every time?
+## Can I set a default project instead of fetching the list every time?
 
 Currently, you need to fetch the list of projects so the LLM has context about the project name or ID. We plan to improve this experience in the future by leveraging prompts. In the meantime, you can set a default project name in your `copilot-instructions.md` file.
diff --git a/docs/GETTINGSTARTED.md b/docs/GETTINGSTARTED.md
@@ -2,12 +2,12 @@
 
 This guide will help you get started with the Azure DevOps MCP Server in different environments.
 
-[Prerequisites](#prerequisites)<br/>
-[Getting started with Visual Studio Code & GitHub Copilot](#-visual-studio-code--github-copilot)<br/>
-[Getting started with Visual Studio 2022 & GitHub Copilot](#-visual-studio-2022--github-copilot)<br/>
-[Getting started with Claude Code](#-using-mcp-server-with-claude-code)<br/>
-[Getting started with Cursor](#-using-mcp-server-with-cursor)<br/>
-[Optimizing Your Experience](#-optimizing-your-experience)<br/>
+- [Prerequisites](#-prerequisites)
+- [Getting started with Visual Studio Code & GitHub Copilot](#️-visual-studio-code--github-copilot)
+- [Getting started with Visual Studio 2022 & GitHub Copilot](#-visual-studio-2022--github-copilot-1)
+- [Getting started with Claude Code](#-using-mcp-server-with-claude-code)
+- [Getting started with Cursor](#-using-mcp-server-with-cursor)
+- [Optimizing Your Experience](#-optimizing-your-experience)
 
 ## 🕐 Prerequisites
 
@@ -80,13 +80,13 @@ In your project, add a `.vscode\mcp.json` file with the following content:
 
 Save the file, then click 'Start'.
 
-<img src="../docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
+![start mcp server](../docs/media/start-mcp-server.gif)
 
 In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
 
 Click "Select Tools" and choose the available tools.
 
-<img src="../docs/media/configure-mcp-server-tools.gif" alt="configure mcp server tools" width="300"/>
+![configure mcp server tools](../docs/media/configure-mcp-server-tools.gif)
 
 > 💥 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.
 
@@ -136,13 +136,13 @@ Edit or add `.vscode/mcp.json`:
 
 Start the Azure DevOps MCP Server.
 
-<img src="../docs/media/start-mcp-server.gif" alt="start mcp server" width="250"/>
+![start mcp server](../docs/media/start-mcp-server.gif)
 
 In chat, switch to [Agent Mode](https://code.visualstudio.com/blogs/2025/02/24/introducing-copilot-agent-mode).
 
 Click "Select Tools" and choose the available tools.
 
-<img src="../docs/media/configure-mcp-server-tools.gif" alt="configure mcp server tools" width="300"/>
+![configure mcp server tools](../docs/media/configure-mcp-server-tools.gif)
 
 > 💥 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.
 
@@ -183,13 +183,13 @@ Save the file.
 
 Add your organization name by clicking on the `input` option.
 
-<img src="../docs/media/start-mcp-server-from-vs.png" alt="start mcp server from visual studio 2022" width="250"/>
+![start mcp server from visual studio 2022](../docs/media/start-mcp-server-from-vs.png)
 
 Open Copilot chat and switch to [Agent Mode](https://learn.microsoft.com/en-us/visualstudio/ide/copilot-agent-mode?view=vs-2022).
 
 Click the "Tools" icon and choose the available tools.
 
-<img src="../docs/media/set-tools-from-vs.png" alt="set tools to use in visual studio 2022" width="250"/>
+![set tools to use in visual studio 2022](../docs/media/set-tools-from-vs.png)
 
 > 💥 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.
 
@@ -210,7 +210,7 @@ See https://docs.anthropic.com/en/docs/claude-code/mcp for general guidance on a
 
 For the Azure DevOps MCP Server, use the following command:
 
-```
+```bash
 claude mcp add azure-devops -- npx -y @azure-devops/mcp Contoso
 ```
 
@@ -235,13 +235,13 @@ Replace `{Contoso}` with your actual Azure DevOps organization name.
 
 Save the file, and when Cursor detects the MCP Server, click **Enable**.
 
-<img src="../docs/media/enable-mcp-server-from-cursor.png" alt="enable mcp server from cursor" width="500"/>
+![enable mcp server from cursor](../docs/media/enable-mcp-server-from-cursor.png)
 
 #### Start the Azure DevOps MCP Server
 
 Open the terminal and start the MCP Server with:
 
-```
+```bash
 npx -y @azure-devops/mcp {Contoso}
 ```
 
diff --git a/docs/HOWTO.md b/docs/HOWTO.md
@@ -1,16 +1,16 @@
-Be sure to follow all the steps in the [Getting Started guide](./GETTINGSTARTED.md) to quickly set up and connect to your Azure DevOps organization.
-
 # 🥇 How to make your experience better
 
-### Modify Copilot Instructions
+Be sure to follow all the steps in the [Getting Started guide](./GETTINGSTARTED.md) to quickly set up and connect to your Azure DevOps organization.
+
+## Modify Copilot Instructions
 
 The `.github/copilot-instructions.md` file is a great way to customize the GitHub Copilot experience, especially when working with MCP Server for Azure DevOps.
 
 From the [GitHub documentation](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot):
 
 > Instead of repeatedly adding this contextual detail to your chat questions, you can create a file in your repository that automatically adds this information for you. The additional information is not displayed in the chat but is available to Copilot to allow it to generate higher-quality responses.
 
-#### Example Modification
+## Example Modification
 
 Here is an example modification you can add to your existing `.github/copilot-instructions.md` file.
 
@@ -20,6 +20,6 @@ Here is an example modification you can add to your existing `.github/copilot-in
 When getting work items using MCP Server for Azure DevOps, always try to use batch tools for updates instead of many individual single updates. For updates, try and update up to 200 updates in a single batch. When getting work items, once you get the list of IDs, use the tool `get_work_items_batch_by_ids` to get the work item details. By default, show fields ID, Type, Title, State. Show work item results in a rendered markdown table.
 ```
 
-### Use different models
+## Use different models
 
 Communicating with the LLM is both an art and a science. If the model does not respond well, switching to a different model may improve your results.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -30,17 +30,22 @@
 1. **npm Authentication Issues for Remote Access**
    If you encounter authentication errors:
    - Ensure you are logged in to Azure DevOps using the `az` CLI:
+
      ```pwsh
      az login
      ```
+
    - Verify your npm configuration:
+
      ```pwsh
      npm config get registry
      ```
+
      It should point to: `https://registry.npmjs.org/`
 
 2. **Dependency Installation Errors**
    If `npm install` fails, verify that you are using Node.js version 20 or higher. You can check your Node.js version with:
+
    ```pwsh
    node -v
    ```
@@ -135,22 +140,22 @@ The MCP server may be authenticating with a different tenant than your Azure Dev
 
 If the tenant configuration solution above doesn't resolve your authentication issues, and you're working in a **Dev Container** or **WSL (Windows Subsystem for Linux)** environment, the root cause may be different.
 
-#### Symptoms
+#### Dev Container/WSL Symptoms
 
 - Same authorization errors as above (`TF400813: The user 'xxx' is not authorized to access this resource`)
 - Tenant ID configuration didn't resolve the issue
 - You're using VS Code with Dev Containers or WSL
 - MCP server is configured in User Settings (global) rather than workspace settings
 
-#### Root Cause
+#### Dev Container/WSL Root Cause
 
 When MCP servers are configured in **User Settings** (global configuration), they inherit the environment context from the **host machine**, including `az login` authentication settings. In Dev Container or WSL scenarios, this means:
 
 - The MCP server uses the host machine's Azure authentication
 - Any `az login` performed inside the Dev Container or WSL environment is ignored
 - There may be a mismatch between the authentication context the MCP server expects and your development environment
 
-#### Solution
+#### Dev Container/WSL Solution
 
 1. **Verify your MCP configuration location**:
    - Check if your MCP server is configured in User Settings (global) vs Workspace Settings
diff --git a/src/tools/workitems.ts b/src/tools/workitems.ts
diff --git a/test/src/tools/workitems.test.ts b/test/src/tools/workitems.test.ts
