Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/pipelines/get-pipeline-run/feature.ts:15-140 (handler)

  The core handler function that implements the logic for retrieving pipeline run details, including API calls, artifact fetching, and error handling.

  export async function getPipelineRun(
    connection: WebApi,
    options: GetPipelineRunOptions,
  ): Promise<PipelineRunDetails> {
    try {
      const pipelinesApi = await connection.getPipelinesApi();
      const projectId = options.projectId ?? defaultProject;
      const runId = options.runId;
      const resolvedPipelineId = await resolvePipelineId(
        connection,
        projectId,
        runId,
        options.pipelineId,
      );
  
      const baseUrl = connection.serverUrl.replace(/\/+$/, '');
      const encodedProject = encodeURIComponent(projectId);
  
      const requestOptions = pipelinesApi.createRequestOptions(
        'application/json',
        API_VERSION,
      );
  
      const buildRunUrl = (pipelineId?: number) => {
        const route =
          typeof pipelineId === 'number'
            ? `${encodedProject}/_apis/pipelines/${pipelineId}/runs/${runId}`
            : `${encodedProject}/_apis/pipelines/runs/${runId}`;
        const url = new URL(`${route}`, `${baseUrl}/`);
        url.searchParams.set('api-version', API_VERSION);
        return url;
      };
  
      const urlsToTry: URL[] = [];
      if (typeof resolvedPipelineId === 'number') {
        urlsToTry.push(buildRunUrl(resolvedPipelineId));
      }
      urlsToTry.push(buildRunUrl());
  
      let response: {
        statusCode: number;
        result: PipelineRunDetails | null;
      } | null = null;
  
      for (const url of urlsToTry) {
        const attempt = await pipelinesApi.rest.get<PipelineRunDetails | null>(
          url.toString(),
          requestOptions,
        );
  
        if (attempt.statusCode !== 404 && attempt.result) {
          response = attempt;
          break;
        }
      }
  
      if (!response || !response.result) {
        throw new AzureDevOpsResourceNotFoundError(
          `Pipeline run ${runId} not found in project ${projectId}`,
        );
      }
  
      const run = pipelinesApi.formatResponse(
        response.result,
        TypeInfo.Run,
        false,
      ) as PipelineRunDetails;
  
      if (!run) {
        throw new AzureDevOpsResourceNotFoundError(
          `Pipeline run ${runId} not found in project ${projectId}`,
        );
      }
  
      const artifacts = await fetchRunArtifacts(
        connection,
        projectId,
        runId,
        resolvedPipelineId,
      );
  
      if (typeof options.pipelineId === 'number') {
        const runPipelineId = coercePipelineId(run.pipeline?.id);
        if (runPipelineId !== options.pipelineId) {
          throw new AzureDevOpsResourceNotFoundError(
            `Run ${runId} does not belong to pipeline ${options.pipelineId}`,
          );
        }
      }
  
      return artifacts.length > 0 ? { ...run, artifacts } : run;
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
  
      if (error instanceof Error) {
        const message = error.message.toLowerCase();
        if (
          message.includes('authentication') ||
          message.includes('unauthorized') ||
          message.includes('401')
        ) {
          throw new AzureDevOpsAuthenticationError(
            `Failed to authenticate: ${error.message}`,
          );
        }
  
        if (
          message.includes('not found') ||
          message.includes('does not exist') ||
          message.includes('404')
        ) {
          throw new AzureDevOpsResourceNotFoundError(
            `Pipeline run or project not found: ${error.message}`,
          );
        }
      }
  
      throw new AzureDevOpsError(
        `Failed to get pipeline run: ${
          error instanceof Error ? error.message : String(error)
        }`,
      );
    }
  }

• src/features/pipelines/get-pipeline-run/schema.ts:4-16 (schema)

  Zod schema defining the input parameters for the get_pipeline_run tool.

  export const GetPipelineRunSchema = z.object({
    projectId: z
      .string()
      .optional()
      .describe(`The ID or name of the project (Default: ${defaultProject})`),
    runId: z.number().int().min(1).describe('Pipeline run identifier'),
    pipelineId: z
      .number()
      .int()
      .min(1)
      .optional()
      .describe('Optional guard; validates the run belongs to this pipeline'),
  });

• src/features/pipelines/tool-definitions.ts:34-39 (registration)

  Tool registration definition including name, description, and input schema conversion for MCP.

  {
    name: 'get_pipeline_run',
    description: 'Get details for a specific pipeline run',
    inputSchema: zodToJsonSchema(GetPipelineRunSchema),
    mcp_enabled: true,
  },

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

  Request handler switch case that invokes the getPipelineRun handler after schema validation.

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