@daghis/teamcity-mcp 0.1.2

package/src/utils/logger/index.ts

@@ -0,0 +1,441 @@
+/**
+ * Centralized Logger Utility for TeamCity MCP Server
+ *
+ * This module provides a unified logging interface that consolidates
+ * the existing logger implementations and enforces consistent logging
+ * patterns throughout the application.
+ */
+import winston, { type Logger } from 'winston';
+
+/**
+ * Log levels supported by the logger
+ */
+export type LogLevel = 'error' | 'warn' | 'info' | 'verbose' | 'debug' | 'silly';
+
+/**
+ * Context information for logging
+ */
+export interface LogContext {
+  /**
+   * Tool name (for MCP tool execution)
+   */
+  toolName?: string;
+
+  /**
+   * Unique request identifier
+   */
+  requestId?: string;
+
+  /**
+   * Session identifier
+   */
+  sessionId?: string;
+
+  /**
+   * User identifier
+   */
+  userId?: string;
+
+  /**
+   * Operation duration in milliseconds
+   */
+  duration?: number;
+
+  /**
+   * Service or module name
+   */
+  service?: string;
+
+  /**
+   * TeamCity build ID
+   */
+  buildId?: string;
+
+  /**
+   * TeamCity project ID
+   */
+  projectId?: string;
+
+  /**
+   * Additional context properties
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Logger configuration options
+ */
+export interface LoggerConfig {
+  name?: string;
+  level?: LogLevel;
+  enableConsole?: boolean;
+  enableFile?: boolean;
+  logDirectory?: string;
+  maxFileSize?: string;
+  maxFiles?: number;
+}
+
+/**
+ * Logger interface for type safety and consistency
+ */
+export interface ILogger {
+  debug(message: string, context?: LogContext): void;
+  info(message: string, context?: LogContext): void;
+  warn(message: string, context?: LogContext): void;
+  error(message: string, error?: Error | unknown, context?: LogContext): void;
+  child(context: LogContext): ILogger;
+}
+
+/**
+ * Enhanced logger implementation
+ */
+export class TeamCityLogger implements ILogger {
+  private winston: Logger;
+  private config: Required<LoggerConfig>;
+  private requestCounter = 0;
+
+  constructor(config: LoggerConfig = {}) {
+    this.config = this.normalizeConfig(config);
+    this.winston = this.createWinstonLogger();
+  }
+
+  /**
+   * Normalize configuration with defaults
+   */
+  private normalizeConfig(config: LoggerConfig): Required<LoggerConfig> {
+    const isProduction = process.env['NODE_ENV'] === 'production';
+    const isDevelopment = process.env['NODE_ENV'] === 'development';
+    const forceFile =
+      process.env['TEAMCITY_LOG_TO_FILE'] === '1' || process.env['TEAMCITY_LOG_TO_FILE'] === 'true';
+
+    return {
+      name: config.name ?? 'teamcity-mcp',
+      level:
+        config.level ??
+        (process.env['LOG_LEVEL'] as LogLevel) ??
+        (isDevelopment ? 'debug' : 'info'),
+      enableConsole: config.enableConsole ?? true,
+      // Allow forcing file logging via env during tests or local runs
+      enableFile: config.enableFile ?? (isProduction || forceFile),
+      logDirectory: config.logDirectory ?? 'logs',
+      maxFileSize: config.maxFileSize ?? '10m',
+      maxFiles: config.maxFiles ?? 5,
+    };
+  }
+
+  /**
+   * Create Winston logger instance
+   */
+  private createWinstonLogger(): Logger {
+    const { level, enableConsole, enableFile, logDirectory, maxFileSize, maxFiles, name } =
+      this.config;
+    const isProduction = process.env['NODE_ENV'] === 'production';
+
+    // Custom format for development
+    const devFormat = winston.format.combine(
+      winston.format.colorize(),
+      winston.format.timestamp({ format: 'HH:mm:ss.SSS' }),
+      winston.format.errors({ stack: true }),
+      winston.format.printf(({ timestamp, level, message, service, ...meta }) => {
+        const baseLog = `${timestamp} [${service}] ${level}: ${message}`;
+        return this.formatContextualLog(baseLog, meta);
+      })
+    );
+
+    // JSON format for production
+    const prodFormat = winston.format.combine(
+      winston.format.timestamp(),
+      winston.format.errors({ stack: true }),
+      winston.format.json()
+    );
+
+    const transports: winston.transport[] = [];
+
+    // Console transport
+    if (enableConsole) {
+      transports.push(
+        new winston.transports.Console({
+          format: isProduction ? prodFormat : devFormat,
+        })
+      );
+    }
+
+    // File transports
+    if (enableFile) {
+      this.ensureLogDirectory(logDirectory);
+
+      // Error-only log file
+      transports.push(
+        new winston.transports.File({
+          filename: `${logDirectory}/error.log`,
+          level: 'error',
+          format: prodFormat,
+          maxsize: this.parseFileSize(maxFileSize),
+          maxFiles,
+        })
+      );
+
+      // Combined log file
+      transports.push(
+        new winston.transports.File({
+          filename: `${logDirectory}/combined.log`,
+          format: prodFormat,
+          maxsize: this.parseFileSize(maxFileSize),
+          maxFiles,
+        })
+      );
+    }
+
+    return winston.createLogger({
+      level,
+      defaultMeta: { service: name },
+      transports,
+      exitOnError: false,
+    });
+  }
+
+  /**
+   * Format contextual log with MCP-specific information
+   */
+  private formatContextualLog(baseLog: string, context: LogContext): string {
+    const { toolName, requestId, sessionId, duration, buildId, projectId, ...otherMeta } = context;
+
+    const contextParts: string[] = [];
+
+    if (requestId) contextParts.push(`req=${requestId}`);
+    if (sessionId) contextParts.push(`session=${sessionId}`);
+    if (toolName) contextParts.push(`tool=${toolName}`);
+    if (buildId) contextParts.push(`build=${buildId}`);
+    if (projectId) contextParts.push(`project=${projectId}`);
+    if (duration !== undefined) contextParts.push(`${duration}ms`);
+
+    const contextString = contextParts.length > 0 ? ` [${contextParts.join(' ')}]` : '';
+    const metaString = Object.keys(otherMeta).length > 0 ? ` ${JSON.stringify(otherMeta)}` : '';
+
+    return `${baseLog}${contextString}${metaString}`;
+  }
+
+  /**
+   * Ensure log directory exists
+   */
+  private ensureLogDirectory(directory: string): void {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const fs = require('fs');
+      if (fs.existsSync(directory) === false) {
+        fs.mkdirSync(directory, { recursive: true });
+      }
+    } catch (error) {
+      // Fallback to current directory if log directory creation fails
+      this.winston?.warn?.('Failed to create log directory, using current directory', { error });
+    }
+  }
+
+  /**
+   * Parse file size string to bytes
+   */
+  private parseFileSize(size: string): number {
+    const match = size.match(/^(\d+)([kmg]?)$/i);
+    if (!match) return 10 * 1024 * 1024; // Default 10MB
+
+    const [, num, unit] = match;
+    if (!num) return 10 * 1024 * 1024; // Default 10MB
+
+    const multiplier =
+      {
+        '': 1,
+        k: 1024,
+        m: 1024 * 1024,
+        g: 1024 * 1024 * 1024,
+      }[unit?.toLowerCase() ?? ''] ?? 1;
+
+    return parseInt(num, 10) * multiplier;
+  }
+
+  /**
+   * Generate unique request ID
+   */
+  public generateRequestId(): string {
+    this.requestCounter++;
+    return `${Date.now()}-${this.requestCounter}`;
+  }
+
+  /**
+   * Debug level logging
+   */
+  public debug(message: string, context: LogContext = {}): void {
+    this.winston.debug(message, context);
+  }
+
+  /**
+   * Info level logging
+   */
+  public info(message: string, context: LogContext = {}): void {
+    this.winston.info(message, context);
+  }
+
+  /**
+   * Warning level logging
+   */
+  public warn(message: string, context: LogContext = {}): void {
+    this.winston.warn(message, context);
+  }
+
+  /**
+   * Error level logging with optional error object
+   */
+  public error(message: string, error?: Error | unknown, context: LogContext = {}): void {
+    const errorContext = { ...context };
+
+    if (error instanceof Error) {
+      errorContext['error'] = error.message;
+      errorContext['stack'] = error.stack;
+    } else if (error != null) {
+      errorContext['error'] = String(error);
+    }
+
+    this.winston.error(message, errorContext);
+  }
+
+  /**
+   * Create child logger with additional context
+   */
+  public child(context: LogContext): ILogger {
+    const childLogger = new TeamCityLogger(this.config);
+    childLogger.winston = this.winston.child(context);
+    return childLogger;
+  }
+
+  /**
+   * Log tool execution with performance metrics
+   */
+  public logToolExecution(
+    toolName: string,
+    args: Record<string, unknown>,
+    result: { success: boolean; error?: string },
+    duration: number,
+    context: LogContext = {}
+  ): void {
+    const toolContext: LogContext = {
+      ...context,
+      toolName,
+      duration,
+      args: JSON.stringify(args),
+      success: result.success,
+    };
+
+    if (result.success) {
+      this.info(`Tool executed successfully: ${toolName}`, toolContext);
+    } else {
+      this.error(`Tool execution failed: ${toolName}`, result.error, toolContext);
+    }
+  }
+
+  /**
+   * Log TeamCity API interactions
+   */
+  public logTeamCityRequest(
+    method: string,
+    url: string,
+    status?: number,
+    duration?: number,
+    context: LogContext = {}
+  ): void {
+    const requestContext: LogContext = {
+      ...context,
+      method,
+      url,
+      status,
+      duration,
+    };
+
+    if (status && status >= 400) {
+      this.warn(`TeamCity API request failed: ${method} ${url}`, requestContext);
+    } else {
+      this.debug(`TeamCity API request: ${method} ${url}`, requestContext);
+    }
+  }
+
+  /**
+   * Log server lifecycle events
+   */
+  public logLifecycle(event: string, details?: Record<string, unknown>): void {
+    this.info(`Server lifecycle: ${event}`, { lifecycle: event, ...details });
+  }
+
+  /**
+   * Set log level dynamically
+   */
+  public setLevel(level: LogLevel): void {
+    this.winston.level = level;
+    this.config.level = level;
+  }
+
+  /**
+   * Get current log level
+   */
+  public getLevel(): LogLevel {
+    return this.winston.level as LogLevel;
+  }
+
+  /**
+   * Get underlying Winston instance (for advanced usage)
+   */
+  public getWinstonInstance(): Logger {
+    return this.winston;
+  }
+}
+
+// Default logger instance
+let defaultLogger: TeamCityLogger | null = null;
+
+/**
+ * Get or create the default logger instance
+ */
+export function getLogger(config?: LoggerConfig): TeamCityLogger {
+  if (!defaultLogger || config) {
+    defaultLogger = new TeamCityLogger(config);
+  }
+  return defaultLogger;
+}
+
+/**
+ * Create a new logger instance
+ */
+export function createLogger(config?: LoggerConfig): TeamCityLogger {
+  return new TeamCityLogger(config);
+}
+
+/**
+ * Convenience functions using the default logger
+ */
+export const logger = {
+  debug: (message: string, context?: LogContext) => getLogger().debug(message, context),
+  info: (message: string, context?: LogContext) => getLogger().info(message, context),
+  warn: (message: string, context?: LogContext) => getLogger().warn(message, context),
+  error: (message: string, error?: Error | unknown, context?: LogContext) =>
+    getLogger().error(message, error, context),
+  child: (context: LogContext) => getLogger().child(context),
+  logToolExecution: (
+    toolName: string,
+    args: Record<string, unknown>,
+    result: { success: boolean; error?: string },
+    duration: number,
+    context?: LogContext
+  ) => getLogger().logToolExecution(toolName, args, result, duration, context),
+  logTeamCityRequest: (
+    method: string,
+    url: string,
+    status?: number,
+    duration?: number,
+    context?: LogContext
+  ) => getLogger().logTeamCityRequest(method, url, status, duration, context),
+  logLifecycle: (event: string, details?: Record<string, unknown>) =>
+    getLogger().logLifecycle(event, details),
+};
+
+// Export types for external usage
+
+// Backward compatibility exports
+export const createTeamCityLogger = createLogger;
+export const getTeamCityLogger = getLogger;

