TAM-MCP-Server

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.

Previously featured in the official MCP community servers list here : https://github.com/modelcontextprotocol/servers/blob/e21dbea731f2ccddcd48525cf9a1e1e405fee12f/README.md

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

Architecture Overview

flowchart TD
    Client[MCP Client] <--> Transports

    subgraph Transports[Transports]
        STDIO[STDIO]
        HTTP[HTTP]
        SSE[SSE]
    end

    Transports <--> ToolTiers

    subgraph ToolTiers[MCP Tool Tiers]
        Tier3[Tier 3: Business Analysis Tools]
        Tier2[Tier 2: Basic Market Tools]
        Tier1[Tier 1: Data Access Tools]

        Tier3 --> Tier2
        Tier3 --> Tier1
        Tier2 --> Tier1
    end

    ToolTiers <--> CacheLayer

    subgraph CacheLayer[Cache Layer]
        InMemory[In-Memory Cache]
        Redis[Redis Cache]
    end

    CacheLayer <--> DataServices

    subgraph DataServices[Data Services]
        AV[Alpha Vantage]
        BLS[BLS]
        Census[Census]
        FRED[FRED]
        IMF[IMF]
        Nasdaq[Nasdaq]
        OECD[OECD]
        WB[World Bank]
    end

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

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

Recommended Keys: (Note: Keys are optional. Without them, Tier 1 direct data access tools and higher-tier analysis tools that depend on these specific sources will degrade in functionality, relying on mock data or limited access.)

• 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 */ }
});

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)

Source	Tools	Description
Alpha Vantage	alphaVantage_getCompanyOverview, alphaVantage_searchSymbols	Company financials and stock data
BLS	bls_getSeriesData	Bureau of Labor Statistics data
Census	census_fetchIndustryData, census_fetchMarketSize	Industry and demographic data
FRED	fred_getSeriesObservations	Federal Reserve economic data
IMF	imf_getDataset, imf_getLatestObservation	International economic data
Nasdaq	nasdaq_getDatasetTimeSeries, nasdaq_getLatestDatasetValue	Financial datasets
OECD	oecd_getDataset, oecd_getLatestObservation	International statistics
World Bank	worldBank_getIndicatorData	Development indicators

Basic Market Tools (4 tools)

Tool	Description
industry_search	Basic industry data search from sources
tam_calculator	Basic Total Addressable Market calculations
market_size_calculator	Market size estimation and calculations
company_financials_retriever	Enhanced company financial data retrieval

Business Analysis Tools (11 tools)

Tool	Description
industry_analysis	Enhanced multi-source industry analysis
industry_data	Detailed industry intelligence with trends and key players
market_size	Advanced market size estimation with confidence scoring
tam_analysis	Advanced Total Addressable Market calculations
sam_calculator	Serviceable Addressable Market analysis
market_segments	Hierarchical market segmentation
market_forecasting	Time series forecasting with scenarios
market_comparison	Multi-market comparative analysis
data_validation	Cross-source data quality validation
market_opportunities	Market gap identification
generic_data_query	Direct data source service access

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

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

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