@azure-devops/mcp 2.8.1 → 2.9.0

package/dist/tools/pipelines.js

@@ -8,325 +8,88 @@ import { ConfigurationType, RepositoryType } from "azure-devops-node-api/interfa
 import { mkdirSync, createWriteStream } from "fs";
 import { createExternalContentResponse } from "../shared/content-safety.js";
 import { join, posix, resolve, win32 } from "path";
-const PIPELINE_TOOLS = {
-    pipelines_get_builds: "pipelines_get_builds",
-    pipelines_get_build_changes: "pipelines_get_build_changes",
-    pipelines_get_build_definitions: "pipelines_get_build_definitions",
-    pipelines_get_build_definition_revisions: "pipelines_get_build_definition_revisions",
-    pipelines_get_build_log: "pipelines_get_build_log",
-    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",
-    pipelines_list_artifacts: "pipelines_list_artifacts",
-    pipelines_download_artifact: "pipelines_download_artifact",
-};
-function configurePipelineTools(server, tokenProvider, connectionProvider, userAgentProvider) {
-    server.tool(PIPELINE_TOOLS.pipelines_get_build_definitions, "Retrieves a list of build definitions for a given project.", {
-        project: z.string().describe("Project ID or name to get build definitions for"),
-        repositoryId: z
-            .string()
-            .optional()
-            .describe("Repository ID to filter build definitions. Can be a GUID or a repository name; when a name is provided, it is auto-resolved to the repository GUID using the project parameter (Azure Repos / TfsGit only)."),
-        repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter build definitions"),
-        name: z.string().optional().describe("Name of the build definition to filter"),
-        path: z.string().optional().describe("Path of the build definition to filter"),
-        queryOrder: z
-            .enum(getEnumKeys(DefinitionQueryOrder))
-            .optional()
-            .describe("Order in which build definitions are returned"),
-        top: z.number().optional().describe("Maximum number of build definitions to return"),
-        continuationToken: z.string().optional().describe("Token for continuing paged results"),
-        minMetricsTime: z.coerce.date().optional().describe("Minimum metrics time to filter build definitions"),
-        definitionIds: z.array(z.coerce.number().min(1)).optional().describe("Array of build definition IDs to filter"),
-        builtAfter: z.coerce.date().optional().describe("Return definitions that have builds after this date"),
-        notBuiltAfter: z.coerce.date().optional().describe("Return definitions that do not have builds after this date"),
-        includeAllProperties: z.boolean().optional().describe("Whether to include all properties in the results"),
-        includeLatestBuilds: z.boolean().optional().describe("Whether to include the latest builds for each definition"),
-        taskIdFilter: z.string().optional().describe("Task ID to filter build definitions"),
-        processType: z.number().optional().describe("Process type to filter build definitions"),
-        yamlFilename: z.string().optional().describe("YAML filename to filter build definitions"),
-    }, async ({ project, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename, }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        // Auto-resolve repositoryId from name to GUID for Azure Repos
-        let resolvedRepositoryId = repositoryId;
-        if (repositoryId) {
-            const isGuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(repositoryId);
-            if (!isGuid && (!repositoryType || repositoryType === "TfsGit")) {
-                const gitApi = await connection.getGitApi();
-                const repositories = await gitApi.getRepositories(project);
-                const repo = repositories?.find((r) => r.name === repositoryId);
-                if (!repo?.id) {
-                    return {
-                        content: [{ type: "text", text: `Error: Repository '${repositoryId}' not found in project '${project}'.` }],
-                        isError: true,
-                    };
-                }
-                resolvedRepositoryId = repo.id;
-            }
-        }
-        const buildDefinitions = await buildApi.getDefinitions(project, name, resolvedRepositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename);
-        return {
-            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();
+import { dispatchAction, errorResult } from "../shared/command.js";
+import { pipelinesWriteShape } from "./pipelines.dto.js";
+// ─── pipelines_write commands ────────────────────────────────────────────────
+// Each write action is a self-contained command. Shared infrastructure arrives
+// via `CommandContext`; the action-specific input arrives via a single typed
+// args object (see pipelines.dto.ts). This keeps the dispatcher agnostic of
+// individual argument lists.
+const runPipelineCommand = {
+    async execute(context, args) {
+        if (!args.pipelineId)
+            return errorResult("pipelineId is required for run_pipeline");
+        if (!args.previewRun && args.yamlOverride)
+            throw new Error("Parameter 'yamlOverride' can only be specified together with parameter 'previewRun'.");
+        const connection = await context.connectionProvider();
         const pipelinesApi = await connection.getPipelinesApi();
-        const repositoryTypeEnumValue = safeEnumConvert(RepositoryType, repositoryType);
-        const repositoryPayload = {
-            type: repositoryType,
+        const runRequest = {
+            previewRun: args.previewRun,
+            resources: { ...args.resources },
+            stagesToSkip: args.stagesToSkip,
+            templateParameters: args.templateParameters,
+            variables: args.variables,
+            yamlOverride: args.yamlOverride,
         };
+        const pipelineRun = await pipelinesApi.runPipeline(runRequest, args.project, args.pipelineId, args.pipelineVersion);
+        if (pipelineRun.id === undefined)
+            throw new Error("Failed to get build ID from pipeline run");
+        return { content: [{ type: "text", text: JSON.stringify(pipelineRun, null, 2) }] };
+    },
+};
+const createPipelineCommand = {
+    async execute(context, args) {
+        if (!args.name)
+            return errorResult("name is required for create_pipeline");
+        if (!args.yamlPath)
+            return errorResult("yamlPath is required for create_pipeline");
+        if (!args.repositoryType)
+            return errorResult("repositoryType is required for create_pipeline");
+        if (!args.repositoryName)
+            return errorResult("repositoryName is required for create_pipeline");
+        const connection = await context.connectionProvider();
+        const pipelinesApi = await connection.getPipelinesApi();
+        const repositoryTypeEnumValue = safeEnumConvert(RepositoryType, args.repositoryType);
+        const repositoryPayload = { type: args.repositoryType };
         if (repositoryTypeEnumValue === RepositoryType.AzureReposGit) {
-            repositoryPayload.id = repositoryId;
-            repositoryPayload.name = repositoryName;
+            repositoryPayload.id = args.repositoryId;
+            repositoryPayload.name = args.repositoryName;
         }
         else if (repositoryTypeEnumValue === RepositoryType.GitHub) {
-            if (!repositoryConnectionId) {
+            if (!args.repositoryConnectionId)
                 throw new Error("Parameter 'repositoryConnectionId' is required for GitHub repositories.");
-            }
-            repositoryPayload.connection = { id: repositoryConnectionId };
-            repositoryPayload.fullname = repositoryName;
+            repositoryPayload.connection = { id: args.repositoryConnectionId };
+            repositoryPayload.fullname = args.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.coerce.number().min(1).describe("ID of the build definition to get revisions for"),
-    }, async ({ project, definitionId }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const revisions = await buildApi.getDefinitionRevisions(project, definitionId);
-        return {
-            content: [{ type: "text", text: JSON.stringify(revisions, null, 2) }],
-        };
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_get_builds, "Retrieves a list of builds for a given project.", {
-        project: z.string().describe("Project ID or name to get builds for"),
-        definitions: z.array(z.coerce.number().min(1)).optional().describe("Array of build definition IDs to filter builds"),
-        queues: z.array(z.coerce.number().min(1)).optional().describe("Array of queue IDs to filter builds"),
-        buildNumber: z.string().optional().describe("Build number to filter builds"),
-        minTime: z.coerce.date().optional().describe("Minimum finish time to filter builds"),
-        maxTime: z.coerce.date().optional().describe("Maximum finish time to filter builds"),
-        requestedFor: z.string().optional().describe("User ID or name who requested the build"),
-        reasonFilter: z.number().optional().describe("Reason filter for the build (see BuildReason enum)"),
-        statusFilter: z.number().optional().describe("Status filter for the build (see BuildStatus enum)"),
-        resultFilter: z.number().optional().describe("Result filter for the build (see BuildResult enum)"),
-        tagFilters: z.array(z.string()).optional().describe("Array of tags to filter builds"),
-        properties: z.array(z.string()).optional().describe("Array of property names to include in the results"),
-        top: z.number().optional().describe("Maximum number of builds to return"),
-        continuationToken: z.string().optional().describe("Token for continuing paged results"),
-        maxBuildsPerDefinition: z.number().optional().describe("Maximum number of builds per definition"),
-        deletedFilter: z.number().optional().describe("Filter for deleted builds (see QueryDeletedOption enum)"),
-        queryOrder: z
-            .enum(getEnumKeys(BuildQueryOrder))
-            .default("QueueTimeDescending")
-            .optional()
-            .describe("Order in which builds are returned"),
-        branchName: z.string().optional().describe("Branch name to filter builds"),
-        buildIds: z.array(z.coerce.number().min(1)).optional().describe("Array of build IDs to retrieve"),
-        repositoryId: z.string().optional().describe("Repository ID to filter builds"),
-        repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Type of repository to filter builds"),
-    }, async ({ project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType, }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const builds = await buildApi.getBuilds(project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType);
-        return {
-            content: [{ type: "text", text: JSON.stringify(builds, null, 2) }],
-        };
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_get_build_log, "Retrieves the logs for a specific build.", {
-        project: z.string().describe("Project ID or name to get the build log for"),
-        buildId: z.coerce.number().min(1).describe("ID of the build to get the log for"),
-    }, async ({ project, buildId }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const logs = await buildApi.getBuildLogs(project, buildId);
-        return {
-            content: [{ type: "text", text: JSON.stringify(logs, null, 2) }],
-        };
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_get_build_log_by_id, "Get a specific build log by log ID.", {
-        project: z.string().describe("Project ID or name to get the build log for"),
-        buildId: z.coerce.number().min(1).describe("ID of the build to get the log for"),
-        logId: z.coerce.number().min(1).describe("ID of the log to retrieve"),
-        startLine: z.coerce.number().optional().describe("Starting line number for the log content, defaults to 0"),
-        endLine: z.coerce.number().optional().describe("Ending line number for the log content, defaults to the end of the log"),
-    }, async ({ project, buildId, logId, startLine, endLine }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const logLines = await buildApi.getBuildLogLines(project, buildId, logId, startLine, endLine);
-        return createExternalContentResponse(logLines, "build log");
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_get_build_changes, "Get the changes associated with a specific build.", {
-        project: z.string().describe("Project ID or name to get the build changes for"),
-        buildId: z.coerce.number().min(1).describe("ID of the build to get changes for"),
-        continuationToken: z.string().optional().describe("Continuation token for pagination"),
-        top: z.number().default(100).describe("Number of changes to retrieve, defaults to 100"),
-        includeSourceChange: z.boolean().optional().describe("Whether to include source changes in the results, defaults to false"),
-    }, async ({ project, buildId, continuationToken, top, includeSourceChange }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const changes = await buildApi.getBuildChanges(project, buildId, continuationToken, top, includeSourceChange);
-        return {
-            content: [{ type: "text", text: JSON.stringify(changes, null, 2) }],
-        };
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_get_run, "Gets a run for a particular pipeline.", {
-        project: z.string().describe("Project ID or name to run the build in"),
-        pipelineId: z.coerce.number().min(1).describe("ID of the pipeline to run"),
-        runId: z.coerce.number().min(1).describe("ID of the run to get"),
-    }, async ({ project, pipelineId, runId }) => {
-        const connection = await connectionProvider();
-        const pipelinesApi = await connection.getPipelinesApi();
-        const pipelineRun = await pipelinesApi.getRun(project, pipelineId, runId);
-        return {
-            content: [{ type: "text", text: JSON.stringify(pipelineRun, null, 2) }],
-        };
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_list_runs, "Gets top 10000 runs for a particular pipeline.", {
-        project: z.string().describe("Project ID or name to run the build in"),
-        pipelineId: z.coerce.number().min(1).describe("ID of the pipeline to run"),
-    }, async ({ project, pipelineId }) => {
-        const connection = await connectionProvider();
-        const pipelinesApi = await connection.getPipelinesApi();
-        const pipelineRuns = await pipelinesApi.listRuns(project, pipelineId);
-        return {
-            content: [{ type: "text", text: JSON.stringify(pipelineRuns, null, 2) }],
-        };
-    });
-    const resourcesSchema = z.object({
-        builds: z
-            .record(z.string().describe("Name of the build resource."), z.object({
-            version: z.string().optional().describe("Version of the build resource."),
-        }))
-            .optional(),
-        containers: z
-            .record(z.string().describe("Name of the container resource."), z.object({
-            version: z.string().optional().describe("Version of the container resource."),
-        }))
-            .optional(),
-        packages: z
-            .record(z.string().describe("Name of the package resource."), z.object({
-            version: z.string().optional().describe("Version of the package resource."),
-        }))
-            .optional(),
-        pipelines: z.record(z.string().describe("Name of the pipeline resource."), z.object({
-            runId: z.coerce.number().min(1).optional().describe("Id of the source pipeline run that triggered or is referenced by this pipeline run."),
-            version: z.string().optional().describe("Version of the source pipeline run."),
-        })),
-        repositories: z
-            .record(z.string().describe("Name of the repository resource."), 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().describe("Version of the repository resource, git commit sha."),
-        }))
-            .optional(),
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_run_pipeline, "Starts a new run of a pipeline.", {
-        project: z.string().describe("Project ID or name to run the build in"),
-        pipelineId: z.coerce.number().min(1).describe("ID of the pipeline to run"),
-        pipelineVersion: z.coerce.number().min(1).optional().describe("Version of the pipeline to run. If not provided, the latest version will be used."),
-        previewRun: z.boolean().optional().describe("If true, returns the final YAML document after parsing templates without creating a new run."),
-        resources: resourcesSchema.optional().describe("A dictionary of resources to pass to the pipeline."),
-        stagesToSkip: z.array(z.string()).optional().describe("A list of stages to skip."),
-        templateParameters: z.record(z.string(), z.string()).optional().describe("Custom build parameters as key-value pairs"),
-        variables: z.record(z.string(), variableSchema).optional().describe("A dictionary of variables to pass to the pipeline."),
-        yamlOverride: z.string().optional().describe("YAML override for the pipeline run."),
-    }, async ({ project, pipelineId, pipelineVersion, previewRun, resources, stagesToSkip, templateParameters, variables, yamlOverride }) => {
-        if (!previewRun && yamlOverride) {
-            throw new Error("Parameter 'yamlOverride' can only be specified together with parameter 'previewRun'.");
-        }
-        const connection = await connectionProvider();
-        const pipelinesApi = await connection.getPipelinesApi();
-        const runRequest = {
-            previewRun: previewRun,
-            resources: {
-                ...resources,
-            },
-            stagesToSkip: stagesToSkip,
-            templateParameters: templateParameters,
-            variables: variables,
-            yamlOverride: yamlOverride,
-        };
-        const pipelineRun = await pipelinesApi.runPipeline(runRequest, project, pipelineId, pipelineVersion);
-        const queuedBuild = { id: pipelineRun.id };
-        const buildId = queuedBuild.id;
-        if (buildId === undefined) {
-            throw new Error("Failed to get build ID from pipeline run");
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(pipelineRun, null, 2) }],
-        };
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_get_build_status, "Fetches the status of a specific build.", {
-        project: z.string().describe("Project ID or name to get the build status for"),
-        buildId: z.coerce.number().min(1).describe("ID of the build to get the status for"),
-    }, async ({ project, buildId }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const build = await buildApi.getBuildReport(project, buildId);
-        return {
-            content: [{ type: "text", text: JSON.stringify(build, null, 2) }],
+        const createParams = {
+            name: args.name,
+            folder: args.folder || "\\",
+            configuration: { type: yamlConfigurationType, path: args.yamlPath, repository: repositoryPayload, variables: undefined },
         };
-    });
-    server.tool(PIPELINE_TOOLS.pipelines_update_build_stage, "Updates the stage of a specific build.", {
-        project: z.string().describe("Project ID or name to update the build stage for"),
-        buildId: z.coerce.number().min(1).describe("ID of the build to update"),
-        stageName: z.string().describe("Name of the stage to update"),
-        status: z.enum(getEnumKeys(StageUpdateType)).describe("New status for the stage"),
-        forceRetryAllJobs: z.boolean().default(false).describe("Whether to force retry all jobs in the stage."),
-    }, async ({ project, buildId, stageName, status, forceRetryAllJobs }) => {
-        const connection = await connectionProvider();
+        const newPipeline = await pipelinesApi.createPipeline(createParams, args.project);
+        return { content: [{ type: "text", text: JSON.stringify(newPipeline, null, 2) }] };
+    },
+};
+const updateBuildStageCommand = {
+    async execute(context, args) {
+        if (!args.buildId)
+            return errorResult("buildId is required for update_build_stage");
+        if (!args.stageName)
+            return errorResult("stageName is required for update_build_stage");
+        if (!args.status)
+            return errorResult("status is required for update_build_stage");
+        const connection = await context.connectionProvider();
         const orgUrl = connection.serverUrl;
-        const endpoint = `${orgUrl}/${encodeURIComponent(project)}/_apis/build/builds/${buildId}/stages/${encodeURIComponent(stageName)}?api-version=${apiVersion}`;
-        const token = await tokenProvider();
-        const body = {
-            forceRetryAllJobs: forceRetryAllJobs,
-            state: safeEnumConvert(StageUpdateType, status),
-        };
+        const endpoint = `${orgUrl}/${encodeURIComponent(args.project)}/_apis/build/builds/${args.buildId}/stages/${encodeURIComponent(args.stageName)}?api-version=${apiVersion}`;
+        const token = await context.tokenProvider();
+        const body = { forceRetryAllJobs: args.forceRetryAllJobs, state: safeEnumConvert(StageUpdateType, args.status) };
         const response = await fetch(endpoint, {
             method: "PATCH",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${token}`,
-                "User-Agent": userAgentProvider(),
-            },
+            headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}`, "User-Agent": context.userAgentProvider() },
             body: JSON.stringify(body),
         });
         if (!response.ok) {
@@ -334,82 +97,296 @@ function configurePipelineTools(server, tokenProvider, connectionProvider, userA
             throw new Error(`Failed to update build stage: ${response.status} ${errorText}`);
         }
         const updatedBuild = await response.text();
-        return {
-            content: [{ type: "text", text: JSON.stringify(updatedBuild, null, 2) }],
-        };
+        return { content: [{ type: "text", text: JSON.stringify(updatedBuild, null, 2) }] };
+    },
+};
+/**
+ * The registry is the lookup table that couples each action to its command.
+ * Adding a new write action means registering one entry here — the dispatcher
+ * (`dispatchAction`) never changes.
+ */
+const pipelinesWriteCommands = {
+    run_pipeline: runPipelineCommand,
+    create_pipeline: createPipelineCommand,
+    update_build_stage: updateBuildStageCommand,
+};
+const pipelinesWriteErrorPrefixes = {
+    run_pipeline: "Error running pipeline: ",
+    create_pipeline: "Error creating pipeline: ",
+    update_build_stage: "Error updating build stage: ",
+};
+const PIPELINE_TOOLS = {
+    pipelines_build: "pipelines_build",
+    pipelines_build_log: "pipelines_build_log",
+    pipelines_definition: "pipelines_definition",
+    pipelines_run: "pipelines_run",
+    pipelines_artifact: "pipelines_artifact",
+    pipelines_write: "pipelines_write",
+};
+function configurePipelineTools(server, tokenProvider, connectionProvider, userAgentProvider) {
+    // ─── pipelines_build ────────────────────────────────────────────────────────
+    server.tool(PIPELINE_TOOLS.pipelines_build, "Retrieve build data for a project. Use the action parameter to specify the operation.", {
+        action: z
+            .enum(["list", "get_status", "get_changes"])
+            .describe("The action to perform. Options: list (list builds with optional filters), get_status (get status, issues, and report metadata for a build), get_changes (get commits and work items associated with a build)."),
+        project: z.string().describe("Project ID or name."),
+        buildId: z.coerce.number().min(1).optional().describe("ID of the build. Required for: get_status, get_changes."),
+        // list-specific
+        definitions: z.array(z.coerce.number().min(1)).optional().describe("Array of build definition IDs to filter builds. Used for: list."),
+        queues: z.array(z.coerce.number().min(1)).optional().describe("Array of queue IDs to filter builds. Used for: list."),
+        buildNumber: z.string().optional().describe("Build number to filter builds. Used for: list."),
+        minTime: z.coerce.date().optional().describe("Minimum finish time to filter builds. Used for: list."),
+        maxTime: z.coerce.date().optional().describe("Maximum finish time to filter builds. Used for: list."),
+        requestedFor: z.string().optional().describe("User ID or name who requested the build. Used for: list."),
+        reasonFilter: z.number().optional().describe("Reason filter (see BuildReason enum). Used for: list."),
+        statusFilter: z.number().optional().describe("Status filter (see BuildStatus enum). Used for: list."),
+        resultFilter: z.number().optional().describe("Result filter (see BuildResult enum). Used for: list."),
+        tagFilters: z.array(z.string()).optional().describe("Array of tags to filter builds. Used for: list."),
+        properties: z.array(z.string()).optional().describe("Array of property names to include in results. Used for: list."),
+        top: z.number().optional().describe("Maximum number of builds to return. Used for: list, get_changes."),
+        continuationToken: z.string().optional().describe("Token for continuing paged results. Used for: list, get_changes."),
+        maxBuildsPerDefinition: z.number().optional().describe("Maximum number of builds per definition. Used for: list."),
+        deletedFilter: z.number().optional().describe("Filter for deleted builds (see QueryDeletedOption enum). Used for: list."),
+        queryOrder: z.string().optional().describe("Order in which builds are returned (BuildQueryOrder values). Used for: list."),
+        branchName: z.string().optional().describe("Branch name to filter builds. Used for: list."),
+        buildIds: z.array(z.coerce.number().min(1)).optional().describe("Array of specific build IDs to retrieve. Used for: list."),
+        repositoryId: z.string().optional().describe("Repository ID to filter builds. Used for: list."),
+        repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Repository type to filter builds. Used for: list."),
+        // get_changes-specific
+        includeSourceChange: z.boolean().optional().describe("Whether to include source changes in results. Used for: get_changes."),
+    }, async ({ action, project, buildId, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, queryOrder, branchName, buildIds, repositoryId, repositoryType, includeSourceChange, }) => {
+        try {
+            const connection = await connectionProvider();
+            const buildApi = await connection.getBuildApi();
+            if (action === "list") {
+                const builds = await buildApi.getBuilds(project, definitions, queues, buildNumber, minTime, maxTime, requestedFor, reasonFilter, statusFilter, resultFilter, tagFilters, properties, top, continuationToken, maxBuildsPerDefinition, deletedFilter, safeEnumConvert(BuildQueryOrder, queryOrder), branchName, buildIds, repositoryId, repositoryType);
+                return { content: [{ type: "text", text: JSON.stringify(builds, null, 2) }] };
+            }
+            if (action === "get_status") {
+                if (!buildId)
+                    return { content: [{ type: "text", text: "buildId is required for get_status" }], isError: true };
+                const build = await buildApi.getBuildReport(project, buildId);
+                return { content: [{ type: "text", text: JSON.stringify(build, null, 2) }] };
+            }
+            if (action === "get_changes") {
+                if (!buildId)
+                    return { content: [{ type: "text", text: "buildId is required for get_changes" }], isError: true };
+                const changes = await buildApi.getBuildChanges(project, buildId, continuationToken, top, includeSourceChange);
+                return { content: [{ type: "text", text: JSON.stringify(changes, null, 2) }] };
+            }
+            return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            const msgs = {
+                list: `Error fetching builds: ${errorMessage}`,
+                get_status: `Error fetching build: ${errorMessage}`,
+                get_changes: `Error fetching build changes: ${errorMessage}`,
+            };
+            return { content: [{ type: "text", text: msgs[action] ?? `Error: ${errorMessage}` }], isError: true };
+        }
     });
-    server.tool(PIPELINE_TOOLS.pipelines_list_artifacts, "Lists artifacts for a given build.", {
-        project: z.string().describe("The name or ID of the project."),
-        buildId: z.coerce.number().min(1).describe("The ID of the build."),
-    }, async ({ project, buildId }) => {
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const artifacts = await buildApi.getArtifacts(project, buildId);
-        return {
-            content: [{ type: "text", text: JSON.stringify(artifacts, null, 2) }],
-        };
+    // ─── pipelines_build_log ────────────────────────────────────────────────────
+    server.tool(PIPELINE_TOOLS.pipelines_build_log, "Retrieve build log data for a project. Use the action parameter to specify the operation.", {
+        action: z.enum(["list", "get_content"]).describe("The action to perform. Options: list (list available logs for a build), get_content (get the text content of a specific log by ID)."),
+        project: z.string().describe("Project ID or name."),
+        buildId: z.coerce.number().min(1).describe("ID of the build. Required for all actions."),
+        logId: z.coerce.number().min(1).optional().describe("ID of the log to retrieve. Required for: get_content."),
+        startLine: z.coerce.number().optional().describe("Starting line number for the log content, defaults to 0. Used for: get_content."),
+        endLine: z.coerce.number().optional().describe("Ending line number for the log content, defaults to end of log. Used for: get_content."),
+    }, async ({ action, project, buildId, logId, startLine, endLine }) => {
+        try {
+            const connection = await connectionProvider();
+            const buildApi = await connection.getBuildApi();
+            if (action === "list") {
+                const logs = await buildApi.getBuildLogs(project, buildId);
+                return { content: [{ type: "text", text: JSON.stringify(logs, null, 2) }] };
+            }
+            if (action === "get_content") {
+                if (!logId)
+                    return { content: [{ type: "text", text: "logId is required for get_content" }], isError: true };
+                const logLines = await buildApi.getBuildLogLines(project, buildId, logId, startLine, endLine);
+                return createExternalContentResponse(logLines, "build log");
+            }
+            return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            const msgs = {
+                list: `Error fetching build log: ${errorMessage}`,
+                get_content: `Error fetching build log: ${errorMessage}`,
+            };
+            return { content: [{ type: "text", text: msgs[action] ?? `Error: ${errorMessage}` }], isError: true };
+        }
     });
-    server.tool(PIPELINE_TOOLS.pipelines_download_artifact, "Downloads a pipeline artifact. When destinationPath is provided, it must be a relative local path; absolute paths and path traversal are not allowed.", {
-        project: z.string().describe("The name or ID of the project."),
-        buildId: z.coerce.number().min(1).describe("The ID of the build."),
-        artifactName: z.string().describe("The name of the artifact to download."),
-        destinationPath: z.string().optional().describe("The relative local path to download the artifact to. If not provided, returns binary content as base64."),
-    }, async ({ project, buildId, artifactName, destinationPath }) => {
-        const hasUnsafePathSegment = (value) => value.split(/[\\/]+/).some((segment) => segment === "." || segment === "..");
-        const hasPathSeparators = (value) => /[\\/]/.test(value);
-        const hasDriveLetter = (value) => /^[a-zA-Z]:/.test(value);
-        const isAbsolutePath = (value) => posix.isAbsolute(value) || win32.isAbsolute(value);
-        if (hasUnsafePathSegment(artifactName) || hasPathSeparators(artifactName) || hasDriveLetter(artifactName) || isAbsolutePath(artifactName)) {
-            throw new Error("Invalid artifactName: artifactName must be a file name, not a path.");
+    // ─── pipelines_definition ───────────────────────────────────────────────────
+    server.tool(PIPELINE_TOOLS.pipelines_definition, "Retrieve pipeline definition data for a project. Use the action parameter to specify the operation.", {
+        action: z
+            .enum(["list", "list_revisions"])
+            .describe("The action to perform. Options: list (list pipeline definitions with optional filters), list_revisions (list revision history for a pipeline definition)."),
+        project: z.string().describe("Project ID or name."),
+        definitionId: z.coerce.number().min(1).optional().describe("ID of the build definition. Required for: list_revisions."),
+        // list-specific
+        repositoryId: z.string().optional().describe("Repository ID to filter definitions. Can be a GUID or name (auto-resolved for TfsGit). Used for: list."),
+        repositoryType: z.enum(["TfsGit", "GitHub", "BitbucketCloud"]).optional().describe("Repository type to filter definitions. Used for: list."),
+        name: z.string().optional().describe("Name filter for build definitions. Used for: list."),
+        path: z.string().optional().describe("Path filter for build definitions. Used for: list."),
+        queryOrder: z.string().optional().describe("Order in which definitions are returned (DefinitionQueryOrder values). Used for: list."),
+        top: z.number().optional().describe("Maximum number of definitions to return. Used for: list."),
+        continuationToken: z.string().optional().describe("Token for continuing paged results. Used for: list."),
+        minMetricsTime: z.coerce.date().optional().describe("Minimum metrics time to filter definitions. Used for: list."),
+        definitionIds: z.array(z.coerce.number().min(1)).optional().describe("Array of definition IDs to filter. Used for: list."),
+        builtAfter: z.coerce.date().optional().describe("Return definitions that have builds after this date. Used for: list."),
+        notBuiltAfter: z.coerce.date().optional().describe("Return definitions without builds after this date. Used for: list."),
+        includeAllProperties: z.boolean().optional().describe("Whether to include all properties in results. Used for: list."),
+        includeLatestBuilds: z.boolean().optional().describe("Whether to include the latest builds for each definition. Used for: list."),
+        taskIdFilter: z.string().optional().describe("Task ID to filter build definitions. Used for: list."),
+        processType: z.number().optional().describe("Process type to filter build definitions. Used for: list."),
+        yamlFilename: z.string().optional().describe("YAML filename to filter build definitions. Used for: list."),
+    }, async ({ action, project, definitionId, repositoryId, repositoryType, name, path, queryOrder, top, continuationToken, minMetricsTime, definitionIds, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename, }) => {
+        try {
+            const connection = await connectionProvider();
+            const buildApi = await connection.getBuildApi();
+            if (action === "list") {
+                let resolvedRepositoryId = repositoryId;
+                if (repositoryId) {
+                    const isGuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(repositoryId);
+                    if (!isGuid && (!repositoryType || repositoryType === "TfsGit")) {
+                        const gitApi = await connection.getGitApi();
+                        const repositories = await gitApi.getRepositories(project);
+                        const repo = repositories?.find((r) => r.name === repositoryId);
+                        if (!repo?.id) {
+                            return { content: [{ type: "text", text: `Error: Repository '${repositoryId}' not found in project '${project}'.` }], isError: true };
+                        }
+                        resolvedRepositoryId = repo.id;
+                    }
+                }
+                const defs = await buildApi.getDefinitions(project, name, resolvedRepositoryId, repositoryType, safeEnumConvert(DefinitionQueryOrder, queryOrder), top, continuationToken, minMetricsTime, definitionIds, path, builtAfter, notBuiltAfter, includeAllProperties, includeLatestBuilds, taskIdFilter, processType, yamlFilename);
+                return { content: [{ type: "text", text: JSON.stringify(defs, null, 2) }] };
+            }
+            if (action === "list_revisions") {
+                if (!definitionId)
+                    return { content: [{ type: "text", text: "definitionId is required for list_revisions" }], isError: true };
+                const revisions = await buildApi.getDefinitionRevisions(project, definitionId);
+                return { content: [{ type: "text", text: JSON.stringify(revisions, null, 2) }] };
+            }
+            return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
         }
-        if (destinationPath && (hasUnsafePathSegment(destinationPath) || isAbsolutePath(destinationPath) || hasDriveLetter(destinationPath))) {
-            throw new Error("Invalid destinationPath: use a relative path without path traversal.");
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            const msgs = {
+                list: `Error fetching build definitions: ${errorMessage}`,
+                list_revisions: `Error fetching build definition revisions: ${errorMessage}`,
+            };
+            return { content: [{ type: "text", text: msgs[action] ?? `Error: ${errorMessage}` }], isError: true };
         }
-        const connection = await connectionProvider();
-        const buildApi = await connection.getBuildApi();
-        const artifact = await buildApi.getArtifact(project, buildId, artifactName);
-        if (!artifact) {
-            return {
-                content: [{ type: "text", text: `Artifact ${artifactName} not found in build ${buildId}.` }],
+    });
+    // ─── pipelines_run ──────────────────────────────────────────────────────────
+    server.tool(PIPELINE_TOOLS.pipelines_run, "Retrieve pipeline run data for a project. Use the action parameter to specify the operation.", {
+        action: z.enum(["get", "list"]).describe("The action to perform. Options: get (get a single pipeline run), list (list runs for a pipeline)."),
+        project: z.string().describe("Project ID or name."),
+        pipelineId: z.coerce.number().min(1).describe("ID of the pipeline. Required for all actions."),
+        runId: z.coerce.number().min(1).optional().describe("ID of the run. Required for: get."),
+    }, async ({ action, project, pipelineId, runId }) => {
+        try {
+            const connection = await connectionProvider();
+            const pipelinesApi = await connection.getPipelinesApi();
+            if (action === "get") {
+                if (!runId)
+                    return { content: [{ type: "text", text: "runId is required for get" }], isError: true };
+                const run = await pipelinesApi.getRun(project, pipelineId, runId);
+                return { content: [{ type: "text", text: JSON.stringify(run, null, 2) }] };
+            }
+            if (action === "list") {
+                const runs = await pipelinesApi.listRuns(project, pipelineId);
+                return { content: [{ type: "text", text: JSON.stringify(runs, null, 2) }] };
+            }
+            return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            const msgs = {
+                get: `Error fetching pipeline run: ${errorMessage}`,
+                list: `Error fetching pipeline runs: ${errorMessage}`,
             };
+            return { content: [{ type: "text", text: msgs[action] ?? `Error: ${errorMessage}` }], isError: true };
         }
-        const fileStream = await buildApi.getArtifactContentZip(project, buildId, artifactName);
-        // If destinationPath is provided, save to disk
-        if (destinationPath) {
-            const fullDestinationPath = resolve(destinationPath);
-            mkdirSync(fullDestinationPath, { recursive: true });
-            const fileDestinationPath = join(fullDestinationPath, `${artifactName}.zip`);
-            const writeStream = createWriteStream(fileDestinationPath);
-            await new Promise((resolve, reject) => {
-                fileStream.pipe(writeStream);
-                fileStream.on("end", () => resolve());
-                fileStream.on("error", (err) => reject(err));
-            });
-            return {
-                content: [{ type: "text", text: `Artifact ${artifactName} downloaded to ${destinationPath}.` }],
+    });
+    server.tool(PIPELINE_TOOLS.pipelines_artifact, "Retrieve and download build artifacts. Use the action parameter to specify the operation.", {
+        action: z.enum(["list", "download"]).describe("The action to perform. Options: list (list artifacts for a build), download (download a named build artifact)."),
+        project: z.string().describe("Project ID or name."),
+        buildId: z.coerce.number().min(1).describe("ID of the build. Required for all actions."),
+        artifactName: z.string().optional().describe("Name of the artifact. Required for: download."),
+        destinationPath: z.string().optional().describe("Relative local path to download the artifact to. If not provided, returns base64 content. Used for: download."),
+    }, async ({ action, project, buildId, artifactName, destinationPath }) => {
+        try {
+            // Validate artifact/path inputs before making any network calls
+            if (action === "download") {
+                if (!artifactName)
+                    return { content: [{ type: "text", text: "artifactName is required for download" }], isError: true };
+                const hasUnsafePathSegment = (value) => value.split(/[\\/]+/).some((segment) => segment === "." || segment === "..");
+                const hasPathSeparators = (value) => /[\\/]/.test(value);
+                const hasDriveLetter = (value) => /^[a-zA-Z]:/.test(value);
+                const isAbsolutePath = (value) => posix.isAbsolute(value) || win32.isAbsolute(value);
+                if (hasUnsafePathSegment(artifactName) || hasPathSeparators(artifactName) || hasDriveLetter(artifactName) || isAbsolutePath(artifactName)) {
+                    throw new Error("Invalid artifactName: artifactName must be a file name, not a path.");
+                }
+                if (destinationPath && (hasUnsafePathSegment(destinationPath) || isAbsolutePath(destinationPath) || hasDriveLetter(destinationPath))) {
+                    throw new Error("Invalid destinationPath: use a relative path without path traversal.");
+                }
+            }
+            const connection = await connectionProvider();
+            const buildApi = await connection.getBuildApi();
+            if (action === "list") {
+                const artifacts = await buildApi.getArtifacts(project, buildId);
+                return { content: [{ type: "text", text: JSON.stringify(artifacts, null, 2) }] };
+            }
+            if (action === "download") {
+                const resolvedArtifactName = artifactName; // validated in pre-flight check above
+                const artifact = await buildApi.getArtifact(project, buildId, resolvedArtifactName);
+                if (!artifact) {
+                    return { content: [{ type: "text", text: `Artifact ${resolvedArtifactName} not found in build ${buildId}.` }], isError: true };
+                }
+                const fileStream = await buildApi.getArtifactContentZip(project, buildId, resolvedArtifactName);
+                if (destinationPath) {
+                    const fullDestinationPath = resolve(destinationPath);
+                    mkdirSync(fullDestinationPath, { recursive: true });
+                    const fileDestinationPath = join(fullDestinationPath, `${resolvedArtifactName}.zip`);
+                    const writeStream = createWriteStream(fileDestinationPath);
+                    await new Promise((resolve, reject) => {
+                        fileStream.pipe(writeStream);
+                        fileStream.on("end", () => resolve());
+                        fileStream.on("error", (err) => reject(err));
+                    });
+                    return { content: [{ type: "text", text: `Artifact ${resolvedArtifactName} downloaded to ${destinationPath}.` }] };
+                }
+                const chunks = [];
+                await new Promise((resolve, reject) => {
+                    fileStream.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+                    fileStream.on("end", () => resolve());
+                    fileStream.on("error", (err) => reject(err));
+                });
+                const buffer = Buffer.concat(chunks);
+                const base64Data = buffer.toString("base64");
+                return {
+                    content: [{ type: "resource", resource: { uri: `data:application/zip;base64,${base64Data}`, mimeType: "application/zip", text: base64Data } }],
+                };
+            }
+            return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            const msgs = {
+                list: `Error fetching artifacts: ${errorMessage}`,
+                download: `Error downloading artifact: ${errorMessage}`,
             };
+            return { content: [{ type: "text", text: msgs[action] ?? `Error: ${errorMessage}` }], isError: true };
         }
-        // Otherwise, return binary content as base64
-        const chunks = [];
-        await new Promise((resolve, reject) => {
-            fileStream.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
-            fileStream.on("end", () => resolve());
-            fileStream.on("error", (err) => reject(err));
-        });
-        const buffer = Buffer.concat(chunks);
-        const base64Data = buffer.toString("base64");
-        return {
-            content: [
-                {
-                    type: "resource",
-                    resource: {
-                        uri: `data:application/zip;base64,${base64Data}`,
-                        mimeType: "application/zip",
-                        text: base64Data,
-                    },
-                },
-            ],
-        };
+    });
+    // ─── pipelines_write ────────────────────────────────────────────────────────
+    server.tool(PIPELINE_TOOLS.pipelines_write, "Write operations for pipelines and builds. Use the action parameter to specify the operation.", pipelinesWriteShape, async (args) => {
+        const context = { connectionProvider, tokenProvider, userAgentProvider };
+        return dispatchAction(pipelinesWriteCommands, context, args, pipelinesWriteErrorPrefixes);
     });
 }
-export { PIPELINE_TOOLS, configurePipelineTools };
+export { PIPELINE_TOOLS, configurePipelineTools, runPipelineCommand, createPipelineCommand, updateBuildStageCommand };