tradingview-mcp-server 0.1.2 → 0.2.0

package/README.md

@@ -12,34 +12,70 @@
 
 **Unofficial** Model Context Protocol (MCP) server for TradingView's stock screener API.
 
+### AI-powered investment research for patient, systematic investors.
+
 </div>
 
+---
+
+## 🎯 Why Use This Tool?
+
+This tool is designed for **curious investors** who want to explore beyond passive index investing without the complexity and competition of day trading.
+
+### The Investment Sweet Spot
+
+**Not for day trading** 📉
+Individual traders can't compete with hedge funds, HFT algorithms, and institutional systems operating at millisecond speeds. Day trading is a zero-sum game dominated by professionals with superior technology and information.
+
+**Not for passive index investing** 📊
+If you're content with market returns through index funds (S&P 500, total market ETFs), that's excellent - but you don't need screening tools. Just buy and hold.
+
+**Perfect for systematic, research-driven investing** 🔍
+This tool is for investors who:
+- Want to **explore higher alpha strategies** than passive investing
+- Are **curious to learn** different investment approaches (value, growth, quality, momentum)
+- Seek **better risk-adjusted returns** through systematic stock selection
+- Prefer **multi-month to multi-year investment horizons** without intraday stress
+- Want to **test investment hypotheses** using fundamental and technical data
+- Value **systematic screening** over gut feelings and tips
+
+### Your Edge: Time, Research, and Patience
+
+Unlike hedge funds competing on speed and information access, you can compete on:
+- **Patience** - Hold positions through volatility without quarterly reporting pressure
+- **Research depth** - Screen comprehensively with 75+ fundamental and technical fields
+- **Strategy experimentation** - Test different approaches (quality, value, growth, momentum)
+- **Risk management** - Build diversified portfolios with systematic criteria
+
+**This tool helps you find opportunities, understand metrics, and make informed decisions - not chase minute-by-minute price movements.**
+
+---
+
 ## Table of Contents
 
 - [Features](#features)
 - [Installation](#installation)
 - [Configuration](#configuration)
-  - [Claude Desktop](#claude-desktop)
-  - [Claude Code](#claude-code-project-level)
-  - [Environment Variables](#environment-variables)
-- [Usage Examples](#usage-examples)
+- [Try It Out: Included Commands](#try-it-out-included-commands)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
 - [Available Tools](#available-tools)
-- [Preset Strategies](#preset-strategies)
-- [Common Fields](#common-fields)
-- [Field Variants (TTM vs FQ vs FY)](#field-variants-ttm-vs-fq-vs-fy)
-- [Development](#development)
 - [Important Notes](#important-notes)
 - [Contributing](#contributing)
 - [License](#license)
 
 ## Features
 
-- 🔍 **Screen stocks, forex, and crypto** with advanced filters
-- 📊 **50+ fundamental, technical, and performance fields** with TTM/FQ/FY variants
-- 🎯 **6 preset strategies** (quality, value, dividend, momentum, growth, comprehensive)
-- ⚡ **Configurable caching and rate limiting**
-- 🔧 **Works with Claude Desktop and Claude Code**
-- 🏦 **Exchange filtering** (NASDAQ, NYSE, CBOE) and primary listing support
+**Built for research-driven investment discovery:**
+
+- 🔍 **Multi-asset screening** - Dedicated tools for stocks, forex, crypto, and ETFs with advanced filters
+- 📊 **75+ investment metrics** - Fundamental (valuation, margins, returns), technical (RSI, moving averages), and performance fields with TTM/FQ/FY variants
+- 🎯 **7 proven strategies & presets** - Pre-configured screens for quality, value, dividend, momentum, growth investing, plus global market indexes
+- 💡 **AI-powered exploration** - Natural language queries through Claude ("Find undervalued companies with strong balance sheets")
+- 💰 **Deep financial analysis** - EV, EV/EBIT, EV/EBITDA, PEG, gross/operating margins, ROIC, ROA, ROE
+- ⚡ **Research-optimized** - Minimal (7 fields) for quick scans vs extended (35 fields) for comprehensive analysis
+- 🏦 **Exchange filtering** - Focus on NASDAQ, NYSE, CBOE, or primary listings only
+- 🌍 **Global coverage** - Screen stocks across multiple markets (America, Europe, Asia) and 9,000+ cryptocurrencies
 
 ## Installation
 
@@ -49,41 +85,38 @@
 npm install -g tradingview-mcp-server
 ```
 
-### Option 2: Local Development
+### Option 2: Clone Repository (with demo commands)
 
 ```bash
 git clone https://github.com/fiale-plus/tradingview-mcp-server.git
 cd tradingview-mcp-server
 npm install
-npm run build
+
+# Quick setup - creates project-level MCP config
+./local-setup.sh          # Linux/Mac
+local-setup.bat           # Windows
+
+# Restart Claude Code and try: /market-regime or /run-screener
 ```
 
 ## Configuration
 
 ### Claude Desktop
 
-Add to your Claude Desktop configuration file:
-
-**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-**Linux**: `~/.config/Claude/claude_desktop_config.json`
+Add to your Claude config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
 
 ```json
 {
   "mcpServers": {
     "tradingview": {
       "command": "npx",
-      "args": ["-y", "tradingview-mcp-server"],
-      "env": {
-        "CACHE_TTL_SECONDS": "300",
-        "RATE_LIMIT_RPM": "10"
-      }
+      "args": ["-y", "tradingview-mcp-server"]
     }
   }
 }
 ```
 
-### Claude Code (Project-Level)
+### Claude Code
 
 Create `.mcp.json` in your project root:
 
@@ -92,11 +125,7 @@ Create `.mcp.json` in your project root:
   "mcpServers": {
     "tradingview": {
       "command": "npx",
-      "args": ["-y", "tradingview-mcp-server"],
-      "env": {
-        "CACHE_TTL_SECONDS": "300",
-        "RATE_LIMIT_RPM": "10"
-      }
+      "args": ["-y", "tradingview-mcp-server"]
     }
   }
 }
@@ -110,58 +139,124 @@ Enable in `.claude/settings.local.json`:
 }
 ```
 
-## Environment Variables
+**Optional environment variables:**
+- `CACHE_TTL_SECONDS` - Cache duration (default: 300)
+- `RATE_LIMIT_RPM` - Requests per minute (default: 10)
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CACHE_TTL_SECONDS` | Cache time-to-live in seconds (0 to disable) | `300` (5 min) |
-| `RATE_LIMIT_RPM` | API requests per minute | `10` |
+## Try It Out: Included Commands
 
-## Usage Examples
+The repository includes two ready-to-use Claude Code commands that demonstrate practical workflows:
 
-### 1. Screen for Quality Stocks
+### `/market-regime` - Check Market Health
 
+Quickly assess overall market conditions by analyzing major indexes relative to their all-time highs.
+
+```bash
+# In Claude Code, run:
+/market-regime
 ```
-Find high-quality stocks with strong fundamentals using the quality_stocks preset
+
+**What you get:**
+- Color-coded status table (🟢/🟡/🔴) for Nasdaq, OMX Stockholm 30, and Nikkei 225
+- Drawdown calculations from all-time highs
+- Market regime summary (bull/correction/bear)
+- Use before making new allocations or for weekly portfolio reviews
+
+### `/run-screener` - Interactive Stock Screening
+
+Run pre-configured screening strategies and save results to CSV for further analysis.
+
+```bash
+# In Claude Code, run:
+/run-screener
+```
+
+**What you get:**
+- Interactive preset selection (quality, value, dividend, momentum, growth)
+- Summary table of top results with key metrics
+- Complete results saved to `docs/local/screening-runs/{preset}_{timestamp}.csv`
+- Perfect for building watchlists and learning different investment styles
+
+**First-time setup:**
+```bash
+# Quick setup script (recommended)
+./local-setup.sh          # Linux/Mac
+local-setup.bat           # Windows
+
+# Or manually copy files:
+cp .mcp.json.example .mcp.json
+cp .claude/settings.json.example .claude/settings.local.json
+
+# Restart Claude Code to load MCP server and commands
 ```
 
-Claude will use the preset with filters:
-- ROE > 12%
-- Low debt (D/E < 0.7)
-- Good margins (Net Margin > 10%)
-- Low volatility
-- Golden cross (SMA50 > SMA200)
+See [`.claude/commands/README.md`](.claude/commands/README.md) for detailed command documentation.
+
+---
+
+## Quick Start
+
+### Learning Investment Strategies
+
+Explore proven investment approaches with pre-configured strategies:
 
-### 2. Custom Screening
+```
+I want to learn about quality investing - show me quality stocks
+```
+
+```
+Find dividend stocks that could provide steady income
+```
 
 ```
-Screen for stocks with:
-- ROE greater than 15%
-- P/E ratio less than 25
-- Market cap above $1 billion
-- Limit to 10 results
+What makes a good value investment? Screen for undervalued companies
 ```
 
-### 3. List Available Fields
+### Research-Driven Stock Selection
+
+Build your investment thesis systematically:
 
 ```
-What fields can I use for stock screening?
+Find companies with:
+- Strong return on equity (>15%)
+- Reasonable valuation (P/E < 25)
+- Significant scale (market cap > $1B)
+- Low debt levels
 ```
 
-Returns all available fields with descriptions, organized by category (fundamental, technical, performance).
+```
+I'm interested in profitable companies trading below their intrinsic value.
+Screen for stocks with EV/EBITDA < 10 and positive free cash flow.
+```
 
-### 4. Get Moving Averages
+### Understanding Investment Metrics
 
 ```
-Get SMA50 and SMA200 for AAPL
+What financial metrics can I use for fundamental analysis?
 ```
 
-### 5. Compare Stocks
+```
+Explain the difference between P/E ratio and PEG ratio
+```
 
 ```
-Compare fundamentals of AAPL, MSFT, and GOOGL
+What's the difference between gross margin and operating margin?
 ```
 
+## Documentation
+
+### 📚 Comprehensive Guides
+
+- **[Preset Strategies](docs/presets.md)** - All 7 preset strategies with detailed criteria, use cases, and examples
+- **[Field Reference](docs/fields.md)** - Complete guide to all 75+ fields with descriptions and usage examples
+- **[Development Guide](docs/development.md)** - Local setup, testing, and extending the server
+
+### 🔧 Advanced Topics
+
+- **[Field Variants (TTM/FQ/FY)](docs/fields.md#understanding-field-variants)** - Understanding time periods
+- **[Column Optimization](docs/presets.md#performance-characteristics)** - Minimal vs extended column sets
+- **[Custom Presets](docs/development.md#creating-new-presets)** - Creating your own screening strategies
+
 ## Available Tools
 
 ### `screen_stocks`
@@ -174,6 +269,7 @@ Screen stocks based on filters.
 - `sort_by` - Field to sort by (default: `"market_cap_basic"`)
 - `sort_order` - `"asc"` or `"desc"` (default: `"desc"`)
 - `limit` - Number of results (1-200, default: 20)
+- `columns` - Optional array of columns to return (default: minimal 7 fields for performance)
 
 **Operators:**
 - `greater`, `less`, `greater_or_equal`, `less_or_equal`
@@ -194,282 +290,108 @@ List available fields for filtering.
 Get a pre-configured screening strategy.
 
 **Available Presets:**
-- `quality_stocks` - Conservative quality stocks (Avanza-based)
-- `value_stocks` - Undervalued stocks with low P/E and P/B
-- `dividend_stocks` - High dividend yield with consistent payout
-- `momentum_stocks` - Strong momentum and technical signals
-- `growth_stocks` - High-growth companies
-- `quality_growth_screener` - Comprehensive 16-filter quality & growth screen
+- `quality_stocks` - Conservative quality (ROE >12%, low debt, low volatility)
+- `value_stocks` - Undervalued (P/E <15, P/B <1.5)
+- `dividend_stocks` - High yield (>3%, low debt)
+- `momentum_stocks` - Technical strength (RSI 50-70, golden cross)
+- `growth_stocks` - High growth (ROE >20%, margins >15%)
+- `quality_growth_screener` - Comprehensive 16-filter screen with 35 extended columns
+
+See **[Preset Strategies Guide](docs/presets.md)** for detailed criteria and usage.
 
 ### `list_presets`
 
 List all available preset strategies.
 
-## Preset Strategies
-
-The server includes 6 pre-configured screening strategies optimized for different investment styles:
-
-### Quality Stocks (Conservative)
-**Preset:** `quality_stocks`
-
-High-quality, low-volatility stocks with strong fundamentals and uptrends. Based on Avanza's conservative screening strategy.
-
-**Criteria:**
-- ROE > 12%
-- Market cap > $200M
-- P/E < 40
-- P/S < 8
-- Debt/Equity < 0.7
-- Net margin > 10%
-- RSI between 45-65
-- Monthly volatility ≤ 3%
-- Golden cross (SMA50 > SMA200)
-
-### Value Stocks
-**Preset:** `value_stocks`
-
-Undervalued stocks trading below intrinsic value with solid fundamentals.
-
-**Criteria:**
-- P/E < 15
-- P/B < 1.5
-- Market cap > $1B
-- ROE > 10%
-
-### Dividend Stocks
-**Preset:** `dividend_stocks`
-
-Income-focused stocks with high dividend yields and financial stability.
-
-**Criteria:**
-- Dividend yield > 3%
-- Market cap > $5B
-- Debt/Equity < 1.0
-
-### Momentum Stocks
-**Preset:** `momentum_stocks`
-
-Stocks showing strong technical momentum and recent performance.
-
-**Criteria:**
-- RSI between 50-70
-- SMA50 > SMA200 (golden cross)
-- 1-month performance > 5%
-- Volume > 1M shares
-
-### Growth Stocks
-**Preset:** `growth_stocks`
-
-High-growth companies with strong profitability and margins.
-
-**Criteria:**
-- ROE > 20%
-- Operating margin > 15%
-- Market cap > $1B
-
-### Quality Growth Screener (Comprehensive)
-**Preset:** `quality_growth_screener`
-
-Comprehensive quality and growth screen combining fundamental strength, growth momentum, financial stability, and technical uptrend. Primary listings only on major US exchanges.
-
-**16-Filter Criteria:**
-
-**Price & Size:**
-- Price ≥ $10
-- Market cap ≥ $2B
+### `screen_forex`
 
-**Valuation:**
-- P/E (TTM) ≤ 35
-- P/S (Current) ≤ 6
+Screen forex pairs based on technical criteria.
 
-**Profitability (FQ/FY):**
-- ROE (FQ) > 15%
-- Net Margin (FY) > 12%
-
-**Financial Strength:**
-- Debt/Equity (FY) < 0.6
-
-**Growth:**
-- Revenue/Share (TTM) > $3
-- Revenue Growth YoY > 8%
+**Parameters:**
+- `filters` - Array of filter conditions (field, operator, value)
+- `sort_by` - Field to sort by (default: `"volume"`)
+- `sort_order` - `"asc"` or `"desc"` (default: `"desc"`)
+- `limit` - Number of results (1-200, default: 20)
 
-**Technical Indicators:**
-- RSI between 45-62
-- Golden cross (SMA50 ≥ SMA200)
-- Price > SMA50 (above trend)
-- Monthly volatility < 3%
+**Example fields:** `close`, `volume`, `change`, `RSI`, `SMA50`, `SMA200`, `Volatility.M`
 
-**Liquidity & Quality:**
-- 90-day avg volume > 200K
-- Exchange: NASDAQ, NYSE, or CBOE only
-- Primary listing only (eliminates duplicates)
+### `screen_crypto`
 
-## Common Fields
+Screen cryptocurrencies based on technical and market criteria.
 
-### Fundamental
-- `return_on_equity` - ROE (%)
-- `price_earnings_ttm` - P/E Ratio
-- `price_book_fq` - P/B Ratio
-- `debt_to_equity` - Debt/Equity Ratio
-- `net_margin_ttm` - Net Margin (%)
-- `market_cap_basic` - Market Capitalization
-- `dividend_yield_recent` - Dividend Yield (%)
-
-### Technical
-- `RSI` - Relative Strength Index (14)
-- `SMA50` - 50-day Simple Moving Average
-- `SMA200` - 200-day Simple Moving Average
-- `Volatility.M` - Monthly Volatility (%)
+**Parameters:**
+- `filters` - Array of filter conditions (field, operator, value)
+- `sort_by` - Field to sort by (default: `"market_cap_basic"`)
+- `sort_order` - `"asc"` or `"desc"` (default: `"desc"`)
+- `limit` - Number of results (1-200, default: 20)
 
-### Performance
-- `close` - Current Price
-- `change` - Daily Change (%)
-- `volume` - Trading Volume
-- `average_volume_90d_calc` - 90-day Average Volume
-- `Perf.W`, `Perf.1M`, `Perf.Y` - Performance metrics
-- `exchange` - Stock exchange (NASDAQ, NYSE, CBOE)
-- `is_primary` - Primary listing indicator
+**Example fields:** `close`, `market_cap_basic`, `volume`, `change`, `Perf.1M`, `Perf.3M`, `Perf.Y`
 
-## Field Variants (TTM vs FQ vs FY)
+### `screen_etf`
 
-Many financial metrics have multiple time period variants. Understanding these is crucial for accurate screening:
+Screen ETFs (Exchange-Traded Funds) based on performance and technical criteria.
 
-### Time Period Suffixes
+**Parameters:**
+- `filters` - Array of filter conditions (field, operator, value)
+- `markets` - Markets to scan (default: `["america"]`)
+- `sort_by` - Field to sort by (default: `"market_cap_basic"`)
+- `sort_order` - `"asc"` or `"desc"` (default: `"desc"`)
+- `limit` - Number of results (1-200, default: 20)
+- `columns` - Optional array of columns to return
 
-- **TTM** (Trailing Twelve Months): Rolling 12-month period
-  - Most recent, updates quarterly
-  - Example: `return_on_equity`, `price_earnings_ttm`, `net_margin_ttm`
+**Example fields:** `close`, `volume`, `change`, `Perf.1M`, `Perf.Y`, `RSI`, `beta_1_year`
 
-- **FQ** (Fiscal Quarter): Most recent completed quarter
-  - Updates quarterly
-  - More volatile than TTM
-  - Example: `return_on_equity_fq`, `price_book_fq`
+### `lookup_symbols`
 
-- **FY** (Fiscal Year): Most recent completed fiscal year
-  - Updates annually
-  - Most stable, less frequent updates
-  - Example: `debt_to_equity_fy`, `net_margin_fy`
+Look up specific symbols (stocks, indexes, ETFs) by ticker. **Use this for market indexes** like TVC:SPX, TVC:DJI, OMXSTO:OMXS30 that cannot be found via screening.
 
-### Common Field Variants
-
-| Base Metric | TTM | FQ | FY |
-|-------------|-----|----|----|
-| Return on Equity | `return_on_equity` | `return_on_equity_fq` | - |
-| Net Margin | `net_margin_ttm` | - | `net_margin_fy` |
-| Debt/Equity | `debt_to_equity` | - | `debt_to_equity_fy` |
-| Price/Sales | `price_sales_ratio` | - | `price_sales_current` |
+**Parameters:**
+- `symbols` - Array of ticker symbols (e.g., `["TVC:SPX", "NASDAQ:AAPL", "OMXSTO:OMXS30"]`). Maximum 100 symbols.
+- `columns` - Optional array of columns to include
 
-### Usage Tips
+**Default columns:** `name`, `close`, `change`, `volume`, `market_cap_basic`, `all_time_high`, `all_time_low`, `price_52_week_high`, `price_52_week_low`
 
-1. **For conservative screening**: Use FY variants for stability
-2. **For current analysis**: Use TTM or FQ for recent performance
-3. **Mixing periods**: You can mix different variants in the same filter
-4. **TradingView UI matching**: Use FQ/FY variants to match TradingView's web screener exactly
+**Use Cases:**
+- **Market regime analysis** - Check if indexes are at all-time highs
+- **Direct symbol lookup** - Faster than screening for known tickers
+- **Portfolio comparison** - Compare your holdings side-by-side
+- **Benchmark analysis** - Compare against market indexes
 
-Example using fiscal year data:
+**Example:** Get S&P 500, Nasdaq, and OMX Stockholm 30 with market regime data
 ```javascript
-{
-  filters: [
-    { field: "return_on_equity_fq", operator: "greater", value: 15 },
-    { field: "debt_to_equity_fy", operator: "less", value: 0.6 },
-    { field: "net_margin_fy", operator: "greater", value: 12 }
-  ]
-}
-```
-
-## Resources
-
-The server exposes preset configurations as MCP resources:
-
-- `preset://quality_stocks`
-- `preset://value_stocks`
-- `preset://dividend_stocks`
-- `preset://momentum_stocks`
-- `preset://growth_stocks`
-- `preset://quality_growth_screener`
-
-## Development
-
-### Local Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/fiale-plus/tradingview-mcp-server.git
-cd tradingview-mcp-server
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Watch tests
-npm test:watch
-```
-
-### Using Local MCP Server with Claude
-
-To test your local development build with Claude Desktop or Claude Code:
-
-#### Option 1: Project-Level MCP (Recommended for Development)
-
-Create `.mcp.json` in your project root:
-
-```json
-{
-  "mcpServers": {
-    "tradingview-local": {
-      "command": "node",
-      "args": ["/absolute/path/to/tradingview-mcp-server/dist/index.js"],
-      "env": {
-        "CACHE_TTL_SECONDS": "300",
-        "RATE_LIMIT_RPM": "10"
-      }
-    }
-  }
-}
+lookup_symbols({
+  symbols: ["TVC:SPX", "TVC:IXIC", "OMXSTO:OMXS30"],
+  columns: ["close", "all_time_high", "price_52_week_high", "Perf.Y", "RSI"]
+})
 ```
 
-Enable in `.claude/settings.local.json`:
-
-```json
-{
-  "enableAllProjectMcpServers": true
-}
-```
+## Key Features at a Glance
 
-**Important**: Replace `/absolute/path/to/tradingview-mcp-server` with the actual path to your local repository.
+### 75+ Available Fields
 
-#### Option 2: Claude Desktop Global Config
+The server provides comprehensive coverage across categories:
 
-Add to your Claude Desktop config file:
+- **Fundamental** - Core metrics (ROE, P/E, P/B), valuation (EV, EV/EBIT, PEG), margins (gross, operating, pre-tax), returns (ROA, ROIC), balance sheet (debt, assets, current ratio)
+- **Technical** - RSI, moving averages (SMA50, SMA200), volatility, beta
+- **Performance** - Price, volume, growth metrics, sector/industry
 
-**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-**Linux**: `~/.config/Claude/claude_desktop_config.json`
+See **[Complete Field Reference](docs/fields.md)** for all 75+ fields with descriptions and examples.
 
-```json
-{
-  "mcpServers": {
-    "tradingview-local": {
-      "command": "node",
-      "args": ["/absolute/path/to/tradingview-mcp-server/dist/index.js"]
-    }
-  }
-}
-```
+### 7 Preset Strategies
 
-### Development Workflow
+Pre-configured screens for common investment strategies:
 
-1. **Make changes** to source files in `src/`
-2. **Build**: `npm run build`
-3. **Restart Claude** (Desktop or Code) to pick up changes
-4. **Test** your changes via Claude's MCP integration
+| Preset | Style | Key Criteria | Columns |
+|--------|-------|--------------|---------|
+| `quality_stocks` | Conservative | ROE >12%, low debt, low volatility | 7 default |
+| `value_stocks` | Value | P/E <15, P/B <1.5 | 7 default |
+| `dividend_stocks` | Income | Yield >3%, low debt | 7 default |
+| `momentum_stocks` | Momentum | RSI 50-70, golden cross | 7 default |
+| `growth_stocks` | Growth | ROE >20%, margins >15% | 7 default |
+| `quality_growth_screener` | Comprehensive | 16 filters, deep analysis | 35 extended |
+| `market_indexes` | Market Regime | 13 global indexes (US, EU, Asia) | 16 extended |
 
-**Tip**: After rebuilding, you must restart Claude to load the new build. The MCP server runs as a separate process and doesn't auto-reload.
+See **[Preset Strategies Guide](docs/presets.md)** for detailed criteria, use cases, and examples.
 
 ## Important Notes
 
@@ -480,24 +402,51 @@ Add to your Claude Desktop config file:
 - No official documentation or support from TradingView
 - Use responsibly with rate limiting
 
-## Limitations
+## Investment Focus & Limitations
+
+This tool is designed for **research and position selection**, not intraday trading:
 
-- **Current snapshot only** - No historical data
-- **Rate limits** - Conservative default (10 req/min) to avoid overloading
-- **Calculated fields** - Some metrics (e.g., Revenue per Share) need post-processing
-- **Market hours** - Data freshness depends on TradingView's update schedule
+- **Current fundamentals snapshot** - Latest quarterly/annual data for investment decisions (no tick-by-tick historical data needed)
+- **Research-paced rate limits** - Conservative default (10 req/min) supports thorough analysis, not high-frequency trading
+- **Strategic timeframes** - Daily/weekly data updates align with multi-month investment horizons
+- **Fundamental-first approach** - Emphasizes financial metrics over intraday price action
+
+**By design**, this tool doesn't support:
+- Real-time tick data or intraday charts (not needed for position investing)
+- High-frequency screening (research takes time and thought)
+- Options chains or derivatives (focused on equity fundamentals)
+- News feeds or sentiment analysis (focus on numbers and metrics)
 
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+For development setup and guidelines, see the **[Development Guide](docs/development.md)**.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
 ## Disclaimer
 
-This is an unofficial tool and is not affiliated with, endorsed by, or connected to TradingView. Use at your own risk.
+**Not Investment Advice**
+
+This tool provides stock screening capabilities for informational and educational purposes only. It is **not investment advice, financial advice, or a recommendation** to buy or sell any security.
+
+- All investment decisions are your sole responsibility
+- Past performance does not indicate future results
+- Screening results do not constitute investment recommendations
+- Always conduct your own research and due diligence
+- Consult qualified financial advisors before making investment decisions
+- You may lose money investing in securities
+
+**Software License**
+
+This software is provided "AS IS" under the [MIT License](LICENSE), without warranty of any kind, express or implied. The authors and contributors are not liable for any damages or losses arising from use of this software.
+
+**Third-Party Services**
+
+This is an unofficial tool and is not affiliated with, endorsed by, or connected to TradingView. Use at your own risk. TradingView's unofficial API may change without notice.
 
 ## Links
 
@@ -508,4 +457,6 @@ This is an unofficial tool and is not affiliated with, endorsed by, or connected
 
 ---
 
+**Smarter screens, not faster trades.**
+
 Built with ❤️ using the [Model Context Protocol](https://modelcontextprotocol.io)