Market Sizing MCP Server

A Model Context Protocol server providing market research and business analysis capabilities through 28 tools, 15 business prompts, and integration with 8 economic data sources.

Overview

This MCP server provides comprehensive market research capabilities including:

• 28 Tools: Market analysis, data access, and business intelligence tools
• 15 Prompts: Professional business analysis templates for funding, strategy, and research
• Data Integration: Alpha Vantage, BLS, Census, FRED, IMF, Nasdaq Data Link, OECD, World Bank
• Smart Defaults: Pre-configured parameters for immediate use without setup
• Multiple Transports: STDIO, Streamable HTTP, and SSE support

Capabilities

Market Analysis Tools

• Total Addressable Market (TAM) and Serviceable Addressable Market (SAM) calculations
• Market size estimation and forecasting
• Industry analysis and competitive intelligence
• Market segmentation and opportunity identification
• Data validation and cross-source verification

Business Intelligence Prompts

• Startup funding pitch preparation
• Private equity investment analysis
• Corporate strategy and market entry
• Crisis management and regulatory impact assessment
• ESG and sustainability analysis

Data Access

• Real-time financial and economic data retrieval
• Multi-source data aggregation and comparison
• Intelligent routing based on data type and availability
• Comprehensive caching for performance optimization

MCP Protocol Features

• Real-time Notifications: 6 types of business-specific notifications for market intelligence, data source health, calculation milestones, and performance monitoring
• Multiple Transports: Full support for STDIO, HTTP, and Server-Sent Events (SSE) protocols
• Resource Access: Documentation and status information available through MCP resources
• Tool Discovery: Complete tool catalog with smart defaults and validation

Project Structure

TAM-MCP-Server/
├── config/                     # Configuration files
│   ├── jest.config.json       # Jest test configuration  
│   ├── vitest.config.ts       # Vitest test configuration
│   └── redis.conf             # Redis configuration
├── doc/                       # Documentation
│   ├── README.md              # Documentation hub
│   ├── consumer/              # Consumer documentation
│   │   ├── getting-started.md # Getting started guide
│   │   ├── default-values-guide.md # Default values guide
│   │   ├── mcp-prompts-guide.md # MCP prompts guide
│   │   ├── tools-guide.md     # Tools reference
│   │   └── api-reference.md   # API documentation
│   ├── contributor/           # Contributor documentation
│   │   ├── contributing.md    # Development guidelines
│   │   └── security.md        # Security policy
│   ├── reference/             # Reference documentation
│   │   ├── RELEASE-NOTES.md   # Version history
│   │   ├── CHANGELOG.md       # Technical changes
│   │   └── requirements.md    # Technical specifications
│   ├── reports/               # Technical reports and validation
│   │   ├── SEMANTIC-VALIDATION-COMPLETE.md # Validation results
│   │   └── DEFAULT-VALUES-SUMMARY.md # Default values analysis
│   └── archive/               # Historical documents
├── examples/                  # Examples and demos
│   ├── README.md              # Examples documentation
│   ├── demo-default-values.mjs # Default values demonstration
│   ├── demo-integration.mjs   # Integration examples
│   └── TAM-MCP-Server-Postman-Collection.json # API testing
├── scripts/                   # Build and development scripts
│   ├── build.sh               # Production build script
│   ├── dev-setup.sh          # Development environment setup
│   └── dev.sh                # Development helper script
├── src/                       # Source code
│   ├── index.ts               # Main entry point
│   ├── server.ts              # Core MCP server
│   ├── http.ts                # HTTP transport
│   ├── sse-new.ts            # SSE transport
│   ├── stdio-simple.ts       # STDIO transport
│   ├── config/               # Configuration modules
│   ├── services/             # Data source services
│   ├── tools/                # MCP tool implementations
│   ├── prompts/              # Business prompt templates
│   ├── notifications/        # Notification system
│   ├── types/                # TypeScript definitions
│   └── utils/                # Utility functions
├── tests/                     # Test suite
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   ├── e2e/                  # End-to-end tests
│   ├── scripts/              # Test and validation scripts
│   │   ├── test-comprehensive.mjs # Comprehensive testing
│   │   ├── test-semantic-validation.mjs # Semantic validation
│   │   └── *.mjs             # Additional test utilities
│   ├── fixtures/             # Test data and mock objects
│   ├── utils/                # Test utilities and helpers
│   └── setup.ts              # Test configuration
├── logs/                      # Application logs
├── dist/                      # Compiled JavaScript (built)
├── .env.example              # Environment template
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
└── README.md                 # Main documentation

