Encode markdown formatted fields to prevent issues with >, <, and $ (#500)

This PR introduces an encoding utility for Markdown used in all work
item creation/update paths to prevent truncation/corruption when <, >,
and ${), appear in Markdown fields.

### Previously

<img width="1476" height="952" alt="image"
src="https://github.com/user-attachments/assets/fc15de30-1778-4034-9209-02a77b392da1"
/>

### With this change

<img width="1478" height="1042" alt="image"
src="https://github.com/user-attachments/assets/5a6cf713-4000-47df-b6b9-4e40ce6e5bb2"
/>


## GitHub issue number

## **Associated Risks**

The user may intend to use `>`,`<`,`$` for their Markdown.
* However, it's **signficantly** more likely the user will be using
GitHub Copilot or another AI coding tool, which the models tend to use
`<` and `>` to represent greater than some value (instead of intending
to use it as html embedded in Markdown).

## ✅ **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?**

I wrote tests and provided the following to Claude Sonnet 4 and GPT-5
both before and after this change:

````
Try creating a Markdown epic again with the following field values:
tool : mcp_ado_wit_create_work_item
args : {
  "fields": [
    {
      "name": "System.Title",
      "value": "Test Epic #3 - Comparison Operators < > in Metrics"
    },
    {
      "format": "Markdown",
      "name": "System.Description",
      "value": "This epic tests comparison operators in metric contexts:

## Metric Examples

- Example Metric: <5 of something
- Another Example Metric: >6 of something
- One Last Metric: <7 of something >8 of something

## Additional Test Cases

- Performance requirement: Response time <500ms
- Throughput requirement: Handle >1000 requests per second
- Memory usage: Keep memory <2GB but >1GB for optimal performance
- Error rate: Maintain error rate <1% and uptime >99.9%

## Code Context

```bash
if [ $count -lt 5 ]; then
  echo \"Count is <5\"
elif [ $count -gt 6 ]; then
  echo \"Count is >6\"
fi
```

Testing how these comparison operators are handled in various contexts."
    }
  ],
  "project": "REPLACE-ME",
  "workItemType": "Epic"
}
````

---------

Co-authored-by: Dan Hellem <dahellem@microsoft.com>

Author: agreaves-ms

src/tools/work-items.ts

@@ -7,7 +7,7 @@ import { WebApi } from "azure-devops-node-api";
 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";
+import { batchApiVersion, markdownCommentsApiVersion, getEnumKeys, safeEnumConvert, encodeFormattedValue } from "../utils.js";
 
 const WORKITEM_TOOLS = {
   my_work_items: "wit_my_work_items",
@@ -292,6 +292,8 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
         }
 
         const body = items.map((item, x) => {
+          const encodedDescription = encodeFormattedValue(item.description, item.format);
+
           const ops = [
             {
               op: "add",
@@ -306,12 +308,12 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
             {
               op: "add",
               path: "/fields/System.Description",
-              value: item.description,
+              value: encodedDescription,
             },
             {
               op: "add",
               path: "/fields/Microsoft.VSTS.TCM.ReproSteps",
-              value: item.description,
+              value: encodedDescription,
             },
             {
               op: "add",
@@ -562,10 +564,10 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
         const connection = await connectionProvider();
         const workItemApi = await connection.getWorkItemTrackingApi();
 
-        const document = fields.map(({ name, value }) => ({
+        const document = fields.map(({ name, value, format }) => ({
           op: "add",
           path: `/fields/${name}`,
-          value: value,
+          value: encodeFormattedValue(value, format),
         }));
 
         // Check if any field has format === "Markdown" and add the multilineFieldsFormat operation
@@ -675,10 +677,10 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
 
       const body = uniqueIds.map((id) => {
         const workItemUpdates = updates.filter((update) => update.id === id);
-        const operations = workItemUpdates.map(({ op, path, value }) => ({
+        const operations = workItemUpdates.map(({ op, path, value, format }) => ({
           op: op,
           path: path,
-          value: value,
+          value: encodeFormattedValue(value, format),
         }));
 
         // Add format operations for Markdown fields

src/utils.ts

@@ -27,7 +27,7 @@ export function mapStringToEnum<T extends Record<string, string | number>>(value
  * @param enumObject The enum object to map to
  * @returns Array of valid enum values
  */
-export function mapStringArrayToEnum<T extends Record<string, string | number>>(values: string[] | undefined, enumObject: T): Array<T[keyof T]> {
+export function mapStringArrayToEnum<T extends Record<string, string | number>>(values: string[] | undefined, enumObject: T): T[keyof T][] {
   if (!values) return [];
   return values.map((value) => mapStringToEnum(value, enumObject)).filter((v): v is T[keyof T] => v !== undefined);
 }
@@ -59,3 +59,16 @@ export function safeEnumConvert<T extends Record<string, string | number>>(enumO
 
   return enumObject[key as keyof T];
 }
+
+/**
+ * Encodes `>` and `<` for Markdown formatted fields.
+ *
+ * @param value The text value to encode
+ * @param format The format of the field ('Markdown' or 'Html')
+ * @returns The encoded text, or original text if format is not Markdown
+ */
+export function encodeFormattedValue(value: string, format?: "Markdown" | "Html"): string {
+  if (!value || format !== "Markdown") return value;
+  const result = value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return result;
+}

test/src/utils.test.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 import { AlertType, AlertValidityStatus, Confidence, Severity, State } from "azure-devops-node-api/interfaces/AlertInterfaces";
-import { createEnumMapping, getEnumKeys, mapStringArrayToEnum, mapStringToEnum, safeEnumConvert } from "../../src/utils";
+import { createEnumMapping, encodeFormattedValue, getEnumKeys, mapStringArrayToEnum, mapStringToEnum, safeEnumConvert } from "../../src/utils";
 
 describe("utils", () => {
   describe("createEnumMapping", () => {
@@ -431,3 +431,40 @@ describe("utils", () => {
     });
   });
 });
+
+describe("encodeFormattedValue", () => {
+  describe("basic encoding behavior (always encode in Markdown)", () => {
+    it("encodes angle brackets and dollar signs", () => {
+      const input = "Value <x> $var > end";
+      const result = encodeFormattedValue(input, "Markdown");
+      expect(result).toBe("Value &lt;x&gt; $var &gt; end");
+    });
+
+    it("does nothing for Html format", () => {
+      const input = "Value <x> $var > end";
+      const result = encodeFormattedValue(input, "Html");
+      expect(result).toBe(input);
+    });
+
+    it("returns original when format undefined", () => {
+      const input = "<raw> $";
+      expect(encodeFormattedValue(input)).toBe(input);
+    });
+
+    it("handles empty/null/undefined", () => {
+      expect(encodeFormattedValue("", "Markdown")).toBe("");
+      expect(encodeFormattedValue(null as unknown as string, "Markdown")).toBe(null);
+      expect(encodeFormattedValue(undefined as unknown as string, "Markdown")).toBe(undefined);
+    });
+  });
+
+  describe("idempotence and entity protection", () => {
+    it("does not double encode entities", () => {
+      const input = "Already &lt;tag&gt; plus <new> and $cash";
+      const once = encodeFormattedValue(input, "Markdown");
+      const twice = encodeFormattedValue(once, "Markdown");
+      expect(once).toBe("Already &lt;tag&gt; plus &lt;new&gt; and $cash");
+      expect(twice).toBe(once);
+    });
+  });
+});