Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/pipelines/get-pipeline-log/feature.ts:12-102 (handler)

  Implements the core logic for retrieving pipeline logs from Azure DevOps, handling both JSON and plain text formats, with error handling for authentication and not found cases.

  export async function getPipelineLog(
    connection: WebApi,
    options: GetPipelineLogOptions,
  ): Promise<PipelineLogContent> {
    try {
      const buildApi = await connection.getBuildApi();
      const projectId = options.projectId ?? defaultProject;
      const { runId, logId, format, startLine, endLine } = options;
  
      if (format === 'json') {
        const route = `${encodeURIComponent(projectId)}/_apis/build/builds/${runId}/logs/${logId}`;
        const baseUrl = connection.serverUrl.replace(/\/+$/, '');
        const url = new URL(`${route}`, `${baseUrl}/`);
        url.searchParams.set('api-version', API_VERSION);
        url.searchParams.set('format', 'json');
        if (typeof startLine === 'number') {
          url.searchParams.set('startLine', startLine.toString());
        }
        if (typeof endLine === 'number') {
          url.searchParams.set('endLine', endLine.toString());
        }
  
        const requestOptions = buildApi.createRequestOptions(
          'application/json',
          API_VERSION,
        );
  
        const response = await buildApi.rest.get<PipelineLogContent | null>(
          url.toString(),
          requestOptions,
        );
  
        if (response.statusCode === 404 || response.result === null) {
          throw new AzureDevOpsResourceNotFoundError(
            `Log ${logId} not found for run ${runId} in project ${projectId}`,
          );
        }
  
        return response.result;
      }
  
      const lines = await buildApi.getBuildLogLines(
        projectId,
        runId,
        logId,
        startLine,
        endLine,
      );
  
      if (!lines) {
        throw new AzureDevOpsResourceNotFoundError(
          `Log ${logId} not found for run ${runId} in project ${projectId}`,
        );
      }
  
      return lines.join('\n');
    } 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 log or project not found: ${error.message}`,
          );
        }
      }
  
      throw new AzureDevOpsError(
        `Failed to retrieve pipeline log: ${
          error instanceof Error ? error.message : String(error)
        }`,
      );
    }
  }

• src/features/pipelines/get-pipeline-log/schema.ts:4-37 (schema)

  Zod schema defining and validating the input parameters for the get_pipeline_log tool.

  export const GetPipelineLogSchema = 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'),
    logId: z
      .number()
      .int()
      .min(1)
      .describe('Log identifier from the timeline record'),
    format: z
      .enum(['plain', 'json'])
      .optional()
      .describe('Optional format for the log contents (plain or json)'),
    startLine: z
      .number()
      .int()
      .min(0)
      .optional()
      .describe('Optional starting line number for the log segment'),
    endLine: z
      .number()
      .int()
      .min(0)
      .optional()
      .describe('Optional ending line number for the log segment'),
    pipelineId: z
      .number()
      .int()
      .min(1)
      .optional()
      .describe('Optional pipeline numeric ID for reference only'),
  });

• src/features/pipelines/tool-definitions.ts:54-60 (registration)

  Registers the get_pipeline_log tool in the MCP tool definitions array, including name, description, and converted input schema.

  {
    name: 'get_pipeline_log',
    description:
      'Retrieve a specific pipeline log using the timeline log identifier',
    inputSchema: zodToJsonSchema(GetPipelineLogSchema),
    mcp_enabled: true,
  },

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

  Dispatches the get_pipeline_log tool request by parsing arguments, calling the handler, and formatting the response in the pipelines request handler.

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