Get Git branches for a version-controlled project

Instructions

Implementation Reference

• src/tools/getBranches.ts:27-77 (handler)

  The handler function that executes the get_branches tool logic: validates the project ID, creates an API client, resolves the space, calls getProjectBranches helper, and returns the formatted branch results.

    async ({ spaceName, projectId, searchByName, skip, take }) => {
      validateEntityId(projectId, 'project', ENTITY_PREFIXES.project);
  
      const options = {
        searchByName,
        skip,
        take,
      };
  
      try {
        const configuration = getClientConfigurationFromEnvironment();
        const client = await Client.create(configuration);
        const spaceId = await resolveSpaceId(client, spaceName);
  
        const branches = await getProjectBranches(client, spaceId, projectId, options);
  
        if (branches.Items.length === 0 && !searchByName) {
          throw new Error(
            `No branches found for project '${projectId}'. This may indicate that the project is not version controlled or ` +
            "uses database storage instead of Git. Only version controlled projects have branches."
          );
        }
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                Items: branches.Items.map(branch => ({
                  Name: branch.Name,
                  IsProtected: branch.IsProtected,
                  CanonicalName: branch.CanonicalName,
                })),
                TotalResults: branches.TotalResults,
                ItemsPerPage: branches.ItemsPerPage,
                NumberOfPages: branches.NumberOfPages,
                LastPageNumber: branches.LastPageNumber,
                ItemType: branches.ItemType,
              }),
            },
          ],
        };
      } catch (error) {
        handleOctopusApiError(error, {
          entityType: 'project',
          entityId: projectId,
          spaceName
        });
      }
    }
  );

• src/tools/getBranches.ts:10-84 (registration)

  Registration of the get_branches tool via McpServer.registerTool with input schema (spaceName, projectId, searchByName, skip, take), description, and read-only annotations.

  export function registerGetBranchesTool(server: McpServer) {
    server.registerTool(
      "get_branches",
      {
        title: "Get Git branches for a version-controlled project",
        description: `Get Git branches for a version-controlled project
  
  This tool retrieves Git branches for a specific project in a space. The space name and project ID are required. Optionally provide searchByName, skip, and take parameters for filtering and pagination.`,
        inputSchema: {
          spaceName: z.string(),
          projectId: z.string(),
          searchByName: z.string().optional(),
          skip: z.number().optional(),
          take: z.number().optional(),
        },
        annotations: READ_ONLY_TOOL_ANNOTATIONS,
      },
      async ({ spaceName, projectId, searchByName, skip, take }) => {
        validateEntityId(projectId, 'project', ENTITY_PREFIXES.project);
  
        const options = {
          searchByName,
          skip,
          take,
        };
  
        try {
          const configuration = getClientConfigurationFromEnvironment();
          const client = await Client.create(configuration);
          const spaceId = await resolveSpaceId(client, spaceName);
  
          const branches = await getProjectBranches(client, spaceId, projectId, options);
  
          if (branches.Items.length === 0 && !searchByName) {
            throw new Error(
              `No branches found for project '${projectId}'. This may indicate that the project is not version controlled or ` +
              "uses database storage instead of Git. Only version controlled projects have branches."
            );
          }
  
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify({
                  Items: branches.Items.map(branch => ({
                    Name: branch.Name,
                    IsProtected: branch.IsProtected,
                    CanonicalName: branch.CanonicalName,
                  })),
                  TotalResults: branches.TotalResults,
                  ItemsPerPage: branches.ItemsPerPage,
                  NumberOfPages: branches.NumberOfPages,
                  LastPageNumber: branches.LastPageNumber,
                  ItemType: branches.ItemType,
                }),
              },
            ],
          };
        } catch (error) {
          handleOctopusApiError(error, {
            entityType: 'project',
            entityId: projectId,
            spaceName
          });
        }
      }
    );
  }
  
  registerToolDefinition({
    toolName: "get_branches",
    config: { toolset: "context", readOnly: true },
    registerFn: registerGetBranchesTool,
    minimumOctopusVersion: "2021.2",

• src/tools/getBranches.ts:80-84 (registration)

  Self-registration via registerToolDefinition, adding to the TOOL_REGISTRY map with toolset 'context', readOnly=true, and minimum Octopus version 2021.2.

  registerToolDefinition({
    toolName: "get_branches",
    config: { toolset: "context", readOnly: true },
    registerFn: registerGetBranchesTool,
    minimumOctopusVersion: "2021.2",

• src/helpers/vcsProjectHelpers.ts:4-34 (helper)

  The getProjectBranches helper function that makes the API call to ~/api/{spaceId}/projects/{projectId}/git/branches with optional query params (searchByName, skip, take).

  export async function getProjectBranches(
    client: Client,
    spaceId: string,
    projectId: string,
    options?: GetProjectBranchesOptions
  ): Promise<ResourceCollection<GitBranch>> {
    const queryParams: Record<string, string> = {};
  
    if (options?.searchByName) {
      queryParams.searchByName = options.searchByName;
    }
  
    if (options?.skip !== undefined) {
      queryParams.skip = options.skip.toString();
    }
  
    if (options?.take !== undefined) {
      queryParams.take = options.take.toString();
    }
  
    const result = await client.get<ResourceCollection<GitBranch>>(
      "~/api/{spaceId}/projects/{projectId}/git/branches{?skip,take,searchByName}",
      {
        spaceId,
        projectId,
        ...queryParams,
      },
    );
  
    return result;
  }

• src/types/gitBranchTypes.ts:1-10 (schema)

  Type definitions for GitBranch interface (IsProtected, Name, CanonicalName) and GetProjectBranchesOptions (searchByName, skip, take).

  export interface GitBranch {
    IsProtected: boolean;
    Name: string;
    CanonicalName: string;
  }
  
  export interface GetProjectBranchesOptions {
    searchByName?: string;
    skip?: number;
    take?: number;