Adding work_item_unlink to remove links from a work item (#365)

Added tool and tests to remove a link from a work item in batch. Meaning
you can remove several links at once.

## GitHub issue number #132 

## **Associated Risks**

N/A

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

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

Added all new automated tests and tested manually. Will post video and
prompts in follow-up commits or PR

---------

Co-authored-by: Copilot <[email protected]>

Author: danhellem

README.md

@@ -73,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
 

docs/EXAMPLES.md

@@ -10,6 +10,7 @@ This guide offers step-by-step examples for using the Azure DevOps MCP Server to
 [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)
 
 ## 🙋‍♂️ Projects and Teams
 
@@ -132,3 +133,19 @@ Update work item 12345 with a new description and use Markdown text. Use Markdow
 ```
 
 📽️ [Azure DevOps MCP Server: Using Markdown format for create and update work items](https://youtu.be/OD4c2m7Fj9U)
+
+### Remove One or More Links from a Work Item
+
+Use this tool to remove one or more links from a work item, either by specifying individual links or by link type.
+
+First, retrieve the work item whose links you want to remove:
+
+```plaintext
+Get work item 1234 in Contoso project and show me the relations
+```
+
+Next, remove a specific link to a work item, pull request, etc. or remove links by type (for example, "related"):
+
+```plaintext
+Remove link 5678 and 91011 from work item 1234. Also remove any related links and links to pull request 121314
+```

src/tools/workitems.ts

@@ -4,7 +4,7 @@
 import { AccessToken } from "@azure/identity";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebApi } from "azure-devops-node-api";
-import { WorkItemExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
+import { WorkItemExpand, WorkItemRelation } 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";
@@ -27,6 +27,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: string) {
@@ -53,6 +54,8 @@ function getLinkTypeFromName(name: string) {
       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}`);
   }
@@ -771,6 +774,85 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
       };
     }
   );
+
+  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: WorkItemRelation[] = workItem.relations ?? [];
+        const linkType = getLinkTypeFromName(type);
+
+        let relationIndexes: number[] = [];
+
+        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 };