get_branches
Retrieve Git branches for version-controlled projects in Octopus Deploy. Filter branches by name and manage results with pagination to streamline DevOps workflows.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spaceName | Yes | ||
| projectId | Yes | ||
| searchByName | No | ||
| skip | No | ||
| take | No |
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, }), }, ], }; } ); }
- 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", });