list_build_configs
Retrieve and filter build configurations from TeamCity with pagination support for efficient CI/CD pipeline management.
Instructions
List build configurations (supports pagination)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| locator | No | Optional build type locator to filter | |
| projectId | No | Filter by project ID | |
| pageSize | No | Items per page (default 100) | |
| maxPages | No | Max pages to fetch (when all=true) | |
| all | No | Fetch all pages up to maxPages | |
| fields | No | Optional fields selector for server-side projection |
Implementation Reference
- Core handler function implementing list_build_configs tool logic: fetches, filters, sorts, caches TeamCity build configurations with optional metadata (VCS roots, parameters, project hierarchy) and advanced filtering (name, VCS, status)./** * List build configurations with optional filtering and metadata extraction */ async listBuildConfigs( params: BuildConfigNavigatorParams = {} ): Promise<BuildConfigNavigatorResult> { const cacheKey = this.generateCacheKey(params); // Check cache first const cachedEntry = this.cache.get(cacheKey); if (cachedEntry != null && Date.now() - cachedEntry.timestamp < this.cacheTtlMs) { debug('Cache hit for build configurations', { cacheKey }); return cachedEntry.data; } try { const locator = this.buildLocator(params); const fields = this.buildFields(params); debug('Fetching build configurations', { locator }); const response = await this.client.modules.buildTypes.getAllBuildTypes(locator, fields); if (response.data == null || !isBuildTypesResponse(response.data)) { throw new Error('Invalid API response from TeamCity'); } const buildConfigs = await this.processBuildConfigs(response.data, params); const totalCount = response.data.count ?? buildConfigs.length; const result: BuildConfigNavigatorResult = { buildConfigs, totalCount, hasMore: this.calculateHasMore(buildConfigs.length, totalCount, params.pagination), viewMode: params.viewMode ?? 'list', groupedByProject: params.viewMode === 'project-grouped' ? this.groupBuildConfigsByProject(buildConfigs) : undefined, }; // Cache successful results this.cacheResult(cacheKey, result); return result; } catch (error) { logError( 'Failed to fetch build configurations', error instanceof Error ? error : new Error(String(error)), { locator: this.buildLocator(params), } ); throw this.transformError(error, params); } }
- Input schema defining parameters for filtering, sorting, pagination, and metadata inclusion in list_build_configs tool.export interface BuildConfigNavigatorParams { projectId?: string; projectIds?: string[]; namePattern?: string; includeVcsRoots?: boolean; includeParameters?: boolean; includeProjectHierarchy?: boolean; viewMode?: 'list' | 'project-grouped'; vcsRootFilter?: { url?: string; branch?: string; vcsName?: string; }; statusFilter?: { lastBuildStatus?: 'SUCCESS' | 'FAILURE' | 'ERROR' | 'UNKNOWN'; paused?: boolean; hasRecentActivity?: boolean; activeSince?: Date; }; sortBy?: 'name' | 'project' | 'lastModified'; sortOrder?: 'asc' | 'desc'; pagination?: { limit?: number; offset?: number; }; }
- Output schema for the list_build_configs tool result, including build configs list, counts, and optional project grouping.export interface BuildConfigNavigatorResult { buildConfigs: BuildConfig[]; totalCount: number; hasMore: boolean; viewMode: 'list' | 'project-grouped'; groupedByProject?: Record<string, ProjectGroup>; }
- Helper method that processes raw TeamCity API response into structured BuildConfig objects, applies client-side filters and extractions.private async processBuildConfigs( data: BuildTypesResponse, params: BuildConfigNavigatorParams ): Promise<BuildConfig[]> { const buildTypes = data.buildType ?? []; let buildConfigs: BuildConfig[] = []; for (const buildType of buildTypes) { const buildConfig: BuildConfig = { id: buildType.id ?? '', name: buildType.name ?? '', projectId: buildType.projectId ?? buildType.project?.id ?? '', projectName: buildType.projectName ?? buildType.project?.name ?? '', description: buildType.description, href: buildType.href, webUrl: buildType.webUrl, lastBuildDate: buildType.lastBuildDate, lastBuildStatus: buildType.lastBuildStatus, paused: buildType.paused, }; // Apply name pattern filtering if specified if (params.namePattern && !this.matchesPattern(buildConfig.name, params.namePattern)) { continue; } // Extract VCS roots if requested or needed for filtering const needVcsRoots = params.includeVcsRoots === true ? true : params.vcsRootFilter != null; if (needVcsRoots && buildType['vcs-root-entries']) { buildConfig.vcsRoots = this.extractVcsRoots(buildType['vcs-root-entries']); // Apply VCS root filtering if specified if ( params.vcsRootFilter && !this.matchesVcsRootFilter(buildConfig.vcsRoots, params.vcsRootFilter) ) { continue; } } // Extract parameters if requested if (params.includeParameters && buildType.parameters) { buildConfig.parameters = this.extractParameters(buildType.parameters); } // Extract project hierarchy if requested if (params.includeProjectHierarchy) { // Intentional sequential per-item hierarchy fetch; keeps API usage simple in list flows // eslint-disable-next-line no-await-in-loop buildConfig.projectHierarchy = await this.extractProjectHierarchy(buildConfig.projectId); } // Apply status filtering if specified if (params.statusFilter && !this.matchesStatusFilter(buildConfig, params.statusFilter)) { continue; } buildConfigs.push(buildConfig); } // Apply sorting if specified if (params.sortBy) { buildConfigs = this.sortBuildConfigs(buildConfigs, params.sortBy, params.sortOrder ?? 'asc'); } // Note: Pagination is already applied at the API level via the locator // (see buildLocator method which adds count and start parameters) // So we don't need to apply client-side pagination here return buildConfigs; }