# MCP Stock Details Server

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-passing-green.svg)](tests/)

A comprehensive Model Context Protocol (MCP) server for Korean stock market analysis, providing detailed financial data, analysis tools, and investment insights.

## 🚀 Features

### Phase 1 ✅ - Core Infrastructure
- **MCP Server Framework**: Model Context Protocol compliant server
- **Data Collection**: DART (Data Analysis, Retrieval and Transfer System) integration
- **Caching System**: Redis-based caching with memory fallback
- **Error Handling**: Comprehensive exception handling and logging

### Phase 2 ✅ - Analysis Tools (Weeks 1-5)

#### Week 1: Company & Financial Analysis
- **`get_company_overview`**: Comprehensive company information
- **`get_financial_statements`**: Income statement, balance sheet, cash flow analysis

#### Week 2: Financial Ratios & Valuation
- **`get_financial_ratios`**: 50+ financial ratios with industry benchmarks
- **`get_valuation_metrics`**: Multiple valuation approaches (DCF, multiples, etc.)

#### Week 3: ESG & Technical Analysis  
- **`get_esg_info`**: Environmental, Social, Governance analysis
- **`get_technical_indicators`**: Technical analysis indicators (RSI, MACD, etc.)

#### Week 4: Shareholder & Business Analysis
- **`get_shareholder_info`**: Shareholder structure, governance metrics
- **`get_business_segments`**: Business segment performance analysis

#### Week 5: Market Analysis
- **`get_peer_comparison`**: Industry peer comparison and benchmarking
- **`get_analyst_consensus`**: Analyst consensus, target prices, investment opinions

### Upcoming Features (Phase 3-5)
- Advanced valuation models (DCF, Monte Carlo simulation)
- Risk analysis engine (VaR, stress testing)
- Real-time data pipeline
- Performance optimization
- Production deployment

## 🛠️ Installation

### Prerequisites
- Python 3.8 or higher
- Redis (optional, for enhanced caching)

### Setup
```bash
# Clone the repository
git clone https://github.com/yourusername/mcp-stock-details.git
cd mcp-stock-details

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your DART API key and other settings
```

### Environment Variables
```bash
# Required
DART_API_KEY=your_dart_api_key_here

# Optional
REDIS_URL=redis://localhost:6379/0
LOG_LEVEL=INFO
CACHE_TTL=3600
```

## 🚀 Quick Start

### Running the Server
```bash
# Start the MCP server
python -m src.server

# Or run with specific configuration
python -m src.server --config config/development.json
```

### Using with Claude Desktop
Add to your Claude Desktop MCP configuration:
```json
{
  "mcpServers": {
    "stock-details": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-stock-details",
      "env": {
        "DART_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Example Usage
```python
# Get company overview
result = await server.call_tool("get_company_overview", {
    "company_code": "005930",  # Samsung Electronics
    "include_financial_summary": True
})

# Analyze financial ratios
result = await server.call_tool("get_financial_ratios", {
    "company_code": "005930",
    "include_industry_comparison": True,
    "analysis_period": "3Y"
})

# Compare with peers
result = await server.call_tool("get_peer_comparison", {
    "company_code": "005930",
    "include_valuation_comparison": True,
    "max_peers": 5
})
```

## 📊 Supported Analysis

### Financial Analysis
- **Profitability Ratios**: ROE, ROA, Operating Margin, Net Margin
- **Liquidity Ratios**: Current Ratio, Quick Ratio, Cash Ratio
- **Leverage Ratios**: Debt-to-Equity, Interest Coverage, EBITDA Coverage
- **Efficiency Ratios**: Asset Turnover, Inventory Turnover, Receivables Turnover
- **Valuation Ratios**: P/E, P/B, EV/EBITDA, PEG Ratio

### Advanced Analysis
- **DCF Valuation**: Multi-stage dividend discount model
- **Peer Comparison**: Industry benchmarking and relative valuation
- **ESG Scoring**: Environmental, Social, Governance metrics
- **Technical Indicators**: RSI, MACD, Bollinger Bands, Moving Averages
- **Risk Analysis**: Beta, VaR, Sharpe Ratio, Maximum Drawdown

### Market Intelligence
- **Analyst Consensus**: Target prices, investment ratings, earnings estimates
- **Shareholder Analysis**: Ownership structure, governance metrics
- **Business Segments**: Revenue breakdown, segment performance analysis

## 🧪 Testing

```bash
# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=src --cov-report=html

# Run specific test categories
python -m pytest tests/unit/
python -m pytest tests/integration/
```

## 📁 Project Structure

```
mcp-stock-details/
├── src/
│   ├── server.py                 # Main MCP server
│   ├── config.py                 # Configuration management
│   ├── exceptions.py             # Custom exceptions
│   ├── models/                   # Data models
│   ├── tools/                    # Analysis tools
│   │   ├── company_tools.py
│   │   ├── financial_tools.py
│   │   ├── valuation_tools.py
│   │   ├── esg_tools.py
│   │   ├── technical_tools.py
│   │   ├── risk_tools.py
│   │   ├── shareholder_tools.py
│   │   ├── business_segment_tools.py
│   │   ├── peer_comparison_tools.py
│   │   └── analyst_consensus_tools.py
│   ├── collectors/               # Data collectors
│   ├── utils/                    # Utility functions
│   └── cache/                    # Caching system
├── tests/
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   └── fixtures/                 # Test data
├── config/                       # Configuration files
├── docs/                         # Documentation
├── requirements.txt
├── development-plan.md
└── README.md
```

## 📈 Development Status

- [x] **Phase 1**: Core Infrastructure (Completed)
- [x] **Phase 2**: Analysis Tools - Weeks 1-5 (Completed) 
- [ ] **Phase 3**: Advanced Analysis Engine - Weeks 6-8
- [ ] **Phase 4**: Performance & Quality - Weeks 9-10
- [ ] **Phase 5**: Deployment & Operations - Weeks 11-12

See [Development Plan](development-plan.md) for detailed roadmap.

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup
```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests before committing
python -m pytest
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Related Resources

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [DART Open API](https://opendart.fss.or.kr/)
- [Korean Stock Market Data](https://finance.naver.com/)

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/mcp-stock-details/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/mcp-stock-details/discussions)
- **Email**: support@example.com

## 🙏 Acknowledgments

- DART (금융감독원) for providing comprehensive financial data
- Model Context Protocol team for the excellent framework
- Korean financial data providers and community

---

**Note**: This project is for educational and research purposes. Please ensure compliance with data usage terms and local regulations when using financial data.