Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/pipelines/list-pipeline-runs/feature.ts:52-160 (handler)

  Implements the core logic for listing pipeline runs using the Azure DevOps Pipelines REST API. Constructs the API URL with filters for top count, continuation token, branch, state, result, date range, and order. Handles pagination, errors like authentication, not found, and generic failures.

  export async function listPipelineRuns(
    connection: WebApi,
    options: ListPipelineRunsOptions,
  ): Promise<ListPipelineRunsResult> {
    try {
      const pipelinesApi = await connection.getPipelinesApi();
      const projectId = options.projectId ?? defaultProject;
      const pipelineId = options.pipelineId;
  
      const baseUrl = connection.serverUrl.replace(/\/+$/, '');
      const route = `${encodeURIComponent(projectId)}/_apis/pipelines/${pipelineId}/runs`;
      const url = new URL(`${route}`, `${baseUrl}/`);
  
      url.searchParams.set('api-version', API_VERSION);
  
      const top = Math.min(Math.max(options.top ?? 50, 1), 100);
      url.searchParams.set('$top', top.toString());
  
      if (options.continuationToken) {
        url.searchParams.set('continuationToken', options.continuationToken);
      }
  
      const branch = normalizeBranch(options.branch);
      if (branch) {
        url.searchParams.set('branch', branch);
      }
  
      if (options.state) {
        url.searchParams.set('state', options.state);
      }
  
      if (options.result) {
        url.searchParams.set('result', options.result);
      }
  
      if (options.createdFrom) {
        url.searchParams.set('createdDate/min', options.createdFrom);
      }
  
      if (options.createdTo) {
        url.searchParams.set('createdDate/max', options.createdTo);
      }
  
      url.searchParams.set('orderBy', options.orderBy ?? 'createdDate desc');
  
      const requestOptions = pipelinesApi.createRequestOptions(
        'application/json',
        API_VERSION,
      );
  
      const response = await pipelinesApi.rest.get<{
        value?: Run[];
        continuationToken?: string;
      }>(url.toString(), requestOptions);
  
      if (response.statusCode === 404 || !response.result) {
        throw new AzureDevOpsResourceNotFoundError(
          `Pipeline ${pipelineId} or project ${projectId} not found`,
        );
      }
  
      const runs =
        (pipelinesApi.formatResponse(
          response.result,
          TypeInfo.Run,
          true,
        ) as Run[]) ?? [];
  
      const continuationToken = extractContinuationToken(
        response.headers as Record<string, unknown>,
        response.result,
      );
  
      return continuationToken ? { runs, continuationToken } : { runs };
    } 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 or project not found: ${error.message}`,
          );
        }
      }
  
      throw new AzureDevOpsError(
        `Failed to list pipeline runs: ${
          error instanceof Error ? error.message : String(error)
        }`,
      );
    }
  }

• src/features/pipelines/list-pipeline-runs/schema.ts:4-47 (schema)

  Zod schema for validating input arguments to the list_pipeline_runs tool, including optional projectId, required pipelineId, pagination top/continuationToken, filters for branch/state/result/date, and ordering.

  export const ListPipelineRunsSchema = z.object({
    projectId: z
      .string()
      .optional()
      .describe(`The ID or name of the project (Default: ${defaultProject})`),
    pipelineId: z.number().int().min(1).describe('Pipeline numeric ID'),
    top: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(50)
      .describe('Maximum number of runs to return (1-100)'),
    continuationToken: z
      .string()
      .optional()
      .describe('Continuation token for pagination'),
    branch: z
      .string()
      .optional()
      .describe('Branch to filter by (e.g., "main" or "refs/heads/main")'),
    state: z
      .enum(['notStarted', 'inProgress', 'completed', 'cancelling', 'postponed'])
      .optional()
      .describe('Filter by current run state'),
    result: z
      .enum(['succeeded', 'partiallySucceeded', 'failed', 'canceled', 'none'])
      .optional()
      .describe('Filter by final run result'),
    createdFrom: z
      .string()
      .datetime()
      .optional()
      .describe('Filter runs created at or after this time (ISO 8601)'),
    createdTo: z
      .string()
      .datetime()
      .optional()
      .describe('Filter runs created at or before this time (ISO 8601)'),
    orderBy: z
      .enum(['createdDate desc', 'createdDate asc'])
      .default('createdDate desc')
      .describe('Sort order for run creation date'),
  });

• src/features/pipelines/tool-definitions.ts:28-33 (registration)

  Registers the list_pipeline_runs tool in the MCP tool definitions array, specifying name, description, input schema converted to JSON schema, and MCP enabled flag.

  {
    name: 'list_pipeline_runs',
    description: 'List recent runs for a pipeline',
    inputSchema: zodToJsonSchema(ListPipelineRunsSchema),
    mcp_enabled: true,
  },

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

  Dispatch handler in pipelines/index.ts that matches on tool name 'list_pipeline_runs', parses arguments using the schema, calls the listPipelineRuns function with default project fallback, and returns JSON stringified result.

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