@azure-devops/mcp 2.2.2-nightly.20251120 → 2.2.2-nightly.20251125

package/README.md

@@ -42,113 +42,7 @@ The Azure DevOps MCP Server is built from tools that are concise, simple, focuse
 
 ## ⚙️ Supported Tools
 
-Interact with these Azure DevOps services:
-
-### 🧿 Core
-
-- **core_list_project_teams**: Retrieve a list of teams for the specified Azure DevOps project.
-- **core_list_projects**: Retrieve a list of projects in your Azure DevOps organization.
-- **core_get_identity_ids**: Retrieve Azure DevOps identity IDs for a list of unique names.
-
-### ⚒️ 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
-
-- **wit_my_work_items**: Retrieve a list of work items relevant to the authenticated user.
-- **wit_list_backlogs**: Retrieve a list of backlogs for a given project and team.
-- **wit_list_backlog_work_items**: Retrieve a list of backlogs for a given project, team, and backlog category.
-- **wit_get_work_item**: Get a single work item by ID.
-- **wit_get_work_items_batch_by_ids**: Retrieve a list of work items by IDs in batch.
-- **wit_update_work_item**: Update a work item by ID with specified fields.
-- **wit_create_work_item**: Create a new work item in a specified project and work item type.
-- **wit_list_work_item_comments**: Retrieve a list of comments for a work item by ID.
-- **wit_list_work_item_revisions**: Retrieve a list of revisions for a work item by ID.
-- **wit_get_work_items_for_iteration**: Retrieve a list of work items for a specified iteration.
-- **wit_add_work_item_comment**: Add a comment to a work item by ID.
-- **wit_add_child_work_items**: Create one or more child work items of a specific work item type for the given parent ID.
-- **wit_link_work_item_to_pull_request**: Link a single work item to an existing pull request.
-- **wit_get_work_item_type**: Get a specific work item type.
-- **wit_get_query**: Get a query by its ID or path.
-- **wit_get_query_results_by_id**: Retrieve the results of a work item query given the query ID.
-- **wit_update_work_items_batch**: Update work items in batch.
-- **wit_work_items_link**: Link work items together in batch.
-- **wit_work_item_unlink**: Unlink one or many links from a work item.
-- **wit_add_artifact_link**: Link to artifacts like branch, pull request, commit, and build.
-
-### 📁 Repositories
-
-- **repo_list_repos_by_project**: Retrieve a list of repositories for a given project.
-- **repo_list_pull_requests_by_repo_or_project**: Retrieve a list of pull requests for a given repository or project.
-- **repo_list_branches_by_repo**: Retrieve a list of branches for a given repository.
-- **repo_list_my_branches_by_repo**: Retrieve a list of your branches for a given repository ID.
-- **repo_list_pull_requests_by_commits**: List pull requests associated with commits.
-- **repo_list_pull_request_threads**: Retrieve a list of comment threads for a pull request.
-- **repo_list_pull_request_thread_comments**: Retrieve a list of comments in a pull request thread.
-- **repo_get_repo_by_name_or_id**: Get the repository by project and repository name or ID.
-- **repo_get_branch_by_name**: Get a branch by its name.
-- **repo_get_pull_request_by_id**: Get a pull request by its ID.
-- **repo_create_pull_request**: Create a new pull request.
-- **repo_create_branch**: Create a new branch in the repository.
-- **repo_update_pull_request**: Update various fields of an existing pull request (title, description, draft status, target branch).
-- **repo_update_pull_request_reviewers**: Add or remove reviewers for an existing pull request.
-- **repo_reply_to_comment**: Replies to a specific comment on a pull request.
-- **repo_resolve_comment**: Resolves a specific comment thread on a pull request.
-- **repo_search_commits**: Searches for commits.
-- **repo_create_pull_request_thread**: Creates a new comment thread on a pull request.
-
-### 🚀 Pipelines
-
-- **pipelines_get_build_definitions**: Retrieve a list of build definitions for a given project.
-- **pipelines_get_build_definition_revisions**: Retrieve a list of revisions for a specific build definition.
-- **pipelines_get_builds**: Retrieve a list of builds for a given project.
-- **pipelines_get_build_log**: Retrieve the logs for a specific build.
-- **pipelines_get_build_log_by_id**: Get a specific build log by log ID.
-- **pipelines_get_build_changes**: Get the changes associated with a specific build.
-- **pipelines_get_build_status**: Fetch the status of a specific build.
-- **pipelines_update_build_stage**: Update the stage of a specific build.
-- **pipelines_create_pipeline**: Creates a pipeline definition with YAML configuration for a given project.
-- **pipelines_get_run**: Gets a run for a particular pipeline.
-- **pipelines_list_runs**: Gets top 10000 runs for a particular pipeline.
-- **pipelines_run_pipeline**: Starts a new run of a pipeline.
-
-### Advanced Security
-
-- **advsec_get_alerts**: Retrieve Advanced Security alerts for a repository.
-- **advsec_get_alert_details**: Get detailed information about a specific Advanced Security alert.
-
-### 🧪 Test Plans
-
-- **testplan_create_test_plan**: Create a new test plan in the project.
-- **testplan_create_test_case**: Create a new test case work item.
-- **testplan_update_test_case_steps**: Update an existing test case work item's steps.
-- **testplan_add_test_cases_to_suite**: Add existing test cases to a test suite.
-- **testplan_list_test_plans**: Retrieve a paginated list of test plans from an Azure DevOps project. Allows filtering for active plans and toggling detailed information.
-- **testplan_list_test_cases**: Get a list of test cases in the test plan.
-- **testplan_show_test_results_from_build_id**: Get a list of test results for a given project and build ID.
-- **testplan_create_test_suite**: Creates a new test suite in a test plan.
-
-### 📖 Wiki
-
-- **wiki_list_wikis**: Retrieve a list of wikis for an organization or project.
-- **wiki_get_wiki**: Get the wiki by wikiIdentifier.
-- **wiki_list_pages**: Retrieve a list of wiki pages for a specific wiki and project.
-- **wiki_get_page**: Retrieve wiki page metadata by path.
-- **wiki_get_page_content**: Retrieve wiki page content by wikiIdentifier and path.
-- **wiki_create_or_update_page**: Create or update wiki pages with full content support.
-
-### 🔎 Search
-
-- **search_code**: Get code search results for a given search text.
-- **search_wiki**: Get wiki search results for a given search text.
-- **search_workitem**: Get work item search results for a given search text.
+See [TOOLSET.md](./docs/TOOLSET.md) for a comprehensive list.
 
 ## 🔌 Installation & Getting Started
 

