@daghis/teamcity-mcp 0.1.2

package/src/teamcity/circuit-breaker.ts

@@ -0,0 +1,219 @@
+/**
+ * Circuit breaker implementation for TeamCity API
+ */
+import { info, warn } from '@/utils/logger';
+
+export enum CircuitState {
+  CLOSED = 'CLOSED',
+  OPEN = 'OPEN',
+  HALF_OPEN = 'HALF_OPEN',
+}
+
+export interface CircuitBreakerOptions {
+  failureThreshold?: number;
+  resetTimeout?: number;
+  monitoringPeriod?: number;
+  successThreshold?: number;
+}
+
+/**
+ * Circuit breaker for API endpoints
+ */
+export class CircuitBreaker {
+  private state: CircuitState = CircuitState.CLOSED;
+  private failureCount = 0;
+  private successCount = 0;
+  private lastFailureTime?: number;
+  private readonly failureThreshold: number;
+  private readonly resetTimeout: number;
+  private readonly monitoringPeriod: number;
+  private readonly successThreshold: number;
+  private readonly name: string;
+
+  constructor(name: string, options: CircuitBreakerOptions = {}) {
+    this.name = name;
+    this.failureThreshold = options.failureThreshold ?? 5;
+    this.resetTimeout = options.resetTimeout ?? 60000; // 1 minute
+    this.monitoringPeriod = options.monitoringPeriod ?? 600000; // 10 minutes
+    this.successThreshold = options.successThreshold ?? 2;
+  }
+
+  /**
+   * Execute function with circuit breaker protection
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // Check if circuit should transition from OPEN to HALF_OPEN
+    if (this.state === CircuitState.OPEN) {
+      if (this.shouldAttemptReset()) {
+        this.transitionTo(CircuitState.HALF_OPEN);
+      } else {
+        throw new Error(`Circuit breaker is OPEN for ${this.name}`);
+      }
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Record successful execution
+   */
+  private onSuccess(): void {
+    this.failureCount = 0;
+
+    if (this.state === CircuitState.HALF_OPEN) {
+      this.successCount++;
+      if (this.successCount >= this.successThreshold) {
+        this.transitionTo(CircuitState.CLOSED);
+      }
+    }
+  }
+
+  /**
+   * Record failed execution
+   */
+  private onFailure(): void {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+
+    if (this.state === CircuitState.HALF_OPEN) {
+      this.transitionTo(CircuitState.OPEN);
+    } else if (this.failureCount >= this.failureThreshold) {
+      this.transitionTo(CircuitState.OPEN);
+    }
+  }
+
+  /**
+   * Check if should attempt to reset from OPEN state
+   */
+  private shouldAttemptReset(): boolean {
+    return (
+      this.lastFailureTime !== undefined && Date.now() - this.lastFailureTime >= this.resetTimeout
+    );
+  }
+
+  /**
+   * Transition to new state
+   */
+  private transitionTo(newState: CircuitState): void {
+    const oldState = this.state;
+    this.state = newState;
+
+    if (newState === CircuitState.CLOSED) {
+      this.failureCount = 0;
+      this.successCount = 0;
+    } else if (newState === CircuitState.HALF_OPEN) {
+      this.successCount = 0;
+    }
+
+    if (oldState !== newState) {
+      const logFn = newState === CircuitState.OPEN ? warn : info;
+      logFn(`Circuit breaker ${this.name} transitioned from ${oldState} to ${newState}`, {
+        failureCount: this.failureCount,
+        successCount: this.successCount,
+      });
+    }
+  }
+
+  /**
+   * Get current circuit state
+   */
+  getState(): CircuitState {
+    return this.state;
+  }
+
+  /**
+   * Get circuit statistics
+   */
+  getStats(): {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime?: number;
+  } {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      successCount: this.successCount,
+      lastFailureTime: this.lastFailureTime,
+    };
+  }
+
+  /**
+   * Reset circuit breaker
+   */
+  reset(): void {
+    this.transitionTo(CircuitState.CLOSED);
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.lastFailureTime = undefined;
+  }
+}
+
+/**
+ * Circuit breaker manager for multiple endpoints
+ */
+export class CircuitBreakerManager {
+  private readonly breakers = new Map<string, CircuitBreaker>();
+  private readonly defaultOptions: CircuitBreakerOptions;
+
+  constructor(defaultOptions: CircuitBreakerOptions = {}) {
+    this.defaultOptions = defaultOptions;
+  }
+
+  /**
+   * Get or create circuit breaker for endpoint
+   */
+  getBreaker(endpoint: string): CircuitBreaker {
+    let breaker = this.breakers.get(endpoint);
+    if (!breaker) {
+      breaker = new CircuitBreaker(endpoint, this.defaultOptions);
+      this.breakers.set(endpoint, breaker);
+    }
+    return breaker;
+  }
+
+  /**
+   * Execute with circuit breaker for endpoint
+   */
+  async execute<T>(endpoint: string, fn: () => Promise<T>): Promise<T> {
+    const breaker = this.getBreaker(endpoint);
+    return breaker.execute(fn);
+  }
+
+  /**
+   * Get all circuit breaker stats
+   */
+  getAllStats(): Record<string, ReturnType<CircuitBreaker['getStats']>> {
+    const stats: Record<string, ReturnType<CircuitBreaker['getStats']>> = {};
+    for (const [endpoint, breaker] of this.breakers) {
+      stats[endpoint] = breaker.getStats();
+    }
+    return stats;
+  }
+
+  /**
+   * Reset all circuit breakers
+   */
+  resetAll(): void {
+    for (const breaker of this.breakers.values()) {
+      breaker.reset();
+    }
+  }
+
+  /**
+   * Reset specific circuit breaker
+   */
+  reset(endpoint: string): void {
+    const breaker = this.breakers.get(endpoint);
+    if (breaker) {
+      breaker.reset();
+    }
+  }
+}

