Market Sizing MCP Server

// src/tools/market-tools.ts import { Tool } from "@modelcontextprotocol/sdk/types.js"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; import { IndustrySearchSchema, MarketSizeSchema, TAMCalculatorSchema, SAMCalculatorSchema, MarketSegmentsSchema, MarketForecastingSchema, MarketComparisonSchema, DataValidationSchema, MarketOpportunitiesSchema, APIResponse, TAMCalculation, SAMCalculation, MarketComparison, ValidationResult, } from "../types/index.js"; import { DataService } from "../services/DataService.js"; import { createAPIResponse, createErrorResponse, handleToolError, validatePositiveNumber, // Keep existing utils validatePercentage, validateYear, validateCurrency, validateRegion, formatCurrency, formatPercentage, calculateCAGR, calculateConfidenceScore, logger, } from "../utils/index.js"; // Define schema for the new generic tool (conceptual - should be in src/types/index.ts) const GenericDataQuerySchema = z.object({ dataSourceName: z .string() .describe( "Name of the data source service (e.g., BlsService, CensusService)", ), dataSourceMethod: z .string() .describe( "Method to call on the specified data source (e.g., fetchIndustryData)", ), dataSourceParams: z .array(z.any()) .describe( "Array of parameters for the method (e.g., [ ['SERIES_ID'], '2022', '2023' ])", ), }); // Update IndustryDataSchema to include both old and new field formats for backward compatibility const ExtendedIndustryDataSchema = z .object({ // New format fields industry_id: z .string() .optional() .describe("Industry identifier or NAICS/SIC code"), include_trends: z .boolean() .default(false) .optional() .describe("Include industry trends in the response"), include_players: z .boolean() .default(false) .optional() .describe("Include key market players in the response"), include_esg: z .boolean() .default(false) .optional() .describe("Include ESG scoring data in the response"), // Old format fields (for backward compatibility with tests) industryId: z.string().optional().describe("Legacy: Industry identifier"), includeMetrics: z .boolean() .default(false) .optional() .describe("Legacy: Include metrics in response"), region: z.string().optional().describe("Legacy: Geographic region"), // Specific data source fields specificDataSourceName: z .string() .optional() .describe( "Name of the specific data source service to query (e.g., BlsService, CensusService)", ), specificDataSourceMethod: z .string() .optional() .describe( "Method to call on the specified data source (e.g., fetchIndustryData, fetchImfDataset)", ), specificDataSourceParams: z .array(z.any()) .optional() .describe("Array of parameters to pass to the data source method"), }) .refine((data) => data.industry_id ?? data.industryId, { message: "Either industry_id or industryId must be provided", }); export class MarketAnalysisTools { private static _dataService: DataService | null = null; static get dataService(): DataService { if (!this._dataService) { this._dataService = new DataService(); } return this._dataService; } static getToolDefinitions(): Tool[] { // This method remains unchanged return [ { name: "industry_analysis", description: `Search for industries by name, keywords, or description with intelligent matching and ranking. 🔍 **What it does:** - Searches across multiple industry classification systems (NAICS, SIC, ISIC) - Uses fuzzy matching and semantic analysis for flexible search queries - Returns ranked results with relevance scores and industry metadata 💼 **Use cases:** - Industry discovery and market research initialization - Finding relevant industries for competitive analysis - Building industry databases and classification mapping - Market opportunity exploration and sector identification 📋 **Parameters:** - **query**: Industry name, keywords, or description (e.g., "software development", "renewable energy") - **limit**: Maximum number of results to return (default: 10) - **includeSubIndustries**: Include detailed sub-industry breakdowns (optional) 🎯 **Example queries:** - "artificial intelligence" → AI software, machine learning services, computer vision - "sustainable energy" → Solar, wind, renewable energy storage - "fintech" → Financial technology, payment processing, digital banking - "NAICS 541511" → Custom computer programming services 💡 **Pro tips:** - Use broad keywords to discover related industries you might not have considered - Great starting point before using industry_data for detailed analysis - Results include confidence scores to help prioritize follow-up research`, inputSchema: zodToJsonSchema(IndustrySearchSchema) as any, }, { name: "industry_data", description: `Get comprehensive industry intelligence including trends, key players, and ESG metrics. 📊 **What it does:** - Aggregates detailed industry information from multiple authoritative sources - Provides market size, growth trends, competitive landscape, and regulatory insights - Includes ESG scoring, innovation metrics, and future outlook analysis 💼 **Use cases:** - Comprehensive industry analysis for investment decisions - Market entry strategy development and competitive intelligence - Due diligence research for M&A and partnerships - Industry trend analysis and strategic planning 📋 **Parameters:** - **industry_id**: Unique industry identifier from industry search results - **include_trends**: Include growth trends and market dynamics (default: false) - **include_players**: Include key market participants and competitive analysis (default: false) - **include_esg**: Include ESG scoring and sustainability metrics (default: false) - **data_source**: Specific data source to prioritize (optional) 🎯 **Enhanced features:** - **Trends**: Historical growth, emerging patterns, market cycles - **Key Players**: Market leaders, disruptors, market share analysis - **ESG**: Environmental impact, social responsibility, governance scores 💡 **Pro tips:** - Enable all includes for comprehensive research reports - Use specific data_source when you need authoritative single-source data - Combine with market_size tool for quantitative analysis`, // Use the extended schema for the definition inputSchema: zodToJsonSchema(ExtendedIndustryDataSchema) as any, }, { name: "market_size", description: `Retrieve comprehensive market size data with historical trends and growth projections. 📈 **What it does:** - Estimates current and historical market size using multiple methodologies - Provides geographic breakdown and segment-level analysis - Includes confidence intervals, data sources, and methodology transparency 💼 **Use cases:** - Total Addressable Market (TAM) validation and sizing - Market opportunity assessment for business planning - Investment thesis development and validation - Competitive benchmarking and market share analysis 📋 **Parameters:** - **industry**: Industry name or identifier - **year_range**: Time period for analysis [start_year, end_year] - **regions**: Geographic scope (e.g., ["US", "EU", "Global"]) - **currency**: Currency for market size values (default: "USD") - **segments**: Industry segments to include (optional) - **adjust_inflation**: Adjust historical data for inflation (default: false) 🌍 **Geographic options:** - **Regional**: "US", "EU", "APAC", "LATAM", "MEA" - **Country-specific**: "USA", "CHN", "DEU", "GBR", "JPN" - **Global**: "Global", "Worldwide" 💡 **Pro tips:** - Use inflation adjustment for accurate historical comparisons - Regional data helps validate global estimates - Combine with forecasting tool for future projections`, inputSchema: zodToJsonSchema(MarketSizeSchema) as any, }, { name: "tam_analysis", description: `Calculate Total Addressable Market (TAM) with advanced methodologies and scenario analysis. 🎯 **What it does:** - Performs sophisticated TAM calculations using multiple proven methodologies - Provides scenario analysis (conservative, optimistic, pessimistic) - Includes confidence scoring, assumptions validation, and sensitivity analysis 💼 **Use cases:** - Startup funding presentations and business plan development - Market entry strategy and investment decision support - Product roadmap planning and resource allocation - Venture capital and private equity market assessments 📋 **Parameters:** - **industry**: Industry name or identifier for TAM calculation - **regions**: Geographic scope for market analysis - **base_year**: Base year for calculation (default: current year) - **methodology**: Calculation approach (top-down, bottom-up, hybrid) - **scenarios**: Include scenario variations and sensitivity analysis - **addressable_population**: Total addressable population size (optional) - **penetration_rate**: Expected market penetration rate (optional) 📊 **Methodologies:** - **Top-down**: Market-wide data broken down to specific segments - **Bottom-up**: Customer/product level data aggregated to total market - **Hybrid**: Combines both approaches for validation and accuracy 🎯 **Example calculation:** For SaaS project management software: - industry: "project management software" - regions: ["US", "EU"] - methodology: "hybrid" - scenarios: true Returns: TAM estimates with confidence intervals, growth projections, and scenario variations. 💡 **Pro tips:** - Use hybrid methodology for most accurate results - Include multiple scenarios for investor presentations - Validate results with market_size tool for consistency`, inputSchema: zodToJsonSchema(TAMCalculatorSchema) as any, }, { name: "sam_calculator", description: `Calculate Serviceable Addressable Market (SAM) and Serviceable Obtainable Market (SOM) from TAM. 🎯 **What it does:** - Refines TAM calculations to realistic serviceable markets - Applies geographic, regulatory, and competitive constraints - Calculates obtainable market share based on business model limitations 💼 **Use cases:** - Realistic market opportunity assessment for business planning - Go-to-market strategy development and resource allocation - Investor presentation preparation with achievable market estimates - Market entry prioritization and sequencing decisions 📋 **Parameters:** - **tam_result**: TAM calculation result as input for SAM calculation - **target_segments**: Specific market segments to focus on - **geographic_constraints**: Geographic limitations or focus areas - **regulatory_barriers**: Regulatory constraints affecting market access - **competitive_filters**: Competitive constraints and market share thresholds - **business_model_constraints**: Business model limitations affecting addressability 🎯 **Constraint types:** - **Geographic**: Regional limitations, distribution challenges - **Regulatory**: Compliance requirements, licensing barriers - **Competitive**: Market saturation, incumbent advantages - **Business Model**: Technology limitations, service delivery constraints 💡 **Pro tips:** - Start with TAM calculator results for accurate SAM estimates - Be realistic about constraints to avoid over-optimistic projections - Use SOM for immediate market opportunity and resource planning`, inputSchema: zodToJsonSchema(SAMCalculatorSchema) as any, }, { name: "market_segments", description: `Analyze comprehensive market segmentation with hierarchical breakdowns and trend analysis. 📊 **What it does:** - Provides detailed market segmentation across multiple dimensions - Creates hierarchical segment structures with sub-segment analysis - Includes growth trends, competitive dynamics, and segment attractiveness scoring 💼 **Use cases:** - Target market identification and prioritization - Product positioning strategy and market entry planning - Competitive analysis and differentiation strategy development - Customer acquisition strategy and marketing channel optimization 📋 **Parameters:** - **industry**: Industry name or identifier for segmentation analysis - **segmentation_type**: Type of segmentation (geographic, demographic, psychographic, behavioral, product) - **depth_level**: Depth of segmentation hierarchy (1-4 levels, default: 2) - **include_trends**: Include trend data for each segment (default: false) 🎯 **Segmentation types:** - **Geographic**: Regional, country, city-level breakdowns - **Demographic**: Age, income, education, company size - **Psychographic**: Values, lifestyle, personality traits - **Behavioral**: Usage patterns, purchase behavior, loyalty - **Product**: Feature sets, price points, technology types 💡 **Pro tips:** - Use multiple segmentation types for comprehensive market understanding - Higher depth levels provide more granular insights for targeting - Include trends to identify growing vs. declining segments`, inputSchema: zodToJsonSchema(MarketSegmentsSchema) as any, }, { name: "market_forecasting", description: `Generate sophisticated market forecasts with scenario analysis and confidence intervals. 📈 **What it does:** - Creates multi-year market projections using advanced forecasting models - Provides scenario analysis with confidence intervals and risk assessment - Includes trend analysis, cyclical patterns, and external factor impacts 💼 **Use cases:** - Strategic planning and long-term business forecasting - Investment planning and capital allocation decisions - Market timing analysis for product launches and expansions - Risk assessment and scenario planning for business continuity 📋 **Parameters:** - **industry**: Industry name or identifier for forecasting - **forecast_years**: Number of years to project (1-10 years) - **scenario_type**: Forecast scenario (conservative, optimistic, pessimistic) - **confidence_level**: Statistical confidence level (0.5-0.99, default: 0.95) 🎯 **Forecast scenarios:** - **Conservative**: Lower growth assumptions, higher risk factors - **Optimistic**: Higher growth potential, favorable conditions - **Pessimistic**: Economic downturns, competitive pressures 📊 **Output includes:** - Year-by-year projections with confidence bands - Key assumptions and risk factors - Sensitivity analysis for major variables - Comparison with historical patterns 💡 **Pro tips:** - Use multiple scenarios for comprehensive planning - Higher confidence levels provide broader but safer ranges - Validate forecasts with industry expert insights`, inputSchema: zodToJsonSchema(MarketForecastingSchema) as any, }, { name: "market_comparison", description: `Compare multiple industries or markets across comprehensive metrics and dimensions. ⚖️ **What it does:** - Performs side-by-side analysis of multiple industries or market segments - Evaluates markets across size, growth, profitability, competition, and innovation metrics - Provides normalized scoring and ranking for objective market comparison 💼 **Use cases:** - Market prioritization and investment allocation decisions - Competitive benchmarking and industry attractiveness analysis - Portfolio optimization and diversification strategy - Market entry sequence planning and resource allocation 📋 **Parameters:** - **industries**: List of industries to compare (2-10 industries) - **comparison_metrics**: Metrics for comparison (size, growth, profitability, competition, innovation) - **time_period**: Time period for comparison analysis [start_year, end_year] - **normalize**: Normalize metrics for fair comparison (default: false) 📊 **Comparison metrics:** - **Size**: Market size, revenue potential, addressable market - **Growth**: Historical and projected growth rates, market momentum - **Profitability**: Margins, pricing power, cost structures - **Competition**: Market concentration, competitive intensity, barriers to entry - **Innovation**: R&D spending, patent activity, disruption potential 💡 **Pro tips:** - Use normalization for comparing markets of very different sizes - Include multiple metrics for holistic market assessment - Focus time periods on strategic planning horizons`, inputSchema: zodToJsonSchema(MarketComparisonSchema) as any, }, { name: "data_validation", description: `Validate market data quality, accuracy, and completeness with detailed recommendations. ✅ **What it does:** - Performs comprehensive quality assessment of market size estimates and data - Cross-validates data across multiple sources and methodologies - Provides data quality scores, confidence indicators, and improvement recommendations 💼 **Use cases:** - Due diligence validation for investment decisions - Data quality assurance for market research reports - Source credibility assessment and data reliability scoring - Market estimate validation and cross-verification 📋 **Parameters:** - **market_size**: Market size estimate to validate - **industry**: Industry name or identifier for context - **year**: Year of the market size estimate - **sources**: Optional list of sources to cross-check against 🔍 **Validation checks:** - **Source credibility**: Authority and reliability of data sources - **Methodology consistency**: Alignment with industry standards - **Cross-source validation**: Agreement across multiple data providers - **Temporal consistency**: Logical progression with historical data - **Geographic consistency**: Regional data alignment with global estimates 📊 **Quality indicators:** - Data confidence score (0-100) - Source reliability rating - Methodology assessment - Recommendations for improvement 💡 **Pro tips:** - Use before making investment decisions based on market size estimates - Higher confidence scores indicate more reliable data for planning - Follow recommendations to improve data quality and reduce uncertainty`, inputSchema: zodToJsonSchema(DataValidationSchema) as any, }, { name: "market_opportunities", description: `Identify emerging market opportunities with growth potential and risk assessment. 🚀 **What it does:** - Discovers high-growth market opportunities using advanced analytics - Evaluates opportunities based on growth criteria, market dynamics, and competitive landscape - Provides risk assessment, timing analysis, and opportunity scoring 💼 **Use cases:** - Investment opportunity identification and evaluation - New market discovery for business expansion - Emerging trend analysis and early market entry - Portfolio development and opportunity pipeline building 📋 **Parameters:** - **industries**: Optional list of industries to focus analysis on - **growth_threshold**: Minimum growth rate threshold for opportunities (default: 5%) - **time_horizon**: Time horizon for opportunity analysis (1-10 years, default: 5) 🎯 **Opportunity criteria:** - **High growth potential**: Above-average growth rates and market expansion - **Market accessibility**: Reasonable barriers to entry and competitive landscape - **Timing advantages**: Early-stage markets with first-mover opportunities - **Risk-adjusted returns**: Attractive opportunity considering risk factors 📊 **Analysis includes:** - Opportunity scoring and ranking - Growth trajectory projections - Competitive landscape assessment - Risk factors and mitigation strategies - Timing recommendations and market entry windows 💡 **Pro tips:** - Set realistic growth thresholds based on your investment criteria - Longer time horizons identify more transformative opportunities - Combine with other tools for comprehensive opportunity assessment`, inputSchema: zodToJsonSchema(MarketOpportunitiesSchema) as any, }, { name: "generic_data_query", description: `Direct access to underlying data services with flexible parameter handling. 🔧 **What it does:** - Provides direct access to specific data source APIs and methods - Allows custom parameter configuration for specialized data requests - Enables advanced users to access raw data capabilities beyond standard tools 💼 **Use cases:** - Custom data extraction for specialized analysis requirements - Direct API access for advanced users and developers - Data source exploration and capability discovery - Integration with external systems and custom analytics 📋 **Parameters:** - **service**: Data service identifier (e.g., "alpha_vantage", "census", "fred") - **method**: Specific method or endpoint within the service - **parameters**: Custom parameters for the data request ⚙️ **Available services:** - Alpha Vantage, Census Bureau, Federal Reserve (FRED) - IMF, OECD, World Bank, Nasdaq Data Link - Bureau of Labor Statistics (BLS) 💡 **Pro tips:** - For advanced users who need specific data configurations - Use standard tools first; this is for specialized requirements - Consult API documentation for service-specific parameters`, inputSchema: zodToJsonSchema(GenericDataQuerySchema) as any, }, ]; } static async industrySearch( params: z.infer<typeof IndustrySearchSchema>, ): Promise<APIResponse<any>> { try { const validatedParams = IndustrySearchSchema.parse(params); const { query, limit, includeSubIndustries } = validatedParams; logger.info(`Industry search: ${query}, limit: ${limit}`); // Use legacy method signature for backward compatibility with tests const industries = await MarketAnalysisTools.dataService.searchIndustries( query, limit, ); const results = industries.map((industry: any) => ({ id: industry.id, name: industry.name, description: industry.description, naicsCode: industry.naicsCode, sicCode: industry.sicCode, marketSize: industry.keyMetrics?.marketSize ? formatCurrency(industry.keyMetrics.marketSize) : "N/A", growthRate: industry.keyMetrics?.growthRate ? formatPercentage(industry.keyMetrics.growthRate) : "N/A", subIndustries: includeSubIndustries ? industry.subIndustries : undefined, // Assuming subIndustries is part of mock lastUpdated: industry.lastUpdated, // Assuming lastUpdated is part of mock })); return createAPIResponse( { query, totalResults: results.length, industries: results, searchTips: results.length === 0 ? [ "Try broader search terms", "Check spelling of industry names", 'Use keywords like "software", "healthcare", "fintech"', ] : undefined, }, "industry-database", ); } catch (error) { return handleToolError(error, "industry_analysis"); } } static async industryData( params: z.infer<typeof ExtendedIndustryDataSchema>, ): Promise<APIResponse<any>> { try { const validatedParams = ExtendedIndustryDataSchema.parse(params); // Handle both old and new parameter formats for backward compatibility let industry_id: string; let include_trends = false; let include_players = false; let include_esg = false; let region: string | undefined; if ("industryId" in validatedParams) { // Old format (for tests) industry_id = (validatedParams as any).industryId; include_players = (validatedParams as any).includeMetrics || false; region = (validatedParams as any).region; } else { // New format industry_id = validatedParams.industry_id!; include_trends = validatedParams.include_trends ?? false; include_players = validatedParams.include_players ?? false; include_esg = validatedParams.include_esg ?? false; region = validatedParams.region; } const { specificDataSourceName, specificDataSourceMethod, specificDataSourceParams, } = validatedParams; // For backward compatibility with tests, use old methods if new schema fields are not present if ("industryId" in validatedParams) { // Use legacy method for tests const industryInfo = await MarketAnalysisTools.dataService.getIndustryById(industry_id); if (!industryInfo) { return createErrorResponse(`Industry not found: ${industry_id}`); } // If region is specified, also call getMarketSize as expected by tests if (region) { await MarketAnalysisTools.dataService.getMarketSize( industry_id, region, ); } const result: any = { id: industryInfo.id, name: industryInfo.name, description: industryInfo.description, classification: { naicsCode: industryInfo.naicsCode, sicCode: industryInfo.sicCode, }, }; if (include_players) { result.metrics = industryInfo.keyMetrics; } return createAPIResponse( result, industryInfo.source || "enhanced-industry-database", ); } else { // Use new enhanced DataService method for new calls const industryData = await MarketAnalysisTools.dataService.getIndustryData({ industry_id, include_trends, include_players, include_esg, }); const result: any = { ...industryData, // Add legacy compatibility fields id: industryData.industry.id, name: industryData.industry.name, description: industryData.industry.description, classification: { naicsCode: industryData.industry.naics_code, sicCode: industryData.industry.sic_code, }, }; // Handle specific data source queries if requested if ( specificDataSourceName && specificDataSourceMethod && specificDataSourceParams ) { logger.info( `IndustryData: Fetching specific data from ${specificDataSourceName}.${specificDataSourceMethod}`, ); try { const detailedData = await MarketAnalysisTools.dataService.getSpecificDataSourceData( specificDataSourceName, specificDataSourceMethod, specificDataSourceParams, ); result.detailedSourceData = detailedData ?? "No data returned from specific source or method returned undefined/null."; } catch (specificError: any) { logger.warn( `IndustryData: Error fetching from ${specificDataSourceName}: ${specificError.message}`, ); result.detailedSourceData = { error: `Failed to fetch from ${specificDataSourceName}: ${specificError.message}`, }; } } return createAPIResponse( result, industryData.data_sources[0] || "enhanced-industry-database", ); } } catch (error) { return handleToolError(error, "industry_data"); } } static async marketSize( params: z.infer<typeof MarketSizeSchema>, ): Promise<APIResponse<any>> { try { const { industryId, region, year, currency } = MarketSizeSchema.parse(params); validateRegion(region); validateCurrency(currency); if (year) { validateYear(year); } const marketDataResult = await MarketAnalysisTools.dataService.getMarketSize(industryId, region); if (!marketDataResult?.value) { return createErrorResponse( `Market size data not available for industry: ${industryId} in region: ${region}`, ); } const details = marketDataResult.details ?? {}; const result = { industry: industryId, marketSize: { value: marketDataResult.value, formattedValue: formatCurrency(marketDataResult.value, currency), currency, year: details.year || details.date || (marketDataResult.source === "mock" ? new Date().getFullYear() : "Latest available"), region: details.region || region, }, dataSource: marketDataResult.source, methodology: details.methodology, confidence: { score: details.confidenceScore, level: details.confidenceScore > 0.8 ? "High" : details.confidenceScore > 0.6 ? "Medium" : "Low", }, sources: details.sources, segments: details.segments?.map((segment: any) => ({ name: segment.name, value: formatCurrency(segment.value, currency), percentage: formatPercentage(segment.percentage), growthRate: formatPercentage(segment.growthRate), description: segment.description, })), metadata: { dataRecency: (details.year || details.date)?.toString() === new Date().getFullYear().toString() ? "Current" : "Historical/Latest", lastUpdated: details.lastUpdated || new Date().toISOString().split("T")[0], }, }; return createAPIResponse( result, marketDataResult.source || "market-data-api", ); } catch (error) { return handleToolError(error, "market_size"); } } static async tamCalculator( params: z.infer<typeof TAMCalculatorSchema>, ): Promise<APIResponse<TAMCalculation>> { try { const { industryId, region, population, penetrationRate, averageSpending, includeScenarios, } = TAMCalculatorSchema.parse(params); validateRegion(region); if (penetrationRate) validatePercentage(penetrationRate, "Penetration rate"); if (population) validatePositiveNumber(population, "Population"); if (averageSpending) validatePositiveNumber(averageSpending, "Average spending"); const industryInfo = await MarketAnalysisTools.dataService.getIndustryById(industryId); const marketDataResult = await MarketAnalysisTools.dataService.getMarketSize(industryId, region); if (!industryInfo || marketDataResult?.value == null) { return createErrorResponse( `Unable to calculate TAM: industry or market data not found for ${industryId} in ${region}`, ); } const marketValue = marketDataResult.value; const marketDataSource = marketDataResult.source; const marketDetails = marketDataResult.details || {}; let tamValue: number; let methodology: string; const assumptions: string[] = []; if (population && penetrationRate && averageSpending) { tamValue = population * penetrationRate * averageSpending; methodology = "Bottom-up: Population × Penetration Rate × Average Spending"; assumptions.push(`Target population: ${population.toLocaleString()}`); assumptions.push( `Penetration rate: ${formatPercentage(penetrationRate)}`, ); assumptions.push( `Average annual spending: ${formatCurrency(averageSpending)}`, ); } else { tamValue = marketValue; // Ensure marketValue is number methodology = `Top-down: Based on existing market size data from ${marketDataSource}`; assumptions.push( `Current market size: ${formatCurrency(marketValue)} (Source: ${marketDataSource})`, ); assumptions.push( `Assumed growth rate: ${formatPercentage(industryInfo.keyMetrics?.growthRate || 0.05)} (from industry profile)`, ); } const scenarios = includeScenarios ? { conservative: tamValue * 0.7, realistic: tamValue, optimistic: tamValue * 1.5, } : { conservative: tamValue, realistic: tamValue, optimistic: tamValue, }; const breakdown = population && penetrationRate && averageSpending ? { population, penetrationRate, averageSpending, } : {}; const confidenceScore = calculateConfidenceScore({ dataRecency: (marketDetails.year || marketDetails.date)?.toString() === new Date().getFullYear().toString() ? 0.9 : 0.7, sourceReliability: marketDataSource !== "mock" ? 0.85 : 0.7, dataCompleteness: Object.keys(breakdown).length > 0 ? 0.9 : marketValue ? 0.75 : 0.5, methodologyRobustness: Object.keys(breakdown).length > 0 ? 0.9 : 0.8, }); const result: TAMCalculation = { totalAddressableMarket: tamValue, methodology, assumptions, scenarios, breakdown, confidenceScore, sources: marketDetails.sources || (marketDataSource ? [marketDataSource] : []), }; return createAPIResponse( result, `tam-calculator (data from ${marketDataSource})`, ); } catch (error) { return handleToolError(error, "tam_analysis"); } } static async samCalculator( params: z.infer<typeof SAMCalculatorSchema>, ): Promise<APIResponse<SAMCalculation>> { try { const { tamValue, targetSegments, geographicConstraints, competitiveFactors, targetMarketShare, timeframe, } = SAMCalculatorSchema.parse(params); validatePositiveNumber(tamValue, "TAM value"); if (targetMarketShare) validatePercentage(targetMarketShare, "Target market share"); let samMultiplier = 1.0; if (geographicConstraints && geographicConstraints.length > 0) { samMultiplier *= 0.6; } if (competitiveFactors && competitiveFactors.length > 0) { const competitiveReduction = Math.min( 0.5, competitiveFactors.length * 0.1, ); samMultiplier *= 1 - competitiveReduction; } if ( targetSegments && targetSegments.length > 0 && targetSegments.length < 5 ) { samMultiplier *= 0.3 + targetSegments.length * 0.15; } const samValue = tamValue * samMultiplier; const somValue = samValue * (targetMarketShare || 0.1); // Default SOM share if not provided const result: SAMCalculation = { serviceableAddressableMarket: samValue, serviceableObtainableMarket: somValue, targetSegments, geographicConstraints, competitiveFactors, marketShare: { target: targetMarketShare || 0.1, timeframe, }, }; return createAPIResponse(result, "sam-calculator"); } catch (error) { return handleToolError(error, "sam_calculator"); } } static async marketSegments( params: z.infer<typeof MarketSegmentsSchema>, ): Promise<APIResponse<any>> { try { const { industryId, segmentationType, region, minSegmentSize } = MarketSegmentsSchema.parse(params); validateRegion(region); if (minSegmentSize) validatePositiveNumber(minSegmentSize, "Minimum segment size"); const marketDataResult = await MarketAnalysisTools.dataService.getMarketSize(industryId, region); const segmentsFromService = await MarketAnalysisTools.dataService.getMarketSegments( industryId, region, ); // Use segments from DataService if available, otherwise fallback or use marketDataResult details const segments = segmentsFromService || marketDataResult?.details?.segments || []; const marketValue = marketDataResult?.value; const dataSource = marketDataResult?.source || "mock-segments"; if (segments.length === 0) { logger.info( `No segment data available for industry: ${industryId} in ${region} from primary sources.`, ); } const filteredSegments = segments.filter( (segment: any) => (segment.value || (marketValue && segment.percentage ? marketValue * segment.percentage : 0)) >= (minSegmentSize || 0), ); const segmentAnalysis = { industry: industryId, segmentationType, region, totalMarketSize: marketValue ? formatCurrency(marketValue) : "N/A", dataSource, segmentCount: filteredSegments.length, segments: filteredSegments.map((segment: any) => ({ name: segment.segmentName || segment.name, // Adapt to different segment structures size: segment.value ? formatCurrency(segment.value) : marketValue && segment.percentage ? formatCurrency(marketValue * segment.percentage) : "N/A", marketShare: segment.percentage ? formatPercentage(segment.percentage) : "N/A", growthRate: segment.growthRate ? formatPercentage(segment.growthRate) : "N/A", description: segment.description, attractiveness: (segment.growthRate || 0) > 0.15 ? "High" : (segment.growthRate || 0) > 0.08 ? "Medium" : "Low", })), // ... (insights as before) }; return createAPIResponse( segmentAnalysis, `market-segmentation-api (data from ${dataSource})`, ); } catch (error) { return handleToolError(error, "market_segments"); } } static async marketForecasting( params: z.infer<typeof MarketForecastingSchema>, ): Promise<APIResponse<any>> { try { const { industryId, years, region, includeScenarios, factors } = MarketForecastingSchema.parse(params); validateRegion(region); validatePositiveNumber(years, "Years to forecast"); const forecastData = await MarketAnalysisTools.dataService.generateMarketForecast( industryId, years, region, ); if (!forecastData?.forecasts || forecastData.forecasts.length === 0) { return createErrorResponse( `Unable to generate forecast for industry: ${industryId}`, ); } const forecasts = forecastData.forecasts; const currentMarketSizeResult = await MarketAnalysisTools.dataService.getMarketSize(industryId, region); const industryInfo = await MarketAnalysisTools.dataService.getIndustryById(industryId); if (currentMarketSizeResult?.value == null || !industryInfo) { return createErrorResponse( `Base data not available for forecasting for ${industryId} in ${region}`, ); } const baseMarketValue = currentMarketSizeResult.value; const baseMarketDetails = currentMarketSizeResult.details || {}; const baseMarketDataSource = currentMarketSizeResult.source; // Ensure forecasts has value, if not, use a mock growth rate for CAGR const endValueForCagr = forecasts[forecasts.length - 1]?.value || baseMarketValue * Math.pow(1 + (industryInfo.keyMetrics?.growthRate || 0.05), years); const cagr = calculateCAGR(baseMarketValue, endValueForCagr, years); const baseYear = baseMarketDetails.year || baseMarketDetails.date || new Date().getFullYear().toString(); const forecastAnalysis = { industry: industryId, region, baseYear, baseMarketSize: formatCurrency(baseMarketValue), baseMarketDataSource, forecastPeriod: `${parseInt(baseYear.toString()) + 1}-${parseInt(baseYear.toString()) + years}`, cagr: formatPercentage(cagr), projections: forecasts.map((forecast: any) => ({ year: forecast.year, marketSize: formatCurrency(forecast.value), // Mock forecast has 'value' growthRate: forecast.growthRate !== undefined ? formatPercentage(forecast.growthRate) : "N/A", // Mock might not have this confidence: forecast.confidence !== undefined ? formatPercentage(forecast.confidence) : "N/A", // Mock might not have this })), keyFactors: factors?.length > 0 ? factors : forecasts[0]?.factors || [ "General economic trends", "Industry specific drivers", ], scenarios: includeScenarios ? { conservative: forecasts.map((f: any) => ({ year: f.year, size: formatCurrency(f.value * 0.8), })), realistic: forecasts.map((f: any) => ({ year: f.year, size: formatCurrency(f.value), })), optimistic: forecasts.map((f: any) => ({ year: f.year, size: formatCurrency(f.value * 1.3), })), } : undefined, // ... (riskFactors as before) }; return createAPIResponse( forecastAnalysis, `forecasting-engine (base data from ${baseMarketDataSource})`, ); } catch (error) { return handleToolError(error, "market_forecasting"); } } static async marketComparison( params: z.infer<typeof MarketComparisonSchema>, ): Promise<APIResponse<MarketComparison>> { try { const { industryIds, region } = MarketComparisonSchema.parse(params); validateRegion(region); const marketDataPromises = industryIds.map(async (id: string) => { const industry = await MarketAnalysisTools.dataService.getIndustryById(id); const marketSizeResult = await MarketAnalysisTools.dataService.getMarketSize(id, region); return { id, industry, marketSizeResult, }; }); const resolvedMarketData = await Promise.all(marketDataPromises); const validMarkets = resolvedMarketData.filter( (m) => m.industry?.marketSizeResult?.value !== undefined, ); if (validMarkets.length < 1) { return createErrorResponse( "Insufficient data for market comparison for the given industries/region.", ); } const markets = validMarkets.map((m: any) => ({ name: m.industry!.name, currentSize: m.marketSizeResult!.value, dataSource: m.marketSizeResult!.source, growthRate: m.industry!.keyMetrics?.growthRate || 0, cagr: m.industry!.keyMetrics?.cagr || 0, region, })); // ... (rest of marketComparison logic) const totalMarketSize = markets.reduce( (sum: number, market: any) => sum + market.currentSize, 0, ); const avgGrowthRate = markets.length > 0 ? markets.reduce( (sum: number, market: any) => sum + market.growthRate, 0, ) / markets.length : 0; let analysisMessage = `Compared ${markets.length} markets in ${region}. `; if (markets.length > 0) analysisMessage += `Total combined size: ${formatCurrency(totalMarketSize)}. Avg growth: ${formatPercentage(avgGrowthRate)}.`; const result: MarketComparison = { markets, analysis: analysisMessage, recommendations: [ "Compare CAGR for growth potential.", "Analyze market share distribution.", ], }; return createAPIResponse(result, "market-comparison-engine"); } catch (error) { return handleToolError(error, "market_comparison"); } } static async dataValidation( params: z.infer<typeof DataValidationSchema>, ): Promise<APIResponse<ValidationResult>> { try { const { dataType, data, strictMode } = DataValidationSchema.parse(params); const issues: string[] = []; const suggestions: string[] = []; let dataQuality: "high" | "medium" | "low" = "high"; switch (dataType) { case "market-size": { if ( !data.value || typeof data.value !== "number" || data.value <= 0 ) { issues.push( "Market size value must be a positive number (data.value)", ); dataQuality = "low"; } const year = data.details?.year || data.details?.date || data.year; // Check new and old structures if ( !year || parseInt(year.toString()) < 1900 || parseInt(year.toString()) > new Date().getFullYear() + 20 ) { issues.push("Invalid or missing year"); dataQuality = dataQuality === "high" ? "medium" : "low"; } const sources = data.details?.sources || (data.source ? [data.source] : []); // Check new and old structures if (!sources || !Array.isArray(sources) || sources.length === 0) { issues.push("Missing or empty data sources"); dataQuality = dataQuality === "high" ? "medium" : dataQuality; } break; } // ... (other dataType cases) } if (strictMode) { const confidenceScore = data.details?.confidenceScore || data.confidenceScore; // Check new and old if (confidenceScore && (confidenceScore < 0 || confidenceScore > 1)) { issues.push("Confidence score must be between 0 and 1"); } const currency = data.details?.currency || data.currency; // Check new and old const supportedCurrencies = await MarketAnalysisTools.dataService.getSupportedCurrencies(); if (currency && !supportedCurrencies.includes(currency.toUpperCase())) { issues.push(`Unsupported currency code: ${currency}`); } } // ... (rest of dataValidation logic) const result: ValidationResult = { isValid: issues.length === 0, issues, suggestions, dataQuality, lastValidated: new Date().toISOString(), }; return createAPIResponse(result, "data-validation-service"); } catch (error) { return handleToolError(error, "data_validation"); } } static async marketOpportunities( params: z.infer<typeof MarketOpportunitiesSchema>, ): Promise<APIResponse<any>> { try { const { industryId, region, minMarketSize, maxCompetition, timeframe } = MarketOpportunitiesSchema.parse(params); // Ensure schema is used validateRegion(region); if (minMarketSize) validatePositiveNumber(minMarketSize, "Minimum market size"); const serviceResponse = await MarketAnalysisTools.dataService.getMarketOpportunities( industryId, region, minMarketSize, ); const opportunitiesArray = serviceResponse?.opportunities; // DataService returns object with 'opportunities' array if (!serviceResponse || !Array.isArray(opportunitiesArray)) { logger.warn( `Market opportunities data for ${industryId} in ${region} was not an array or was null/undefined.`, ); return createAPIResponse( { industry: industryId, region, opportunityCount: 0, opportunities: [], recommendations: [ "No opportunities found or data issue. Consider broadening search or checking data source.", ], }, serviceResponse?.source || "opportunity-analyzer-no-data", ); } const filteredOpportunities = opportunitiesArray.filter((opp: any) => { const competitionLevels = ["low", "medium", "high"]; const maxCompetitionIndex = competitionLevels.indexOf( maxCompetition || "high", ); const oppCompetitionIndex = competitionLevels.indexOf( opp.competitiveIntensity, ); // Use opp.marketSize directly as DataService mock now provides it const sizeCondition = minMarketSize ? opp.marketSize >= minMarketSize : true; return oppCompetitionIndex <= maxCompetitionIndex && sizeCondition; }); const analysis = { industry: industryId, region, searchCriteria: { minMarketSize: minMarketSize ? formatCurrency(minMarketSize) : undefined, maxCompetition, timeframe, }, opportunityCount: filteredOpportunities.length, opportunities: filteredOpportunities .map((opp: any) => ({ id: opp.id, title: opp.title, description: opp.description, marketSize: opp.marketSize ? formatCurrency(opp.marketSize) : "N/A", growthPotential: opp.growthPotential ? formatPercentage(opp.growthPotential) : "N/A", competitiveIntensity: opp.competitiveIntensity, // ... (rest of mapping) attractivenessScore: MarketAnalysisTools.calculateAttractivenessScore(opp), })) .sort( (a: any, b: any) => b.attractivenessScore - a.attractivenessScore, ), // ... (recommendations) }; return createAPIResponse( analysis, serviceResponse?.source || "opportunity-analyzer", ); } catch (error) { return handleToolError(error, "market_opportunities"); } } /** * Calculate attractiveness score for market opportunities */ static calculateAttractivenessScore(opportunity: any): number { let score = 0; // Market size factor (0-30 points) if (opportunity.marketSize) { const marketSizeB = opportunity.marketSize / 1000000000; // Convert to billions score += Math.min(30, marketSizeB * 0.5); } // Growth potential factor (0-25 points) if (opportunity.growthPotential) { score += opportunity.growthPotential * 25; } // Competitive intensity factor (0-20 points, inverse) if (opportunity.competitiveIntensity) { const competitionScores: Record<string, number> = { low: 20, medium: 10, high: 5, }; const competitionScore = competitionScores[opportunity.competitiveIntensity] || 10; score += competitionScore; } // Time to opportunity factor (0-15 points, inverse) if (opportunity.timeToOpportunity) { score += Math.max(0, 15 - opportunity.timeToOpportunity * 3); } // Risk factors penalty (0-10 points) if (opportunity.riskFactors && Array.isArray(opportunity.riskFactors)) { score += Math.max(0, 10 - opportunity.riskFactors.length * 2); } else { score += 10; // No risk factors identified } return Math.round(Math.min(100, Math.max(0, score))); } // New Tool Implementation static async genericDataQuery( params: z.infer<typeof GenericDataQuerySchema>, ): Promise<APIResponse<any>> { try { const { dataSourceName, dataSourceMethod, dataSourceParams } = GenericDataQuerySchema.parse(params); logger.info( `GenericDataQuery: Calling ${dataSourceName}.${dataSourceMethod} with params:`, dataSourceParams, ); const result = await MarketAnalysisTools.dataService.getSpecificDataSourceData( dataSourceName, dataSourceMethod, dataSourceParams, ); if (result === null || result === undefined) { return createAPIResponse( { message: `No data returned from ${dataSourceName}.${dataSourceMethod} for the given parameters.`, query: { dataSourceName, dataSourceMethod, dataSourceParams }, data: null, }, dataSourceName, ); } return createAPIResponse( { query: { dataSourceName, dataSourceMethod, dataSourceParams }, data: result, }, dataSourceName, ); } catch (error: any) { logger.error( `GenericDataQuery failed for ${params.dataSourceName}.${params.dataSourceMethod}: ${error.message}`, { originalError: error }, ); return createErrorResponse( `Error from ${params.dataSourceName}.${params.dataSourceMethod}: ${error.message}`, "generic_data_query_error", ); } } }