Encode markdown formatted fields by default

[agreaves-ms]

Summary

Encode HTML characters >, <, and additionally $ to their corresponding >, <, and $. The models (GPT-5 and Claude Sonnet 4, as an example) will use these characters without realizing that they will cause issue in Markdown, sometimes making it seem like parts of these field were truncated, instead of having malformed Markdown. Claude Sonnet also tends to turn > and < into > and < when explicitly requesting the model to encode these fields (or add the fields as-is with the encoding).

Example

(There should be <6 of something and >8 of something, the codeblock is missing lines as well)

Repro Steps

1. Use the azure-devops-mcp server with GitHub Copilot and Claude Sonnet 4 or GPT-5.
2. Ask it to use the mcp_ado_wit_create_work_item to create an Epic wth a Markdown formatted description. Ask it to add a list of metrics showing less than and greater than some metrics.

Expected

The Epic is made with a Markdown description and shows a list of metrics with > and < values.

Actual

The Markdown interpretter produces inconsistent content for the field leading to confusion.

[drk-mtr]

Although not related to character encoding, it may be relevant to note here that (as far as I know) Azure DevOps does not use proper spec-compliant HTML for lists.

In "Azure DevOps modified HTML", nested ol elements appear after the parent li element, rather than being contained within it. When converting markdown to HTML, the conversion needs to be to "Azure DevOps modified HTML" not "proper HTML", else lists exhibit some very frustrating behaviour when you try to modify them within DevOps.

I was using the following prompt to address this when I was writing a tool that covered a limited subset of the Azure DevOps MCP server:

1. The acceptance criteria input will be defined using markdown, and this should be translated to a specialised form of HTML that we will call "Azure DevOps Modified HTML". This will be done in two steps:
   1. Step 1 - Convert the markdown to HTML with the following rules:
      1. Always use ordered lists for numbered items i.e. always `<ol>` and never `<ul>`.
      1. Apply the following styles to lists (`<ol>` tags):
         - Use an inline style of `list-style:decimal` for all top level lists except the first one (levels 4, 7, 10 etc.)
         - Do not use any inline styles for the top level list (level 1)
         - Use an inlie style of `list-style:lower-alpha` for the second level of lists (levels 2, 5, 8, etc.)
         - Use an inline style of `list-style:lower-roman` for the third level (3, 6, 9, etc.)
      1. For markdown input that is not a list, do not convert it to a list, but instead convert it to a paragraph using `<p>` tags.
      1. When converting acceptance criteria written in Gherkin syntax (GIVEN / WHEN / THEN), do not use ordered or unordered list tags. Instead, format each step as a separate `<div>` element, and do not use `<p>` elements inside the `<div>` elements. Only use `<ol>` for actual numbered lists, not for scenario steps.
   1. Step 2 - Apply specific formatting rules to the HTML to translate it into "Azure DevOps Modified HTML".
      1. Reformat lists such that a nested list `ol` element will be moved AFTER the parent list `<li>` element, instead of being nested inside it, as follows:
         - This source HTML:
         ```html
         <ol>
           <li>
             Parent item
             <ol>
               <li>Child item 1</li>
               <li>Child item 2</li>
             </ol>
           </li>
           <li>Another parent item</li>
         </ol>
         ```
         - Will be transformed to:
         ```html
         <ol>
           <li>Parent item</li>
           <ol>
             <li>Child item 1</li>
             <li>Child item 2</li>
           </ol>
           <li>Another parent item</li>
         </ol>
         ```
      1. When transforming lists to "Azure DevOps Modified HTML", always move each nested <ol> directly after its containing <li> element, not after the parent <ol>. This rule must be strictly enforced for all acceptance criteria formatting.
      1. If the input is not a list, do not perform any further conversion.