@azure-devops/mcp 2.7.0-nightly.20260427 → 2.7.0-nightly.20260429

package/dist/tools/pipelines.js

@@ -27,7 +27,10 @@ const PIPELINE_TOOLS = {
 function configurePipelineTools(server, tokenProvider, connectionProvider, userAgentProvider) {
     server.tool(PIPELINE_TOOLS.pipelines_get_build_definitions, "Retrieves a list of build definitions for a given project.", {
         project: z.string().describe("Project ID or name to get build definitions for"),
-        repositoryId: z.string().optional().describe("Repository ID to filter build definitions"),
+        repositoryId: z
+            .string()
+            .optional()
+            .describe("Repository ID to filter build definitions. Can be a GUID or a repository name; when a name is provided, it is auto-resolved to the repository GUID using the project parameter (Azure Repos / TfsGit only)."),
         repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter build definitions"),
         name: z.string().optional().describe("Name of the build definition to filter"),
         path: z.string().optional().describe("Path of the build definition to filter"),
@@ -49,7 +52,24 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
     }, async ({ project, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename, }) => {
         const connection = await connectionProvider();
         const buildApi = await connection.getBuildApi();
-        const buildDefinitions = await buildApi.getDefinitions(project, name, repositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename);
+        // Auto-resolve repositoryId from name to GUID for Azure Repos
+        let resolvedRepositoryId = repositoryId;
+        if (repositoryId) {
+            const isGuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(repositoryId);
+            if (!isGuid && (!repositoryType || repositoryType === "TfsGit")) {
+                const gitApi = await connection.getGitApi();
+                const repositories = await gitApi.getRepositories(project);
+                const repo = repositories?.find((r) => r.name === repositoryId);
+                if (!repo?.id) {
+                    return {
+                        content: [{ type: "text", text: `Error: Repository '${repositoryId}' not found in project '${project}'.` }],
+                        isError: true,
+                    };
+                }
+                resolvedRepositoryId = repo.id;
+            }
+        }
+        const buildDefinitions = await buildApi.getDefinitions(project, name, resolvedRepositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename);
         return {
             content: [{ type: "text", text: JSON.stringify(buildDefinitions, null, 2) }],
         };
@@ -329,19 +349,21 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
             content: [{ type: "text", text: JSON.stringify(artifacts, null, 2) }],
         };
     });
-    server.tool(PIPELINE_TOOLS.pipelines_download_artifact, "Downloads a pipeline artifact.", {
+    server.tool(PIPELINE_TOOLS.pipelines_download_artifact, "Downloads a pipeline artifact. When destinationPath is provided, it must be a relative local path; absolute paths and path traversal are not allowed.", {
         project: z.string().describe("The name or ID of the project."),
         buildId: z.coerce.number().min(1).describe("The ID of the build."),
         artifactName: z.string().describe("The name of the artifact to download."),
-        destinationPath: z.string().optional().describe("The local path to download the artifact to. If not provided, returns binary content as base64."),
+        destinationPath: z.string().optional().describe("The relative local path to download the artifact to. If not provided, returns binary content as base64."),
     }, async ({ project, buildId, artifactName, destinationPath }) => {
-        const isAbsolutePath = (value) => posix.isAbsolute(value) || win32.isAbsolute(value);
+        const hasUnsafePathSegment = (value) => value.split(/[\\/]+/).some((segment) => segment === "." || segment === "..");
+        const hasPathSeparators = (value) => /[\\/]/.test(value);
         const hasDriveLetter = (value) => /^[a-zA-Z]:/.test(value);
-        if (artifactName.includes("..")) {
-            throw new Error("Invalid artifactName: path traversal is not allowed.");
+        const isAbsolutePath = (value) => posix.isAbsolute(value) || win32.isAbsolute(value);
+        if (hasUnsafePathSegment(artifactName) || hasPathSeparators(artifactName) || hasDriveLetter(artifactName) || isAbsolutePath(artifactName)) {
+            throw new Error("Invalid artifactName: artifactName must be a file name, not a path.");
         }
-        if (destinationPath && (destinationPath.includes("..") || isAbsolutePath(destinationPath) || hasDriveLetter(destinationPath))) {
-            throw new Error("Invalid destinationPath: absolute paths and path traversals are not allowed.");
+        if (destinationPath && (hasUnsafePathSegment(destinationPath) || isAbsolutePath(destinationPath) || hasDriveLetter(destinationPath))) {
+            throw new Error("Invalid destinationPath: use a relative path without path traversal.");
         }
         const connection = await connectionProvider();
         const buildApi = await connection.getBuildApi();

package/dist/tools/repositories.js

@@ -3,7 +3,7 @@
 import { PullRequestStatus, GitVersionType, GitPullRequestQueryType, CommentThreadStatus, GitPullRequestMergeStrategy, VersionControlChangeType, VersionControlRecursionType, } from "azure-devops-node-api/interfaces/GitInterfaces.js";
 import { z } from "zod";
 import { getCurrentUserDetails, getUserIdFromEmail } from "./auth.js";
-import { getEnumKeys, streamToString } from "../utils.js";
+import { extractAdoStreamError, getEnumKeys, streamToString } from "../utils.js";
 const REPO_TOOLS = {
     list_repos_by_project: "repo_list_repos_by_project",
     list_pull_requests_by_repo_or_project: "repo_list_pull_requests_by_repo_or_project",
@@ -618,33 +618,33 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
         try {
             const connection = await connectionProvider();
             const gitApi = await connection.getGitApi();
-            const threads = await gitApi.getThreads(repositoryId, pullRequestId, project, iteration, baseIteration);
+            const threads = (await gitApi.getThreads(repositoryId, pullRequestId, project, iteration, baseIteration)) ?? [];
             let filteredThreads = threads;
             if (status !== undefined) {
                 const statusValue = CommentThreadStatus[status];
-                filteredThreads = filteredThreads?.filter((thread) => thread.status === statusValue);
+                filteredThreads = filteredThreads.filter((thread) => thread.status === statusValue);
             }
             if (authorEmail !== undefined) {
-                filteredThreads = filteredThreads?.filter((thread) => {
+                filteredThreads = filteredThreads.filter((thread) => {
                     const firstComment = thread.comments?.[0];
                     return firstComment?.author?.uniqueName?.toLowerCase() === authorEmail.toLowerCase();
                 });
             }
             if (authorDisplayName !== undefined) {
                 const lowerAuthorName = authorDisplayName.toLowerCase();
-                filteredThreads = filteredThreads?.filter((thread) => {
+                filteredThreads = filteredThreads.filter((thread) => {
                     const firstComment = thread.comments?.[0];
                     return firstComment?.author?.displayName?.toLowerCase().includes(lowerAuthorName);
                 });
             }
-            const paginatedThreads = filteredThreads?.sort((a, b) => (a.id ?? 0) - (b.id ?? 0)).slice(skip, skip + top);
+            const paginatedThreads = filteredThreads.sort((a, b) => (a.id ?? 0) - (b.id ?? 0)).slice(skip, skip + top);
             if (fullResponse) {
                 return {
                     content: [{ type: "text", text: JSON.stringify(paginatedThreads, null, 2) }],
                 };
             }
             // Return trimmed thread data focusing on essential information
-            const trimmedThreads = paginatedThreads?.map((thread) => trimPullRequestThread(thread));
+            const trimmedThreads = paginatedThreads.map((thread) => trimPullRequestThread(thread));
             return {
                 content: [{ type: "text", text: JSON.stringify(trimmedThreads, null, 2) }],
             };
@@ -693,7 +693,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
             };
         }
     });
-    server.tool(REPO_TOOLS.list_branches_by_repo, "Retrieve a list of branches for a given repository.", {
+    server.tool(REPO_TOOLS.list_branches_by_repo, "Retrieve a list of branch names for a given repository. Returns an array of branch name strings, not full branch objects. Use repo_get_branch_by_name to get full details for a specific branch.", {
         repositoryId: z
             .string()
             .describe("The ID or name of the repository where the branches are located. When using a repository name instead of a GUID, the project parameter must also be provided."),
@@ -718,7 +718,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
             };
         }
     });
-    server.tool(REPO_TOOLS.list_my_branches_by_repo, "Retrieve a list of my branches for a given repository Id.", {
+    server.tool(REPO_TOOLS.list_my_branches_by_repo, "Retrieve a list of my branch names for a given repository Id. Returns an array of branch name strings, not full branch objects. Use repo_get_branch_by_name to get full details for a specific branch.", {
         repositoryId: z
             .string()
             .describe("The ID or name of the repository where the branches are located. When using a repository name instead of a GUID, the project parameter must also be provided."),
@@ -770,7 +770,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
             };
         }
     });
-    server.tool(REPO_TOOLS.get_branch_by_name, "Get a branch by its name.", {
+    server.tool(REPO_TOOLS.get_branch_by_name, "Get a branch by its name. Returns isError: true if the branch is not found.", {
         repositoryId: z.string().describe("The ID or name of the repository where the branch is located. When using a repository name instead of a GUID, the project parameter must also be provided."),
         branchName: z.string().describe("The name of the branch to retrieve, e.g., 'main' or 'feature-branch'."),
         project: z.string().optional().describe("Project ID or project name. Required when repositoryId is a repository name instead of a GUID."),
@@ -1608,7 +1608,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
             ],
         };
     });
-    server.tool(REPO_TOOLS.list_directory, "List files and folders in a directory within a repository. Useful for exploring the structure of a codebase or finding related files.", {
+    server.tool(REPO_TOOLS.list_directory, "List files and folders in a directory within a repository. Useful for exploring the structure of a codebase or finding related files. Returns isError: true if the path is not found.", {
         repositoryId: z.string().describe("The ID or name of the repository."),
         path: z.string().optional().default("/").describe("The directory path to list (e.g., '/src' or '/src/components'). Defaults to repository root."),
         project: z.string().optional().describe("Project ID or name. Required if repositoryId is a name rather than a GUID."),
@@ -1629,7 +1629,8 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
             const items = await gitApi.getItems(repositoryId, project, path, recursionType, true, false, false, false, versionDescriptor);
             if (!items || items.length === 0) {
                 return {
-                    content: [{ type: "text", text: `No items found at path: ${path}` }],
+                    content: [{ type: "text", text: `No items found at path: ${path}. The path may not exist in the repository.` }],
+                    isError: true,
                 };
             }
             let filteredItems = items;
@@ -1677,7 +1678,8 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
     // ── Get file content at a specific version (branch, tag, or commit) ──
     const fileVersionTypeStrings = getEnumKeys(GitVersionType);
     server.tool(REPO_TOOLS.get_file_content, "Get the content of a file from a Git repository at a specific version (branch, tag, or commit SHA). " +
-        "Useful for reading source files from PR branches, specific commits, or tags without having them checked out locally.", {
+        "Useful for reading source files from PR branches, specific commits, or tags without having them checked out locally. " +
+        "Returns isError: true if the file is not found.", {
         repositoryId: z.string().describe("The ID (GUID) or name of the repository."),
         path: z.string().describe("The full path to the file in the repository, e.g., '/src/main.ts' or 'src/main.ts'."),
         project: z.string().optional().describe("Project ID or project name. Required when repositoryId is a name."),
@@ -1710,6 +1712,13 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
             versionDescriptor, true // includeContent
             );
             const content = await streamToString(stream);
+            const streamError = extractAdoStreamError(content);
+            if (streamError) {
+                return {
+                    content: [{ type: "text", text: `Error getting file content for '${path}': ${streamError}` }],
+                    isError: true,
+                };
+            }
             return {
                 content: [{ type: "text", text: content }],
             };

package/dist/tools/test-plans.js

@@ -357,7 +357,9 @@ function configureTestPlanTools(server, tokenProvider, connectionProvider, userA
             if (testResultDetails.resultsForGroup) {
                 for (const group of testResultDetails.resultsForGroup) {
                     if (group.results) {
-                        allResults.push(...group.results);
+                        for (const result of group.results) {
+                            allResults.push(result);
+                        }
                     }
                 }
             }

package/dist/tools/wiki.js

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 import { z } from "zod";
-import { apiVersion } from "../utils.js";
+import { apiVersion, extractAdoStreamError } from "../utils.js";
 import { createExternalContentResponse } from "../shared/content-safety.js";
 const WIKI_TOOLS = {
     list_wikis: "wiki_list_wikis",
@@ -88,7 +88,7 @@ function configureWikiTools(server, tokenProvider, connectionProvider, userAgent
             };
         }
     });
-    server.tool(WIKI_TOOLS.get_wiki_page, "Retrieve wiki page metadata by path. This tool does not return page content.", {
+    server.tool(WIKI_TOOLS.get_wiki_page, "Retrieve wiki page metadata by path. This tool does not return page content. Returns isError: true if the page is not found.", {
         wikiIdentifier: z.string().describe("The unique identifier of the wiki."),
         project: z.string().describe("The project name or ID where the wiki is located."),
         path: z.string().describe("The path of the wiki page (e.g., '/Home' or '/Documentation/Setup')."),
@@ -136,7 +136,7 @@ function configureWikiTools(server, tokenProvider, connectionProvider, userAgent
             };
         }
     });
-    server.tool(WIKI_TOOLS.get_wiki_page_content, "Retrieve wiki page content. Provide either a 'url' parameter OR the combination of 'wikiIdentifier' and 'project' parameters.", {
+    server.tool(WIKI_TOOLS.get_wiki_page_content, "Retrieve wiki page content. Provide either a 'url' parameter OR the combination of 'wikiIdentifier' and 'project' parameters. " + "Returns isError: true if the wiki page is not found.", {
         url: z
             .string()
             .optional()
@@ -209,6 +209,13 @@ function configureWikiTools(server, tokenProvider, connectionProvider, userAgent
                     return { content: [{ type: "text", text: "No wiki page content found" }], isError: true };
                 }
                 pageContent = await streamToString(stream);
+                const streamError = extractAdoStreamError(pageContent);
+                if (streamError) {
+                    return {
+                        content: [{ type: "text", text: `Error fetching wiki page content: ${streamError}` }],
+                        isError: true,
+                    };
+                }
             }
             return createExternalContentResponse(pageContent, "wiki page");
         }

package/dist/tools/work-items.js

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+import * as fs from "fs";
+import * as path from "path";
 import { WorkItemExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { QueryExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { z } from "zod";
@@ -407,8 +409,9 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             if (revisions && Array.isArray(revisions)) {
                 revisions.forEach((revision) => {
                     if (revision.fields) {
-                        Object.keys(revision.fields).forEach((fieldName) => {
-                            const fieldValue = revision.fields ? revision.fields[fieldName] : undefined;
+                        const fields = revision.fields;
+                        Object.keys(fields).forEach((fieldName) => {
+                            const fieldValue = fields[fieldName];
                             // Check if this is an identity object by looking for common identity properties
                             if (fieldValue &&
                                 typeof fieldValue === "object" &&
@@ -1210,11 +1213,23 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
             };
         }
     });
-    server.tool(WORKITEM_TOOLS.get_work_item_attachment, "Download a work item attachment by its ID and return the content as a base64-encoded resource. Useful for viewing images (e.g. screenshots) attached to work items such as bugs. If a project is not specified, you will be prompted to select one.", {
+    server.tool(WORKITEM_TOOLS.get_work_item_attachment, "Download a work item attachment by its ID. By default returns the content as a base64-encoded resource. If savePath is provided, saves the file locally to that directory and returns the file path instead. Useful for viewing images (e.g. screenshots) or other files attached to work items such as bugs. If a project is not specified, you will be prompted to select one.", {
         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."),
         attachmentId: z.string().describe("The GUID of the attachment. Found in the attachment URL: https://dev.azure.com/{org}/{project}/_apis/wit/attachments/{attachmentId}"),
-        fileName: z.string().optional().describe("The file name of the attachment, e.g. 'screenshot.png'. Used to determine the MIME type for the returned resource."),
-    }, async ({ project, attachmentId, fileName }) => {
+        fileName: z.string().optional().describe("The file name of the attachment, e.g. 'screenshot.png'. Used to determine the MIME type or the saved file's name."),
+        savePath: z
+            .string()
+            .optional()
+            .describe("Optional local directory path where the file should be saved. Must be a relative path (e.g. 'temp' or 'downloads/attachments'); absolute paths and path traversals are not allowed. If provided, saves the attachment to this directory and returns the file path. If omitted, returns the content as a base64-encoded resource."),
+    }, async ({ project, attachmentId, fileName, savePath }) => {
+        const isAbsolutePath = (value) => path.posix.isAbsolute(value) || path.win32.isAbsolute(value);
+        const hasDriveLetter = (value) => /^[a-zA-Z]:/.test(value);
+        if (savePath !== undefined && (savePath.includes("..") || isAbsolutePath(savePath) || hasDriveLetter(savePath))) {
+            throw new Error("Invalid savePath: absolute paths and path traversals are not allowed.");
+        }
+        if (fileName !== undefined && fileName.includes("..")) {
+            throw new Error("Invalid fileName: path traversal is not allowed.");
+        }
         try {
             const connection = await connectionProvider();
             let resolvedProject = project;
@@ -1233,8 +1248,24 @@ function configureWorkItemTools(server, tokenProvider, connectionProvider, userA
                 stream.on("error", reject);
             });
             const buffer = Buffer.concat(chunks);
-            const base64Data = buffer.toString("base64");
+            if (savePath) {
+                const resolvedFileName = fileName ?? attachmentId;
+                const localFilePath = path.join(savePath, resolvedFileName);
+                if (fs.existsSync(localFilePath)) {
+                    throw new Error(`File already exists: ${localFilePath}`);
+                }
+                fs.writeFileSync(localFilePath, buffer);
+                return {
+                    content: [{ type: "text", text: `Attachment saved to: ${localFilePath}` }],
+                };
+            }
             const mimeType = getMimeType(fileName);
+            if (mimeType.startsWith("text/")) {
+                return {
+                    content: [{ type: "text", text: buffer.toString("utf-8") }],
+                };
+            }
+            const base64Data = buffer.toString("base64");
             return {
                 content: [
                     {
@@ -1269,6 +1300,15 @@ function getMimeType(fileName) {
         webp: "image/webp",
         pdf: "application/pdf",
         txt: "text/plain",
+        md: "text/markdown",
+        markdown: "text/markdown",
+        csv: "text/csv",
+        html: "text/html",
+        htm: "text/html",
+        xml: "text/xml",
+        json: "application/json",
+        yaml: "text/yaml",
+        yml: "text/yaml",
         zip: "application/zip",
     };
     return (ext && mimeTypes[ext]) ?? "application/octet-stream";

package/dist/utils.js

@@ -67,6 +67,29 @@ export function encodeFormattedValue(value, format) {
     const result = value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
     return result;
 }
+/**
+ * Detects whether a string returned from an ADO API stream is actually an error
+ * response serialized as JSON (e.g. a 404 GitItemNotFoundException or
+ * WikiPageNotFoundException) rather than real content.
+ *
+ * The ADO Node API client swallows non-2xx HTTP responses and delivers the
+ * error body as a stream, so callers must check explicitly after reading.
+ *
+ * @returns The human-readable error message extracted from the JSON, or null if
+ *          the content is not an ADO error response.
+ */
+export function extractAdoStreamError(content) {
+    try {
+        const json = JSON.parse(content.trim());
+        if (json && typeof json.typeName === "string" && typeof json.message === "string") {
+            return json.message;
+        }
+    }
+    catch {
+        // Not JSON — not an ADO error response.
+    }
+    return null;
+}
 /**
  * Convert a Node.js ReadableStream to a string.
  * Shared utility for consistent stream handling across tools.

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "2.7.0-nightly.20260427";
+export const packageVersion = "2.7.0-nightly.20260429";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "2.7.0-nightly.20260427",
+  "version": "2.7.0-nightly.20260429",
   "mcpName": "microsoft.com/azure-devops",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",