screen_opportunities

Filter Spanish stock market investments using criteria like P/E ratio, market cap, sectors, and governance quality to identify matching opportunities.

Instructions

Screen for investment opportunities based on specific criteria (value, growth, dividend, ESG, etc.)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`screening_criteria`	Yes
`limit`	No	Maximum number of opportunities to return

Implementation Reference

src/analytics.ts:559-625 (handler)

Main handler function for screen_opportunities tool. Screens IBEX 35 companies based on criteria like P/E ratio, market cap, sectors, etc., scores them, and returns top opportunities.

async screenOpportunities(criteria: any, limit: number = 10): Promise<any> {
  try {
    const companies = await this.db.getAllCompanies();
    const screening = {
      criteria: criteria,
      total_companies_screened: companies.length,
      opportunities: [],
      screening_date: new Date().toISOString(),
      summary: {}
    };

    // Apply screening filters
    let filteredCompanies = companies;

    if (criteria.pe_ratio_min !== undefined || criteria.pe_ratio_max !== undefined) {
      filteredCompanies = filteredCompanies.filter(company => {
        const pe = company.price_to_earnings || company.pe_ratio;
        if (pe === null || pe === undefined) return false;
        
        if (criteria.pe_ratio_min !== undefined && pe < criteria.pe_ratio_min) return false;
        if (criteria.pe_ratio_max !== undefined && pe > criteria.pe_ratio_max) return false;
        return true;
      });
    }

    if (criteria.market_cap_min !== undefined || criteria.market_cap_max !== undefined) {
      filteredCompanies = filteredCompanies.filter(company => {
        if (!company.market_cap) return false;
        
        if (criteria.market_cap_min !== undefined && company.market_cap < criteria.market_cap_min) return false;
        if (criteria.market_cap_max !== undefined && company.market_cap > criteria.market_cap_max) return false;
        return true;
      });
    }

    if (criteria.sectors && criteria.sectors.length > 0) {
      filteredCompanies = filteredCompanies.filter(company => 
        criteria.sectors.some(sector => 
          company.sector?.toLowerCase().includes(sector.toLowerCase())
        )
      );
    }

    if (criteria.exclude_sectors && criteria.exclude_sectors.length > 0) {
      filteredCompanies = filteredCompanies.filter(company => 
        !criteria.exclude_sectors.some(sector => 
          company.sector?.toLowerCase().includes(sector.toLowerCase())
        )
      );
    }

    // Score and rank opportunities
    const scoredOpportunities = await this.scoreOpportunities(filteredCompanies, criteria);
    screening.opportunities = scoredOpportunities.slice(0, limit);

    screening.summary = {
      companies_passed_screening: scoredOpportunities.length,
      top_scoring_sector: this.getTopSector(scoredOpportunities),
      average_score: scoredOpportunities.length > 0 ? 
        scoredOpportunities.reduce((sum, opp) => sum + opp.score, 0) / scoredOpportunities.length : 0
    };

    return screening;
  } catch (error) {
    throw new Error(`Opportunity screening failed: ${error}`);
  }
}

src/index.ts:482-541 (schema)

Input schema definition for the screen_opportunities tool, specifying parameters like screening_criteria (with PE ratios, market caps, sectors) and limit.

  name: 'screen_opportunities',
  description: 'Screen for investment opportunities based on specific criteria (value, growth, dividend, ESG, etc.)',
  inputSchema: {
    type: 'object',
    properties: {
      screening_criteria: {
        type: 'object',
        properties: {
          pe_ratio_max: {
            type: 'number',
            description: 'Maximum P/E ratio',
          },
          pe_ratio_min: {
            type: 'number',
            description: 'Minimum P/E ratio',
          },
          market_cap_min: {
            type: 'number',
            description: 'Minimum market capitalization',
          },
          market_cap_max: {
            type: 'number',
            description: 'Maximum market capitalization',
          },
          sectors: {
            type: 'array',
            items: {
              type: 'string',
            },
            description: 'Specific sectors to include',
          },
          exclude_sectors: {
            type: 'array',
            items: {
              type: 'string',
            },
            description: 'Sectors to exclude',
          },
          performance_period: {
            type: 'number',
            description: 'Days to look back for performance metrics',
            default: 30,
          },
          governance_quality: {
            type: 'string',
            enum: ['high', 'medium', 'low', 'any'],
            description: 'Required governance quality level',
            default: 'any',
          },
        },
      },
      limit: {
        type: 'number',
        description: 'Maximum number of opportunities to return',
        default: 10,
      },
    },
    required: ['screening_criteria'],
  },
},

src/index.ts:686-688 (registration)
Registration and dispatch handler in the MCP server that calls the analytics.screenOpportunities method when screen_opportunities tool is invoked.
```
case 'screen_opportunities':
  result = await this.analytics.screenOpportunities((args as any)?.screening_criteria, (args as any)?.limit || 10);
  break;
```

src/analytics.ts:1001-1033 (helper)

Helper function to score and rank filtered companies based on criteria like PE ratio, market cap, and sector for opportunity screening.

private async scoreOpportunities(companies: any[], criteria: any): Promise<any[]> {
  const scored = companies.map(company => {
    let score = 5.0; // Base score
    
    // Scoring based on P/E ratio
    const pe = company.price_to_earnings || company.pe_ratio;
    if (pe && pe < 15) score += 1.0;
    if (pe && pe > 25) score -= 0.5;
    
    // Scoring based on market cap
    if (company.market_cap > 10e9) score += 0.5; // Large cap bonus
    if (company.market_cap < 1e9) score -= 0.3; // Small cap penalty
    
    // Scoring based on sector
    if (company.sector && ['banking', 'technology', 'healthcare'].includes(company.sector.toLowerCase())) {
      score += 0.3;
    }
    
    return {
      company: company,
      symbol: company.symbol,
      name: company.name,
      sector: company.sector,
      score: Math.max(0, Math.min(10, score)), // Clamp between 0-10
      key_metrics: {
        market_cap: company.market_cap,
        pe_ratio: pe
      }
    };
  });
  
  return scored.sort((a, b) => b.score - a.score);
}

src/analytics.ts:1035-1045 (helper)

Helper function to determine the top scoring sector from screened opportunities.

private getTopSector(opportunities: any[]): string {
  const sectorCounts = {};
  opportunities.forEach(opp => {
    const sector = opp.sector || 'Other';
    sectorCounts[sector] = (sectorCounts[sector] || 0) + 1;
  });
  
  return Object.entries(sectorCounts).reduce((top, [sector, count]) => 
    count > (sectorCounts[top] || 0) ? sector : top, 'Other'
  );
}

ibex35-mcp