Merge branch 'main' into user/kyrader/add-support-access-token-via-env-var

Author: danhellem

.github/copilot-instructions.md

@@ -15,7 +15,6 @@ When adding new tool, always prioritize using an Azure DevOps Typescript client
 Only if the client or client method is not available, interact with the API directly.
 The tools are located in the `src/tools.ts` file.
 
-## Adding new prompts
+## Using MCP Server for Azure DevOps
 
-Ensure the instructions for the language model are clear and concise so that the language model can follow them reliably.
-The prompts are located in the `src/prompts.ts` file.
+When getting work items using MCP Server for Azure DevOps, always try to use batch tools for updates instead of many individual single updates. For updates, try and update up to 200 updates in a single batch. When getting work items, once you get the list of IDs, use the tool `get_work_items_batch_by_ids` to get the work item details.

CONTRIBUTING.md

@@ -28,7 +28,7 @@ For reference, see [this example of a well-formed issue](https://github.com/micr
 
 ## 👩‍💻 Writing code
 
-We are accepting a limited number of pull requests during the public preview phase. If you notice something that should be changed or added, please create an issue first and provide details. Once reviewed, and if it makes sense to proceed, we will respond with a 👍.
+We’re currently accepting a limited number of pull requests, provided they follow the established process and remain simple in scope. If you notice something that should be changed or added, please **create an issue first** and provide details. Once reviewed, and if it makes sense to proceed, we will respond with a 👍.
 
 Please include tests with your pull request. Pull requests will not be accepted until all relevant tests are updated and passing.
 

README.md

@@ -55,6 +55,9 @@ Interact with these Azure DevOps services:
 - **work_list_team_iterations**: Retrieve a list of iterations for a specific team in a 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-lock.json

@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "@azure/identity": "^4.10.0",
-    "@modelcontextprotocol/sdk": "1.20.0",
+    "@modelcontextprotocol/sdk": "1.20.2",
     "azure-devops-extension-api": "^4.252.0",
     "azure-devops-extension-sdk": "^4.0.2",
     "azure-devops-node-api": "^15.1.0",

package.json

@@ -1,3 +1,6 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
 import { AzureCliCredential, ChainedTokenCredential, DefaultAzureCredential, TokenCredential } from "@azure/identity";
 import { AccountInfo, AuthenticationResult, PublicClientApplication } from "@azure/msal-node";
 import open from "open";
@@ -36,7 +39,7 @@ class OAuthAuthenticator {
           scopes,
           account: this.accountId,
         });
-      } catch (error) {
+      } catch {
         authResult = null;
       }
     }

src/auth.ts

@@ -5,7 +5,7 @@
 
 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";
 
@@ -63,11 +63,11 @@ const orgUrl = "https://dev.azure.com/" + orgName;
 const domainsManager = new DomainsManager(argv.domains);
 export const enabledDomains = domainsManager.getEnabledDomains();
 
-function getAzureDevOpsClient(getAzureDevOpsToken: () => Promise<string>, userAgentComposer: UserAgentComposer): () => Promise<azdev.WebApi> {
+function getAzureDevOpsClient(getAzureDevOpsToken: () => Promise<string>, userAgentComposer: UserAgentComposer): () => Promise<WebApi> {
   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,

src/index.ts

@@ -1,32 +1,33 @@
-import * as fs from "fs/promises";
-import * as os from "os";
-import * as path from "path";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
 
 interface OrgTenantCacheEntry {
   tenantId: string;
   refreshedOn: number;
 }
 
-interface OrgTenantCache {
-  [orgName: string]: OrgTenantCacheEntry;
-}
+type OrgTenantCache = Record<string, OrgTenantCacheEntry>;
 
-const CACHE_FILE = path.join(os.homedir(), ".ado_orgs.cache");
+const CACHE_FILE = join(homedir(), ".ado_orgs.cache");
 const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 1 week in milliseconds
 
 async function loadCache(): Promise<OrgTenantCache> {
   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: OrgTenantCache): Promise<void> {
   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);
   }

src/org-tenants.ts

@@ -64,7 +64,7 @@ function getLinkTypeFromName(name: string) {
 function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<string>, connectionProvider: () => Promise<WebApi>, userAgentProvider: () => string) {
   server.tool(
     WORKITEM_TOOLS.list_backlogs,
-    "Revieve a list of backlogs for a given project and team.",
+    "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."),

src/tools/work-items.ts

@@ -10,6 +10,9 @@ const WORK_TOOLS = {
   list_team_iterations: "work_list_team_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: McpServer, _: () => Promise<string>, connectionProvider: () => Promise<WebApi>) {
@@ -150,6 +153,174 @@ function configureWorkTools(server: McpServer, _: () => Promise<string>, connect
       }
     }
   );
+
+  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 };
+
+        // Define interface for capacity patch
+        interface CapacityPatch {
+          activities: { name: string; capacityPerDay: number }[];
+          daysOff?: { start: Date; end: Date }[];
+        }
+
+        // Prepare the capacity update object
+        const capacityPatch: 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 };