@azure-devops/mcp 2.2.1 → 2.2.2

package/README.md

@@ -53,8 +53,12 @@ Interact with these Azure DevOps services:
 ### ⚒️ Work
 
 - **work_list_team_iterations**: Retrieve a list of iterations for a specific team in a project.
+- **work_list_iterations**: List all iterations in a specified Azure DevOps project.
 - **work_create_iterations**: Create new iterations in a specified Azure DevOps project.
 - **work_assign_iterations**: Assign existing iterations to a specific team in a project.
+- **work_get_team_capacity**: Get the team capacity of a specific team and iteration in a project.
+- **work_update_team_capacity**: Update the team capacity of a team member for a specific iteration in a project.
+- **work_get_iteration_capacities**: Get an iteration's capacity for all teams in iteration and project.
 
 ### 📅 Work Items
 

package/dist/auth.js

@@ -1,3 +1,5 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
 import { AzureCliCredential, ChainedTokenCredential, DefaultAzureCredential } from "@azure/identity";
 import { PublicClientApplication } from "@azure/msal-node";
 import open from "open";
@@ -30,7 +32,7 @@ class OAuthAuthenticator {
                     account: this.accountId,
                 });
             }
-            catch (error) {
+            catch {
                 authResult = null;
             }
         }
@@ -51,6 +53,15 @@ class OAuthAuthenticator {
 }
 function createAuthenticator(type, tenantId) {
     switch (type) {
+        case "envvar":
+            // Read token from fixed environment variable
+            return async () => {
+                const token = process.env["ADO_MCP_AUTH_TOKEN"];
+                if (!token) {
+                    throw new Error("Environment variable 'ADO_MCP_AUTH_TOKEN' is not set or empty. Please set it with a valid Azure DevOps Personal Access Token.");
+                }
+                return token;
+            };
         case "azcli":
         case "env":
             if (type !== "env") {

package/dist/index.js

@@ -3,7 +3,7 @@
 // Licensed under the MIT License.
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import * as azdev from "azure-devops-node-api";
+import { getBearerHandler, WebApi } from "azure-devops-node-api";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { createAuthenticator } from "./auth.js";
@@ -38,9 +38,9 @@ const argv = yargs(hideBin(process.argv))
 })
     .option("authentication", {
     alias: "a",
-    describe: "Type of authentication to use. Supported values are 'interactive', 'azcli' and 'env' (default: 'interactive')",
+    describe: "Type of authentication to use",
     type: "string",
-    choices: ["interactive", "azcli", "env"],
+    choices: ["interactive", "azcli", "env", "envvar"],
     default: defaultAuthenticationType,
 })
     .option("tenant", {
@@ -57,8 +57,8 @@ export const enabledDomains = domainsManager.getEnabledDomains();
 function getAzureDevOpsClient(getAzureDevOpsToken, userAgentComposer) {
     return async () => {
         const accessToken = await getAzureDevOpsToken();
-        const authHandler = azdev.getBearerHandler(accessToken);
-        const connection = new azdev.WebApi(orgUrl, authHandler, undefined, {
+        const authHandler = getBearerHandler(accessToken);
+        const connection = new WebApi(orgUrl, authHandler, undefined, {
             productName: "AzureDevOps.MCP",
             productVersion: packageVersion,
             userAgent: userAgentComposer.userAgent,
@@ -70,6 +70,11 @@ async function main() {
     const server = new McpServer({
         name: "Azure DevOps MCP Server",
         version: packageVersion,
+        icons: [
+            {
+                src: "https://cdn.vsassets.io/content/icons/favicon.ico",
+            },
+        ],
     });
     const userAgentComposer = new UserAgentComposer(packageVersion);
     server.server.oninitialized = () => {

package/dist/org-tenants.js

@@ -1,21 +1,23 @@
-import * as fs from "fs/promises";
-import * as os from "os";
-import * as path from "path";
-const CACHE_FILE = path.join(os.homedir(), ".ado_orgs.cache");
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+const CACHE_FILE = join(homedir(), ".ado_orgs.cache");
 const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 1 week in milliseconds
 async function loadCache() {
     try {
-        const cacheData = await fs.readFile(CACHE_FILE, "utf-8");
+        const cacheData = await readFile(CACHE_FILE, "utf-8");
         return JSON.parse(cacheData);
     }
-    catch (error) {
+    catch {
         // Cache file doesn't exist or is invalid, return empty cache
         return {};
     }
 }
 async function trySavingCache(cache) {
     try {
-        await fs.writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), "utf-8");
+        await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), "utf-8");
     }
     catch (error) {
         console.error("Failed to save org tenants cache:", error);

package/dist/tools/repositories.js

@@ -39,6 +39,7 @@ function trimPullRequestThread(thread) {
         lastUpdatedDate: thread.lastUpdatedDate,
         status: thread.status,
         comments: trimComments(thread.comments),
+        threadContext: thread.threadContext,
     };
 }
 /**
@@ -106,7 +107,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
         sourceRefName: z.string().describe("The source branch name for the pull request, e.g., 'refs/heads/feature-branch'."),
         targetRefName: z.string().describe("The target branch name for the pull request, e.g., 'refs/heads/main'."),
         title: z.string().describe("The title of the pull request."),
-        description: z.string().optional().describe("The description of the pull request. Optional."),
+        description: z.string().max(4000).optional().describe("The description of the pull request. Must not be longer than 4000 characters. Optional."),
         isDraft: z.boolean().optional().default(false).describe("Indicates whether the pull request is a draft. Defaults to false."),
         workItems: z.string().optional().describe("Work item IDs to associate with the pull request, space-separated."),
         forkSourceRepositoryId: z.string().optional().describe("The ID of the fork repository that the pull request originates from. Optional, used when creating a pull request from a fork."),
@@ -224,7 +225,7 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
         repositoryId: z.string().describe("The ID of the repository where the pull request exists."),
         pullRequestId: z.number().describe("The ID of the pull request to update."),
         title: z.string().optional().describe("The new title for the pull request."),
-        description: z.string().optional().describe("The new description for the pull request."),
+        description: z.string().max(4000).optional().describe("The new description for the pull request. Must not be longer than 4000 characters."),
         isDraft: z.boolean().optional().describe("Whether the pull request should be a draft."),
         targetRefName: z.string().optional().describe("The new target branch name (e.g., 'refs/heads/main')."),
         status: z.enum(["Active", "Abandoned"]).optional().describe("The new status of the pull request. Can be 'Active' or 'Abandoned'."),
@@ -704,9 +705,10 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
         };
     });
     const gitVersionTypeStrings = Object.values(GitVersionType).filter((value) => typeof value === "string");
-    server.tool(REPO_TOOLS.search_commits, "Searches for commits in a repository", {
+    server.tool(REPO_TOOLS.search_commits, "Search for commits in a repository with comprehensive filtering capabilities. Supports searching by description/comment text, time range, author, committer, specific commit IDs, and more. This is the unified tool for all commit search operations.", {
         project: z.string().describe("Project name or ID"),
         repository: z.string().describe("Repository name or ID"),
+        // Existing parameters
         fromCommit: z.string().optional().describe("Starting commit ID"),
         toCommit: z.string().optional().describe("Ending commit ID"),
         version: z.string().optional().describe("The name of the branch, tag or commit to filter commits by"),
@@ -719,16 +721,79 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
         top: z.number().optional().default(10).describe("Maximum number of commits to return"),
         includeLinks: z.boolean().optional().default(false).describe("Include commit links"),
         includeWorkItems: z.boolean().optional().default(false).describe("Include associated work items"),
-    }, async ({ project, repository, fromCommit, toCommit, version, versionType, skip, top, includeLinks, includeWorkItems }) => {
+        // Enhanced search parameters
+        searchText: z.string().optional().describe("Search text to filter commits by description/comment. Supports partial matching."),
+        author: z.string().optional().describe("Filter commits by author email or display name"),
+        authorEmail: z.string().optional().describe("Filter commits by exact author email address"),
+        committer: z.string().optional().describe("Filter commits by committer email or display name"),
+        committerEmail: z.string().optional().describe("Filter commits by exact committer email address"),
+        fromDate: z.string().optional().describe("Filter commits from this date (ISO 8601 format, e.g., '2024-01-01T00:00:00Z')"),
+        toDate: z.string().optional().describe("Filter commits to this date (ISO 8601 format, e.g., '2024-12-31T23:59:59Z')"),
+        commitIds: z.array(z.string()).optional().describe("Array of specific commit IDs to retrieve. When provided, other filters are ignored except top/skip."),
+        historySimplificationMode: z.enum(["FirstParent", "SimplifyMerges", "FullHistory", "FullHistorySimplifyMerges"]).optional().describe("How to simplify the commit history"),
+    }, async ({ project, repository, fromCommit, toCommit, version, versionType, skip, top, includeLinks, includeWorkItems, searchText, author, authorEmail, committer, committerEmail, fromDate, toDate, commitIds, historySimplificationMode, }) => {
         try {
             const connection = await connectionProvider();
             const gitApi = await connection.getGitApi();
+            // If specific commit IDs are provided, use getCommits with commit ID filtering
+            if (commitIds && commitIds.length > 0) {
+                const commits = [];
+                const batchSize = Math.min(top || 10, commitIds.length);
+                const startIndex = skip || 0;
+                const endIndex = Math.min(startIndex + batchSize, commitIds.length);
+                // Process commits in the requested range
+                const requestedCommitIds = commitIds.slice(startIndex, endIndex);
+                // Use getCommits for each commit ID to maintain consistency
+                for (const commitId of requestedCommitIds) {
+                    try {
+                        const searchCriteria = {
+                            includeLinks: includeLinks,
+                            includeWorkItems: includeWorkItems,
+                            fromCommitId: commitId,
+                            toCommitId: commitId,
+                        };
+                        const commitResults = await gitApi.getCommits(repository, searchCriteria, project, 0, 1);
+                        if (commitResults && commitResults.length > 0) {
+                            commits.push(commitResults[0]);
+                        }
+                    }
+                    catch (error) {
+                        // Log error but continue with other commits
+                        console.warn(`Failed to retrieve commit ${commitId}: ${error instanceof Error ? error.message : String(error)}`);
+                        // Add error information to result instead of failing completely
+                        commits.push({
+                            commitId: commitId,
+                            error: `Failed to retrieve: ${error instanceof Error ? error.message : String(error)}`,
+                        });
+                    }
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(commits, null, 2) }],
+                };
+            }
             const searchCriteria = {
                 fromCommitId: fromCommit,
                 toCommitId: toCommit,
                 includeLinks: includeLinks,
                 includeWorkItems: includeWorkItems,
             };
+            // Add author filter
+            if (author) {
+                searchCriteria.author = author;
+            }
+            // Add date range filters (ADO API expects ISO string format)
+            if (fromDate) {
+                searchCriteria.fromDate = fromDate;
+            }
+            if (toDate) {
+                searchCriteria.toDate = toDate;
+            }
+            // Add history simplification if specified
+            if (historySimplificationMode) {
+                // Note: This parameter might not be directly supported by all ADO API versions
+                // but we'll include it in the criteria for forward compatibility
+                searchCriteria.historySimplificationMode = historySimplificationMode;
+            }
             if (version) {
                 const itemVersion = {
                     version: version,
@@ -736,10 +801,27 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
                 };
                 searchCriteria.itemVersion = itemVersion;
             }
-            const commits = await gitApi.getCommits(repository, searchCriteria, project, skip, // skip
-            top);
+            const commits = await gitApi.getCommits(repository, searchCriteria, project, skip, top);
+            // Additional client-side filtering for enhanced search capabilities
+            let filteredCommits = commits;
+            // Filter by search text in commit message if not handled by API
+            if (searchText && filteredCommits) {
+                filteredCommits = filteredCommits.filter((commit) => commit.comment?.toLowerCase().includes(searchText.toLowerCase()));
+            }
+            // Filter by author email if specified
+            if (authorEmail && filteredCommits) {
+                filteredCommits = filteredCommits.filter((commit) => commit.author?.email?.toLowerCase() === authorEmail.toLowerCase());
+            }
+            // Filter by committer if specified
+            if (committer && filteredCommits) {
+                filteredCommits = filteredCommits.filter((commit) => commit.committer?.name?.toLowerCase().includes(committer.toLowerCase()) || commit.committer?.email?.toLowerCase().includes(committer.toLowerCase()));
+            }
+            // Filter by committer email if specified
+            if (committerEmail && filteredCommits) {
+                filteredCommits = filteredCommits.filter((commit) => commit.committer?.email?.toLowerCase() === committerEmail.toLowerCase());
+            }
             return {
-                content: [{ type: "text", text: JSON.stringify(commits, null, 2) }],
+                content: [{ type: "text", text: JSON.stringify(filteredCommits, null, 2) }],
             };
         }
         catch (error) {

package/dist/tools/work-items.js

@@ -56,7 +56,7 @@ function getLinkTypeFromName(name) {
     }
 }
 function configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider) {
-    server.tool(WORKITEM_TOOLS.list_backlogs, "Revieve a list of backlogs for a given project and team.", {
+    server.tool(WORKITEM_TOOLS.list_backlogs, "Receive a list of backlogs for a given project and team.", {
         project: z.string().describe("The name or ID of the Azure DevOps project."),
         team: z.string().describe("The name or ID of the Azure DevOps team."),
     }, async ({ project, team }) => {

package/dist/tools/work.js

@@ -1,11 +1,15 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 import { z } from "zod";
-import { TreeStructureGroup } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
+import { TreeStructureGroup, TreeNodeStructureType } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 const WORK_TOOLS = {
     list_team_iterations: "work_list_team_iterations",
+    list_iterations: "work_list_iterations",
     create_iterations: "work_create_iterations",
     assign_iterations: "work_assign_iterations",
+    get_team_capacity: "work_get_team_capacity",
+    update_team_capacity: "work_update_team_capacity",
+    get_iteration_capacities: "work_get_iteration_capacities",
 };
 function configureWorkTools(server, _, connectionProvider) {
     server.tool(WORK_TOOLS.list_team_iterations, "Retrieve a list of iterations for a specific team in a project.", {
@@ -74,6 +78,38 @@ function configureWorkTools(server, _, connectionProvider) {
             };
         }
     });
+    server.tool(WORK_TOOLS.list_iterations, "List all iterations in a specified Azure DevOps project.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        depth: z.number().default(2).describe("Depth of children to fetch."),
+    }, async ({ project, depth }) => {
+        try {
+            const connection = await connectionProvider();
+            const workItemTrackingApi = await connection.getWorkItemTrackingApi();
+            if (depth === undefined) {
+                depth = 1;
+            }
+            const results = await workItemTrackingApi.getClassificationNodes(project, [], depth);
+            // Handle null or undefined results
+            if (!results) {
+                return { content: [{ type: "text", text: "No iterations were found" }], isError: true };
+            }
+            // Filter out items with structureType=0 (Area nodes), only keep structureType=1 (Iteration nodes)
+            const filteredResults = results.filter((node) => node.structureType === TreeNodeStructureType.Iteration);
+            if (filteredResults.length === 0) {
+                return { content: [{ type: "text", text: "No iterations were found" }], isError: true };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(filteredResults, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [{ type: "text", text: `Error fetching iterations: ${errorMessage}` }],
+                isError: true,
+            };
+        }
+    });
     server.tool(WORK_TOOLS.assign_iterations, "Assign existing iterations to a specific team in a project.", {
         project: z.string().describe("The name or ID of the Azure DevOps project."),
         team: z.string().describe("The name or ID of the Azure DevOps team."),
@@ -110,5 +146,134 @@ function configureWorkTools(server, _, connectionProvider) {
             };
         }
     });
+    server.tool(WORK_TOOLS.get_team_capacity, "Get the team capacity of a specific team and iteration in a project.", {
+        project: z.string().describe("The name or Id of the Azure DevOps project."),
+        team: z.string().describe("The name or Id of the Azure DevOps team."),
+        iterationId: z.string().describe("The Iteration Id to get capacity for."),
+    }, async ({ project, team, iterationId }) => {
+        try {
+            const connection = await connectionProvider();
+            const workApi = await connection.getWorkApi();
+            const teamContext = { project, team };
+            const rawResults = await workApi.getCapacitiesWithIdentityRefAndTotals(teamContext, iterationId);
+            if (!rawResults || rawResults.teamMembers?.length === 0) {
+                return { content: [{ type: "text", text: "No team capacity assigned to the team" }], isError: true };
+            }
+            // Remove unwanted fields from teamMember and url
+            const simplifiedResults = {
+                ...rawResults,
+                teamMembers: (rawResults.teamMembers || []).map((member) => {
+                    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                    const { url, ...rest } = member;
+                    return {
+                        ...rest,
+                        teamMember: member.teamMember
+                            ? {
+                                displayName: member.teamMember.displayName,
+                                id: member.teamMember.id,
+                                uniqueName: member.teamMember.uniqueName,
+                            }
+                            : undefined,
+                    };
+                }),
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(simplifiedResults, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [{ type: "text", text: `Error getting team capacity: ${errorMessage}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool(WORK_TOOLS.update_team_capacity, "Update the team capacity of a team member for a specific iteration in a project.", {
+        project: z.string().describe("The name or Id of the Azure DevOps project."),
+        team: z.string().describe("The name or Id of the Azure DevOps team."),
+        teamMemberId: z.string().describe("The team member Id for the specific team member."),
+        iterationId: z.string().describe("The Iteration Id to update the capacity for."),
+        activities: z
+            .array(z.object({
+            name: z.string().describe("The name of the activity (e.g., 'Development')."),
+            capacityPerDay: z.number().describe("The capacity per day for this activity."),
+        }))
+            .describe("Array of activities and their daily capacities for the team member."),
+        daysOff: z
+            .array(z.object({
+            start: z.string().describe("Start date of the day off in ISO format."),
+            end: z.string().describe("End date of the day off in ISO format."),
+        }))
+            .optional()
+            .describe("Array of days off for the team member, each with a start and end date in ISO format."),
+    }, async ({ project, team, teamMemberId, iterationId, activities, daysOff }) => {
+        try {
+            const connection = await connectionProvider();
+            const workApi = await connection.getWorkApi();
+            const teamContext = { project, team };
+            // Prepare the capacity update object
+            const capacityPatch = {
+                activities: activities.map((a) => ({
+                    name: a.name,
+                    capacityPerDay: a.capacityPerDay,
+                })),
+                daysOff: (daysOff || []).map((d) => ({
+                    start: new Date(d.start),
+                    end: new Date(d.end),
+                })),
+            };
+            // Update the team member's capacity
+            const updatedCapacity = await workApi.updateCapacityWithIdentityRef(capacityPatch, teamContext, iterationId, teamMemberId);
+            if (!updatedCapacity) {
+                return { content: [{ type: "text", text: "Failed to update team member capacity" }], isError: true };
+            }
+            // Simplify output
+            const simplifiedResult = {
+                teamMember: updatedCapacity.teamMember
+                    ? {
+                        displayName: updatedCapacity.teamMember.displayName,
+                        id: updatedCapacity.teamMember.id,
+                        uniqueName: updatedCapacity.teamMember.uniqueName,
+                    }
+                    : undefined,
+                activities: updatedCapacity.activities,
+                daysOff: updatedCapacity.daysOff,
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(simplifiedResult, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [{ type: "text", text: `Error updating team capacity: ${errorMessage}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool(WORK_TOOLS.get_iteration_capacities, "Get an iteration's capacity for all teams in iteration and project.", {
+        project: z.string().describe("The name or Id of the Azure DevOps project."),
+        iterationId: z.string().describe("The Iteration Id to get capacity for."),
+    }, async ({ project, iterationId }) => {
+        try {
+            const connection = await connectionProvider();
+            const workApi = await connection.getWorkApi();
+            const rawResults = await workApi.getTotalIterationCapacities(project, iterationId);
+            if (!rawResults || !rawResults.teams || rawResults.teams.length === 0) {
+                return { content: [{ type: "text", text: "No iteration capacity assigned to the teams" }], isError: true };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(rawResults, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [{ type: "text", text: `Error getting iteration capacities: ${errorMessage}` }],
+                isError: true,
+            };
+        }
+    });
 }
 export { WORK_TOOLS, configureWorkTools };

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "2.2.1";
+export const packageVersion = "2.2.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
   "author": "Microsoft Corporation",
@@ -38,7 +38,8 @@
   },
   "dependencies": {
     "@azure/identity": "^4.10.0",
-    "@modelcontextprotocol/sdk": "1.20.0",
+    "@azure/msal-node": "^3.6.0",
+    "@modelcontextprotocol/sdk": "1.21.0",
     "azure-devops-extension-api": "^4.252.0",
     "azure-devops-extension-sdk": "^4.0.2",
     "azure-devops-node-api": "^15.1.0",
@@ -54,7 +55,7 @@
     "eslint-plugin-header": "^3.1.1",
     "glob": "^11.0.3",
     "jest": "^30.0.2",
-    "jest-extended": "^6.0.0",
+    "jest-extended": "^7.0.0",
     "prettier": "3.6.2",
     "shx": "^0.4.0",
     "ts-jest": "^29.4.0",