compare_versions

Instructions

Implementation Reference

• src/index.ts:726-809 (handler)

  The core handler function that executes the compare_versions tool. It validates input, fetches product cycle data from EOL API, finds current and latest supported versions, performs EOL validation, generates upgrade recommendations, and returns formatted JSON response.

  private async handleCompareVersions(args: CompareVersionsArgs) {
    const { product, version } = args;
  
    // Validate product exists
    if (!this.availableProducts.includes(product)) {
      return {
        content: [{
          type: "text",
          text: `Invalid product: ${product}. Use list_products tool to see available products.`
        }],
        isError: true
      };
    }
  
    try {
      const cycles = await this.getProductDetails(product);
      const currentDate = new Date();
  
      // Validate current version
      const currentCycle = cycles.find(c => c?.cycle?.startsWith(version));
      if (!currentCycle) {
        return {
          content: [{
            type: "text",
            text: `Version ${version} not found for ${product}`
          }],
          isError: true
        };
      }
  
      // Find and validate latest supported version
      const latestSupportedCycle = cycles.find(c => {
        const validation = this.validateVersion(c, currentDate);
        return validation.isValid && validation.isSupported;
      }) || cycles[0];
  
      // Validate both versions
      const currentValidation = this.validateVersion(currentCycle, currentDate);
      const latestValidation = this.validateVersion(latestSupportedCycle, currentDate);
  
      // Cache the query
      this.recentQueries.unshift({
        product,
        version,
        response: [currentCycle, latestSupportedCycle],
        timestamp: currentDate.toISOString()
      });
  
      if (this.recentQueries.length > API_CONFIG.MAX_CACHED_QUERIES) {
        this.recentQueries.pop();
      }
  
      const response = {
        current_date: currentDate.toISOString(),
        validations: {
          current: this.formatVersionValidation(currentCycle, currentValidation),
          latest: this.formatVersionValidation(latestSupportedCycle, latestValidation)
        },
        recommendation: {
          needs_update: !currentValidation.isValid || !currentValidation.isSupported,
          urgency: this.getUpgradeUrgency(currentValidation.daysToEol),
          message: this.getRecommendationMessage(currentValidation)
        }
      };
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(response, null, 2)
        }]
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          content: [{
            type: "text",
            text: `API error: ${error.response?.data?.message ?? error.message}`
          }],
          isError: true
        };
      }
      throw error;
    }
  }

• src/types.ts:109-123 (schema)

  TypeScript interface defining the input arguments for compare_versions tool and the type guard function used to validate arguments before execution.

  export interface CompareVersionsArgs {
    product: string;
    version: string;
  }
  
  export function isValidCompareVersionsArgs(args: any): args is CompareVersionsArgs {
    return (
      typeof args === "object" &&
      args !== null &&
      "product" in args &&
      typeof args.product === "string" &&
      "version" in args &&
      typeof args.version === "string"
    );
  }

• src/index.ts:343-362 (registration)

  Tool registration in the ListToolsRequestSchema response. Defines the tool's metadata, description, and JSON schema for input validation in MCP protocol.

  {
    name: "compare_versions",
    description: "Compare versions and get detailed upgrade analysis",
    inputSchema: {
      type: "object",
      properties: {
        product: {
          type: "string",
          description: "Software product name (e.g., python, nodejs)",
          examples: ["python", "nodejs"]
        },
        version: {
          type: "string",
          description: "Current version being used",
          examples: ["3.8", "16"]
        }
      },
      required: ["product", "version"]
    }
  },

• src/index.ts:416-425 (registration)

  Dispatch handler in CallToolRequestSchema that validates arguments using the type guard and invokes the main handleCompareVersions function.

  case "compare_versions": {
    if (!isValidCompareVersionsArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Invalid version comparison arguments"
      );
    }
  
    return this.handleCompareVersions(args);
  }

• src/index.ts:855-875 (helper)

  Helper function used by the handler to validate a version's EOL status, calculate days to EOL, and determine support status.

  private validateVersion(cycle: EOLCycle | undefined, currentDate: Date = new Date()): ValidationResult {
    if (!cycle?.eol) {
      return {
        isValid: false,
        daysToEol: 0,
        isSupported: false,
        validationMessage: `Invalid cycle data for version ${cycle?.cycle ?? 'unknown'}`
      };
    }
  
    const eolDate = new Date(cycle.eol);
    const daysToEol = Math.floor((eolDate.getTime() - currentDate.getTime()) / (1000 * 60 * 60 * 24));
    const isSupported = this.isValueTruthy(cycle.support);
  
    return {
      isValid: daysToEol > 0,
      daysToEol,
      isSupported,
      validationMessage: `Version ${cycle.cycle} EOL date ${cycle.eol} is ${daysToEol > 0 ? 'valid' : 'invalid'}, ${daysToEol > 0 ? '+' : ''}${daysToEol} days from now`
    };
  }