package/dist/auth.js

@@ -3,6 +3,7 @@
 import { AzureCliCredential, ChainedTokenCredential, DefaultAzureCredential } from "@azure/identity";
 import { PublicClientApplication } from "@azure/msal-node";
 import open from "open";
+import { logger } from "./logger.js";
 const scopes = ["499b84ac-1321-427f-aa17-267ca6975798/.default"];
 class OAuthAuthenticator {
     static clientId = "0d50963b-7bb9-4fe7-94c7-a99af00b5136";
@@ -15,6 +16,10 @@ class OAuthAuthenticator {
         let authority = OAuthAuthenticator.defaultAuthority;
         if (tenantId && tenantId !== OAuthAuthenticator.zeroTenantId) {
             authority = `https://login.microsoftonline.com/${tenantId}`;
+            logger.debug(`OAuthAuthenticator: Using tenant-specific authority for tenantId='${tenantId}'`);
+        }
+        else {
+            logger.debug(`OAuthAuthenticator: Using default common authority`);
         }
         this.publicClientApp = new PublicClientApplication({
             auth: {
@@ -22,49 +27,67 @@ class OAuthAuthenticator {
                 authority,
             },
         });
+        logger.debug(`OAuthAuthenticator: Initialized with clientId='${OAuthAuthenticator.clientId}'`);
     }
     async getToken() {
         let authResult = null;
         if (this.accountId) {
+            logger.debug(`OAuthAuthenticator: Attempting silent token acquisition for cached account`);
             try {
                 authResult = await this.publicClientApp.acquireTokenSilent({
                     scopes,
                     account: this.accountId,
                 });
+                logger.debug(`OAuthAuthenticator: Successfully acquired token silently`);
             }
-            catch {
+            catch (error) {
+                logger.debug(`OAuthAuthenticator: Silent token acquisition failed: ${error instanceof Error ? error.message : String(error)}`);
                 authResult = null;
             }
         }
+        else {
+            logger.debug(`OAuthAuthenticator: No cached account available, interactive auth required`);
+        }
         if (!authResult) {
+            logger.debug(`OAuthAuthenticator: Starting interactive token acquisition`);
             authResult = await this.publicClientApp.acquireTokenInteractive({
                 scopes,
                 openBrowser: async (url) => {
+                    logger.debug(`OAuthAuthenticator: Opening browser for authentication`);
                     open(url);
                 },
             });
             this.accountId = authResult.account;
+            logger.debug(`OAuthAuthenticator: Successfully acquired token interactively, account cached`);
         }
         if (!authResult.accessToken) {
+            logger.error(`OAuthAuthenticator: Authentication result contains no access token`);
             throw new Error("Failed to obtain Azure DevOps OAuth token.");
         }
+        logger.debug(`OAuthAuthenticator: Token obtained successfully`);
         return authResult.accessToken;
     }
 }
 function createAuthenticator(type, tenantId) {
+    logger.debug(`Creating authenticator of type '${type}' with tenantId='${tenantId ?? "undefined"}'`);
     switch (type) {
         case "envvar":
+            logger.debug(`Authenticator: Using environment variable authentication (ADO_MCP_AUTH_TOKEN)`);
             // Read token from fixed environment variable
             return async () => {
+                logger.debug(`${type}: Reading token from ADO_MCP_AUTH_TOKEN environment variable`);
                 const token = process.env["ADO_MCP_AUTH_TOKEN"];
                 if (!token) {
+                    logger.error(`${type}: ADO_MCP_AUTH_TOKEN environment variable is not set or empty`);
                     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.");
                 }
+                logger.debug(`${type}: Successfully retrieved token from environment variable`);
                 return token;
             };
         case "azcli":
         case "env":
             if (type !== "env") {
+                logger.debug(`${type}: Setting AZURE_TOKEN_CREDENTIALS to 'dev' for development credential chain`);
                 process.env.AZURE_TOKEN_CREDENTIALS = "dev";
             }
             let credential = new DefaultAzureCredential(); // CodeQL [SM05138] resolved by explicitly setting AZURE_TOKEN_CREDENTIALS
@@ -76,11 +99,14 @@ function createAuthenticator(type, tenantId) {
             return async () => {
                 const result = await credential.getToken(scopes);
                 if (!result) {
+                    logger.error(`${type}: Failed to obtain token - credential.getToken returned null/undefined`);
                     throw new Error("Failed to obtain Azure DevOps token. Ensure you have Azure CLI logged or use interactive type of authentication.");
                 }
+                logger.debug(`${type}: Successfully obtained Azure DevOps token`);
                 return result.token;
             };
         default:
+            logger.debug(`Authenticator: Using OAuth interactive authentication (default)`);
             const authenticator = new OAuthAuthenticator(tenantId);
             return () => {
                 return authenticator.getToken();

package/dist/index.js

@@ -7,6 +7,7 @@ import { getBearerHandler, WebApi } from "azure-devops-node-api";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { createAuthenticator } from "./auth.js";
+import { logger } from "./logger.js";
 import { getOrgTenant } from "./org-tenants.js";
 //import { configurePrompts } from "./prompts.js";
 import { configureAllTools } from "./tools.js";
@@ -67,6 +68,16 @@ function getAzureDevOpsClient(getAzureDevOpsToken, userAgentComposer) {
     };
 }
 async function main() {
+    logger.info("Starting Azure DevOps MCP Server", {
+        organization: orgName,
+        organizationUrl: orgUrl,
+        authentication: argv.authentication,
+        tenant: argv.tenant,
+        domains: argv.domains,
+        enabledDomains: Array.from(enabledDomains),
+        version: packageVersion,
+        isCodespace: isGitHubCodespaceEnv(),
+    });
     const server = new McpServer({
         name: "Azure DevOps MCP Server",
         version: packageVersion,
@@ -89,6 +100,6 @@ async function main() {
     await server.connect(transport);
 }
 main().catch((error) => {
-    console.error("Fatal error in main():", error);
+    logger.error("Fatal error in main():", error);
     process.exit(1);
 });

package/dist/logger.js

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import winston from "winston";
+import { setLogLevel } from "@azure/logger";
+const logLevel = process.env.LOG_LEVEL?.toLowerCase();
+if (logLevel && ["verbose", "debug", "info", "warning", "error"].includes(logLevel)) {
+    // Map Winston log levels to Azure log levels
+    const logLevelMap = {
+        verbose: "verbose",
+        debug: "info",
+        info: "info",
+        warning: "warning",
+        error: "error",
+    };
+    const azureLogLevel = logLevelMap[logLevel];
+    setLogLevel(azureLogLevel);
+}
+/**
+ * Logger utility for MCP server
+ *
+ * Since MCP servers use stdio transport for communication on stdout,
+ * we log to stderr to avoid interfering with the MCP protocol.
+ */
+export const logger = winston.createLogger({
+    level: process.env.LOG_LEVEL || "info",
+    format: winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json()),
+    transports: [
+        new winston.transports.Stream({
+            stream: process.stderr,
+        }),
+    ],
+    // Prevent Winston from exiting on error
+    exitOnError: false,
+});

package/dist/org-tenants.js

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 import { readFile, writeFile } from "fs/promises";
+import { logger } from "./logger.js";
 import { homedir } from "os";
 import { join } from "path";
 const CACHE_FILE = join(homedir(), ".ado_orgs.cache");
@@ -20,7 +21,7 @@ async function trySavingCache(cache) {
         await writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), "utf-8");
     }
     catch (error) {
-        console.error("Failed to save org tenants cache:", error);
+        logger.error("Failed to save org tenants cache:", error);
     }
 }
 async function fetchTenantFromApi(orgName) {
@@ -65,11 +66,11 @@ export async function getOrgTenant(orgName) {
     catch (error) {
         // If we have an expired cache entry, return it as fallback
         if (cachedEntry) {
-            console.error(`Failed to fetch fresh tenant for ADO org ${orgName}, using expired cache entry:`, error);
+            logger.error(`Failed to fetch fresh tenant for ADO org ${orgName}, using expired cache entry:`, error);
             return cachedEntry.tenantId;
         }
         // No cache entry available, log and return empty result
-        console.error(`Failed to fetch tenant for ADO org ${orgName}:`, error);
+        logger.error(`Failed to fetch tenant for ADO org ${orgName}:`, error);
         return undefined;
     }
 }

package/dist/shared/domains.js

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+import { logger } from "../logger.js";
 /**
  * Available Azure DevOps MCP domains
  */
@@ -68,7 +69,7 @@ export class DomainsManager {
                 this.enableAllDomains();
             }
             else {
-                console.error(`Error: Specified invalid domain '${domain}'. Please specify exactly as available domains: ${Object.values(Domain).join(", ")}`);
+                logger.error(`Error: Specified invalid domain '${domain}'. Please specify exactly as available domains: ${Object.values(Domain).join(", ")}`);
             }
         });
         if (this.enabledDomains.size === 0) {

package/dist/tools/pipelines.js

@@ -65,8 +65,8 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
     }, async ({ project, name, folder, yamlPath, repositoryType, repositoryName, repositoryId, repositoryConnectionId }) => {
         const connection = await connectionProvider();
         const pipelinesApi = await connection.getPipelinesApi();
-        let repositoryTypeEnumValue = safeEnumConvert(RepositoryType, repositoryType);
-        let repositoryPayload = {
+        const repositoryTypeEnumValue = safeEnumConvert(RepositoryType, repositoryType);
+        const repositoryPayload = {
             type: repositoryType,
         };
         if (repositoryTypeEnumValue === RepositoryType.AzureReposGit) {

package/dist/tools/repositories.js

@@ -94,6 +94,7 @@ function trimPullRequest(pr, includeDescription = false) {
             uniqueName: pr.createdBy?.uniqueName,
         },
         creationDate: pr.creationDate,
+        closedDate: pr.closedDate,
         title: pr.title,
         ...(includeDescription ? { description: pr.description ?? "" } : {}),
         isDraft: pr.isDraft,
@@ -472,14 +473,38 @@ function configureRepoTools(server, tokenProvider, connectionProvider, userAgent
         project: z.string().optional().describe("Project ID or project name (optional)"),
         iteration: z.number().optional().describe("The iteration ID for which to retrieve threads. Optional, defaults to the latest iteration."),
         baseIteration: z.number().optional().describe("The base iteration ID for which to retrieve threads. Optional, defaults to the latest base iteration."),
-        top: z.number().default(100).describe("The maximum number of threads to return."),
-        skip: z.number().default(0).describe("The number of threads to skip."),
+        top: z.number().default(100).describe("The maximum number of threads to return after filtering."),
+        skip: z.number().default(0).describe("The number of threads to skip after filtering."),
         fullResponse: z.boolean().optional().default(false).describe("Return full thread JSON response instead of trimmed data."),
-    }, async ({ repositoryId, pullRequestId, project, iteration, baseIteration, top, skip, fullResponse }) => {
+        status: z
+            .enum(getEnumKeys(CommentThreadStatus))
+            .optional()
+            .describe("Filter threads by status. If not specified, returns threads of all statuses."),
+        authorEmail: z.string().optional().describe("Filter threads by the email of the thread author (first comment author)."),
+        authorDisplayName: z.string().optional().describe("Filter threads by the display name of the thread author (first comment author). Case-insensitive partial matching."),
+    }, async ({ repositoryId, pullRequestId, project, iteration, baseIteration, top, skip, fullResponse, status, authorEmail, authorDisplayName }) => {
         const connection = await connectionProvider();
         const gitApi = await connection.getGitApi();
         const threads = await gitApi.getThreads(repositoryId, pullRequestId, project, iteration, baseIteration);
-        const paginatedThreads = threads?.sort((a, b) => (a.id ?? 0) - (b.id ?? 0)).slice(skip, skip + top);
+        let filteredThreads = threads;
+        if (status !== undefined) {
+            const statusValue = CommentThreadStatus[status];
+            filteredThreads = filteredThreads?.filter((thread) => thread.status === statusValue);
+        }
+        if (authorEmail !== undefined) {
+            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) => {
+                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);
         if (fullResponse) {
             return {
                 content: [{ type: "text", text: JSON.stringify(paginatedThreads, null, 2) }],

package/dist/version.js

@@ -1 +1 @@
-export const packageVersion = "2.2.2-nightly.20251120";
+export const packageVersion = "2.2.2-nightly.20251125";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "2.2.2-nightly.20251120",
+  "version": "2.2.2-nightly.20251125",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
   "author": "Microsoft Corporation",
@@ -25,7 +25,7 @@
     "prebuild": "node -p \"'export const packageVersion = ' + JSON.stringify(require('./package.json').version) + ';\\n'\" > src/version.ts && prettier --write src/version.ts",
     "validate-tools": "tsc --noEmit && node scripts/build-validate-tools.js",
     "build": "tsc && shx chmod +x dist/*.js",
-    "prepare": "npm run build",
+    "prepare": "npm run build && husky",
     "watch": "tsc --watch",
     "inspect": "ALLOWED_ORIGINS=http://127.0.0.1:6274 npx @modelcontextprotocol/inspector node dist/index.js",
     "start": "node -r tsconfig-paths/register dist/index.js",
@@ -43,6 +43,7 @@
     "azure-devops-extension-api": "^4.252.0",
     "azure-devops-extension-sdk": "^4.0.2",
     "azure-devops-node-api": "^15.1.0",
+    "winston": "^3.18.3",
     "yargs": "^18.0.0",
     "zod": "^3.25.63",
     "zod-to-json-schema": "^3.24.5"
@@ -50,17 +51,24 @@
   "devDependencies": {
     "@modelcontextprotocol/inspector": "^0.17.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^22",
+    "@types/node": "^22.19.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-header": "^3.1.1",
     "glob": "^11.0.3",
+    "husky": "^9.1.7",
     "jest": "^30.0.2",
     "jest-extended": "^7.0.0",
+    "lint-staged": "^16.2.7",
     "prettier": "3.6.2",
     "shx": "^0.4.0",
     "ts-jest": "^29.4.0",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.4"
+  },
+  "lint-staged": {
+    "**/*.(js|ts|jsx|tsx|json|css|md)": [
+      "npm run format"
+    ]
   }
 }