Stock Market Analysis MCP Server

# Stock MCP Server - Project Structure ## 📁 Organized File Structure ``` stock_mcp_server/ │ ├── 📄 Python Modules (Core Application) │ ├── stock.server.py # Main MCP server entry point │ ├── run_mcp_server.py # Helper script to start server │ ├── utils.py # Shared utilities (load/save functions) │ ├── price_data.py # Price and stock information tools │ ├── portfolio.py # Portfolio management tools │ ├── analysis.py # Technical analysis indicators │ ├── alerts.py # Alert system (price & RSI) │ ├── dividends.py # Dividend tracking and analysis │ ├── sector.py # Sector analysis and comparison │ ├── risk.py # Risk metrics (Sharpe, Beta, VaR, etc.) │ └── sentiment.py # Market sentiment tracker ✨ NEW │ ├── 📊 data/ (Your Personal Data - Auto-generated) │ ├── portfolio.json # Your stock holdings and transactions │ ├── alerts.json # Your price and RSI alerts │ ├── sentiment_history.json # Sentiment tracking history (90 days) │ └── .gitkeep # Keeps folder in version control │ ├── 📚 docs/ (Documentation) │ ├── TOOLS_REFERENCE.md # Complete guide to all 48+ tools │ ├── SENTIMENT_TRACKER_SUMMARY.md # Sentiment tracker technical docs │ ├── CURRENT_MARKET_ANALYSIS.md # Example market analysis │ ├── IMPLEMENTATION_SUMMARY.md # Implementation details │ ├── ROADMAP.md # Future features and enhancements │ └── .gitkeep # Keeps folder in version control │ ├── 📦 Configuration & Setup │ ├── requirements.txt # Python dependencies │ ├── .gitignore # Git ignore rules (keeps data private) │ ├── README.md # Main documentation and setup guide │ └── PROJECT_STRUCTURE.md # This file │ └── 🐍 venv/ (Virtual Environment) └── [Python packages installed here] ``` ## 📋 File Categories ### Core Python Modules (Root Directory) All Python source code remains in the root directory for easy imports. Each module is self-contained and registers its tools with the MCP server. | Module | Tools | Purpose | |--------|-------|---------| | `price_data.py` | 3 | Basic stock data retrieval | | `portfolio.py` | 4 | Holdings and transaction management | | `analysis.py` | 5 | Technical indicators (RSI, MACD, etc.) | | `alerts.py` | 6 | Price and RSI alert system | | `dividends.py` | 4 | Dividend tracking and income | | `sector.py` | 4 | Sector analysis and rotation | | `risk.py` | 5 | Risk metrics and portfolio risk | | `sentiment.py` | 8 | Market sentiment aggregation ✨ | | **Total** | **48+** | **Complete stock analysis suite** | ### Data Files (`data/` folder) All JSON data files are now organized in the `data/` folder: - **Private Data**: Your portfolio, alerts, and sentiment history - **Auto-generated**: Created automatically when you use features - **Git-ignored**: Won't be committed to version control (keeps private) - **Easy Backup**: Copy entire `data/` folder to backup ### Documentation (`docs/` folder) All markdown documentation organized in the `docs/` folder: - **User Guides**: How to use tools and features - **Technical Docs**: Implementation details and architecture - **Examples**: Market analysis examples and use cases - **Roadmap**: Future features and enhancements ## 🔐 Privacy & Security ### What's Git-Ignored (Private) The `.gitignore` file keeps these private: - `data/*.json` - All your personal data files - `venv/` - Virtual environment (large, not needed in repo) - `__pycache__/` - Python cache files - `.DS_Store` - macOS system files ### What's Version Controlled (Shared) - All Python source code (`.py` files) - Documentation files (`.md` files) - Configuration files (`requirements.txt`, `.gitignore`) - Folder structure markers (`.gitkeep`) ## 📦 Setup & Installation ### Quick Start ```bash # 1. Navigate to project cd stock_mcp_server # 2. Activate virtual environment source venv/bin/activate # macOS/Linux # or venv\Scripts\activate # Windows # 3. Verify structure ls -la data/ # Should see .gitkeep and any existing .json files ls -la docs/ # Should see all .md documentation files # 4. Run server (via MCP config in Cursor) # The server will automatically create data files as needed ``` ## 🔄 Migration from Old Structure ### What Changed (v0.4.0) **Before:** ``` stock_mcp_server/ ├── [python files] ├── portfolio.json ├── alerts.json ├── TOOLS_REFERENCE.md ├── ROADMAP.md └── [other .md files] ``` **After:** ``` stock_mcp_server/ ├── [python files] ├── data/ │ ├── portfolio.json │ ├── alerts.json │ └── sentiment_history.json └── docs/ ├── TOOLS_REFERENCE.md ├── ROADMAP.md └── [other .md files] ``` ### Automatic Path Updates ✅ All file paths updated in `utils.py` ✅ No code changes needed in your MCP configuration ✅ Existing data automatically found in new locations ✅ All imports and tools work seamlessly ## 📊 Data Management ### Accessing Your Data ```bash # View your portfolio cat data/portfolio.json | python -m json.tool # View your alerts cat data/alerts.json | python -m json.tool # View sentiment history cat data/sentiment_history.json | python -m json.tool ``` ### Backing Up Your Data ```bash # Backup all data cp -r data/ data_backup_$(date +%Y%m%d)/ # Restore from backup cp -r data_backup_20251023/* data/ ``` ### Resetting Data ```bash # Clear all data (keeps folder structure) rm data/*.json # Data will be recreated automatically when you use features ``` ## 📚 Documentation Quick Links | Document | Purpose | |----------|---------| | `README.md` | Main documentation, setup guide, features overview | | `docs/TOOLS_REFERENCE.md` | Complete reference for all 48+ tools | | `docs/SENTIMENT_TRACKER_SUMMARY.md` | Market sentiment tracker technical docs | | `docs/CURRENT_MARKET_ANALYSIS.md` | Example market analysis with sentiment data | | `docs/IMPLEMENTATION_SUMMARY.md` | Technical implementation details | | `docs/ROADMAP.md` | Future features and enhancement roadmap | | `PROJECT_STRUCTURE.md` | This file - project organization | ## 🎯 Benefits of New Structure ### ✅ Better Organization - Clear separation: Code vs Data vs Docs - Easier to navigate and find files - Professional project structure ### ✅ Privacy First - All personal data in one folder - Easy to gitignore and keep private - Simple backup and restore ### ✅ Documentation Hub - All guides in one place (`docs/`) - Easy to reference and share - Clean separation from code ### ✅ Scalability - Easy to add new data files - Easy to add new documentation - Maintains clean root directory ## 🚀 Next Steps 1. **Explore Documentation** - Read `docs/TOOLS_REFERENCE.md` for complete tool guide - Check `docs/SENTIMENT_TRACKER_SUMMARY.md` for sentiment features 2. **Start Using Features** - Portfolio tracking → Data saved in `data/portfolio.json` - Set alerts → Saved in `data/alerts.json` - Track sentiment → History in `data/sentiment_history.json` 3. **Backup Regularly** - Copy `data/` folder to safe location - Consider cloud backup for important portfolios 4. **Share Knowledge** - Share `docs/` folder with team - Keep `data/` private - Contribute improvements to code --- **Project Structure Version:** 0.4.0 **Last Updated:** October 23, 2025 **Status:** ✅ Production Ready