|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +TradingView MCP Server is an unofficial Model Context Protocol server that provides access to TradingView's market screener API. It enables AI-powered stock, forex, crypto, and ETF screening through Claude Desktop or Claude Code. |
| 8 | + |
| 9 | +## Build and Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +npm install # Install dependencies |
| 13 | +npm run build # Compile TypeScript to dist/ |
| 14 | +npm test # Run all tests |
| 15 | +npm run test:watch # Run tests in watch mode |
| 16 | +npm run dev # Run directly with tsx (no build step) |
| 17 | +``` |
| 18 | + |
| 19 | +### Running a single test file |
| 20 | +```bash |
| 21 | +npm test -- fields.test.ts |
| 22 | +``` |
| 23 | + |
| 24 | +### Development workflow |
| 25 | +For local development, use `npm run dev` which runs TypeScript directly via tsx without requiring a build step. After making changes: |
| 26 | +1. Restart Claude to reload the MCP server (no hot-reload) |
| 27 | +2. Test via Claude's MCP integration |
| 28 | + |
| 29 | +## Architecture |
| 30 | + |
| 31 | +### Entry Point and MCP Server Setup |
| 32 | +`src/index.ts` - Creates the MCP server, registers tools and resources, handles tool calls. Initializes core components: |
| 33 | +- `TradingViewClient` - API client |
| 34 | +- `Cache` - Response caching (configurable TTL) |
| 35 | +- `RateLimiter` - Request throttling (configurable RPM) |
| 36 | +- `ScreenTool`, `FieldsTool`, `PresetsTool` - Tool implementations |
| 37 | + |
| 38 | +### Core Components |
| 39 | + |
| 40 | +**API Layer** (`src/api/`) |
| 41 | +- `client.ts` - HTTP client for TradingView scanner API endpoints (`/global/scan`, `/forex/scan`, `/crypto/scan`) |
| 42 | +- `types.ts` - TypeScript interfaces for API requests/responses |
| 43 | + |
| 44 | +**Tools** (`src/tools/`) |
| 45 | +- `screen.ts` - Stock/forex/crypto/ETF screening and symbol lookup. Contains `OPERATOR_MAP` for filter operators and `DEFAULT_COLUMNS`/`EXTENDED_COLUMNS` for response fields |
| 46 | +- `fields.ts` - Field metadata and listing (75+ fields across fundamental/technical/performance categories) |
| 47 | + |
| 48 | +**Resources** (`src/resources/`) |
| 49 | +- `presets.ts` - Pre-configured screening strategies (quality_stocks, value_stocks, dividend_stocks, momentum_stocks, growth_stocks, quality_growth_screener, market_indexes). Presets can be filter-based or symbol-based (for direct lookup) |
| 50 | + |
| 51 | +**Utilities** (`src/utils/`) |
| 52 | +- `cache.ts` - In-memory cache with TTL |
| 53 | +- `rateLimit.ts` - Token bucket rate limiter |
| 54 | + |
| 55 | +### MCP Tools Exposed |
| 56 | +1. `screen_stocks` - Screen stocks with filters |
| 57 | +2. `screen_forex` - Screen forex pairs |
| 58 | +3. `screen_crypto` - Screen cryptocurrencies |
| 59 | +4. `screen_etf` - Screen ETFs |
| 60 | +5. `lookup_symbols` - Direct symbol lookup (for indexes like TVC:SPX) |
| 61 | +6. `list_fields` - List available screening fields |
| 62 | +7. `get_preset` / `list_presets` - Access pre-configured strategies |
| 63 | + |
| 64 | +### Data Flow |
| 65 | +1. Tool call received → validate input → check cache |
| 66 | +2. Convert MCP operators to TradingView operators via `OPERATOR_MAP` |
| 67 | +3. Rate limit → API request → format response → cache result |
| 68 | + |
| 69 | +## Configuration |
| 70 | + |
| 71 | +Environment variables (set in `.mcp.json`): |
| 72 | +- `CACHE_TTL_SECONDS` - Cache duration (default: 300) |
| 73 | +- `RATE_LIMIT_RPM` - Requests per minute (default: 10) |
| 74 | + |
| 75 | +## Testing |
| 76 | + |
| 77 | +Tests use Node's built-in test runner with tsx. Test files are in `src/tests/` with `.test.ts` suffix. |
| 78 | + |
| 79 | +## Adding New Features |
| 80 | + |
| 81 | +### New Field |
| 82 | +1. Add to `STOCK_FIELDS` in `src/tools/fields.ts` with name, label, category, type, description |
| 83 | +2. Optionally add to `EXTENDED_COLUMNS` in `src/tools/screen.ts` |
| 84 | + |
| 85 | +### New Preset |
| 86 | +Add to `PRESETS` in `src/resources/presets.ts` with filters array, markets, sort config, and optional custom columns. |
| 87 | + |
| 88 | +### New Tool |
| 89 | +1. Create implementation in `src/tools/` |
| 90 | +2. Register in `ListToolsRequestSchema` handler in `src/index.ts` |
| 91 | +3. Add case in `CallToolRequestSchema` handler |
| 92 | + |
| 93 | +## Claude Code Commands |
| 94 | + |
| 95 | +Project includes ready-to-use commands in `.claude/commands/`: |
| 96 | +- `/market-regime` - Analyze global market indexes relative to ATH |
| 97 | +- `/run-screener` - Interactive stock screening with preset strategies |
0 commit comments