Tools Reference

MCP Data Access Tools (17 tools)

Direct Data Source Access (13 tools)

Basic Market Tools (4 tools)

Business Analysis Tools (11 tools)

Business Prompts (15 templates)

15 Professional Business Analysis Prompts designed for real-world business scenarios:

Strategic Business Analysis

• startup_funding_pitch - Series A-C funding presentations with TAM/SAM analysis
• private_equity_research - Investment committee packages for PE deals
• corporate_strategy_entry - Fortune 500 market entry strategy analysis
• venture_capital_thesis - VC investment thesis development
• asset_management_research - Institutional asset management research

Crisis & Specialized Analysis

• crisis_management_analysis - Emergency market analysis for crisis response
• regulatory_impact_assessment - Regulatory change impact analysis
• international_expansion - Global market entry strategy analysis
• technology_disruption_analysis - Technology disruption impact assessment
• esg_sustainability_analysis - ESG and sustainability market analysis

Quick Analysis & Guidance

• market_opportunity_scan - Rapid market opportunity identification
• competitive_intelligence - Competitive landscape analysis
• investment_screening - Investment opportunity screening
• tool_guidance - Interactive guide to TAM MCP Server tools
• best_practices_guide - Best practices for market analysis

Designed for AI applications serving business analysts, developers, and market researchers with deep market intelligence and data access tools.

Development

Testing

The project uses a comprehensive test structure with Vitest as the primary testing framework:

tests/
├── unit/                    # Fast, isolated component tests
├── integration/            # Component interaction tests
├── e2e/                   # End-to-end workflow tests
├── scripts/               # Integration test scripts
│   ├── test-comprehensive.mjs # Comprehensive testing
│   ├── test-http-streaming.mjs # HTTP streaming transport
│   ├── test-simple-mcp.mjs # Basic MCP functionality
│   └── test-mcp-tool-calls.mjs # Individual tool validation
├── fixtures/              # Test data and mock objects
├── utils/                 # Test utilities and helpers
└── setup.ts              # Vitest global configuration

Running Tests

# Run all tests
npm test

# Run by category
npm run test:unit          # Fast unit tests
npm run test:integration   # Integration tests
npm run test:e2e          # End-to-end tests

# Advanced options
npm run test:coverage     # With coverage report
npm run test:watch       # Watch mode for development
npm run test:ui          # Vitest UI mode
npm run test:ci          # CI-optimized test run

# Run integration scripts
npm run test:scripts              # Comprehensive backend integration
npm run test:scripts:http         # HTTP streaming transport  
npm run test:scripts:simple       # Basic MCP functionality
npm run test:scripts:tools        # Individual tool validation
npm run test:scripts:inspector    # MCP Inspector compatibility

# Or run directly
node tests/scripts/test-comprehensive.mjs
node tests/scripts/test-http-streaming.mjs

API Testing with Postman

Import the comprehensive Postman collection for testing both MCP endpoints and backend API integrations:

MCP Server Testing Collection

1. Import Collection: examples/TAM-MCP-Server-Postman-Collection.json
2. Set Environment Variables:
   • serverUrl: http://localhost:3000
   • sessionId: (automatically set after initialization)
3. Run Tests:
   • Health check and server status
   • MCP session initialization
   • All 28 tools (11 market analysis + 17 data access)
   • Resource access endpoints
   • Session management and cleanup

Newman CLI Testing Automate Postman tests from command line:

# Install Newman
npm install -g newman

# Run backend API tests
newman run examples/TAM-MCP-Server-Postman-Collection.json \
  -e tests/postman/environments/TAM-MCP-Server-Environment.postman_environment.json \
  --reporters cli,json

# Or use npm script
npm run test:postman

Test Coverage

• Unit Level: Individual tool functionality and business logic
• Integration Level: MCP protocol compliance and server behavior
• System Level: Complete workflows through real transports
• API Level: REST endpoints and session management
• Performance: Response time and resource usage monitoring