package/src/utils/logger.ts

@@ -0,0 +1,49 @@
+// Thin compatibility wrapper around the enhanced TeamCityLogger
+// to keep existing imports (`@/utils/logger`) stable across the codebase.
+import type { Logger } from 'winston';
+
+import {
+  TeamCityLogger,
+  createLogger as createTeamCityLogger,
+  logger as enhancedLogger,
+  getLogger as getTeamCityLogger,
+} from './logger/index';
+
+export type { TeamCityLogger };
+
+export function createLogger(name = 'teamcity-mcp'): Logger {
+  // Map legacy createLogger(name) to enhanced logger factory
+  const instance = createTeamCityLogger({ name });
+  return instance.getWinstonInstance();
+}
+
+export function getLogger(): Logger {
+  return getTeamCityLogger().getWinstonInstance();
+}
+
+export function info(message: string, meta?: Record<string, unknown>): void {
+  enhancedLogger.info(message, meta);
+}
+
+export function error(
+  message: string,
+  err?: Error | unknown,
+  meta?: Record<string, unknown>
+): void {
+  enhancedLogger.error(message, err, meta);
+}
+
+export function warn(message: string, meta?: Record<string, unknown>): void {
+  enhancedLogger.warn(message, meta);
+}
+
+export function debug(message: string, meta?: Record<string, unknown>): void {
+  enhancedLogger.debug(message, meta);
+}
+
+export function child(meta: Record<string, unknown>): Logger {
+  // Create a child on the underlying Winston instance to preserve expected type
+  return getTeamCityLogger()
+    .getWinstonInstance()
+    .child(meta as never);
+}