package/src/teamcity/client-adapter.ts

@@ -0,0 +1,35 @@
+/**
+ * Lightweight adapter so managers can work with the unified TeamCityAPI
+ * without depending on the legacy TeamCityClient implementation.
+ */
+import type { AxiosResponse, RawAxiosRequestConfig } from 'axios';
+
+import type { TeamCityAPI } from '@/api-client';
+
+export interface BuildApiLike {
+  getBuild: (
+    buildLocator: string,
+    fields?: string,
+    options?: RawAxiosRequestConfig
+  ) => Promise<AxiosResponse<unknown>>;
+  getMultipleBuilds: (
+    locator: string,
+    fields?: string,
+    options?: RawAxiosRequestConfig
+  ) => Promise<AxiosResponse<unknown>>;
+  getBuildProblems: (
+    buildLocator: string,
+    fields?: string,
+    options?: RawAxiosRequestConfig
+  ) => Promise<AxiosResponse<unknown>>;
+}
+
+export interface TeamCityClientAdapter {
+  builds: BuildApiLike;
+}
+
+export function createAdapterFromTeamCityAPI(api: TeamCityAPI): TeamCityClientAdapter {
+  return {
+    builds: api.builds as unknown as BuildApiLike,
+  };
+}

package/src/teamcity/client.ts

