@azure-devops/mcp 2.2.2 → 2.3.0-nightly.20251204

package/README.md

@@ -42,111 +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_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_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

@@ -4,6 +4,7 @@ import { apiVersion, getEnumKeys, safeEnumConvert } from "../utils.js";
 import { BuildQueryOrder, DefinitionQueryOrder } from "azure-devops-node-api/interfaces/BuildInterfaces.js";
 import { z } from "zod";
 import { StageUpdateType } from "azure-devops-node-api/interfaces/BuildInterfaces.js";
+import { ConfigurationType, RepositoryType } from "azure-devops-node-api/interfaces/PipelinesInterfaces.js";
 const PIPELINE_TOOLS = {
     pipelines_get_builds: "pipelines_get_builds",
     pipelines_get_build_changes: "pipelines_get_build_changes",
@@ -13,6 +14,7 @@ const PIPELINE_TOOLS = {
     pipelines_get_build_log_by_id: "pipelines_get_build_log_by_id",
     pipelines_get_build_status: "pipelines_get_build_status",
     pipelines_update_build_stage: "pipelines_update_build_stage",
+    pipelines_create_pipeline: "pipelines_create_pipeline",
     pipelines_get_run: "pipelines_get_run",
     pipelines_list_runs: "pipelines_list_runs",
     pipelines_run_pipeline: "pipelines_run_pipeline",
@@ -47,6 +49,56 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
             content: [{ type: "text", text: JSON.stringify(buildDefinitions, null, 2) }],
         };
     });
+    const variableSchema = z.object({
+        value: z.string().optional(),
+        isSecret: z.boolean().optional(),
+    });
+    server.tool(PIPELINE_TOOLS.pipelines_create_pipeline, "Creates a pipeline definition with YAML configuration for a given project.", {
+        project: z.string().describe("Project ID or name to run the build in."),
+        name: z.string().describe("Name of the new pipeline."),
+        folder: z.string().optional().describe("Folder path for the new pipeline. Defaults to '\\' if not specified."),
+        yamlPath: z.string().describe("The path to the pipeline's YAML file in the repository"),
+        repositoryType: z.enum(getEnumKeys(RepositoryType)).describe("The type of repository where the pipeline's YAML file is located."),
+        repositoryName: z.string().describe("The name of the repository. In case of GitHub repository, this is the full name (:owner/:repo) - e.g. octocat/Hello-World."),
+        repositoryId: z.string().optional().describe("The ID of the repository."),
+        repositoryConnectionId: z.string().optional().describe("The service connection ID for GitHub repositories. Not required for Azure Repos Git."),
+    }, async ({ project, name, folder, yamlPath, repositoryType, repositoryName, repositoryId, repositoryConnectionId }) => {
+        const connection = await connectionProvider();
+        const pipelinesApi = await connection.getPipelinesApi();
+        const repositoryTypeEnumValue = safeEnumConvert(RepositoryType, repositoryType);
+        const repositoryPayload = {
+            type: repositoryType,
+        };
+        if (repositoryTypeEnumValue === RepositoryType.AzureReposGit) {
+            repositoryPayload.id = repositoryId;
+            repositoryPayload.name = repositoryName;
+        }
+        else if (repositoryTypeEnumValue === RepositoryType.GitHub) {
+            if (!repositoryConnectionId) {
+                throw new Error("Parameter 'repositoryConnectionId' is required for GitHub repositories.");
+            }
+            repositoryPayload.connection = { id: repositoryConnectionId };
+            repositoryPayload.fullname = repositoryName;
+        }
+        else {
+            throw new Error("Unsupported repository type");
+        }
+        const yamlConfigurationType = getEnumKeys(ConfigurationType).find((k) => ConfigurationType[k] === ConfigurationType.Yaml);
+        const createPipelineParams = {
+            name: name,
+            folder: folder || "\\",
+            configuration: {
+                type: yamlConfigurationType,
+                path: yamlPath,
+                repository: repositoryPayload,
+                variables: undefined,
+            },
+        };
+        const newPipeline = await pipelinesApi.createPipeline(createPipelineParams, project);
+        return {
+            content: [{ type: "text", text: JSON.stringify(newPipeline, null, 2) }],
+        };
+    });
     server.tool(PIPELINE_TOOLS.pipelines_get_build_definition_revisions, "Retrieves a list of revisions for a specific build definition.", {
         project: z.string().describe("Project ID or name to get the build definition revisions for"),
         definitionId: z.number().describe("ID of the build definition to get revisions for"),
@@ -154,10 +206,6 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
             content: [{ type: "text", text: JSON.stringify(pipelineRuns, null, 2) }],
         };
     });
-    const variableSchema = z.object({
-        value: z.string().optional(),
-        isSecret: z.boolean().optional(),
-    });
     const resourcesSchema = z.object({
         builds: z
             .record(z.string().describe("Name of the build resource."), z.object({