Octopus Deploy MCP Server

Instructions

Implementation Reference

• src/tools/getBranches.ts:25-57 (handler)

  The main handler function implementing the get_branches tool logic: sets up Octopus client, resolves space ID, calls helper to fetch branches, formats and returns as MCP text content.

  async ({ spaceName, projectId, searchByName, skip, take }) => {
    const configuration = getClientConfigurationFromEnvironment();
    const client = await Client.create(configuration);
    const spaceId = await resolveSpaceId(client, spaceName);
  
    const options = {
      searchByName,
      skip,
      take,
    };
  
    const branches = await getProjectBranches(client, spaceId, projectId, options);
  
    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,
          }),
        },
      ],
    };
  }

• src/tools/getBranches.ts:15-20 (schema)

  Zod input schema for the get_branches tool parameters.

    spaceName: z.string(),
    projectId: z.string(),
    searchByName: z.string().optional(),
    skip: z.number().optional(),
    take: z.number().optional(),
  },

• src/tools/getBranches.ts:8-59 (registration)

  Registration of the get_branches tool on the MCP server using server.tool(), including name, description, input schema, output metadata, and handler function.

  export function registerGetBranchesTool(server: McpServer) {
    server.tool(
      "get_branches",
      `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.`,
      {
        spaceName: z.string(),
        projectId: z.string(),
        searchByName: z.string().optional(),
        skip: z.number().optional(),
        take: z.number().optional(),
      },
      {
        title: "Get Git branches for a version-controlled project",
        readOnlyHint: true,
      },
      async ({ spaceName, projectId, searchByName, skip, take }) => {
        const configuration = getClientConfigurationFromEnvironment();
        const client = await Client.create(configuration);
        const spaceId = await resolveSpaceId(client, spaceName);
  
        const options = {
          searchByName,
          skip,
          take,
        };
  
        const branches = await getProjectBranches(client, spaceId, projectId, options);
  
        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,
              }),
            },
          ],
        };
      }
    );
  }

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

  Supporting helper function that performs the actual API call to retrieve Git branches for a project, handling query parameters for search, skip, and 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/tools/getBranches.ts:61-66 (registration)

  Self-registration of the get_branches tool into the global TOOL_REGISTRY for conditional registration in index.ts based on toolset config.

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