Code coverage reports are generated in the coverage/ directory.

Project Structure

src/
├── index.ts              # Main entry point
├── server.ts             # MCP server implementation
├── http.ts               # HTTP transport
├── sse-new.ts           # SSE transport
├── stdio-simple.ts      # STDIO transport
├── config/              # Configuration modules
│   └── apiConfig.ts     # API endpoint configurations
├── services/            # Data source services
│   ├── dataService.ts   # Main data orchestrator
│   ├── cache/           # Caching services
│   │   ├── cacheService.ts # In-memory caching
│   │   └── persistenceService.ts # File persistence
│   └── dataSources/     # Individual data source clients
│       ├── alphaVantageService.ts
│       ├── blsService.ts
│       ├── censusService.ts
│       ├── fredService.ts
│       ├── imfService.ts
│       ├── nasdaqDataService.ts
│       ├── oecdService.ts
│       └── worldBankService.ts
├── tools/               # MCP tool implementations
│   └── market-tools.ts  # MarketAnalysisTools class
├── prompts/             # Business prompt templates
├── notifications/       # Notification system
├── types/               # TypeScript definitions
│   ├── index.ts         # Core schemas and types
│   ├── dataSources.ts   # Data source interfaces
│   └── cache.ts         # Cache-related types
└── utils/               # Utility functions
    ├── dataTransform.ts # Data transformation
    ├── envHelper.ts     # Environment parsing
    ├── rateLimit.ts     # Rate limiting
    └── logger.ts        # Winston logging

tests/
├── unit/                # Unit tests
├── integration/         # Integration tests
├── e2e/                 # End-to-end tests
└── scripts/             # Test automation scripts

API Testing

Use the included Postman collection:

# Import collection
examples/TAM-MCP-Server-Postman-Collection.json

# Or run with Newman
npm run test:postman

Technology Stack

• Language: TypeScript 5.x
• Protocol: MCP 2025-03-26
• Framework: Express.js 4.x
• Validation: Zod schemas
• Testing: Vitest + Postman
• Cache: NodeCache (Redis optional)
• Logging: Winston

Documentation

Complete Documentation

• Documentation Hub - Complete guide to all project documentation
• Getting Started Guide - Quick setup and first-use instructions
• Configuration Guide - Environment setup and API key management
• Tools Reference - Complete tool documentation and usage examples
• Prompts Guide - Business analysis prompt templates and scenarios
• API Reference - Complete API documentation and integration guides
• Default Values Guide - Smart defaults documentation
• MCP Integration Guide - MCP resources and protocol usage

Development Documentation

• Contributing Guide - Guidelines for contributors and developers
• Security Policy - Security guidelines and vulnerability reporting
• Release Notes - Detailed change history and version information
• Changelog - Technical changes and updates

Testing Documentation

• Integration Tests - Integration test scripts documentation

Examples & Scripts

• Examples Directory - API examples and integration resources
• Postman Collection - Comprehensive API testing collection
• Development Scripts - Build and setup automation scripts

Implementation Guides

• Notifications Guide - Real-time notification system
• Architecture Overview - System design and architecture decisions

MCP Resources Access

All documentation is also accessible through the MCP protocol:

// Discover all available documentation
{
  "method": "resources/list",
  "params": {}
}

// Read specific documentation
{
  "method": "resources/read", 
  "params": {
    "uri": "file:///README.md"
  }
}

Available Documentation Resources:

• README.md - Complete project overview and feature documentation
• Getting Started Guide - Quick setup and first-use instructions
• Configuration Guide - Environment setup and API key management
• Tools Reference - Complete tool documentation and usage examples
• Prompts Guide - Business analysis prompt templates and scenarios
• API Reference - Complete API documentation and integration guides
• Security Policy - Security guidelines and best practices
• Contributing Guide - Development and contribution instructions

Contributing

Contributions welcome! See Contributing Guidelines for requirements.

License

MIT License - see LICENSE file for details.

Created by Vaibhav Gupta

Installation

Prerequisites

• Node.js 20.x or later
• npm or yarn
• API keys for data sources (optional, see Configuration)

Quick Setup

