Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/pipelines/download-pipeline-artifact/feature.ts:304-388 (handler)

  Core handler function that orchestrates downloading a specific file from a pipeline run's artifact using Azure DevOps Build and Pipelines APIs, handling both container and zip-based artifacts.

  export async function downloadPipelineArtifact(
    connection: WebApi,
    options: DownloadPipelineArtifactOptions,
  ): Promise<PipelineArtifactContent> {
    try {
      const projectId = options.projectId ?? defaultProject;
      const runId = options.runId;
      const { artifactName, relativePath } = normalizeArtifactPath(
        options.artifactPath,
      );
  
      const buildApi = await connection.getBuildApi();
  
      let artifacts: BuildArtifact[];
      try {
        artifacts = await buildApi.getArtifacts(projectId, runId);
      } catch (error) {
        throw new AzureDevOpsResourceNotFoundError(
          `Pipeline run ${runId} not found in project ${projectId}: ${String(error)}`,
        );
      }
  
      const artifact = artifacts.find((item) => item.name === artifactName);
      if (!artifact) {
        throw new AzureDevOpsResourceNotFoundError(
          `Artifact ${artifactName} not found for run ${runId} in project ${projectId}.`,
        );
      }
  
      const containerResult = await downloadFromContainer(
        connection,
        projectId,
        artifactName,
        artifact,
        relativePath,
      );
  
      if (containerResult) {
        return containerResult;
      }
  
      return await downloadFromPipelineArtifact(
        connection,
        projectId,
        runId,
        artifactName,
        artifact,
        relativePath,
        options.pipelineId,
      );
    } 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 artifact or project not found: ${error.message}`,
          );
        }
      }
  
      throw new AzureDevOpsError(
        `Failed to download pipeline artifact: ${
          error instanceof Error ? error.message : String(error)
        }`,
      );
    }
  }

• src/features/pipelines/download-pipeline-artifact/schema.ts:4-22 (schema)

  Zod schema defining the input parameters for the download_pipeline_artifact tool.

  export const DownloadPipelineArtifactSchema = 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'),
    artifactPath: z
      .string()
      .min(1)
      .describe(
        'Path to the desired file inside the artifact (format: <artifactName>/<path/to/file>)',
      ),
    pipelineId: z
      .number()
      .int()
      .min(1)
      .optional()
      .describe('Optional guard; validates the run belongs to this pipeline'),
  });

• src/features/pipelines/tool-definitions.ts:40-46 (registration)

  Tool definition registration including name, description, and input schema.

  {
    name: 'download_pipeline_artifact',
    description:
      'Download a file from a pipeline run artifact and return its textual content',
    inputSchema: zodToJsonSchema(DownloadPipelineArtifactSchema),
    mcp_enabled: true,
  },

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

  Request handler switch case that parses arguments with the schema and invokes the downloadPipelineArtifact handler.

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