TeamCity MCP Server

Instructions

Implementation Reference

• src/teamcity/build-config-navigator.ts:102-158 (handler)

  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);
    }
  }

• src/teamcity/build-config-navigator.ts:17-42 (schema)

  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;
    };
  }

• src/teamcity/build-config-navigator.ts:79-85 (schema)

  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>;
  }

• src/teamcity/build-config-navigator.ts:223-293 (helper)

  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;
  }