@azure-devops/mcp 2.8.1 → 2.9.0

package/README.md

@@ -1,7 +1,7 @@
 # ⭐ Azure DevOps MCP Server
 
 > [!IMPORTANT]
-> The Azure DevOps Remote MCP Server is now available in public preview for all organizations. We recommend migrating to the [Remote MCP Server](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server) going forward.
+> We recommend using the [Remote MCP Server](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server) instead of this local server. It requires no installation and gets new features first.
 >
 > [Learn more](#-remote-mcp-server-recommended)
 
@@ -44,7 +44,7 @@ The Azure DevOps MCP Server is built around tools that are concise, simple, focu
 
 ## 🚀 Remote MCP Server (Recommended)
 
-The Azure DevOps **Remote MCP Server** is now available in [public preview](https://devblogs.microsoft.com/devops/azure-devops-remote-mcp-server-public-preview).
+For complete instructions, see the [Remote MCP Server onboarding documentation](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops).
 
 Over time, the Remote MCP Server will replace this local MCP Server. We will continue to support the local server for now, but future investments will primarily focus on the remote experience.
 
@@ -52,11 +52,6 @@ We encourage all users of the local MCP Server to begin migrating to the Remote
 
 If you encounter issues with tools, need support, or have a feature request, you can report an issue using the [Remote MCP Server issue template](https://github.com/microsoft/azure-devops-mcp/issues/new?template=remote-mcp-server-issue.md). During the preview period, we will track Remote MCP Server issues through this repository.
 
-> [!WARNING]
-> Internal Microsoft users of the Remote MCP Server should **not** create issues in this repository. Please use the dedicated Teams channel instead.
-
-For complete instructions, see the [Remote MCP Server onboarding documentation](https://learn.microsoft.com/en-us/azure/devops/mcp-server/remote-mcp-server?view=azure-devops).
-
 ### Quick start with `.vscode/mcp.json`
 
 Use this configuration to connect directly to the Azure DevOps-hosted endpoint using streamable HTTP transport:

package/dist/shared/command.js

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/** Builds an error `CallToolResult`. */
+export const errorResult = (text) => ({ content: [{ type: "text", text }], isError: true });
+/**
+ * Routes a validated, action-carrying args object to the matching command.
+ *
+ * This is what removes long positional parameter lists from grouped ("action")
+ * tools: instead of destructuring every possible field, the whole typed args
+ * object is forwarded to the single command keyed by `args.action`, coupling
+ * each action to exactly one command.
+ *
+ * - Unknown actions short-circuit with an "Unknown action" error and never
+ *   touch the context (so no connection is opened).
+ * - Errors thrown by a command are caught and formatted using the optional
+ *   per-action `errorPrefixes` map (falling back to a generic message).
+ * - Errors returned by a command (e.g. validation `errorResult`s) pass through
+ *   unchanged.
+ */
+export async function dispatchAction(commands, context, args, errorPrefixes) {
+    const command = commands[args.action];
+    if (!command) {
+        const supportedActions = Object.keys(commands).sort().join(", ");
+        return errorResult(`Unknown action: ${args.action}. Supported actions: ${supportedActions}`);
+    }
+    try {
+        return await command.execute(context, args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error occurred";
+        const prefix = errorPrefixes?.[args.action];
+        return errorResult(prefix ? `${prefix}${message}` : `Error: ${message}`);
+    }
+}

package/dist/tools/advanced-security.js

@@ -8,7 +8,7 @@ const ADVSEC_TOOLS = {
     get_alert_details: "advsec_get_alert_details",
 };
 function configureAdvSecTools(server, _, connectionProvider) {
-    server.tool(ADVSEC_TOOLS.get_alerts, "Retrieve Advanced Security alerts for a repository.", {
+    server.tool(ADVSEC_TOOLS.get_alerts, "Retrieve Advanced Security alerts for a repository. Results are scoped to the specified project and repository. Branch filters (onlyDefaultBranch, ref) apply only to code, dependency, and license alerts; they are not applicable to secret alerts and are ignored by the service, so they neither include nor exclude secrets. To narrow secret alerts by confidence, pass a single 'confidenceLevels' value ('High' or 'Other'); selecting every level is treated as no confidence filter.", {
         project: z.string().describe("The name or ID of the Azure DevOps project."),
         repository: z.string().describe("The name or ID of the repository to get alerts for."),
         alertType: z
@@ -26,17 +26,22 @@ function configureAdvSecTools(server, _, connectionProvider) {
         ruleId: z.string().optional().describe("Filter alerts by rule ID."),
         ruleName: z.string().optional().describe("Filter alerts by rule name."),
         toolName: z.string().optional().describe("Filter alerts by tool name."),
-        ref: z.string().optional().describe("Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch."),
-        onlyDefaultBranch: z.boolean().optional().default(true).describe("If true, only return alerts found on the default branch. Defaults to true."),
+        ref: z
+            .string()
+            .optional()
+            .describe("Filter non-secret alerts by git reference (branch), e.g. 'refs/heads/main'. When omitted and onlyDefaultBranch is true, only alerts on the default branch are returned. Not applicable to secret alerts and ignored by this tool when alertType is 'Secret'. When alertType is unspecified, this filter is still sent and may exclude secret alerts from the results; query alertType 'Secret' separately to retrieve all secrets."),
+        onlyDefaultBranch: z
+            .boolean()
+            .optional()
+            .describe("For non-secret alerts: if true (the service default when omitted) only return alerts found on the default branch; if false, return alerts from all branches. Ignored when 'ref' is provided. Not applicable to secret alerts and ignored by this tool when alertType is 'Secret'. When alertType is unspecified, this filter is still sent and may exclude secret alerts from the results; query alertType 'Secret' separately to retrieve all secrets."),
         confidenceLevels: z
             .array(z.enum(getEnumKeys(Confidence)))
             .optional()
-            .default(["high", "other"])
-            .describe("Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'."),
+            .describe("Only applicable to secret alerts. Accepted values are 'High' and 'Other'. Pass a single value (e.g. ['High']) to narrow secrets to that confidence level. Leave unset to return secrets without a confidence filter. Do not select both levels to widen results: the Alerts service does not accept a multi-value confidence filter and would return no alerts, so this tool treats an all-levels selection as no filter and omits it."),
         validity: z
             .array(z.enum(getEnumKeys(AlertValidityStatus)))
             .optional()
-            .describe("Filter alerts by validity status. Only applicable for secret alerts."),
+            .describe("Only applicable to secret alerts. If omitted, alerts of all validity statuses are returned (no validity filter is applied). Filtering by validity may return fewer alerts than 'top'; use the continuation token to fetch any remaining alerts."),
         top: z.coerce.number().optional().default(100).describe("Maximum number of alerts to return. Defaults to 100."),
         orderBy: z.enum(["id", "firstSeen", "lastSeen", "fixedOn", "severity"]).optional().default("severity").describe("Order results by specified field. Defaults to 'severity'."),
         continuationToken: z.string().optional().describe("Continuation token for pagination."),
@@ -44,7 +49,22 @@ function configureAdvSecTools(server, _, connectionProvider) {
         try {
             const connection = await connectionProvider();
             const alertApi = await connection.getAlertApi();
-            const isSecretAlert = !alertType || alertType.toLowerCase() === "secret";
+            const normalizedAlertType = alertType?.toLowerCase();
+            // "onlyDefaultBranch" and "ref" are not applicable to secret alerts (secrets are not
+            // branch-scoped and carry a null gitRef). Forwarding them for a secret-only query diverges
+            // from the REST API / Advanced Security UI and can incorrectly return no alerts, so only
+            // include them when the query is not restricted to secret alerts.
+            const isSecretOnly = normalizedAlertType === "secret";
+            // "confidenceLevels" and "validity" only apply to secret alerts, so include them whenever
+            // the result set can contain secrets (an explicit "secret" type or no type filter at all).
+            const canIncludeSecrets = !alertType || isSecretOnly;
+            // The Alerts service does not accept the multi-value (comma-serialized) confidence filter
+            // that the SDK emits: selecting every level (e.g. both "High" and "Other") returns zero
+            // alerts, and it is a no-op filter regardless. Only forward confidenceLevels when it
+            // narrows the result to a proper subset (a single level); otherwise omit it so secrets are
+            // returned without a confidence filter instead of an empty set.
+            const confidenceLevelValues = confidenceLevels ? mapStringArrayToEnum(confidenceLevels, Confidence) : [];
+            const narrowsByConfidence = confidenceLevelValues.length > 0 && confidenceLevelValues.length < getEnumKeys(Confidence).length;
             const criteria = {
                 ...(alertType && { alertType: mapStringToEnum(alertType, AlertType) }),
                 ...(states && { states: mapStringArrayToEnum(states, State) }),
@@ -52,10 +72,10 @@ function configureAdvSecTools(server, _, connectionProvider) {
                 ...(ruleId && { ruleId }),
                 ...(ruleName && { ruleName }),
                 ...(toolName && { toolName }),
-                ...(ref && { ref }),
-                ...(onlyDefaultBranch !== undefined && { onlyDefaultBranch }),
-                ...(isSecretAlert && confidenceLevels && { confidenceLevels: mapStringArrayToEnum(confidenceLevels, Confidence) }),
-                ...(isSecretAlert && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }),
+                ...(!isSecretOnly && ref && { ref }),
+                ...(!isSecretOnly && onlyDefaultBranch !== undefined && { onlyDefaultBranch }),
+                ...(canIncludeSecrets && narrowsByConfidence && { confidenceLevels: confidenceLevelValues }),
+                ...(canIncludeSecrets && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }),
             };
             const result = await alertApi.getAlerts(project, repository, top, orderBy, criteria, undefined, // expand parameter
             continuationToken);

package/dist/tools/pipelines.dto.js

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { z } from "zod";
+import { getEnumKeys } from "../utils.js";
+import { RepositoryType } from "azure-devops-node-api/interfaces/PipelinesInterfaces.js";
+import { StageUpdateType } from "azure-devops-node-api/interfaces/BuildInterfaces.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// DTOs for the pipelines_write tool.
+//
+// Each action's inputs are declared once as a Zod "raw shape". The shapes are
+// the single source of truth: the tool's input schema is composed from them,
+// and the TypeScript argument types are derived via `z.infer` (no hand-written,
+// drift-prone duplicate types). These types are safe to export — they are
+// compile-time only and erased at runtime, so they have no effect on the MCP
+// protocol or a local server.
+// ─────────────────────────────────────────────────────────────────────────────
+export const variableSchema = z.object({
+    value: z.string().optional(),
+    isSecret: z.boolean().optional(),
+});
+export const resourcesSchema = z.object({
+    builds: z.record(z.string(), z.object({ version: z.string().optional() })).optional(),
+    containers: z.record(z.string(), z.object({ version: z.string().optional() })).optional(),
+    packages: z.record(z.string(), z.object({ version: z.string().optional() })).optional(),
+    pipelines: z
+        .record(z.string(), z.object({
+        runId: z.coerce.number().min(1).optional().describe("Id of the source pipeline run."),
+        version: z.string().optional(),
+    }))
+        .optional(),
+    repositories: z
+        .record(z.string(), z.object({
+        refName: z.string().describe("Reference name, e.g., refs/heads/main."),
+        token: z.string().optional(),
+        tokenType: z.string().optional(),
+        version: z.string().optional(),
+    }))
+        .optional(),
+});
+/** Fields shared by every write action. */
+const projectShape = {
+    project: z.string().describe("Project ID or name."),
+};
+/** run_pipeline inputs. */
+export const runPipelineShape = {
+    ...projectShape,
+    pipelineId: z.coerce.number().min(1).optional().describe("ID of the pipeline to run. Required for: run_pipeline."),
+    pipelineVersion: z.coerce.number().min(1).optional().describe("Version of the pipeline to run. Used for: run_pipeline."),
+    previewRun: z.boolean().optional().describe("If true, returns the final YAML without creating a run. Used for: run_pipeline."),
+    resources: resourcesSchema.optional().describe("Resources to pass to the pipeline. Used for: run_pipeline."),
+    stagesToSkip: z.array(z.string()).optional().describe("Stages to skip. Used for: run_pipeline."),
+    templateParameters: z.record(z.string(), z.string()).optional().describe("Custom build parameters as key-value pairs. Used for: run_pipeline."),
+    variables: z.record(z.string(), variableSchema).optional().describe("Variables to pass to the pipeline. Used for: run_pipeline."),
+    yamlOverride: z.string().optional().describe("YAML override (only valid with previewRun). Used for: run_pipeline."),
+};
+/** create_pipeline inputs. */
+export const createPipelineShape = {
+    ...projectShape,
+    name: z.string().optional().describe("Name of the new pipeline. Required for: create_pipeline."),
+    folder: z.string().optional().describe("Folder path for the new pipeline. Used for: create_pipeline."),
+    yamlPath: z.string().optional().describe("Path to the YAML file in the repository. Required for: create_pipeline."),
+    repositoryType: z
+        .enum(getEnumKeys(RepositoryType))
+        .optional()
+        .describe("Type of the repository. Required for: create_pipeline."),
+    repositoryName: z.string().optional().describe("Name of the repository (for GitHub: owner/repo). Required for: create_pipeline."),
+    repositoryId: z.string().optional().describe("ID of the repository. Used for: create_pipeline."),
+    repositoryConnectionId: z.string().optional().describe("Service connection ID for GitHub repositories. Used for: create_pipeline."),
+};
+/** update_build_stage inputs. */
+export const updateBuildStageShape = {
+    ...projectShape,
+    buildId: z.coerce.number().min(1).optional().describe("ID of the build to update. Required for: update_build_stage."),
+    stageName: z.string().optional().describe("Name of the stage to update. Required for: update_build_stage."),
+    status: z
+        .enum(getEnumKeys(StageUpdateType))
+        .optional()
+        .describe("New status for the stage. Required for: update_build_stage."),
+    forceRetryAllJobs: z.boolean().default(false).describe("Whether to force retry all jobs in the stage. Used for: update_build_stage."),
+};
+/** The composed input shape for the grouped `pipelines_write` tool. */
+export const pipelinesWriteShape = {
+    action: z
+        .enum(["run_pipeline", "create_pipeline", "update_build_stage"])
+        .describe("The action to perform. Options: run_pipeline (queue a new pipeline run), create_pipeline (create a new YAML pipeline definition), update_build_stage (cancel, retry, or run a stage on an in-flight build)."),
+    ...runPipelineShape,
+    ...createPipelineShape,
+    ...updateBuildStageShape,
+};
+// Per-action schemas + inferred argument DTOs. `z.infer` keeps these types in
+// lockstep with the schemas above.
+export const runPipelineSchema = z.object(runPipelineShape);
+export const createPipelineSchema = z.object(createPipelineShape);
+export const updateBuildStageSchema = z.object(updateBuildStageShape);
+export const pipelinesWriteSchema = z.object(pipelinesWriteShape);