@@ -0,0 +1,269 @@
+/**
+ * TeamCity API Client Wrapper
+ * Provides authentication and configuration for the generated client
+ *
+ * @deprecated Prefer using the unified TeamCityAPI (src/api-client.ts) directly.
+ *             Managers should depend on a small adapter interface instead of this class.
+ */
+import axios, { type InternalAxiosRequestConfig } from 'axios';
+import axiosRetry from 'axios-retry';
+
+import { AgentApi } from '@/teamcity-client/api/agent-api';
+import { AgentPoolApi } from '@/teamcity-client/api/agent-pool-api';
+import { BuildApi } from '@/teamcity-client/api/build-api';
+import { BuildQueueApi } from '@/teamcity-client/api/build-queue-api';
+import { BuildTypeApi } from '@/teamcity-client/api/build-type-api';
+import { ChangeApi } from '@/teamcity-client/api/change-api';
+import { ProjectApi } from '@/teamcity-client/api/project-api';
+import { TestApi } from '@/teamcity-client/api/test-api';
+import { TestOccurrenceApi } from '@/teamcity-client/api/test-occurrence-api';
+import { UserApi } from '@/teamcity-client/api/user-api';
+import { VcsRootApi } from '@/teamcity-client/api/vcs-root-api';
+import { Configuration } from '@/teamcity-client/configuration';
+import { debug, info } from '@/utils/logger';
+
+import { addRequestId, logAndTransformError, logResponse, validateConfiguration } from './auth';
+// import { CircuitBreakerManager } from './circuit-breaker';
+import { TeamCityAPIError, getRetryDelay, isRetryableError } from './errors';
+
+export interface TeamCityClientConfig {
+  baseUrl: string;
+  token: string;
+  timeout?: number;
+  retryConfig?: {
+    retries?: number;
+    retryDelay?: number;
+    retryCondition?: (error: unknown) => boolean;
+  };
+}
+
+export class TeamCityClient {
+  private config: InstanceType<typeof Configuration>;
+  // private readonly circuitBreaker: CircuitBreakerManager;
+  private _buildApi?: BuildApi;
+  private _projectApi?: ProjectApi;
+  private _buildTypeApi?: BuildTypeApi;
+  private _buildQueueApi?: BuildQueueApi;
+  private _vcsRootApi?: VcsRootApi;
+  private _changeApi?: ChangeApi;
+  private _testApi?: TestApi;
+  private _testOccurrenceApi?: TestOccurrenceApi;
+  private _userApi?: UserApi;
+  private _agentApi?: AgentApi;
+  private _agentPoolApi?: AgentPoolApi;
+
+  constructor(config: TeamCityClientConfig) {
+    // Remove trailing slash from base URL
+    const basePath = config.baseUrl.replace(/\/$/, '');
+
+    // Create axios instance with interceptors
+    const axiosInstance = axios.create({
+      timeout: config.timeout ?? 30000,
+    });
+
+    // Initialize circuit breaker (commented out for now)
+    // this.circuitBreaker = new CircuitBreakerManager({
+    //   failureThreshold: 5,
+    //   resetTimeout: 60000, // 1 minute
+    //   successThreshold: 2,
+    // });
+
+    // Add retry logic with custom error handling
+    axiosRetry(axiosInstance, {
+      retries: config.retryConfig?.retries ?? 3,
+      retryDelay: (retryCount, error) => {
+        const teamcityError = TeamCityAPIError.fromAxiosError(error);
+        return getRetryDelay(teamcityError, retryCount, config.retryConfig?.retryDelay ?? 1000);
+      },
+      retryCondition: (error) => {
+        const teamcityError = TeamCityAPIError.fromAxiosError(error);
+        return isRetryableError(teamcityError);
+      },
+    });
+
+    // Validate configuration before proceeding
+    const validation = validateConfiguration(basePath, config.token);
+    if (!validation.isValid) {
+      throw new Error(`Invalid TeamCity configuration: ${validation.errors.join(', ')}`);
+    }
+
+    // Add request interceptor for authentication and request ID
+    axiosInstance.interceptors.request.use((requestConfig: InternalAxiosRequestConfig) => {
+      // Add Bearer token to all requests
+      requestConfig.headers['Authorization'] = `Bearer ${config.token}`;
+      requestConfig.headers['Accept'] = 'application/json';
+
+      // Debug logging
+      debug('TeamCity request', {
+        method: requestConfig.method,
+        url: requestConfig.url,
+        hasAuth: Boolean(requestConfig.headers['Authorization']),
+      });
+
+      // Add request ID for tracing
+      return addRequestId(requestConfig);
+    });
+
+    // Add response interceptor for logging and error transformation
+    axiosInstance.interceptors.response.use(logResponse, logAndTransformError);
+
+    // Create configuration for generated client
+    this.config = new Configuration({
+      basePath,
+      accessToken: config.token,
+      baseOptions: {
+        timeout: config.timeout ?? 30000,
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${config.token}`,
+        },
+      },
+    });
+
+    info('TeamCity client initialized', {
+      baseUrl: basePath,
+      timeout: config.timeout ?? 30000,
+    });
+  }
+
+  /**
+   * Get Build API client
+   */
+  get builds(): BuildApi {
+    if (!this._buildApi) {
+      this._buildApi = new BuildApi(this.config);
+    }
+    return this._buildApi;
+  }
+
+  /**
+   * Get Project API client
+   */
+  get projects(): ProjectApi {
+    if (!this._projectApi) {
+      this._projectApi = new ProjectApi(this.config);
+    }
+    return this._projectApi;
+  }
+
+  /**
+   * Get BuildType API client
+   */
+  get buildTypes(): BuildTypeApi {
+    if (!this._buildTypeApi) {
+      this._buildTypeApi = new BuildTypeApi(this.config);
+    }
+    return this._buildTypeApi;
+  }
+
+  /**
+   * Get BuildQueue API client
+   */
+  get buildQueue(): BuildQueueApi {
+    if (!this._buildQueueApi) {
+      this._buildQueueApi = new BuildQueueApi(this.config);
+    }
+    return this._buildQueueApi;
+  }
+
+  /**
+   * Get VCS Root API client
+   */
+  get vcsRoots(): VcsRootApi {
+    if (!this._vcsRootApi) {
+      this._vcsRootApi = new VcsRootApi(this.config);
+    }
+    return this._vcsRootApi;
+  }
+
+  /**
+   * Get Change API client
+   */
+  get changes(): ChangeApi {
+    if (!this._changeApi) {
+      this._changeApi = new ChangeApi(this.config);
+    }
+    return this._changeApi;
+  }
+
+  /**
+   * Get Test API client
+   */
+  get tests(): TestApi {
+    if (!this._testApi) {
+      this._testApi = new TestApi(this.config);
+    }
+    return this._testApi;
+  }
+
+  /**
+   * Get TestOccurrence API client
+   */
+  get testOccurrences(): TestOccurrenceApi {
+    if (!this._testOccurrenceApi) {
+      this._testOccurrenceApi = new TestOccurrenceApi(this.config);
+    }
+    return this._testOccurrenceApi;
+  }
+
+  /**
+   * Get User API client
+   */
+  get users(): UserApi {
+    if (!this._userApi) {
+      this._userApi = new UserApi(this.config);
+    }
+    return this._userApi;
+  }
+
+  /**
+   * Get Agent API client
+   */
+  get agents(): AgentApi {
+    if (!this._agentApi) {
+      this._agentApi = new AgentApi(this.config);
+    }
+    return this._agentApi;
+  }
+
+  /**
+   * Get Agent Pool API client
+   */
+  get agentPools(): AgentPoolApi {
+    if (!this._agentPoolApi) {
+      this._agentPoolApi = new AgentPoolApi(this.config);
+    }
+    return this._agentPoolApi;
+  }
+
+  /**
+   * Test connection to TeamCity server
+   */
+  async testConnection(): Promise<boolean> {
+    try {
+      // Try to get server info
+      const token = typeof this.config.accessToken === 'string' ? this.config.accessToken : '';
+      const response = await axios.get(`${this.config.basePath}/app/rest/server`, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: 'application/json',
+        },
+        timeout: 5000,
+      });
+
+      const data = response.data as { version?: string; buildNumber?: string };
+      info('TeamCity connection test successful', {
+        version: data.version,
+        buildNumber: data.buildNumber,
+      });
+
+      return response.status === 200;
+    } catch (error) {
+      info('TeamCity connection test failed', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+      });
+      return false;
+    }
+  }
+}

package/src/teamcity/config.ts

@@ -0,0 +1,188 @@
+/**
+ * Configuration module for TeamCity client
+ */
+import { getConfig, getTeamCityOptions } from '@/config';
+
+import type { TeamCityClientConfig } from './client';
+
+export interface TeamCityConnectionConfig {
+  baseUrl: string;
+  token: string;
+  timeout?: number;
+  maxConcurrentRequests?: number;
+  keepAlive?: boolean;
+  compression?: boolean;
+}
+
+export interface TeamCityRetryConfig {
+  enabled?: boolean;
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  retryableStatuses?: number[];
+}
+
+export interface TeamCityPaginationConfig {
+  defaultPageSize?: number;
+  maxPageSize?: number;
+  autoFetchAll?: boolean;
+}
+
+export interface TeamCityFullConfig {
+  connection: TeamCityConnectionConfig;
+  retry?: TeamCityRetryConfig;
+  pagination?: TeamCityPaginationConfig;
+  circuitBreaker?: {
+    enabled?: boolean;
+    failureThreshold?: number;
+    resetTimeout?: number;
+    successThreshold?: number;
+  };
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG: TeamCityFullConfig = {
+  connection: {
+    baseUrl: '',
+    token: '',
+    timeout: 30000,
+    maxConcurrentRequests: 10,
+    keepAlive: true,
+    compression: true,
+  },
+  retry: {
+    enabled: true,
+    maxRetries: 3,
+    baseDelay: 1000,
+    maxDelay: 30000,
+    retryableStatuses: [408, 429, 500, 502, 503, 504],
+  },
+  pagination: {
+    defaultPageSize: 100,
+    maxPageSize: 1000,
+    autoFetchAll: false,
+  },
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 5,
+    resetTimeout: 60000,
+    successThreshold: 2,
+  },
+};
+
+/**
+ * Load configuration from environment variables
+ */
+export function loadTeamCityConfig(): TeamCityFullConfig {
+  const appConfig = getConfig();
+
+  const { connection: conn, retry, pagination, circuitBreaker: circuit } = getTeamCityOptions();
+
+  return {
+    connection: {
+      baseUrl: appConfig.teamcity?.url ?? '',
+      token: appConfig.teamcity?.token ?? '',
+      timeout: conn.timeout,
+      maxConcurrentRequests: conn.maxConcurrentRequests,
+      keepAlive: conn.keepAlive,
+      compression: conn.compression,
+    },
+    retry: {
+      enabled: retry.enabled,
+      maxRetries: retry.maxRetries,
+      baseDelay: retry.baseDelay,
+      maxDelay: retry.maxDelay,
+      retryableStatuses: DEFAULT_CONFIG.retry?.retryableStatuses,
+    },
+    pagination: {
+      defaultPageSize: pagination.defaultPageSize,
+      maxPageSize: pagination.maxPageSize,
+      autoFetchAll: pagination.autoFetchAll,
+    },
+    circuitBreaker: {
+      enabled: circuit.enabled,
+      failureThreshold: circuit.failureThreshold,
+      resetTimeout: circuit.resetTimeout,
+      successThreshold: circuit.successThreshold,
+    },
+  };
+}
+
+/**
+ * Merge configurations with defaults
+ */
+export function mergeConfig(...configs: Array<Partial<TeamCityFullConfig>>): TeamCityFullConfig {
+  const result = { ...DEFAULT_CONFIG };
+
+  for (const config of configs) {
+    if (config.connection) {
+      result.connection = { ...result.connection, ...config.connection };
+    }
+    if (config.retry) {
+      result.retry = { ...result.retry, ...config.retry };
+    }
+    if (config.pagination) {
+      result.pagination = { ...result.pagination, ...config.pagination };
+    }
+    if (config.circuitBreaker) {
+      result.circuitBreaker = { ...result.circuitBreaker, ...config.circuitBreaker };
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convert full config to client config
+ */
+export function toClientConfig(config: TeamCityFullConfig): TeamCityClientConfig {
+  return {
+    baseUrl: config.connection.baseUrl,
+    token: config.connection.token,
+    timeout: config.connection.timeout,
+    retryConfig:
+      config.retry?.enabled === true
+        ? {
+            retries: config.retry.maxRetries,
+            retryDelay: config.retry.baseDelay,
+          }
+        : undefined,
+  };
+}
+
+/**
+ * Validate configuration
+ */
+export function validateConfig(config: TeamCityFullConfig): {
+  isValid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  if (!config.connection.baseUrl) {
+    errors.push('TeamCity base URL is required');
+  }
+
+  if (!config.connection.token) {
+    errors.push('TeamCity authentication token is required');
+  }
+
+  if (config.connection.timeout !== undefined && config.connection.timeout < 1000) {
+    errors.push('Timeout must be at least 1000ms');
+  }
+
+  if (config.retry?.maxRetries !== undefined && config.retry.maxRetries < 0) {
+    errors.push('Max retries must be non-negative');
+  }
+
+  if (config.pagination?.defaultPageSize !== undefined && config.pagination.defaultPageSize < 1) {
+    errors.push('Page size must be at least 1');
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+}