MCP 服务器

yfnhanced-mcp

Production-grade financial data infrastructure for AI assistants, providing reliable market data from Yahoo Finance with enterprise resilience patterns.

README

Yahoo Finance MCP Server

Production-grade financial data infrastructure for AI assistants

Overview

Transforms unreliable financial APIs into dependable data sources with enterprise-grade resilience, comprehensive data quality validation, and production-ready monitoring.

Built for: AI assistants, investment platforms, algorithmic trading systems, and financial research tools

Key Features:

✅ Circuit breaker pattern with automatic recovery
✅ Multi-strategy rate limiting (token bucket + adaptive + per-endpoint)
✅ Data quality scoring with completeness and integrity validation
✅ Comprehensive caching with graceful fallback
✅ 13+ financial data tools covering stocks, crypto, and forex
✅ Enterprise-grade testing (unit, integration, e2e, chaos)

Quick Start

Installation

Via npm (Recommended):

npm install -g yfnhanced-mcp

From source:

# Clone and install
git clone https://github.com/kanishka-namdeo/yfnhanced-mcp.git
cd yfnhanced-mcp
npm install

# Build TypeScript
npm run build

Start Server

# If installed globally via npm
yfnhanced-mcp

# Or if running from source
npm start

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "yfnhanced-mcp"
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "node",
      "args": ["absolute:\\path\\to\\yfnhanced-mcp\\dist\\index.js"],
      "cwd": "absolute:\\path\\to\\yfnhanced-mcp"
    }
  }
}

Usage with Other AI Tools

Cursor AI:

Add to Cursor's MCP settings:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "yfnhanced-mcp"
    }
  }
}

Cline AI:

Add to Cline's MCP configuration:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "yfnhanced-mcp"
    }
  }
}

Custom Integration:

Use the MCP SDK to integrate with any AI assistant:

import { Client } from '@modelcontextprotocol/sdk';

const client = new Client({
  name: 'your-app',
  version: '1.0.0',
});

await client.connect({
  command: 'yfnhanced-mcp',
});

// Use financial data tools
const quote = await client.callTool({
  name: 'get_quote',
  arguments: { symbol: 'AAPL' }
});

Documentation

Document	Description
TOOLS.md	Complete reference for all 13+ MCP tools
USAGE_GUIDE.md	Practical guide with examples and patterns
CONFIGURATION.md	Detailed configuration guide with best practices
ARCHITECTURE.md	Deep dive into resilience patterns and architecture
DATA_VERIFICATION.md	Verification of data availability and limitations

Available Tools

Market Data

get_quote - Real-time quotes with quality reporting
get_historical_prices - OHLCV data with date ranges
get_historical_prices_multi - Batch historical data

Company Intelligence

get_quote_summary - Comprehensive company overview
get_balance_sheet - Assets, liabilities, equity
get_income_statement - Revenue, expenses, net income
get_cash_flow_statement - Operating, investing, financing cash flows
get_earnings - Quarterly earnings with estimates
get_analysis - Analyst recommendations and price targets
get_major_holders - Institutional and insider ownership

Market Sentiment

get_news - Latest articles with relevance scoring
get_options - Options chains with Greeks
get_trending_symbols - Top movers with volume metrics
screener - Filter stocks by 12+ criteria

Cross-Asset

get_crypto_quote - Cryptocurrency prices
get_forex_quote - Currency pair exchange rates

Note: See DATA_VERIFICATION.md for data availability status

Quick Reference

What Works ✅

Real-time quotes (price, volume, market cap, etc.)
Historical OHLCV data with integrity validation
Company profiles and business information
Earnings data with surprise analysis
Analyst ratings and target prices
Company news with metadata
Options chains with Greeks
Major holders information
Trending symbols and stock screener

Known Issues ⚠️

Financial Statements: May encounter validation errors for some symbols
- See DATA_VERIFICATION.md for workarounds
Crypto/Forex: Tools exist but return placeholder data
- See DATA_VERIFICATION.md for alternatives

Performance

Metric	Value
Quote queries	60 requests/minute (configurable)
Batch operations	Up to 100 symbols per request
Cache hit ratio	70-90% for frequently accessed symbols
Cold start time	<500ms
Test coverage	95%+ for core middleware

Configuration

For detailed configuration options, see CONFIGURATION.md.

Quick Configuration

Create config.json:

{
  "rateLimit": {
    "requestsPerMinute": 60,
    "requestsPerHour": 1500
  },
  "cache": {
    "ttlQuotes": 60000,
    "maxCacheSize": 1000
  },
  "circuitBreaker": {
    "failureThreshold": 5,
    "monitoringWindow": 60000,
    "successThreshold": 3
  },
  "server": {
    "transport": "stdio",
    "logLevel": "info"
  }
}

Testing

npm test              # All tests
npm run test:coverage  # With coverage report
npm run lint         # Code quality checks
npm run typecheck     # TypeScript validation

Test suites include:

Unit tests (95%+ coverage for core middleware)
Integration tests (full tool and resource workflows)
End-to-end tests (complete user journeys)
Chaos tests (network failures, API changes, partial data)

Development

Scripts

npm run dev         # Watch mode for development
npm run build       # Compile TypeScript
npm run start       # Start server
npm run test        # Run tests
npm run test:watch   # Watch mode for tests
npm run lint        # Run linter
npm run lint:fix    # Fix linting issues
npm run typecheck   # Type checking

Project Structure

src/
├── config/          # Configuration management
├── middleware/      # Rate limiting, caching, circuit breaker, retry
├── prompts/         # Pre-built financial analysis prompts
├── schemas/         # Zod validation schemas
├── services/        # Yahoo Finance API client
├── tools/           # MCP tool implementations (13+ tools)
├── types/           # TypeScript type definitions
├── utils/           # Data quality, formatting, security
└── index.ts         # Server entry point

For architecture details, see ARCHITECTURE.md.

Comparison

Feature	This Implementation	Typical Python MCP
Circuit Breaker	✅ Full 3-state implementation	❌ None
Rate Limiting	✅ Token bucket + adaptive + per-endpoint	⚠️ Simple fixed limit
Retry Logic	✅ Exponential backoff + jitter	⚠️ Linear or none
Data Quality	✅ Completeness + integrity + recommendations	❌ None
Observability	✅ Metrics + logging + stats	⚠️ Basic logging
Testing	✅ Unit + integration + e2e + chaos	⚠️ Unit only
Type Safety	✅ TypeScript compile-time checks	❌ Runtime only
Performance	✅ <500ms cold start	⚠️ 2-3s cold start
Configuration	✅ JSON/YAML with validation	⚠️ Environment variables
Security	✅ Input validation + output sanitization	❌ None