@mcp-consultant-tools/azure-devops 27.0.0-beta.1 → 27.0.0-beta.10

package/build/index.js

@@ -10,6 +10,14 @@ import { realpathSync } from "node:fs";
 import { createMcpServer, createEnvLoader } from "@mcp-consultant-tools/core";
 import { AzureDevOpsService } from "./AzureDevOpsService.js";
 import { z } from 'zod';
+import { descWithExamples, WIQL_EXAMPLES, PATCH_OP_EXAMPLES, WORK_ITEM_FIELD_EXAMPLES, SYNC_TO_FILE_EXAMPLES, SYNC_FROM_FILE_EXAMPLES, SYNC_TASKS_TO_FILE_EXAMPLES, SYNC_TASKS_FROM_FILE_EXAMPLES, PR_BRANCH_REF_EXAMPLES, PR_MERGE_STRATEGY_EXAMPLES, PR_VOTE_EXAMPLES, } from './tool-examples.js';
+import { checkFieldFormats, workItemToMarkdown, commentsToMarkdown, buildPatchOperations, updateSyncRevision, getSyncConfig, ensureFolderExists, getWorkItemFilePath, getCommentsFilePath, fileExists, writeWorkItemFile, readWorkItemFile, readFileContent, listSyncedWorkItems, validateFolderPath, autoCommitMultipleFiles, 
+// Task sync utilities
+tasksToMarkdown, parseTasksMarkdown, buildTaskPatchOperations, buildNewTaskFields, getTasksFilePath, updateTasksFileAfterCreate, 
+// New work item utilities
+parseNewWorkItemMarkdown, buildNewWorkItemFields, generateNewWorkItemTemplate, convertNewFileToSynced, getNewWorkItemFilePath, findNextNewFileIndex, findNewWorkItemFiles, renameFile, 
+// Markdown format utilities
+getAllLargeTextFields, autoConvertFieldsToMarkdown, isHtmlContent, } from './sync/index.js';
 /**
  * Register azure-devops tools and prompts to an MCP server
  * @param server - The MCP server instance
@@ -316,6 +324,45 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
     // ========================================
     // TOOLS
     // ========================================
+    server.tool("get-configuration", "Get the configured Azure DevOps organization and projects. Use this to construct correct URLs.", {}, async () => {
+        try {
+            const organization = process.env.AZUREDEVOPS_ORGANIZATION;
+            const projects = process.env.AZUREDEVOPS_PROJECTS?.split(",").map(p => p.trim()).filter(p => p) || [];
+            const syncFolder = process.env.AZUREDEVOPS_SYNC_FOLDER || 'docs/user-stories';
+            if (!organization || projects.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Azure DevOps not configured. Set AZUREDEVOPS_ORGANIZATION and AZUREDEVOPS_PROJECTS environment variables.",
+                        }],
+                };
+            }
+            const config = {
+                organization,
+                projects,
+                syncFolder,
+                urlPatterns: {
+                    workItem: `https://dev.azure.com/${organization}/{project}/_workitems/edit/{id}`,
+                    pullRequest: `https://dev.azure.com/${organization}/{project}/_git/{repo}/pullrequest/{id}`,
+                    wiki: `https://dev.azure.com/${organization}/{project}/_wiki/wikis/{wikiName}/{pagePath}`,
+                },
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Azure DevOps Configuration:\n\n${JSON.stringify(config, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to get configuration: ${error.message}`,
+                    }],
+            };
+        }
+    });
     server.tool("get-wikis", "Get all wikis in an Azure DevOps project", {
         project: z.string().describe("The project name"),
     }, async ({ project }) => {
@@ -469,7 +516,7 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
             };
         }
     });
-    server.tool("azuredevops-str-replace-wiki-page", "Replace a specific string in an Azure DevOps wiki page without rewriting entire content. More efficient than update-wiki-page for small changes. (requires AZUREDEVOPS_ENABLE_WIKI_WRITE=true)", {
+    server.tool("ado-str-replace-wiki", "Replace a specific string in an Azure DevOps wiki page without rewriting entire content. More efficient than update-wiki-page for small changes. (requires AZUREDEVOPS_ENABLE_WIKI_WRITE=true)", {
         project: z.string().describe("The project name"),
         wikiId: z.string().describe("The wiki identifier (ID or name)"),
         pagePath: z.string().describe("The path to the wiki page (e.g., '/SharePoint-Online/04-DEV-Configuration')"),
@@ -535,7 +582,7 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
     });
     server.tool("query-work-items", "Query work items using WIQL (Work Item Query Language) in Azure DevOps", {
         project: z.string().describe("The project name"),
-        wiql: z.string().describe("The WIQL query string (e.g., \"SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.State] = 'Active'\")"),
+        wiql: z.string().describe(descWithExamples("The WIQL query string. SQL-like syntax with field names in brackets. Common fields: [System.Id], [System.Title], [System.State], [System.WorkItemType], [System.AssignedTo], [System.Parent]. Use @Me for current user.", WIQL_EXAMPLES)),
         maxResults: z.number().optional().describe("Maximum number of results (default: 200)"),
     }, async ({ project, wiql, maxResults }) => {
         try {
@@ -622,24 +669,53 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
             };
         }
     });
-    server.tool("update-work-item", "Update a work item in Azure DevOps using JSON Patch operations (requires AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true)", {
+    server.tool("update-work-item", "Update a work item in Azure DevOps using JSON Patch operations (requires AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true). Auto-injects markdown format operations for large text fields.", {
         project: z.string().describe("The project name"),
         workItemId: z.number().describe("The work item ID"),
         patchOperations: z.array(z.object({
-            op: z.string().describe("The operation type (e.g., 'add', 'replace', 'remove')"),
-            path: z.string().describe("The field path (e.g., '/fields/System.State')"),
+            op: z.string().describe("The operation type: 'add' (set value), 'replace' (update existing), or 'remove' (clear field)"),
+            path: z.string().describe("The field path starting with '/fields/' (e.g., '/fields/System.State', '/fields/System.Title')"),
             value: z.any().optional().describe("The value to set (not required for 'remove' operation)")
-        })).describe("Array of JSON Patch operations"),
-    }, async ({ project, workItemId, patchOperations }) => {
+        })).describe(descWithExamples("Array of JSON Patch operations. Each operation specifies what to change.", PATCH_OP_EXAMPLES)),
+        skipAutoConvert: z.boolean().optional().describe("Skip automatic markdown format injection for large text fields. Only use when explicitly requested. Default: false"),
+    }, async ({ project, workItemId, patchOperations, skipAutoConvert }) => {
         try {
             const service = getAzureDevOpsService();
-            const result = await service.updateWorkItem(project, workItemId, patchOperations);
+            // Auto-inject markdown format operations for large text fields
+            let finalOperations = [...patchOperations];
+            const formatOpsAdded = [];
+            if (!skipAutoConvert) {
+                // Find large text fields being updated (includes custom fields)
+                const allLargeTextFields = getAllLargeTextFields();
+                const largeTextFieldsBeingUpdated = patchOperations
+                    .filter((op) => op.path?.startsWith('/fields/'))
+                    .map((op) => op.path.replace('/fields/', ''))
+                    .filter((field) => allLargeTextFields.includes(field));
+                for (const field of largeTextFieldsBeingUpdated) {
+                    // Check if format operation already exists
+                    const hasFormatOp = finalOperations.some((op) => op.path === `/multilineFieldsFormat/${field}`);
+                    if (!hasFormatOp) {
+                        // Add format operation to ensure markdown
+                        finalOperations.push({
+                            op: 'add',
+                            path: `/multilineFieldsFormat/${field}`,
+                            value: 'Markdown'
+                        });
+                        formatOpsAdded.push(field);
+                    }
+                }
+            }
+            const result = await service.updateWorkItem(project, workItemId, finalOperations);
+            let message = `Updated work item ${workItemId}`;
+            if (formatOpsAdded.length > 0) {
+                message += ` (auto-set markdown format for: ${formatOpsAdded.join(', ')})`;
+            }
             const resultStr = JSON.stringify(result, null, 2);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Updated work item ${workItemId}:\n\n${resultStr}`,
+                        text: `${message}:\n\n${resultStr}`,
                     },
                 ],
             };
@@ -658,8 +734,8 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
     });
     server.tool("create-work-item", "Create a new work item in Azure DevOps with optional parent relationship (requires AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true)", {
         project: z.string().describe("The project name"),
-        workItemType: z.string().describe("The work item type (e.g., 'Bug', 'Task', 'User Story')"),
-        fields: z.record(z.any()).describe("Object with field values (e.g., {\"System.Title\": \"Bug title\", \"System.Description\": \"Details\"})"),
+        workItemType: z.string().describe("The work item type: 'Bug', 'Task', 'User Story', 'Feature', 'Epic', or custom types"),
+        fields: z.record(z.any()).describe(descWithExamples("Object with field values. Required: System.Title. Common fields: System.Description, System.State, System.AssignedTo, Microsoft.VSTS.Common.AcceptanceCriteria, Microsoft.VSTS.TCM.ReproSteps (bugs).", WORK_ITEM_FIELD_EXAMPLES)),
         parentId: z.number().optional().describe("Optional parent work item ID (for creating child items). Simplified alternative to relations parameter."),
         relations: z.array(z.object({
             rel: z.string().describe("Relation type (e.g., 'System.LinkTypes.Hierarchy-Reverse' for parent)"),
@@ -839,6 +915,120 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
                 return { content: [{ type: "text", text: `Failed to add pull request thread: ${error.message}` }] };
             }
         });
+        server.tool("create-pull-request", "Create a new pull request in a Git repository. (requires AZUREDEVOPS_ENABLE_PR_WRITE=true)", {
+            project: z.string().describe("The project name"),
+            repositoryId: z.string().describe("Repository ID (GUID) or name"),
+            sourceRefName: z.string().describe(descWithExamples("Source branch full ref name", PR_BRANCH_REF_EXAMPLES)),
+            targetRefName: z.string().describe(descWithExamples("Target branch full ref name", PR_BRANCH_REF_EXAMPLES)),
+            title: z.string().describe("Pull request title"),
+            description: z.string().optional().describe("Pull request description (markdown supported)"),
+            reviewerIds: z.array(z.string()).optional().describe("Reviewer GUIDs or unique names"),
+            isDraft: z.boolean().optional().describe("Create as draft PR (default: false)"),
+        }, async ({ project, repositoryId, sourceRefName, targetRefName, title, description, reviewerIds, isDraft }) => {
+            try {
+                const service = getAzureDevOpsService();
+                const result = await service.createPullRequest(project, repositoryId, sourceRefName, targetRefName, title, description, reviewerIds, isDraft);
+                return { content: [{ type: "text", text: `Created PR #${result.pullRequestId}:\n\n${JSON.stringify(result, null, 2)}` }] };
+            }
+            catch (error) {
+                console.error("Error creating pull request:", error);
+                return { content: [{ type: "text", text: `Failed to create pull request: ${error.message}` }] };
+            }
+        });
+        server.tool("update-pull-request", "Update a pull request's title, description, status, or draft state. (requires AZUREDEVOPS_ENABLE_PR_WRITE=true)", {
+            project: z.string().describe("The project name"),
+            repositoryId: z.string().describe("Repository ID (GUID) or name"),
+            pullRequestId: z.number().describe("The pull request ID"),
+            title: z.string().optional().describe("New title"),
+            description: z.string().optional().describe("New description"),
+            status: z.enum(["abandoned", "active"]).optional().describe("Set PR status (abandoned or active)"),
+            isDraft: z.boolean().optional().describe("Set draft state"),
+        }, async ({ project, repositoryId, pullRequestId, title, description, status, isDraft }) => {
+            try {
+                const service = getAzureDevOpsService();
+                const result = await service.updatePullRequest(project, repositoryId, pullRequestId, { title, description, status, isDraft });
+                return { content: [{ type: "text", text: `Updated PR #${pullRequestId}:\n\n${JSON.stringify(result, null, 2)}` }] };
+            }
+            catch (error) {
+                console.error("Error updating pull request:", error);
+                return { content: [{ type: "text", text: `Failed to update pull request: ${error.message}` }] };
+            }
+        });
+        server.tool("complete-pull-request", "Complete (merge) a pull request with configurable merge strategy. (requires AZUREDEVOPS_ENABLE_PR_WRITE=true)", {
+            project: z.string().describe("The project name"),
+            repositoryId: z.string().describe("Repository ID (GUID) or name"),
+            pullRequestId: z.number().describe("The pull request ID"),
+            mergeStrategy: z.enum(["squash", "noFastForward", "rebase", "rebaseMerge"]).optional()
+                .describe(descWithExamples("Merge strategy (default: squash)", PR_MERGE_STRATEGY_EXAMPLES)),
+            deleteSourceBranch: z.boolean().optional().describe("Delete source branch after merge (default: true)"),
+            transitionWorkItems: z.boolean().optional().describe("Transition linked work items (default: true)"),
+            mergeCommitMessage: z.string().optional().describe("Custom merge commit message"),
+        }, async ({ project, repositoryId, pullRequestId, mergeStrategy, deleteSourceBranch, transitionWorkItems, mergeCommitMessage }) => {
+            try {
+                const service = getAzureDevOpsService();
+                const result = await service.completePullRequest(project, repositoryId, pullRequestId, mergeStrategy || 'squash', deleteSourceBranch !== undefined ? deleteSourceBranch : true, transitionWorkItems !== undefined ? transitionWorkItems : true, mergeCommitMessage);
+                return { content: [{ type: "text", text: `Completed PR #${pullRequestId}:\n\n${JSON.stringify(result, null, 2)}` }] };
+            }
+            catch (error) {
+                console.error("Error completing pull request:", error);
+                return { content: [{ type: "text", text: `Failed to complete pull request: ${error.message}` }] };
+            }
+        });
+        server.tool("add-pr-reviewer", "Add or remove a reviewer from a pull request. (requires AZUREDEVOPS_ENABLE_PR_WRITE=true)", {
+            project: z.string().describe("The project name"),
+            repositoryId: z.string().describe("Repository ID (GUID) or name"),
+            pullRequestId: z.number().describe("The pull request ID"),
+            reviewerId: z.string().describe("Reviewer GUID or unique name"),
+            isRequired: z.boolean().optional().describe("Whether the reviewer is required (default: false)"),
+            remove: z.boolean().optional().describe("Set to true to remove the reviewer instead of adding"),
+        }, async ({ project, repositoryId, pullRequestId, reviewerId, isRequired, remove }) => {
+            try {
+                const service = getAzureDevOpsService();
+                const result = await service.addOrRemovePrReviewer(project, repositoryId, pullRequestId, reviewerId, isRequired, remove);
+                return { content: [{ type: "text", text: `${remove ? 'Removed' : 'Added'} reviewer on PR #${pullRequestId}:\n\n${JSON.stringify(result, null, 2)}` }] };
+            }
+            catch (error) {
+                console.error("Error managing PR reviewer:", error);
+                return { content: [{ type: "text", text: `Failed to manage PR reviewer: ${error.message}` }] };
+            }
+        });
+        server.tool("vote-pull-request", "Submit a vote (approve, reject, etc.) on a pull request. Defaults to authenticated user. (requires AZUREDEVOPS_ENABLE_PR_WRITE=true)", {
+            project: z.string().describe("The project name"),
+            repositoryId: z.string().describe("Repository ID (GUID) or name"),
+            pullRequestId: z.number().describe("The pull request ID"),
+            vote: z.enum(["approve", "approveWithSuggestions", "noResponse", "waitForAuthor", "reject"])
+                .describe(descWithExamples("Vote to submit", PR_VOTE_EXAMPLES)),
+            reviewerId: z.string().optional().describe("Reviewer GUID (defaults to authenticated user)"),
+        }, async ({ project, repositoryId, pullRequestId, vote, reviewerId }) => {
+            try {
+                const service = getAzureDevOpsService();
+                const result = await service.votePullRequest(project, repositoryId, pullRequestId, vote, reviewerId);
+                return { content: [{ type: "text", text: `Voted '${vote}' on PR #${pullRequestId}:\n\n${JSON.stringify(result, null, 2)}` }] };
+            }
+            catch (error) {
+                console.error("Error voting on pull request:", error);
+                return { content: [{ type: "text", text: `Failed to vote on pull request: ${error.message}` }] };
+            }
+        });
+        server.tool("reply-to-pr-thread", "Reply to a pull request comment thread and/or update thread status (e.g., resolve). (requires AZUREDEVOPS_ENABLE_PR_WRITE=true)", {
+            project: z.string().describe("The project name"),
+            repositoryId: z.string().describe("Repository ID (GUID) or name"),
+            pullRequestId: z.number().describe("The pull request ID"),
+            threadId: z.number().describe("The thread ID to reply to"),
+            content: z.string().optional().describe("Reply text (markdown supported)"),
+            status: z.enum(["active", "fixed", "wontFix", "closed", "byDesign", "pending"]).optional()
+                .describe("Update thread status (e.g., 'fixed' to resolve)"),
+        }, async ({ project, repositoryId, pullRequestId, threadId, content, status }) => {
+            try {
+                const service = getAzureDevOpsService();
+                const result = await service.replyToPrThread(project, repositoryId, pullRequestId, threadId, content, status);
+                return { content: [{ type: "text", text: `Reply to thread #${threadId} on PR #${pullRequestId}:\n\n${JSON.stringify(result, null, 2)}` }] };
+            }
+            catch (error) {
+                console.error("Error replying to PR thread:", error);
+                return { content: [{ type: "text", text: `Failed to reply to PR thread: ${error.message}` }] };
+            }
+        });
     }
     // ========================================
     // VARIABLE GROUP TOOLS
@@ -900,9 +1090,736 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
             };
         }
     });
+    // ========================================
+    // BUILD TROUBLESHOOTING TOOLS (Read-only)
+    // NOTE: These tools are duplicated in azure-devops-admin package.
+    // If you update these, also update packages/azure-devops-admin/src/index.ts
+    // ========================================
+    server.tool("get-build-status", "Get build status and details. Use detail='summary' for basic status, 'timeline' for step breakdown (default scope='problems' shows only failed/warning items), or 'full' for logs. The timelineScope controls what records are included: 'problems' (default, only errors/warnings), 'stages' (minimal), 'jobs' (moderate), 'all' (everything).", {
+        project: z.string().describe("The project name"),
+        buildId: z.number().describe("The build ID"),
+        detail: z.enum(["summary", "timeline", "full"]).optional().describe("Level of detail: 'summary' (default), 'timeline' (include steps), or 'full' (include logs)"),
+        timelineScope: z.enum(["stages", "jobs", "all", "problems"]).optional().describe("Timeline scope: 'problems' (default, only errors/warnings/failures), 'stages' (minimal), 'jobs' (moderate), 'all' (everything - may be large)"),
+        maxIssues: z.number().optional().describe("Maximum issues per record (default: 5, prioritizes errors over warnings)"),
+    }, async ({ project, buildId, detail, timelineScope, maxIssues }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const result = await service.getBuildStatus(project, buildId, detail || 'summary', timelineScope || 'problems', maxIssues || 5);
+            return { content: [{ type: "text", text: `Build ${buildId} status:\n\n${JSON.stringify(result, null, 2)}` }] };
+        }
+        catch (error) {
+            console.error("Error getting build status:", error);
+            return { content: [{ type: "text", text: `Failed to get build status: ${error.message}` }] };
+        }
+    });
+    server.tool("get-build-timeline", "Get step-by-step breakdown of a build. Shows stages, jobs, and tasks with timing, status, and error/warning counts. Use scope to control output size: 'problems' (default, only errors/warnings), 'stages' (minimal), 'jobs' (moderate), 'all' (everything). Always includes summary stats regardless of scope.", {
+        project: z.string().describe("The project name"),
+        buildId: z.number().describe("The build ID"),
+        scope: z.enum(["stages", "jobs", "all", "problems"]).optional().describe("Filter scope: 'problems' (default, only errors/warnings/failures), 'stages' (minimal), 'jobs' (moderate), 'all' (everything - may be large)"),
+        maxIssues: z.number().optional().describe("Maximum issues per record (default: 5, prioritizes errors over warnings)"),
+    }, async ({ project, buildId, scope, maxIssues }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const result = await service.getBuildTimeline(project, buildId, scope || 'problems', maxIssues || 5);
+            return { content: [{ type: "text", text: `Build ${buildId} timeline:\n\n${JSON.stringify(result, null, 2)}` }] };
+        }
+        catch (error) {
+            console.error("Error getting build timeline:", error);
+            return { content: [{ type: "text", text: `Failed to get build timeline: ${error.message}` }] };
+        }
+    });
+    server.tool("get-build-logs", "Get build logs. Without logId, returns list of available logs with line counts. With logId, returns that log's content. NOTE: For verbose logs, consider using a sub-agent to analyze the content.", {
+        project: z.string().describe("The project name"),
+        buildId: z.number().describe("The build ID"),
+        logId: z.number().optional().describe("Optional specific log ID to retrieve content"),
+    }, async ({ project, buildId, logId }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const result = await service.getBuildLogs(project, buildId, logId);
+            return { content: [{ type: "text", text: `Build ${buildId} logs:\n\n${JSON.stringify(result, null, 2)}` }] };
+        }
+        catch (error) {
+            console.error("Error getting build logs:", error);
+            return { content: [{ type: "text", text: `Failed to get build logs: ${error.message}` }] };
+        }
+    });
+    // ========================================
+    // WORK ITEM SYNC TOOLS (Local Markdown)
+    // ========================================
+    server.tool("sync-work-item-to-file", descWithExamples("Download work item(s) from ADO and save as local markdown file(s). Token-efficient for editing. Auto-converts HTML fields to markdown. Can also pull all child work items under a parent (e.g., all User Stories under a Feature).", SYNC_TO_FILE_EXAMPLES), {
+        project: z.string().describe("The project name"),
+        workItemIds: z.array(z.number()).default([]).describe("Work item IDs to pull (optional if using parentId)"),
+        parentId: z.number().optional().describe("Pull all child work items of this parent (e.g., Feature ID to pull all User Stories)"),
+        childType: z.string().optional().describe("Filter by work item type when using parentId (default: 'User Story'). Common values: 'User Story', 'Bug', 'Task'"),
+        folder: z.string().optional().describe("Override folder path (default: docs/user-stories or AZUREDEVOPS_SYNC_FOLDER)"),
+        includeComments: z.boolean().optional().describe("Also save comments to {id}-comments.md (default: false)"),
+        skipAutoConvert: z.boolean().optional().describe("Skip automatic HTML-to-markdown conversion. Only use when explicitly requested. Default: false (auto-convert enabled)"),
+    }, async ({ project, workItemIds: providedWorkItemIds, parentId, childType, folder, includeComments, skipAutoConvert }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            // Determine which work items to pull
+            let workItemIds = providedWorkItemIds || [];
+            // If parentId is provided, query for child work items
+            if (parentId) {
+                const type = childType || 'User Story';
+                const wiql = `SELECT [System.Id] FROM WorkItems WHERE [System.Parent] = ${parentId} AND [System.WorkItemType] = '${type}' ORDER BY [System.Id] ASC`;
+                const queryResult = await service.queryWorkItems(project, wiql, 200);
+                if (queryResult.workItems && queryResult.workItems.length > 0) {
+                    const childIds = queryResult.workItems.map((wi) => wi.id);
+                    workItemIds = [...workItemIds, ...childIds];
+                }
+            }
+            // Validate that we have work items to pull
+            if (workItemIds.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: parentId
+                                ? `No ${childType || 'User Story'} work items found under parent #${parentId}`
+                                : "No work item IDs provided. Specify workItemIds or parentId.",
+                        }],
+                };
+            }
+            // Remove duplicates
+            workItemIds = [...new Set(workItemIds)];
+            const pulled = [];
+            const skipped = [];
+            const commentsFiles = [];
+            const filesToCommit = [];
+            await ensureFolderExists(syncConfig.folder);
+            for (const workItemId of workItemIds) {
+                try {
+                    // Fetch work item from ADO
+                    let workItem = await service.getWorkItem(project, workItemId);
+                    let revision = workItem.rev || workItem._rev || 1;
+                    let convertedFields = [];
+                    // Check field formats
+                    const formats = checkFieldFormats(workItem);
+                    if (!formats.ready) {
+                        if (skipAutoConvert) {
+                            // User explicitly requested to skip conversion
+                            const htmlFields = [];
+                            if (formats.description === 'html')
+                                htmlFields.push('Description');
+                            if (formats.acceptanceCriteria === 'html')
+                                htmlFields.push('Acceptance Criteria');
+                            skipped.push({
+                                id: workItemId,
+                                reason: `HTML fields: ${htmlFields.join(', ')}. skipAutoConvert=true, skipping.`,
+                            });
+                            continue;
+                        }
+                        // Auto-convert HTML fields to markdown in ADO
+                        const fieldsToConvert = [];
+                        if (formats.description === 'html')
+                            fieldsToConvert.push('System.Description');
+                        if (formats.acceptanceCriteria === 'html')
+                            fieldsToConvert.push('Microsoft.VSTS.Common.AcceptanceCriteria');
+                        try {
+                            convertedFields = await autoConvertFieldsToMarkdown(service, project, workItemId, workItem.fields, fieldsToConvert);
+                            // Re-fetch work item with converted content
+                            workItem = await service.getWorkItem(project, workItemId);
+                            revision = workItem.rev || workItem._rev || 1;
+                        }
+                        catch (convertError) {
+                            skipped.push({
+                                id: workItemId,
+                                reason: `Failed to auto-convert HTML: ${convertError.message}`,
+                            });
+                            continue;
+                        }
+                    }
+                    // Convert to markdown and save
+                    const { content: markdown, skippedFields: secondarySkipped } = workItemToMarkdown(workItem, revision);
+                    const filePath = getWorkItemFilePath(syncConfig.folder, workItemId);
+                    await writeWorkItemFile(filePath, markdown);
+                    pulled.push({
+                        id: workItemId,
+                        file: filePath,
+                        revision,
+                        ...(convertedFields.length > 0 ? { converted: convertedFields } : {}),
+                        ...(secondarySkipped.length > 0 ? { skippedFields: secondarySkipped } : {}),
+                    });
+                    filesToCommit.push({ filePath, workItemId });
+                    // Optionally save comments
+                    if (includeComments) {
+                        const comments = await service.getWorkItemComments(project, workItemId);
+                        const commentsMarkdown = commentsToMarkdown(workItem, comments.comments || []);
+                        const commentsPath = getCommentsFilePath(syncConfig.folder, workItemId);
+                        await writeWorkItemFile(commentsPath, commentsMarkdown);
+                        commentsFiles.push({
+                            id: workItemId,
+                            file: commentsPath,
+                            count: (comments.comments || []).length,
+                        });
+                        filesToCommit.push({ filePath: commentsPath, workItemId });
+                    }
+                }
+                catch (error) {
+                    skipped.push({ id: workItemId, reason: error.message });
+                }
+            }
+            // Auto-commit if enabled
+            let committed = false;
+            if (syncConfig.autoCommit && filesToCommit.length > 0) {
+                const commitResult = await autoCommitMultipleFiles(filesToCommit, 'synced');
+                committed = commitResult.committed;
+            }
+            const result = {
+                pulled,
+                skipped,
+                ...(includeComments ? { commentsFiles } : {}),
+                folder: syncConfig.folder,
+                committed,
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Synced ${pulled.length} work item(s) to local files:\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error syncing work items to files:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to sync work items: ${error.message}`,
+                    }],
+            };
+        }
+    });
+    server.tool("sync-work-item-from-file", descWithExamples("Upload local markdown changes back to ADO. Auto-detects new_*.md files and creates them as new work items. Auto-converts HTML fields to markdown. Requires AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true.", SYNC_FROM_FILE_EXAMPLES), {
+        project: z.string().describe("The project name"),
+        workItemIds: z.array(z.number()).default([]).describe("Work item IDs to push (optional - new_*.md files are auto-detected)"),
+        folder: z.string().optional().describe("Override folder path (default: docs/user-stories or AZUREDEVOPS_SYNC_FOLDER)"),
+        skipAutoConvert: z.boolean().optional().describe("Skip automatic HTML-to-markdown conversion. Only use when explicitly requested. Default: false (auto-convert enabled)"),
+    }, async ({ project, workItemIds, folder, skipAutoConvert }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            const pushed = [];
+            const partial = [];
+            const created = [];
+            const failed = [];
+            // Step 1: Auto-detect and process new_*.md files
+            const newFiles = await findNewWorkItemFiles(syncConfig.folder);
+            for (const filePath of newFiles) {
+                try {
+                    // Parse the new work item file
+                    const content = await readFileContent(filePath);
+                    const parsed = parseNewWorkItemMarkdown(content);
+                    // Fetch parent work item to inherit area/iteration paths
+                    const parentWorkItem = await service.getWorkItem(project, parsed.frontmatter.parent);
+                    // Build fields for creation
+                    const fields = buildNewWorkItemFields(parsed, parentWorkItem);
+                    // Create the work item in ADO with parent link
+                    const createdWorkItem = await service.createWorkItem(project, parsed.frontmatter.type || 'User Story', fields, parsed.frontmatter.parent);
+                    const newId = createdWorkItem.id;
+                    const revision = createdWorkItem.rev || createdWorkItem._rev || 1;
+                    const url = createdWorkItem._links?.html?.href || `https://dev.azure.com/_workitems/edit/${newId}`;
+                    // Convert the file content to synced format
+                    const syncedContent = convertNewFileToSynced(content, newId, revision, url);
+                    // Rename file from new_*.md to {id}.md
+                    const newFilePath = getWorkItemFilePath(syncConfig.folder, newId);
+                    await writeWorkItemFile(newFilePath, syncedContent);
+                    await renameFile(filePath, filePath + '.created'); // Mark original as processed
+                    // Actually delete the .created file (cleanup)
+                    try {
+                        const fs = await import('node:fs/promises');
+                        await fs.unlink(filePath + '.created');
+                    }
+                    catch {
+                        // Ignore cleanup errors
+                    }
+                    created.push({
+                        id: newId,
+                        oldFile: filePath,
+                        newFile: newFilePath,
+                        parentId: parsed.frontmatter.parent,
+                    });
+                }
+                catch (error) {
+                    failed.push({ file: filePath, error: error.message });
+                }
+            }
+            // Step 2: Process existing work items (if workItemIds provided)
+            const idsToProcess = workItemIds || [];
+            for (const workItemId of idsToProcess) {
+                const filePath = getWorkItemFilePath(syncConfig.folder, workItemId);
+                try {
+                    // Check if file exists
+                    if (!await fileExists(filePath)) {
+                        failed.push({ id: workItemId, error: `File not found: ${filePath}` });
+                        continue;
+                    }
+                    // Parse local file
+                    const parsed = await readWorkItemFile(filePath);
+                    const oldRevision = parsed.frontmatter.lastSyncedRevision;
+                    // Fetch current work item from ADO to compare
+                    const currentWorkItem = await service.getWorkItem(project, workItemId);
+                    // Build patch operations (auto-converts HTML fields unless skipAutoConvert)
+                    const { operations, skippedFields, convertedFields } = buildPatchOperations(parsed, currentWorkItem, skipAutoConvert);
+                    if (operations.length === 0 && skippedFields.length === 0) {
+                        // No changes
+                        pushed.push({
+                            id: workItemId,
+                            oldRevision,
+                            newRevision: currentWorkItem.rev || currentWorkItem._rev || oldRevision,
+                            fieldsUpdated: [],
+                        });
+                        continue;
+                    }
+                    // Update ADO if there are operations
+                    let newRevision = oldRevision;
+                    let fieldsUpdated = [];
+                    if (operations.length > 0) {
+                        const updatedWorkItem = await service.updateWorkItem(project, workItemId, operations);
+                        newRevision = updatedWorkItem.rev || updatedWorkItem._rev || oldRevision + 1;
+                        // Filter out format operations from fieldsUpdated
+                        fieldsUpdated = operations
+                            .filter(op => op.path.startsWith('/fields/'))
+                            .map(op => op.path.replace('/fields/', ''));
+                        // Update local file with new revision
+                        const content = await readFileContent(filePath);
+                        const updatedContent = updateSyncRevision(content, newRevision);
+                        await writeWorkItemFile(filePath, updatedContent);
+                    }
+                    if (skippedFields.length > 0) {
+                        partial.push({
+                            id: workItemId,
+                            oldRevision,
+                            newRevision,
+                            fieldsUpdated,
+                            skippedFields,
+                            ...(convertedFields.length > 0 ? { convertedFields } : {}),
+                        });
+                    }
+                    else {
+                        pushed.push({
+                            id: workItemId,
+                            oldRevision,
+                            newRevision,
+                            fieldsUpdated,
+                            ...(convertedFields.length > 0 ? { convertedFields } : {}),
+                        });
+                    }
+                }
+                catch (error) {
+                    failed.push({ id: workItemId, error: error.message });
+                }
+            }
+            const result = {
+                created,
+                pushed,
+                partial,
+                failed,
+                folder: syncConfig.folder,
+            };
+            const summary = [];
+            if (created.length > 0)
+                summary.push(`Created ${created.length} new work item(s)`);
+            if (pushed.length > 0)
+                summary.push(`Updated ${pushed.length} work item(s)`);
+            if (partial.length > 0)
+                summary.push(`Partially updated ${partial.length} work item(s)`);
+            if (failed.length > 0)
+                summary.push(`Failed: ${failed.length}`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `${summary.join(', ')}:\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error syncing work items from files:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to push work items: ${error.message}`,
+                    }],
+            };
+        }
+    });
+    server.tool("check-work-item-markdown", "Check if work item fields are markdown (required for sync) or HTML format.", {
+        project: z.string().describe("The project name"),
+        workItemIds: z.array(z.number()).describe("Work item IDs to check"),
+    }, async ({ project, workItemIds }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const results = [];
+            let readyCount = 0;
+            let needsConversionCount = 0;
+            for (const workItemId of workItemIds) {
+                try {
+                    const workItem = await service.getWorkItem(project, workItemId);
+                    const formats = checkFieldFormats(workItem);
+                    results.push({
+                        id: workItemId,
+                        description: formats.description,
+                        acceptanceCriteria: formats.acceptanceCriteria,
+                        howToTest: formats.additionalFields.howToTest,
+                        predeploymentSteps: formats.additionalFields.predeploymentSteps,
+                        postdeploymentSteps: formats.additionalFields.postdeploymentSteps,
+                        deploymentInformation: formats.additionalFields.deploymentInformation,
+                        ready: formats.ready,
+                        ...(formats.warnings.length > 0 ? { warnings: formats.warnings } : {}),
+                    });
+                    if (formats.ready) {
+                        readyCount++;
+                    }
+                    else {
+                        needsConversionCount++;
+                    }
+                }
+                catch (error) {
+                    results.push({
+                        id: workItemId,
+                        description: 'error',
+                        acceptanceCriteria: 'error',
+                        ready: false,
+                        error: error.message || String(error),
+                    });
+                    needsConversionCount++;
+                }
+            }
+            const result = {
+                results,
+                summary: {
+                    ready: readyCount,
+                    needsConversion: needsConversionCount,
+                },
+                autoConvertAvailable: true,
+                message: needsConversionCount === 0
+                    ? 'All work items are markdown format - ready to sync'
+                    : `${needsConversionCount} work item(s) have HTML fields. Will be auto-converted to markdown on sync (unless skipAutoConvert=true).`,
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Work item format check:\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error checking work item formats:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to check work item formats: ${error.message}`,
+                    }],
+            };
+        }
+    });
+    server.tool("list-synced-work-items", "List work items that have been synced to local markdown files.", {
+        folder: z.string().optional().describe("Override folder path (default: docs/user-stories or AZUREDEVOPS_SYNC_FOLDER)"),
+    }, async ({ folder }) => {
+        try {
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            const workItems = await listSyncedWorkItems(syncConfig.folder);
+            const result = {
+                workItems,
+                folder: syncConfig.folder,
+                count: workItems.length,
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Synced work items in ${syncConfig.folder}:\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error listing synced work items:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to list synced work items: ${error.message}`,
+                    }],
+            };
+        }
+    });
+    server.tool("create-user-story-file", "Create a new user story template file locally. The file can be edited and then pushed to ADO using sync-work-item-from-file.", {
+        project: z.string().describe("The project name"),
+        parentId: z.number().describe("Parent Feature ID - the new user story will be created under this feature"),
+        folder: z.string().optional().describe("Override folder path (default: docs/user-stories or AZUREDEVOPS_SYNC_FOLDER)"),
+    }, async ({ project, parentId, folder }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            // Fetch parent work item to get title
+            const parentWorkItem = await service.getWorkItem(project, parentId);
+            const parentTitle = parentWorkItem.fields?.['System.Title'] || '';
+            // Find next available index for new file
+            const nextIndex = await findNextNewFileIndex(syncConfig.folder, parentId);
+            const filePath = getNewWorkItemFilePath(syncConfig.folder, parentId, nextIndex);
+            // Generate template content
+            const template = generateNewWorkItemTemplate(parentId, parentTitle, project, 'User Story');
+            // Ensure folder exists and write file
+            await ensureFolderExists(syncConfig.folder);
+            await writeWorkItemFile(filePath, template);
+            const result = {
+                file: filePath,
+                parentId,
+                parentTitle,
+                instructions: [
+                    `1. Edit the file to update title, description, and acceptance criteria`,
+                    `2. Run sync-work-item-from-file(project: "${project}") to create in ADO`,
+                    `3. The file will be renamed to {newId}.md after creation`,
+                ],
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Created new user story template:\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error creating user story file:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to create user story file: ${error.message}`,
+                    }],
+            };
+        }
+    });
+    // ========================================
+    // TASK SYNC TOOLS
+    // ========================================
+    server.tool("sync-tasks-to-file", descWithExamples("Download all tasks under a parent work item (User Story) to a local markdown file. Auto-converts HTML descriptions to markdown. Supports pulling tasks for multiple parents at once.", SYNC_TASKS_TO_FILE_EXAMPLES), {
+        project: z.string().describe("The project name"),
+        parentIds: z.array(z.number()).describe("Parent work item IDs (User Stories) to fetch tasks for"),
+        folder: z.string().optional().describe("Override folder path (default: docs/user-stories or AZUREDEVOPS_SYNC_FOLDER)"),
+        skipAutoConvert: z.boolean().optional().describe("Skip automatic HTML-to-markdown conversion for task descriptions. Only use when explicitly requested. Default: false"),
+    }, async ({ project, parentIds, folder, skipAutoConvert }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            const pulled = [];
+            const failed = [];
+            const filesToCommit = [];
+            await ensureFolderExists(syncConfig.folder);
+            for (const parentId of parentIds) {
+                try {
+                    // Fetch parent work item to get title and validate existence
+                    const parentWorkItem = await service.getWorkItem(project, parentId);
+                    // Query for child tasks using WIQL
+                    const wiql = `SELECT [System.Id] FROM WorkItems WHERE [System.Parent] = ${parentId} AND [System.WorkItemType] = 'Task' ORDER BY [System.Id] ASC`;
+                    const queryResult = await service.queryWorkItems(project, wiql, 200);
+                    // Fetch full details for each task and auto-convert HTML descriptions
+                    const tasks = [];
+                    let tasksConverted = 0;
+                    if (queryResult.workItems && queryResult.workItems.length > 0) {
+                        for (const wi of queryResult.workItems) {
+                            try {
+                                let task = await service.getWorkItem(project, wi.id);
+                                // Auto-convert HTML description to markdown unless skipAutoConvert
+                                const description = task.fields?.['System.Description'];
+                                if (description && !skipAutoConvert && isHtmlContent(description)) {
+                                    try {
+                                        await autoConvertFieldsToMarkdown(service, project, wi.id, task.fields, ['System.Description']);
+                                        // Re-fetch with converted content
+                                        task = await service.getWorkItem(project, wi.id);
+                                        tasksConverted++;
+                                    }
+                                    catch (convertError) {
+                                        console.error(`Failed to convert HTML description for task ${wi.id}:`, convertError.message);
+                                    }
+                                }
+                                tasks.push(task);
+                            }
+                            catch (taskError) {
+                                console.error(`Error fetching task ${wi.id}:`, taskError.message);
+                            }
+                        }
+                    }
+                    // Convert to markdown and save
+                    const markdown = tasksToMarkdown(parentWorkItem, tasks, project);
+                    const filePath = getTasksFilePath(syncConfig.folder, parentId);
+                    await writeWorkItemFile(filePath, markdown);
+                    pulled.push({
+                        parentId,
+                        file: filePath,
+                        taskCount: tasks.length,
+                    });
+                    filesToCommit.push({ filePath, workItemId: parentId });
+                }
+                catch (error) {
+                    failed.push({ parentId, error: error.message });
+                }
+            }
+            // Auto-commit if enabled
+            let committed = false;
+            if (syncConfig.autoCommit && filesToCommit.length > 0) {
+                const commitResult = await autoCommitMultipleFiles(filesToCommit, 'synced tasks for');
+                committed = commitResult.committed;
+            }
+            const result = {
+                pulled,
+                failed,
+                folder: syncConfig.folder,
+                committed,
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Synced tasks for ${pulled.length} parent(s) to local files:\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error syncing tasks to files:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to sync tasks: ${error.message}`,
+                    }],
+            };
+        }
+    });
+    server.tool("sync-tasks-from-file", descWithExamples("Push local task changes back to ADO with upsert semantics. Existing tasks (## Task #ID) are updated, new tasks (## NEW TASK) are created. Auto-converts HTML fields to markdown. Requires AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true.", SYNC_TASKS_FROM_FILE_EXAMPLES), {
+        project: z.string().describe("The project name"),
+        parentIds: z.array(z.number()).describe("Parent work item IDs to sync tasks for"),
+        folder: z.string().optional().describe("Override folder path (default: docs/user-stories or AZUREDEVOPS_SYNC_FOLDER)"),
+        skipAutoConvert: z.boolean().optional().describe("Skip automatic HTML-to-markdown conversion for task descriptions. Only use when explicitly requested. Default: false"),
+    }, async ({ project, parentIds, folder, skipAutoConvert }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            const updated = [];
+            const created = [];
+            const failed = [];
+            for (const parentId of parentIds) {
+                const filePath = getTasksFilePath(syncConfig.folder, parentId);
+                try {
+                    // Check if file exists
+                    if (!await fileExists(filePath)) {
+                        failed.push({ parentId, error: `File not found: ${filePath}` });
+                        continue;
+                    }
+                    // Parse local file
+                    const content = await readFileContent(filePath);
+                    const parsed = parseTasksMarkdown(content);
+                    // Get parent work item for area/iteration path
+                    const parentWorkItem = await service.getWorkItem(project, parentId);
+                    const parentFields = parentWorkItem.fields || {};
+                    const areaPath = parentFields['System.AreaPath'];
+                    const iterationPath = parentFields['System.IterationPath'];
+                    const createdInThisFile = [];
+                    // Process each task
+                    for (const task of parsed.tasks) {
+                        try {
+                            if (task.id !== null) {
+                                // Existing task - update (auto-converts HTML fields unless skipAutoConvert)
+                                const currentTask = await service.getWorkItem(project, task.id);
+                                const { operations, fieldsUpdated, convertedFields } = buildTaskPatchOperations(task, currentTask, skipAutoConvert);
+                                if (operations.length > 0) {
+                                    await service.updateWorkItem(project, task.id, operations);
+                                    updated.push({
+                                        id: task.id,
+                                        parentId,
+                                        fieldsUpdated,
+                                        ...(convertedFields.length > 0 ? { convertedFields } : {}),
+                                    });
+                                }
+                                else {
+                                    // No changes needed
+                                    updated.push({
+                                        id: task.id,
+                                        parentId,
+                                        fieldsUpdated: [],
+                                    });
+                                }
+                            }
+                            else {
+                                // New task - create
+                                if (!task.title) {
+                                    continue; // Skip tasks without title
+                                }
+                                const fields = buildNewTaskFields(task, areaPath, iterationPath);
+                                const createdTask = await service.createWorkItem(project, 'Task', fields, parentId);
+                                created.push({
+                                    id: createdTask.id,
+                                    parentId,
+                                    title: task.title,
+                                });
+                                createdInThisFile.push({
+                                    title: task.title,
+                                    id: createdTask.id,
+                                });
+                            }
+                        }
+                        catch (taskError) {
+                            failed.push({
+                                parentId,
+                                taskId: task.id || undefined,
+                                error: taskError.message,
+                            });
+                        }
+                    }
+                    // Update the file with new task IDs if any were created
+                    if (createdInThisFile.length > 0) {
+                        const updatedContent = updateTasksFileAfterCreate(content, createdInThisFile);
+                        await writeWorkItemFile(filePath, updatedContent);
+                    }
+                }
+                catch (error) {
+                    failed.push({ parentId, error: error.message });
+                }
+            }
+            const result = {
+                updated,
+                created,
+                failed,
+                folder: syncConfig.folder,
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Pushed tasks to ADO (${updated.length} updated, ${created.length} created):\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            console.error("Error syncing tasks from files:", error);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to push tasks: ${error.message}`,
+                    }],
+            };
+        }
+    });
     // Log registration summary (enablePullRequestWrite already defined above)
-    const baseToolsCount = 21; // 15 original + 6 PR read-only tools
-    const prWriteToolsCount = enablePullRequestWrite ? 1 : 0;
+    // Tool count breakdown:
+    // - Wiki: 6 (get-wikis, search-wiki-pages, get-wiki-page, create-wiki-page, update-wiki-page, str-replace-wiki-page)
+    // - Work Item: 7 (get-work-item, query-work-items, get-work-item-comments, add-work-item-comment, update-work-item, create-work-item, delete-work-item)
+    // - Variable Group: 2 (list-variable-groups, get-variable-group)
+    // - PR Read-only: 6 (list-repositories, list-pull-requests, get-pull-request, get-pull-request-threads, get-pull-request-commits, get-pull-request-changes)
+    // - Build Troubleshooting: 3 (get-build-status, get-build-timeline, get-build-logs)
+    // - Work Item Sync: 5 (sync-work-item-to-file, sync-work-item-from-file, check-work-item-markdown, list-synced-work-items, create-user-story-file)
+    // - Task Sync: 2 (sync-tasks-to-file, sync-tasks-from-file)
+    // - Config: 1 (get-configuration)
+    // Total base: 6 + 7 + 2 + 6 + 3 + 5 + 2 + 1 = 32
+    // + PR Write: 7 (add-pull-request-thread, create-pull-request, update-pull-request, complete-pull-request, add-pr-reviewer, vote-pull-request, reply-to-pr-thread) - conditional
+    const baseToolsCount = 32;
+    const prWriteToolsCount = enablePullRequestWrite ? 7 : 0;
     const totalToolsCount = baseToolsCount + prWriteToolsCount;
     console.error(`azure-devops tools registered: ${totalToolsCount} tools (${baseToolsCount} base + ${prWriteToolsCount} PR write), 4 prompts`);
     // NOTE: Admin tools (pipelines, service connections, agent pools, environments)