Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/pipelines/trigger-pipeline/feature.ts:17-101 (handler)

  The core handler function that triggers a pipeline run using the Azure DevOps Pipelines API. It prepares run parameters including variables, template parameters, stages to skip, and branch resources, then calls pipelinesApi.runPipeline() and handles errors appropriately.

  export async function triggerPipeline(
    connection: WebApi,
    options: TriggerPipelineOptions,
  ): Promise<Run> {
    try {
      const pipelinesApi = await connection.getPipelinesApi();
      const {
        projectId = defaultProject,
        pipelineId,
        branch,
        variables,
        templateParameters,
        stagesToSkip,
      } = options;
  
      // Prepare run parameters
      const runParameters: Record<string, unknown> = {};
  
      // Add variables
      if (variables) {
        runParameters.variables = variables;
      }
  
      // Add template parameters
      if (templateParameters) {
        runParameters.templateParameters = templateParameters;
      }
  
      // Add stages to skip
      if (stagesToSkip && stagesToSkip.length > 0) {
        runParameters.stagesToSkip = stagesToSkip;
      }
  
      // Prepare resources (including branch)
      const resources: Record<string, unknown> = branch
        ? { repositories: { self: { refName: `refs/heads/${branch}` } } }
        : {};
  
      // Add resources to run parameters if not empty
      if (Object.keys(resources).length > 0) {
        runParameters.resources = resources;
      }
      // Call pipeline API to run pipeline
      const result = await pipelinesApi.runPipeline(
        runParameters,
        projectId,
        pipelineId,
      );
  
      return result;
    } catch (error) {
      // Handle specific error types
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
  
      // Check for specific error types and convert to appropriate Azure DevOps errors
      if (error instanceof Error) {
        if (
          error.message.includes('Authentication') ||
          error.message.includes('Unauthorized') ||
          error.message.includes('401')
        ) {
          throw new AzureDevOpsAuthenticationError(
            `Failed to authenticate: ${error.message}`,
          );
        }
  
        if (
          error.message.includes('not found') ||
          error.message.includes('does not exist') ||
          error.message.includes('404')
        ) {
          throw new AzureDevOpsResourceNotFoundError(
            `Pipeline or project not found: ${error.message}`,
          );
        }
      }
  
      // Otherwise, wrap it in a generic error
      throw new AzureDevOpsError(
        `Failed to trigger pipeline: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/pipelines/trigger-pipeline/schema.ts:7-46 (schema)

  Zod schema defining the input parameters for the trigger_pipeline tool, including projectId, pipelineId, branch, variables, templateParameters, and stagesToSkip.

  export const TriggerPipelineSchema = z.object({
    // The project containing the pipeline
    projectId: z
      .string()
      .optional()
      .describe(`The ID or name of the project (Default: ${defaultProject})`),
    // The ID of the pipeline to trigger
    pipelineId: z
      .number()
      .int()
      .positive()
      .describe('The numeric ID of the pipeline to trigger'),
    // The branch to run the pipeline on
    branch: z
      .string()
      .optional()
      .describe(
        'The branch to run the pipeline on (e.g., "main", "feature/my-branch"). If left empty, the default branch will be used',
      ),
    // Variables to pass to the pipeline run
    variables: z
      .record(
        z.object({
          value: z.string(),
          isSecret: z.boolean().optional(),
        }),
      )
      .optional()
      .describe('Variables to pass to the pipeline run'),
    // Parameters for template-based pipelines
    templateParameters: z
      .record(z.string())
      .optional()
      .describe('Parameters for template-based pipelines'),
    // Stages to skip in the pipeline run
    stagesToSkip: z
      .array(z.string())
      .optional()
      .describe('Stages to skip in the pipeline run'),
  });

• src/features/pipelines/tool-definitions.ts:61-67 (registration)

  Tool registration in the pipelinesTools array, defining the name, description, input schema, and MCP enablement.

    {
      name: 'trigger_pipeline',
      description: 'Trigger a pipeline run',
      inputSchema: zodToJsonSchema(TriggerPipelineSchema),
      mcp_enabled: true,
    },
  ];

• src/features/pipelines/index.ts:142-151 (registration)

  Dispatch handler in the pipelines request switch statement that parses arguments with TriggerPipelineSchema and calls the triggerPipeline function.

  case 'trigger_pipeline': {
    const args = TriggerPipelineSchema.parse(request.params.arguments);
    const result = await triggerPipeline(connection, {
      ...args,
      projectId: args.projectId ?? defaultProject,
    });
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/features/pipelines/index.ts:56-56 (registration)

  Inclusion of 'trigger_pipeline' in the isPipelinesRequest tool name check.

  'trigger_pipeline',