# Clone repository
git clone https://github.com/your-username/TAM-MCP-Server.git
cd TAM-MCP-Server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Build and start (HTTP - recommended)
npm run build
npm run start:http

Development Setup

# Use development script
chmod +x scripts/dev-setup.sh
./scripts/dev-setup.sh

# Or manual setup
npm install
npm run build
npm run start  # HTTP server
npm run start:stdio  # STDIO transport

Docker Deployment

# Build image
docker build -t tam-mcp-server .

# Run container with environment file
docker run -p 3000:3000 --env-file .env tam-mcp-server

# Or run with individual environment variables
docker run -p 3000:3000 \
  -e ALPHA_VANTAGE_API_KEY=your_key_here \
  -e FRED_API_KEY=your_key_here \
  -e NODE_ENV=production \
  tam-mcp-server

MCP Integration

HTTP Transport (Recommended) For Claude Desktop, add to your configuration:

{
  "mcpServers": {
    "tam": {
      "command": "npm",
      "args": ["run", "start:http"],
      "cwd": "/path/to/TAM-MCP-Server"
    }
  }
}

STDIO Transport (Alternative)

{
  "mcpServers": {
    "tam": {
      "command": "npm",
      "args": ["run", "start:stdio"],
      "cwd": "/path/to/TAM-MCP-Server"
    }
  }
}

For MCP Inspector:

# HTTP mode
npm run start:http

# STDIO mode  
npx @modelcontextprotocol/inspector npm run start:stdio

Usage

Smart Default Values - Zero-Friction Start

Get professional market insights instantly - no parameter research required!

All 28 tools include intelligent default values that let you start analyzing immediately:

// Call any tool with empty parameters - defaults automatically applied
{
  "name": "alphaVantage_getCompanyOverview",
  "arguments": {} // Server provides: symbol="AAPL" (Apple Inc.)
}

{
  "name": "tam_analysis", 
  "arguments": {} // Server provides: $10B market, 15% growth, 5-year projection
}

Professional Defaults Include:

• Stock Analysis: AAPL, MSFT, GOOGL (Fortune 500 companies)
• Economic Data: US GDP, Global indicators, 2020-2024 timeframes
• Industry Codes: Technology sector, Professional Services (NAICS 54)
• Market Calculations: $10B base market, 15% growth rates, 5-year projections

Perfect for:

• First-time users getting immediate results without parameter research
• Demo environments showcasing professional market analysis capabilities
• Rapid prototyping with realistic business data and scenarios

Basic Tool Usage

// Market analysis with defaults
{
  "name": "tam_analysis",
  "arguments": {}
}

// Company overview with default symbol (AAPL)
{
  "name": "alphaVantage_getCompanyOverview", 
  "arguments": {}
}

// Custom parameters
{
  "name": "market_size",
  "arguments": {
    "industryId": "technology",
    "region": "north-america"
  }
}

Business Analysis Prompts

Access professional templates through the prompts interface:

// List available prompts
{
  "method": "prompts/list"
}

// Get startup funding prompt
{
  "method": "prompts/get",
  "params": {
    "name": "startup_funding_pitch",
    "arguments": {
      "company_name": "TechCorp",
      "industry": "SaaS"
    }
  }
}

MCP Tools - Three-Tier Architecture System

The TAM MCP Server provides 28 total MCP tools organized in three complementary tiers:

Tier 1: Direct Data Access Tools (13 tools)

Purpose: Raw access to external data sources
Target Users: Developers, data engineers, custom analytics builders

• alphaVantage_getCompanyOverview: Get detailed company overview and financials
• alphaVantage_searchSymbols: Search for stock symbols and company names
• bls_getSeriesData: Retrieve Bureau of Labor Statistics employment data
• census_fetchIndustryData: Access U.S. Census Bureau industry statistics
• census_fetchMarketSize: Get market size data from Census surveys
• fred_getSeriesObservations: Fetch Federal Reserve economic data series
• imf_getDataset: Access International Monetary Fund datasets
• imf_getLatestObservation: Get latest IMF economic observations
• nasdaq_getDatasetTimeSeries: Retrieve Nasdaq Data Link time series
• nasdaq_getLatestDatasetValue: Get latest values from Nasdaq datasets
• oecd_getDataset: Access OECD statistical datasets
• oecd_getLatestObservation: Get latest OECD economic observations
• worldBank_getIndicatorData: Fetch World Bank development indicators

