Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/pull-requests/update-pull-request/feature.ts:45-245 (handler)

  The core handler function that executes the update_pull_request tool logic. It uses Azure DevOps Git API to update PR properties, links/unlinks work items, adds/removes reviewers, and manages tags.

  export const updatePullRequest = async (
    options: UpdatePullRequestOptions,
  ): Promise<GitPullRequest> => {
    const {
      projectId,
      repositoryId,
      pullRequestId,
      title,
      description,
      status,
      isDraft,
      addWorkItemIds,
      removeWorkItemIds,
      addReviewers,
      removeReviewers,
      addTags,
      removeTags,
      additionalProperties,
    } = options;
  
    try {
      // Get connection to Azure DevOps
      const client = new AzureDevOpsClient({
        method:
          (process.env.AZURE_DEVOPS_AUTH_METHOD as AuthenticationMethod) ?? 'pat',
        organizationUrl: process.env.AZURE_DEVOPS_ORG_URL ?? '',
        personalAccessToken: process.env.AZURE_DEVOPS_PAT,
      });
      const connection = await client.getWebApiClient();
  
      // Get the Git API client
      const gitApi = await connection.getGitApi();
  
      // First, get the current pull request
      const pullRequest = await gitApi.getPullRequestById(
        pullRequestId,
        projectId,
      );
  
      if (!pullRequest) {
        throw new AzureDevOpsError(
          `Pull request ${pullRequestId} not found in repository ${repositoryId}`,
        );
      }
  
      // Store the artifactId for work item linking
      const artifactId = pullRequest.artifactId;
      const effectivePullRequestId = pullRequest.pullRequestId ?? pullRequestId;
  
      // Create an object with the properties to update
      const updateObject: Partial<GitPullRequest> = {};
  
      if (title !== undefined) {
        updateObject.title = title;
      }
  
      if (description !== undefined) {
        updateObject.description = description;
      }
  
      if (isDraft !== undefined) {
        updateObject.isDraft = isDraft;
      }
  
      if (status) {
        const enumStatus = pullRequestStatusMapper.toEnum(status);
        if (enumStatus !== undefined) {
          updateObject.status = enumStatus;
        } else {
          throw new AzureDevOpsError(
            `Invalid status: ${status}. Valid values are: active, abandoned, completed`,
          );
        }
      }
  
      // Add any additional properties that were specified
      if (additionalProperties) {
        Object.assign(updateObject, additionalProperties);
      }
  
      // Update the pull request
      const updatedPullRequest = await gitApi.updatePullRequest(
        updateObject,
        repositoryId,
        pullRequestId,
        projectId,
      );
  
      // Handle work items separately if needed
      const addIds = addWorkItemIds ?? [];
      const removeIds = removeWorkItemIds ?? [];
      if (addIds.length > 0 || removeIds.length > 0) {
        await handleWorkItems({
          connection,
          pullRequestId,
          repositoryId,
          projectId,
          workItemIdsToAdd: addIds,
          workItemIdsToRemove: removeIds,
          artifactId,
        });
      }
  
      // Handle reviewers separately if needed
      const addReviewerIds = addReviewers ?? [];
      const removeReviewerIds = removeReviewers ?? [];
      if (addReviewerIds.length > 0 || removeReviewerIds.length > 0) {
        await handleReviewers({
          connection,
          pullRequestId,
          repositoryId,
          projectId,
          reviewersToAdd: addReviewerIds,
          reviewersToRemove: removeReviewerIds,
        });
      }
  
      const normalizedTagsToAdd = normalizeTags(addTags);
      const normalizedTagsToRemove = normalizeTags(removeTags);
  
      if (
        effectivePullRequestId &&
        (normalizedTagsToAdd.length > 0 || normalizedTagsToRemove.length > 0)
      ) {
        let labels =
          (await gitApi.getPullRequestLabels(
            repositoryId,
            effectivePullRequestId,
            projectId,
          )) ?? [];
  
        const existingNames = new Set(
          labels
            .map((label) => label.name?.toLowerCase())
            .filter((name): name is string => Boolean(name)),
        );
  
        const tagsToCreate = normalizedTagsToAdd.filter(
          (tag) => !existingNames.has(tag.toLowerCase()),
        );
  
        for (const tag of tagsToCreate) {
          try {
            const createdLabel = await gitApi.createPullRequestLabel(
              { name: tag },
              repositoryId,
              effectivePullRequestId,
              projectId,
            );
            labels.push(createdLabel);
            existingNames.add(tag.toLowerCase());
          } catch (error) {
            throw new Error(
              `Failed to add tag '${tag}': ${
                error instanceof Error ? error.message : String(error)
              }`,
            );
          }
        }
  
        for (const tag of normalizedTagsToRemove) {
          try {
            await gitApi.deletePullRequestLabels(
              repositoryId,
              effectivePullRequestId,
              tag,
              projectId,
            );
            labels = labels.filter((label) => {
              const name = label.name?.toLowerCase();
              return name ? name !== tag.toLowerCase() : true;
            });
            existingNames.delete(tag.toLowerCase());
          } catch (error) {
            if (
              error &&
              typeof error === 'object' &&
              'statusCode' in error &&
              (error as { statusCode?: number }).statusCode === 404
            ) {
              continue;
            }
  
            throw new Error(
              `Failed to remove tag '${tag}': ${
                error instanceof Error ? error.message : String(error)
              }`,
            );
          }
        }
  
        updatedPullRequest.labels = labels;
      }
  
      return updatedPullRequest;
    } catch (error) {
      throw new AzureDevOpsError(
        `Failed to update pull request ${pullRequestId} in repository ${repositoryId}: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  };

• src/features/pull-requests/schemas.ts:180-237 (schema)

  Zod schema for validating input arguments to the update_pull_request tool.

  export const UpdatePullRequestSchema = 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'),
    pullRequestId: z.number().describe('The ID of the pull request to update'),
    title: z
      .string()
      .optional()
      .describe('The updated title of the pull request'),
    description: z
      .string()
      .optional()
      .describe('The updated description of the pull request'),
    status: z
      .enum(['active', 'abandoned', 'completed'])
      .optional()
      .describe('The updated status of the pull request'),
    isDraft: z
      .boolean()
      .optional()
      .describe(
        'Whether the pull request should be marked as a draft (true) or unmarked (false)',
      ),
    addWorkItemIds: z
      .array(z.number())
      .optional()
      .describe('List of work item IDs to link to the pull request'),
    removeWorkItemIds: z
      .array(z.number())
      .optional()
      .describe('List of work item IDs to unlink from the pull request'),
    addReviewers: z
      .array(z.string())
      .optional()
      .describe('List of reviewer email addresses or IDs to add'),
    removeReviewers: z
      .array(z.string())
      .optional()
      .describe('List of reviewer email addresses or IDs to remove'),
    addTags: z
      .array(z.string().trim().min(1))
      .optional()
      .describe('List of tags to add to the pull request'),
    removeTags: z
      .array(z.string().trim().min(1))
      .optional()
      .describe('List of tags to remove from the pull request'),
    additionalProperties: z
      .record(z.string(), z.any())
      .optional()
      .describe('Additional properties to update on the pull request'),
  });

• src/features/pull-requests/tool-definitions.ts:39-44 (registration)

  Tool definition registration for the update_pull_request MCP tool, including name, description, and JSON schema.

  {
    name: 'update_pull_request',
    description:
      'Update an existing pull request with new properties, manage reviewers and work items, and add or remove tags',
    inputSchema: zodToJsonSchema(UpdatePullRequestSchema),
  },

• src/features/pull-requests/index.ts:147-157 (registration)

  MCP request handler dispatcher switch case that parses tool arguments and invokes the updatePullRequest handler.

  case 'update_pull_request': {
    const params = UpdatePullRequestSchema.parse(request.params.arguments);
    const fixedParams = {
      ...params,
      projectId: params.projectId ?? defaultProject,
    };
    const result = await updatePullRequest(fixedParams);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/features/pull-requests/types.ts:111-126 (helper)

  TypeScript interface defining options for the updatePullRequest handler.

  export interface UpdatePullRequestOptions {
    projectId: string;
    repositoryId: string;
    pullRequestId: number;
    title?: string;
    description?: string;
    status?: 'active' | 'abandoned' | 'completed';
    isDraft?: boolean;
    addWorkItemIds?: number[];
    removeWorkItemIds?: number[];
    addReviewers?: string[]; // Array of reviewer identifiers (email or ID)
    removeReviewers?: string[]; // Array of reviewer identifiers (email or ID)
    addTags?: string[];
    removeTags?: string[];
    additionalProperties?: Record<string, string | number | boolean>;
  }