feat: Update work item comment format to default to Markdown (#1155)

This pull request standardizes the handling of the `format` parameter
for work item comments and field values in the Azure DevOps integration.
The default format is now consistently set to `"Markdown"` instead of
`"Html"` across all relevant tools, and the code logic and tests have
been updated to use the correct casing and default values. This ensures
more predictable behavior and aligns the API with user expectations.

## GitHub issue number
#1154

## **Associated Risks**

None

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

manual testing. updated automated tests to account for empty

Author: danhellem

src/tools/work-items.ts

@@ -356,7 +356,7 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
       project: z.string().optional().describe("The name or ID of the Azure DevOps project. Reuse from prior context if already known. If not provided, a project selection prompt will be shown."),
       workItemId: z.coerce.number().min(1).describe("The ID of the work item to add a comment to."),
       comment: z.string().describe("The text of the comment to add to the work item."),
-      format: z.enum(["markdown", "html"]).optional().default("html"),
+      format: z.enum(["Markdown", "Html"]).optional().default("Markdown").describe("The format of the comment text, e.g., 'Markdown', 'Html'. Optional, defaults to 'Markdown'."),
     },
     async ({ project, workItemId, comment, format }) => {
       try {
@@ -376,7 +376,7 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
           text: comment,
         };
 
-        const formatParameter = format === "markdown" ? 0 : 1;
+        const formatParameter = (format ?? "Markdown") === "Markdown" ? 0 : 1;
         const response = await fetch(
           `${orgUrl}/${encodeURIComponent(resolvedProject)}/_apis/wit/workItems/${workItemId}/comments?format=${formatParameter}&api-version=${markdownCommentsApiVersion}`,
           {
@@ -417,7 +417,7 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
       workItemId: z.coerce.number().min(1).describe("The ID of the work item."),
       commentId: z.coerce.number().min(1).describe("The ID of the comment to update."),
       text: z.string().describe("The updated comment text."),
-      format: z.enum(["markdown", "html"]).optional().default("html"),
+      format: z.enum(["Markdown", "Html"]).optional().default("Markdown").describe("The format of the comment text, e.g., 'Markdown', 'Html'. Optional, defaults to 'Markdown'."),
     },
     async ({ project, workItemId, commentId, text, format }) => {
       try {
@@ -433,8 +433,8 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
         const orgUrl = connection.serverUrl;
         const accessToken = await tokenProvider();
         const body: Record<string, string> = { text };
+        const formatParameter = (format ?? "Markdown") === "Markdown" ? 0 : 1;
 
-        const formatParameter = format === "markdown" ? 0 : 1;
         const response = await fetch(
           `${orgUrl}/${encodeURIComponent(resolvedProject)}/_apis/wit/workItems/${workItemId}/comments/${commentId}?format=${formatParameter}&api-version=${markdownCommentsApiVersion}`,
           {
@@ -547,7 +547,7 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
         z.object({
           title: z.string().describe("The title of the child work item."),
           description: z.string().describe("The description of the child work item."),
-          format: z.enum(["Markdown", "Html"]).default("Html").describe("Format for the description on the child work item, e.g., 'Markdown', 'Html'. Defaults to 'Html'."),
+          format: z.enum(["Markdown", "Html"]).default("Markdown").describe("Format for the description on the child work item, e.g., 'Markdown', 'Html'. Defaults to 'Markdown'."),
           areaPath: z.string().optional().describe("Optional area path for the child work item."),
           iterationPath: z.string().optional().describe("Optional iteration path for the child work item."),
         })
@@ -877,7 +877,7 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
           z.object({
             name: z.string().describe("The name of the field, e.g., 'System.Title'."),
             value: z.string().describe("The value of the field."),
-            format: z.enum(["Html", "Markdown"]).optional().describe("the format of the field value, e.g., 'Html', 'Markdown'. Optional, defaults to 'Html'."),
+            format: z.enum(["Html", "Markdown"]).optional().default("Markdown").describe("the format of the field value, e.g., 'Html', 'Markdown'. Optional, defaults to 'Markdown'."),
           })
         )
         .describe("A record of field names and values to set on the new work item. Each fild is the field name and each value is the corresponding value to set for that field."),
@@ -1027,7 +1027,11 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
             id: z.coerce.number().min(1).describe("The ID of the work item to update."),
             path: z.string().describe("The path of the field to update, e.g., '/fields/System.Title'."),
             value: z.string().describe("The new value for the field. This is required for 'add' and 'replace' operations, and should be omitted for 'remove' operations."),
-            format: z.enum(["Html", "Markdown"]).optional().describe("The format of the field value. Only to be used for large text fields. e.g., 'Html', 'Markdown'. Optional, defaults to 'Html'."),
+            format: z
+              .enum(["Html", "Markdown"])
+              .optional()
+              .default("Markdown")
+              .describe("The format of the field value. Only to be used for large text fields. e.g., 'Html', 'Markdown'. Optional, defaults to 'Markdown'."),
           })
         )
         .describe("An array of updates to apply to work items. Each update should include the operation (op), work item ID (id), field path (path), and new value (value)."),

test/src/tools/work-items.test.ts

@@ -819,7 +819,7 @@ describe("configureWorkItemTools", () => {
       const result = await handler(params);
 
       expect(mockFetch).toHaveBeenCalledWith(
-        "https://dev.azure.com/contoso/Contoso/_apis/wit/workItems/299/comments?format=1&api-version=7.2-preview.4",
+        "https://dev.azure.com/contoso/Contoso/_apis/wit/workItems/299/comments?format=0&api-version=7.2-preview.4",
         expect.objectContaining({
           method: "POST",
           headers: expect.objectContaining({
@@ -854,7 +854,7 @@ describe("configureWorkItemTools", () => {
         comment: "hello world!",
         project: "Contoso",
         workItemId: 299,
-        format: "markdown",
+        format: "Markdown",
       };
 
       const result = await handler(params);
@@ -873,6 +873,23 @@ describe("configureWorkItemTools", () => {
       expect(result.content[0].text).toBe(JSON.stringify(_mockWorkItemComment));
     });
 
+    it("should call Add Work Item Comments API with format=1 when format is Html", async () => {
+      configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
+
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "wit_add_work_item_comment");
+      if (!call) throw new Error("wit_add_work_item_comment tool not registered");
+      const [, , , handler] = call;
+
+      mockConnection.serverUrl = "https://dev.azure.com/contoso";
+      (tokenProvider as jest.Mock).mockResolvedValue("fake-token");
+      const mockFetch = jest.fn().mockResolvedValue({ ok: true, text: () => Promise.resolve(JSON.stringify(_mockWorkItemComment)) });
+      global.fetch = mockFetch;
+
+      await handler({ comment: "hello world!", project: "Contoso", workItemId: 299, format: "Html" });
+
+      expect(mockFetch).toHaveBeenCalledWith("https://dev.azure.com/contoso/Contoso/_apis/wit/workItems/299/comments?format=1&api-version=7.2-preview.4", expect.objectContaining({ method: "POST" }));
+    });
+
     it("should handle fetch failure response", async () => {
       configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
 
@@ -971,7 +988,7 @@ describe("configureWorkItemTools", () => {
       const result = await handler(params);
 
       expect(mockFetch).toHaveBeenCalledWith(
-        "https://dev.azure.com/contoso/TestProject/_apis/wit/workItems/42/comments/100?format=1&api-version=7.2-preview.4",
+        "https://dev.azure.com/contoso/TestProject/_apis/wit/workItems/42/comments/100?format=0&api-version=7.2-preview.4",
         expect.objectContaining({
           method: "PATCH",
           headers: expect.objectContaining({
@@ -4605,11 +4622,22 @@ describe("configureWorkItemTools", () => {
       (tokenProvider as jest.Mock).mockResolvedValue("fake-token");
       global.fetch = jest.fn().mockResolvedValue({ ok: true, text: () => Promise.resolve("{}") });
 
-      await handler({ project: "P", workItemId: 1, commentId: 1, text: "updated", format: "markdown" });
+      await handler({ project: "P", workItemId: 1, commentId: 1, text: "updated", format: "Markdown" });
       const calledUrl = (global.fetch as jest.Mock).mock.calls[0][0] as string;
       expect(calledUrl).toContain("format=0");
     });
 
+    it("update_work_item_comment: should use format=1 when format is Html", async () => {
+      const handler = getHandler("wit_update_work_item_comment");
+      mockConnection.serverUrl = "https://dev.azure.com/contoso";
+      (tokenProvider as jest.Mock).mockResolvedValue("fake-token");
+      global.fetch = jest.fn().mockResolvedValue({ ok: true, text: () => Promise.resolve("{}") });
+
+      await handler({ project: "P", workItemId: 1, commentId: 1, text: "updated", format: "Html" });
+      const calledUrl = (global.fetch as jest.Mock).mock.calls[0][0] as string;
+      expect(calledUrl).toContain("format=1");
+    });
+
     it("list_work_item_revisions: should return unknown error message for non-Error throws", async () => {
       const handler = getHandler("wit_list_work_item_revisions");
       (connectionProvider as jest.Mock).mockRejectedValue("string error");