Tier 2: Basic Market Tools (4 tools)

Purpose: Foundational market analysis capabilities
Target Users: Business analysts starting with basic market research

• industry_search: Basic industry data retrieval from multiple sources
• tam_calculator: Basic Total Addressable Market calculations
• market_size_calculator: Basic market size estimation with methodology explanations
• company_financials_retriever: Basic company financial data retrieval

Tier 3: Business Analysis Tools (11 tools)

Purpose: Advanced market intelligence and comprehensive business analysis
Target Users: Senior analysts, market researchers, investment teams

1. industry_analysis: Enhanced multi-source industry analysis with intelligent ranking
2. industry_data: Detailed industry intelligence with trends, ESG, and key players
3. market_size: Advanced market size estimation and analysis with confidence scoring
4. tam_analysis: Advanced Total Addressable Market calculations with scenario projections
5. sam_calculator: Serviceable Addressable Market with constraint analysis
6. market_segments: Hierarchical market segmentation analysis
7. market_forecasting: Time series forecasting with scenario analysis
8. market_comparison: Multi-market comparative analysis and rankings
9. data_validation: Cross-source data quality validation and scoring
10. market_opportunities: Market gap and growth opportunity identification
11. generic_data_query: Direct access to any data source service and method

Data Sources

The server integrates with 8 data sources:

• Alpha Vantage: Company financials, stock data
• BLS: Employment and labor statistics
• Census: Industry and demographic data
• FRED: Federal Reserve economic data
• IMF: International economic data
• Nasdaq Data Link: Financial datasets
• OECD: International statistics
• World Bank: Development indicators

Transport Methods

HTTP Server (Recommended)

npm run start:http
# Server available at http://localhost:3000

STDIO Transport

npm run start:stdio

Server-Sent Events

npm run start:sse

Configuration

Environment Variables

Copy .env.example to .env and configure as needed:

# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# API Keys (Optional - tools work without keys but with limited data)
ALPHA_VANTAGE_API_KEY=your_key_here
CENSUS_API_KEY=your_key_here
FRED_API_KEY=your_key_here
NASDAQ_DATA_LINK_API_KEY=your_key_here
BLS_API_KEY=your_key_here

# Cache Configuration (Optional)
CACHE_TTL_DEFAULT_MS=86400000
CACHE_TTL_ALPHA_VANTAGE_MS=86400000
CACHE_TTL_FRED_MS=86400000

Data Source Setup

Required Keys:

• Alpha Vantage: Free tier provides 25 requests/day
• Census Bureau: Free API access
• FRED: Free API access
• Nasdaq Data Link: Free tier available

No Key Required:

• World Bank, OECD, IMF (public APIs)
• BLS (optional key for higher limits)

Tool Defaults

All tools include professional defaults. See Default Values Guide for complete parameter lists.

Example Defaults:

• Stock symbols: AAPL, MSFT, GOOGL
• Industry codes: NAICS 54 (Professional Services)
• Market sizes: $10B base with 15% growth
• Time periods: 2020-2024

Caching Strategy

In-Memory Cache (Default)

• NodeCache-based with configurable TTLs
• Automatic cleanup and statistics
• Per-source cache invalidation

Redis Cache (Production)

const dataService = new EnhancedDataService({
  cache: { type: 'redis' },
  apiKeys: { /* your keys */ }
});

Troubleshooting

Common Issues

Services showing as disabled despite API keys

• Ensure .env file is in project root
• Check API key variable names match exactly
• Restart server after adding keys
• Verify startup logs show service initialization

MCP Inspector connection issues

• Use: npx @modelcontextprotocol/inspector node dist/stdio-simple.js
• Ensure no console.log statements contaminate stdout
• Check Winston logger uses stderr for output

Build errors

• Run npm install to update dependencies
• Check Node.js version (20.x recommended)
• Clear build cache: rm -rf dist && npm run build

No data returned from tools

• Check service status in startup logs
• Verify API quotas not exceeded
• Test with generic_data_query tool
• Check network connectivity

Getting Help

• Check GitHub Issues
• Review Release Notes
• Submit issues with error logs and environment details