Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/pull-requests/list-pull-requests/feature.ts:18-127 (handler)

  The core handler function that implements the logic to list pull requests using the Azure DevOps Git API, including filtering by status, creator, reviewer, branches, pagination with top/skip, and single PR lookup by ID.

  export async function listPullRequests(
    connection: WebApi,
    projectId: string,
    repositoryId: string,
    options: ListPullRequestsOptions,
  ): Promise<{
    count: number;
    value: PullRequest[];
    hasMoreResults: boolean;
    warning?: string;
  }> {
    try {
      const gitApi = await connection.getGitApi();
  
      if (options.pullRequestId !== undefined) {
        const pullRequest = await gitApi.getPullRequest(
          repositoryId,
          options.pullRequestId,
          projectId,
        );
  
        const value = pullRequest ? [pullRequest] : [];
        return {
          count: value.length,
          value,
          hasMoreResults: false,
          warning: undefined,
        };
      }
  
      // Create search criteria
      const searchCriteria: GitPullRequestSearchCriteria = {};
  
      // Add filters if provided
      if (options.status) {
        // Map our status enum to Azure DevOps PullRequestStatus
        switch (options.status) {
          case 'active':
            searchCriteria.status = PullRequestStatus.Active;
            break;
          case 'abandoned':
            searchCriteria.status = PullRequestStatus.Abandoned;
            break;
          case 'completed':
            searchCriteria.status = PullRequestStatus.Completed;
            break;
          case 'all':
            // Don't set status to get all
            break;
        }
      }
  
      if (options.creatorId) {
        searchCriteria.creatorId = options.creatorId;
      }
  
      if (options.reviewerId) {
        searchCriteria.reviewerId = options.reviewerId;
      }
  
      if (options.sourceRefName) {
        searchCriteria.sourceRefName = options.sourceRefName;
      }
  
      if (options.targetRefName) {
        searchCriteria.targetRefName = options.targetRefName;
      }
  
      // Set default values for pagination
      const top = options.top ?? 10;
      const skip = options.skip ?? 0;
  
      // List pull requests with search criteria
      const pullRequests = await gitApi.getPullRequests(
        repositoryId,
        searchCriteria,
        projectId,
        undefined, // maxCommentLength
        skip,
        top,
      );
  
      const results = pullRequests || [];
      const count = results.length;
  
      // Determine if there are likely more results
      // If we got exactly the number requested, there are probably more
      const hasMoreResults = count === top;
  
      // Add a warning message if results were truncated
      let warning: string | undefined;
      if (hasMoreResults) {
        warning = `Results limited to ${top} items. Use 'skip: ${skip + top}' to get the next page.`;
      }
  
      return {
        count,
        value: results,
        hasMoreResults,
        warning,
      };
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to list pull requests: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/pull-requests/schemas.ts:53-89 (schema)

  Zod schema defining the input parameters for the list_pull_requests tool, including projectId, repositoryId, filters like status, creatorId, pagination options.

  export const ListPullRequestsSchema = z.object({
    projectId: z
      .string()
      .optional()
      .describe(`The ID or name of the project (Default: ${defaultProject})`),
    organizationId: z
      .string()
      .optional()
      .describe(`The ID or name of the organization (Default: ${defaultOrg})`),
    repositoryId: z.string().describe('The ID or name of the repository'),
    status: z
      .enum(['all', 'active', 'completed', 'abandoned'])
      .optional()
      .describe('Filter by pull request status'),
    creatorId: z
      .string()
      .optional()
      .describe('Filter by creator ID (must be a UUID string)'),
    reviewerId: z
      .string()
      .optional()
      .describe('Filter by reviewer ID (must be a UUID string)'),
    sourceRefName: z.string().optional().describe('Filter by source branch name'),
    targetRefName: z.string().optional().describe('Filter by target branch name'),
    top: z
      .number()
      .default(10)
      .describe('Maximum number of pull requests to return (default: 10)'),
    skip: z
      .number()
      .optional()
      .describe('Number of pull requests to skip for pagination'),
    pullRequestId: z
      .number()
      .optional()
      .describe('If provided, return only the matching pull request ID'),
  });

• src/features/pull-requests/tool-definitions.ts:23-27 (registration)

  Tool definition registration in the pullRequestsTools array, specifying name, description, and input JSON schema for MCP tool discovery.

  {
    name: 'list_pull_requests',
    description: 'List pull requests in a repository',
    inputSchema: zodToJsonSchema(ListPullRequestsSchema),
  },

• src/features/pull-requests/index.ts:77-98 (registration)

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

  case 'list_pull_requests': {
    const params = ListPullRequestsSchema.parse(request.params.arguments);
    const result = await listPullRequests(
      connection,
      params.projectId ?? defaultProject,
      params.repositoryId,
      {
        projectId: params.projectId ?? defaultProject,
        repositoryId: params.repositoryId,
        status: params.status,
        creatorId: params.creatorId,
        reviewerId: params.reviewerId,
        sourceRefName: params.sourceRefName,
        targetRefName: params.targetRefName,
        top: params.top,
        skip: params.skip,
        pullRequestId: params.pullRequestId,
      },
    );
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };

• src/features/pull-requests/types.ts:58-69 (helper)

  TypeScript interface defining the options parameter for the listPullRequests handler function.

  export interface ListPullRequestsOptions {
    projectId: string;
    repositoryId: string;
    status?: 'all' | 'active' | 'completed' | 'abandoned';
    creatorId?: string;
    reviewerId?: string;
    sourceRefName?: string;
    targetRefName?: string;
    top?: number;
    skip?: number;
    pullRequestId?: number;
  }