package/src/utils/lru-cache.ts

@@ -0,0 +1,105 @@
+interface CacheEntry<T> {
+  value: T;
+  timestamp: number;
+}
+
+export interface LRUCacheOptions {
+  maxSize?: number;
+  ttl?: number; // Time to live in milliseconds
+}
+
+export class LRUCache<T> {
+  private cache: Map<string, CacheEntry<T>>;
+  private maxSize: number;
+  private ttl: number;
+
+  constructor(options: LRUCacheOptions = {}) {
+    this.cache = new Map();
+    this.maxSize = options.maxSize ?? 100;
+    this.ttl = options.ttl ?? 300000; // Default 5 minutes
+  }
+
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if entry has expired
+    if (this.isExpired(entry)) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Move to end (most recently used)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    // Remove if already exists to update position
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Check size limit
+    if (this.cache.size >= this.maxSize) {
+      // Remove least recently used (first item)
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    this.cache.set(key, {
+      value,
+      timestamp: Date.now(),
+    });
+  }
+
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return false;
+    }
+
+    if (this.isExpired(entry)) {
+      this.cache.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+
+  keys(): IterableIterator<string> {
+    return this.cache.keys();
+  }
+
+  private isExpired(entry: CacheEntry<T>): boolean {
+    return Date.now() - entry.timestamp > this.ttl;
+  }
+
+  // Clean up expired entries
+  evictExpired(): void {
+    for (const [key, entry] of this.cache.entries()) {
+      if (this.isExpired(entry)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+}

package/src/utils/mcp.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+
+import { formatError } from '@/middleware/error';
+import { globalErrorHandler } from '@/middleware/global-error-handler';
+import { getLogger as getTeamCityLogger } from '@/utils/logger/index';
+
+// Minimal ToolResponse shape to avoid cyclic imports with tools
+export interface ToolResponse {
+  content?: Array<{ type: string; text: string }>;
+  error?: string;
+  success?: boolean;
+  data?: unknown;
+}
+
+// Helpers to build consistent MCP tool responses
+export function text(content: string): ToolResponse {
+  return { content: [{ type: 'text', text: content }], success: true };
+}
+
+export function json(data: unknown): ToolResponse {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], success: true };
+}
+
+export function errorText(message: string): ToolResponse {
+  return { content: [{ type: 'text', text: message }], success: false, error: message };
+}
+
+// Validate args with Zod (if provided) and route errors via the global handler
+export async function runTool<T>(
+  toolName: string,
+  schema: z.ZodSchema<T> | null,
+  handler: (args: T) => Promise<ToolResponse>,
+  rawArgs: unknown,
+  context?: { requestId?: string; userId?: string }
+): Promise<ToolResponse> {
+  const logger = getTeamCityLogger();
+  const reqId = context?.requestId ?? logger.generateRequestId();
+  const started = Date.now();
+  try {
+    const args = schema ? schema.parse(rawArgs) : (rawArgs as T);
+    const result = await handler(args);
+    const duration = Date.now() - started;
+    const success = result?.success !== false;
+    logger.logToolExecution(
+      toolName,
+      // Avoid logging secrets by shallow masking of obvious keys
+      typeof args === 'object' && args != null
+        ? Object.fromEntries(
+            Object.entries(args as Record<string, unknown>).map(([k, v]) => [
+              k,
+              /token|authorization|password/i.test(k) ? '***' : v,
+            ])
+          )
+        : ({} as Record<string, unknown>),
+      { success, error: result?.error as string | undefined },
+      duration,
+      { requestId: reqId }
+    );
+    return result;
+  } catch (err) {
+    const duration = Date.now() - started;
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.logToolExecution(
+      toolName,
+      typeof rawArgs === 'object' && rawArgs != null
+        ? (rawArgs as Record<string, unknown>)
+        : ({} as Record<string, unknown>),
+      { success: false, error: msg },
+      duration,
+      { requestId: reqId }
+    );
+    // Preserve validation error details for proper shaping
+    if (err instanceof z.ZodError) {
+      const formatted = formatError(err, { ...context, requestId: reqId });
+      return json(formatted);
+    }
+    // Pass through original error so handler can extract rich details
+    const formatted = globalErrorHandler.handleToolError(err, toolName, {
+      ...context,
+      requestId: reqId,
+    });
+    return json(formatted);
+  }
+}