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

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAMH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAI7D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,GAAG,EAAE,kBAAkB,CAAC,EAAE,kBAAkB,QAkkC5F;AAED;;GAEG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAMH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAgC7D;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,GAAG,EAAE,kBAAkB,CAAC,EAAE,kBAAkB,QAgrD5F;AAED;;GAEG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}

package/build/index.js

@@ -10,6 +10,9 @@ import { realpathSync } from "node:fs";
 import { createMcpServer, createEnvLoader } from "@mcp-consultant-tools/core";
 import { AzureDevOpsService } from "./AzureDevOpsService.js";
 import { z } from 'zod';
+import { checkFieldFormats, getConversionInstructions, workItemToMarkdown, commentsToMarkdown, buildPatchOperations, updateSyncRevision, getSyncConfig, ensureFolderExists, getWorkItemFilePath, getCommentsFilePath, fileExists, writeWorkItemFile, readWorkItemFile, readFileContent, listSyncedWorkItems, validateFolderPath, autoCommitMultipleFiles, 
+// Task sync utilities
+tasksToMarkdown, parseTasksMarkdown, buildTaskPatchOperations, buildNewTaskFields, getTasksFilePath, updateTasksFileAfterCreate, } from './sync/index.js';
 /**
  * Register azure-devops tools and prompts to an MCP server
  * @param server - The MCP server instance
@@ -316,6 +319,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 }) => {
@@ -900,8 +942,493 @@ export function registerAzureDevOpsTools(server, azuredevopsService) {
             };
         }
     });
+    // ========================================
+    // WORK ITEM SYNC TOOLS (Local Markdown)
+    // ========================================
+    server.tool("sync-work-item-to-file", "Download work item(s) from ADO and save as local markdown file(s). Token-efficient for editing. Requires markdown format fields (not HTML).", {
+        project: z.string().describe("The project name"),
+        workItemIds: z.array(z.number()).describe("Work item IDs to pull"),
+        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)"),
+    }, async ({ project, workItemIds, folder, includeComments }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            const pulled = [];
+            const skipped = [];
+            const commentsFiles = [];
+            const filesToCommit = [];
+            await ensureFolderExists(syncConfig.folder);
+            for (const workItemId of workItemIds) {
+                try {
+                    // Fetch work item from ADO
+                    const workItem = await service.getWorkItem(project, workItemId);
+                    const revision = workItem.rev || workItem._rev || 1;
+                    // Check field formats
+                    const formats = checkFieldFormats(workItem);
+                    if (!formats.ready) {
+                        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(', ')}. Convert to markdown in ADO first.`,
+                        });
+                        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,
+                        ...(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", "Upload local markdown changes back to ADO. Requires AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true. Only updates markdown fields.", {
+        project: z.string().describe("The project name"),
+        workItemIds: z.array(z.number()).describe("Work item IDs to push"),
+        folder: z.string().optional().describe("Override folder path (default: docs/user-stories or AZUREDEVOPS_SYNC_FOLDER)"),
+    }, async ({ project, workItemIds, folder }) => {
+        try {
+            const service = getAzureDevOpsService();
+            const syncConfig = getSyncConfig(folder);
+            // Validate folder path for security
+            validateFolderPath(syncConfig.folder);
+            const pushed = [];
+            const partial = [];
+            const failed = [];
+            for (const workItemId of workItemIds) {
+                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
+                    const { operations, skippedFields } = buildPatchOperations(parsed, currentWorkItem);
+                    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;
+                        fieldsUpdated = operations.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,
+                        });
+                    }
+                    else {
+                        pushed.push({
+                            id: workItemId,
+                            oldRevision,
+                            newRevision,
+                            fieldsUpdated,
+                        });
+                    }
+                }
+                catch (error) {
+                    failed.push({ id: workItemId, error: error.message });
+                }
+            }
+            const result = {
+                pushed,
+                partial,
+                failed,
+                folder: syncConfig.folder,
+            };
+            return {
+                content: [{
+                        type: "text",
+                        text: `Pushed ${pushed.length} work item(s) to ADO:\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,
+                },
+                conversionInstructions: needsConversionCount > 0 ? getConversionInstructions() : undefined,
+            };
+            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}`,
+                    }],
+            };
+        }
+    });
+    // ========================================
+    // TASK SYNC TOOLS
+    // ========================================
+    server.tool("sync-tasks-to-file", "Download all tasks under a parent work item (User Story) to a local markdown file. Supports pulling tasks for multiple parents at once.", {
+        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)"),
+    }, async ({ project, parentIds, folder }) => {
+        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
+                    const tasks = [];
+                    if (queryResult.workItems && queryResult.workItems.length > 0) {
+                        for (const wi of queryResult.workItems) {
+                            try {
+                                const task = await service.getWorkItem(project, wi.id);
+                                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", "Push local task changes back to ADO with upsert semantics. Existing tasks (## Task #ID) are updated, new tasks (## NEW TASK) are created. Requires AZUREDEVOPS_ENABLE_WORK_ITEM_WRITE=true.", {
+        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)"),
+    }, async ({ project, parentIds, folder }) => {
+        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
+                                const currentTask = await service.getWorkItem(project, task.id);
+                                const { operations, fieldsUpdated } = buildTaskPatchOperations(task, currentTask);
+                                if (operations.length > 0) {
+                                    await service.updateWorkItem(project, task.id, operations);
+                                    updated.push({
+                                        id: task.id,
+                                        parentId,
+                                        fieldsUpdated,
+                                    });
+                                }
+                                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 syncToolsCount = 4; // Work item sync tools
+    const taskSyncToolsCount = 2; // Task sync tools
+    const baseToolsCount = 21 + syncToolsCount + taskSyncToolsCount; // 15 original + 6 PR read-only + 4 work item sync + 2 task sync
     const prWriteToolsCount = enablePullRequestWrite ? 1 : 0;
     const totalToolsCount = baseToolsCount + prWriteToolsCount;
     console.error(`azure-devops tools registered: ${totalToolsCount} tools (${baseToolsCount} base + ${prWriteToolsCount} PR write), 4 prompts`);