get_sector_correlation_analysis

Instructions

Implementation Reference

• src/analytics.ts:99-158 (handler)

  Core implementation of get_sector_correlation_analysis tool. Groups IBEX 35 companies by sector, calculates aggregate performance metrics (market cap, PE ratio), sorts sectors by size, and includes market concentration analysis.

  async getSectorCorrelationAnalysis(days: number = 30): Promise<any> {
    const companies = await this.db.getAllCompanies();
    
    // Group companies by sector
    const sectorMap = new Map();
    companies.forEach(company => {
      if (!company.sector) return;
      
      if (!sectorMap.has(company.sector)) {
        sectorMap.set(company.sector, []);
      }
      sectorMap.get(company.sector).push(company);
    });
  
    // Calculate sector performance metrics
    const sectorPerformance = [];
    for (const [sector, sectorCompanies] of sectorMap.entries()) {
      let totalMarketCap = 0;
      let companiesWithData = 0;
      let avgPE = 0;
      let peCount = 0;
  
      sectorCompanies.forEach(company => {
        if (company.market_cap) {
          totalMarketCap += company.market_cap;
          companiesWithData++;
        }
        
        const pe = company.price_to_earnings || company.pe_ratio;
        if (pe) {
          avgPE += pe;
          peCount++;
        }
      });
  
      sectorPerformance.push({
        sector: sector,
        company_count: sectorCompanies.length,
        total_market_cap: totalMarketCap,
        avg_market_cap: companiesWithData > 0 ? totalMarketCap / companiesWithData : 0,
        avg_pe_ratio: peCount > 0 ? avgPE / peCount : null,
        companies: sectorCompanies.slice(0, 5).map(c => ({
          symbol: c.symbol,
          name: c.name,
          market_cap: c.market_cap
        }))
      });
    }
  
    // Sort by total market cap
    sectorPerformance.sort((a, b) => b.total_market_cap - a.total_market_cap);
  
    return {
      period_days: days,
      sector_performance: sectorPerformance,
      total_sectors: sectorPerformance.length,
      largest_sector: sectorPerformance[0]?.sector || 'Unknown',
      market_concentration: this.calculateMarketConcentration(sectorPerformance)
    };
  }

• src/index.ts:346-358 (registration)

  Tool registration in MCP listTools handler, including name, description, and input schema for optional 'days' parameter.

    name: 'get_sector_correlation_analysis',
    description: 'Analyze sector performance correlations and market trends',
    inputSchema: {
      type: 'object',
      properties: {
        days: {
          type: 'number',
          description: 'Number of days to analyze',
          default: 30,
        },
      },
    },
  },

• src/index.ts:653-655 (registration)

  Dispatch handler in MCP callToolRequest that invokes the analytics method with parsed arguments.

  case 'get_sector_correlation_analysis':
    result = await this.analytics.getSectorCorrelationAnalysis((args as any)?.days || 30);
    break;

• src/analytics.ts:160-182 (helper)

  Supporting function called by the handler to compute market concentration using Herfindahl-Hirschman Index (HHI) and top sector shares.

  private calculateMarketConcentration(sectorPerformance: any[]): any {
    const totalMarketCap = sectorPerformance.reduce((sum, sector) => sum + sector.total_market_cap, 0);
    
    if (totalMarketCap === 0) return { hhi_index: 0, concentration_level: 'unknown' };
  
    // Calculate Herfindahl-Hirschman Index
    const hhi = sectorPerformance.reduce((sum, sector) => {
      const share = sector.total_market_cap / totalMarketCap;
      return sum + (share * share * 10000); // HHI scale
    }, 0);
  
    let concentrationLevel;
    if (hhi > 2500) concentrationLevel = 'highly_concentrated';
    else if (hhi > 1500) concentrationLevel = 'moderately_concentrated';
    else concentrationLevel = 'competitive';
  
    return {
      hhi_index: Math.round(hhi),
      concentration_level: concentrationLevel,
      top_3_market_share: sectorPerformance.slice(0, 3).reduce((sum, sector) => 
        sum + (sector.total_market_cap / totalMarketCap), 0) * 100
    };
  }

• dist/analytics.d.ts:9-9 (schema)

  TypeScript declaration for the analytics method signature.

  getSectorCorrelationAnalysis(days?: number): Promise<any>;