From 6d8399f300983a8097c2efa0b56b9d5eb603fdbe Mon Sep 17 00:00:00 2001
From: achmad <anakinskywalk1@gmail.com>
Date: Sun, 17 May 2026 11:11:04 +0700
Subject: [PATCH] Add README.md with tool docs, filter reference, and setup
 guide

---
 README.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b04fd3b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# TradingView Screener MCP Server
+
+MCP server that wraps the [tradingview-screener](https://github.com/trendoscope/tradingview-screener) library as granular MCP tools for stock screening, technical analysis, and market data retrieval.
+
+## Tools
+
+### Quotes & Screening
+
+| Tool | Description |
+|------|-------------|
+| `get_stock_quotes` | Get quote data for specific tickers |
+| `screen_market` | General-purpose screener with filters, sorting, pagination |
+| `find_top_gainers` | Top gainers by percent change |
+| `find_top_losers` | Top losers by percent change |
+| `find_most_active` | Most active by volume |
+| `technical_scan` | Screen by technical indicator conditions |
+| `fundamental_scan` | Screen by fundamental metrics |
+
+### Utilities
+
+| Tool | Description |
+|------|-------------|
+| `list_markets` | List available market types and stock countries |
+| `list_fields` | List screener fields by category |
+| `set_session` | Store TradingView session ID in memory |
+| `clear_session` | Clear stored session ID |
+
+## Filter Conditions
+
+Simple condition:
+```json
+{"field": "RSI", "operator": ">", "value": 70}
+```
+
+Nested group:
+```json
+{"operator": "or", "filters": [
+  {"field": "RSI", "operator": ">", "value": 70},
+  {"field": "RSI", "operator": "<", "value": 30}
+]}
+```
+
+### Supported Operators
+
+| Operator | Aliases | Description |
+|----------|---------|-------------|
+| `>` | `greater` | Greater than |
+| `>=` | `egreater` | Greater or equal |
+| `<` | `less` | Less than |
+| `<=` | `eless` | Less or equal |
+| `==` | `equal` | Equal |
+| `!=` | `nequal` | Not equal |
+| `between` | | Value between [lo, hi] |
+| `not_between` | | Value not between [lo, hi] |
+| `isin` | | Value in list |
+| `not_in` | | Value not in list |
+| `has` | | String contains |
+| `has_none_of` | | String contains none of |
+| `like` | | Pattern match |
+| `not_like` | | Pattern not match |
+| `empty` | | Field is empty |
+| `not_empty` | | Field is not empty |
+| `crosses` | | Crosses another field |
+| `crosses_above` | | Crosses above another field |
+| `crosses_below` | | Crosses below another field |
+| `above_pct` | | Above field by % multiplier |
+| `below_pct` | | Below field by % multiplier |
+| `between_pct` | | Between % of field |
+| `in_day_range` | | In 1-day range [lo, hi] |
+| `in_week_range` | | In 1-week range [lo, hi] |
+| `in_month_range` | | In 1-month range [lo, hi] |
+
+### Market Types
+
+- `stocks` (default) — use `market_country` for country (e.g. `"america"`, `"india"`)
+- `crypto`, `crypto_dex`, `coin` — cryptocurrency markets
+- `forex` — currency pairs
+- `futures`, `bond`, `cfd` — derivative markets
+- `options` — use `market_country` for underlying symbol
+
+## Session ID
+
+TradingView session cookies enable real-time data. Priority:
+
+1. Per-call `sessionid` parameter
+2. `set_session` tool (in-memory)
+3. `TV_SESSION_ID` environment variable (loaded from `.env` via `python-dotenv`)
+
+## Setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install .
+cp .env.example .env
+# Edit .env with your TV_SESSION_ID
+```
+
+## Run
+
+```bash
+python server.py
+```
+
+## Tests
+
+```bash
+pytest tests/
+```