Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/repositories/create-branch/feature.ts:9-49 (handler)

  Core handler function that executes the branch creation logic using Azure DevOps Git API: fetches source branch commit, creates ref update, and pushes the new branch.

  export async function createBranch(
    connection: WebApi,
    options: CreateBranchOptions,
  ): Promise<void> {
    try {
      const gitApi = await connection.getGitApi();
      const source = await gitApi.getBranch(
        options.repositoryId,
        options.sourceBranch,
        options.projectId,
      );
      const commitId = source?.commit?.commitId;
      if (!commitId) {
        throw new AzureDevOpsError(
          `Source branch '${options.sourceBranch}' not found`,
        );
      }
  
      const refUpdate: GitRefUpdate = {
        name: `refs/heads/${options.newBranch}`,
        oldObjectId: '0000000000000000000000000000000000000000',
        newObjectId: commitId,
      };
  
      const result = await gitApi.updateRefs(
        [refUpdate],
        options.repositoryId,
        options.projectId,
      );
      if (!result.every((r) => r.success)) {
        throw new AzureDevOpsError('Failed to create new branch');
      }
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to create branch: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/repositories/schemas.ts:169-195 (schema)

  Zod schema for validating input arguments to the create_branch tool: projectId, organizationId, repositoryId, sourceBranch, newBranch.

  export const CreateBranchSchema = 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'),
      sourceBranch: z
        .string()
        .describe(
          'Name of the branch to copy from (without "refs/heads/", e.g., "master")',
        ),
      newBranch: z
        .string()
        .describe(
          'Name of the new branch to create (without "refs/heads/", e.g., "feature/my-branch")',
        ),
    })
    .describe(
      'Create a new branch from an existing branch.\n' +
        '- Pass plain branch names (no "refs/heads/"). Example: sourceBranch="master", newBranch="codex/test1".\n' +
        '- When creating pull requests later, use fully-qualified refs (e.g., "refs/heads/codex/test1").',
    );

• src/features/repositories/tool-definitions.ts:52-56 (registration)

  MCP tool registration defining the 'create_branch' tool name, description, and JSON schema for inputs.

  {
    name: 'create_branch',
    description: 'Create a new branch from an existing one',
    inputSchema: zodToJsonSchema(CreateBranchSchema),
  },

• src/features/repositories/index.ts:180-189 (registration)

  Request handler switch case that parses arguments with CreateBranchSchema and invokes the createBranch handler function.

  case 'create_branch': {
    const args = CreateBranchSchema.parse(request.params.arguments);
    await createBranch(connection, {
      ...args,
      projectId: args.projectId ?? defaultProject,
    });
    return {
      content: [{ type: 'text', text: 'Branch created successfully' }],
    };
  }

• src/features/repositories/types.ts:72-79 (helper)

  TypeScript interface defining options passed to the createBranch handler function.

  export interface CreateBranchOptions {
    projectId: string;
    repositoryId: string;
    /** Source branch name to copy from */
    sourceBranch: string;
    /** Name of the new branch to create */
    newBranch: string;
  }