PINE_SCRIPT.md

Pine Script MCP Server Documentation

Comprehensive Pine Script development tools integrated with TradingViewMCPServer.

Overview

The Pine Script MCP Server provides professional-grade development tools for Pine Script v1-v6, including real-time syntax validation, intelligent code completion, version detection, code conversion, comprehensive documentation, and a testing sandbox.

Latest Version: Pine Script v6 (LATEST) with full support for type, enum, map, and 100+ built-in functions including all ta., strategy., plot., and map. functions!

Features

1. Real-time Syntax Validation ✓

Validates Pine Script code before execution with detailed error reporting.

Tool: validate_pine_script

# Example usage in Claude Desktop
validate_pine_script("""
//@version=5
indicator("My Indicator")
myMa = ta.sma(close, 20)
plot(myMa)
""")

Features:

• Syntax error detection (missing brackets, invalid operators)
• Function signature validation
• Parameter type checking
• Deprecated function warnings
• Version compatibility checks
• Line-by-line error reporting with suggestions

Error Codes:

• E001: Syntax error
• E101: Unknown function
• E102: Version compatibility error
• E103: Invalid function arguments
• W101: Deprecated function warning

2. Live Documentation Access 📚

Fetch comprehensive documentation for any Pine Script function or topic.

Tool: get_pine_documentation

# Get function documentation
get_pine_documentation("ta.sma")

# Get topic documentation
get_pine_documentation("variables")
get_pine_documentation("operators")

Provides:

• Function signatures with all parameters
• Parameter types (series, simple, const, input)
• Return types
• Detailed descriptions
• Code examples
• Related functions
• Links to official TradingView docs

Available Topics:

• variables - Variable declarations and scoping
• operators - Arithmetic, comparison, logical operators
• types - Pine Script type system

3. Function Signature Checking ✓

Validates function calls with comprehensive parameter checking.

Built into validate_pine_script tool. Checks:

• Required vs optional parameters
• Parameter types (int, float, bool, color, string)
• Type qualifiers (series, simple, const, input)
• Named parameter validation
• Parameter count verification

4. Code Testing Sandbox 🧪

Safe environment for testing Pine Script code with validation and metrics.

Tool: test_pine_script

test_pine_script(
    code="//@version=5\nindicator('Test')\nplot(ta.sma(close, 20))",
    symbol="AAPL",
    timeframe="1h",
    bars=100
)

Features:

• Syntax validation before execution
• Performance metrics
• Execution time tracking
• Error catching and reporting
• Simulated execution environment
• Test with different symbols and timeframes

Note: Full backtesting requires TradingView platform integration. This sandbox validates syntax and provides static analysis.

5. Error Explanations 💡

Get detailed, actionable explanations for Pine Script errors.

Tool: explain_pine_error

explain_pine_error("E101", "Unknown function: sma")

Provides:

• Clear error description
• Common causes (multiple)
• Step-by-step solutions
• Before/after code examples
• Links to relevant documentation

Error Database:

• E001: Syntax errors
• E101: Unknown functions
• E102: Version compatibility
• E103: Invalid arguments
• W101: Deprecated functions
• TYPE_ERROR: Type mismatches

6. Version Detection & Auto-adaptation 🔍

Automatically detect Pine Script version and analyze compatibility.

Tool: detect_pine_version

detect_pine_version("""
study("Old Indicator")
myMa = sma(close, 20)
plot(myMa)
""")

Detection Methods:

1. Version directive parsing (//@version=5)
2. Syntax analysis (v5 namespaces, v4 var keyword)
3. Function usage patterns

Provides:

• Detected version (v1-v5)
• Detection confidence (0-100%)
• Detection source (directive/syntax/functions)
• Compatibility issues
• Deprecated features list
• Upgrade suggestions

Supported Versions:

• Pine Script v1 (legacy)
• Pine Script v2 (legacy)
• Pine Script v3 (deprecated)
• Pine Script v4 (stable)
• Pine Script v5 (current)
• Pine Script v6 (LATEST) ⭐ RECOMMENDED

7. Version Conversion 🔄

Automatically convert Pine Script code between versions.

Tool: convert_pine_version

convert_pine_version(
    code='study("Test")\nplot(sma(close, 20))',
    target_version=5
)

Automatic Conversions:

• study() → indicator()
• security() → request.security()
• sma() → ta.sma()
• ema() → ta.ema()
• rsi() → ta.rsi()
• macd() → ta.macd()
• Math functions → math.* namespace
• String functions → str.* namespace
• All technical indicators → ta.* namespace

Supported Migrations:

• v3 → v4
• v4 → v5
• v5 → v6 ⭐ NEW
• Any version → v6 (recommended)
• Auto-detects source version if not specified

Returns:

• Converted code
• List of changes made
• Warnings for manual review

8. Intelligent Autocomplete 🚀

Context-aware code completion with function signatures.

Tool: autocomplete_pine

autocomplete_pine(
    code="indicator('Test')\nta.",
    cursor_position=23
)

Features:

• Function completions with signatures
• Parameter hints during typing
• Keyword completions
• Built-in variable suggestions
• Namespace-aware completions (ta., math., str.)
• Relevance scoring
• Documentation preview

Completion Types:

• Functions (with parameter placeholders)
• Keywords (if, for, while, var, etc.)
• Built-in variables (close, open, high, low, volume)
• Type qualifiers (series, simple, const, input)

9. Code Templates 📝

Ready-to-use Pine Script templates for common patterns.

Tool: get_pine_template

get_pine_template("strategy")

Available Templates:

Simple Indicator:

//@version=5
indicator("My Indicator", overlay=true)

length = input.int(14, "Period", minval=1)
myValue = ta.sma(close, length)
plot(myValue, color=color.blue, linewidth=2)

Trading Strategy:

//@version=5
strategy("My Strategy", overlay=true, initial_capital=10000)

fastLength = input.int(12, "Fast MA Length")
slowLength = input.int(26, "Slow MA Length")

fastMa = ta.ema(close, fastLength)
slowMa = ta.ema(close, slowLength)

longCondition = ta.crossover(fastMa, slowMa)
shortCondition = ta.crossunder(fastMa, slowMa)

if longCondition
    strategy.entry("Long", strategy.long)
if shortCondition
    strategy.close("Long")

plot(fastMa, color=color.blue)
plot(slowMa, color=color.red)

Overlay Indicator:

//@version=5
indicator("Support/Resistance", overlay=true)

length = input.int(20, "Lookback Length")

resistance = ta.highest(high, length)
support = ta.lowest(low, length)

plot(resistance, color=color.red, linewidth=2)
plot(support, color=color.green, linewidth=2)

Usage Examples

Example 1: Validate Pine Script Code

Ask Claude:
"Validate this Pine Script code:
//@version=5
indicator('RSI')
myRsi = ta.rsi(close, 14)
plot(myRsi)"

Response includes:

• Validation status (pass/fail)
• Detected version
• Any errors with line numbers
• Warnings about deprecated features
• Suggestions for improvements

Example 2: Convert v4 Code to v5

Ask Claude:
"Convert this Pine Script v4 code to v5:
study('My Indicator')
myMa = sma(close, 20)
myRsi = rsi(close, 14)
plot(myMa)"

Response includes:

• Converted code with v5 syntax
• List of all changes made
• Warnings for manual review
• Migration guide

Example 3: Get Function Documentation

Ask Claude:
"Show me the documentation for ta.macd function"

Response includes:

• Function signature
• All parameters with types
• Return type
• Description
• Usage examples
• Related functions

Example 4: Test Code in Sandbox

Ask Claude:
"Test this Pine Script code for AAPL on 1h timeframe:
//@version=5
indicator('MACD')
[macd, signal, hist] = ta.macd(close, 12, 26, 9)
plot(macd, color=color.blue)
plot(signal, color=color.red)"

Response includes:

• Validation results
• Execution metrics
• Any errors or warnings
• Performance statistics

Technical Details

Architecture

tradingview_mcp/
├── pine_script/
│   ├── __init__.py           # Module exports
│   ├── lexer.py              # Tokenization (500+ lines)
│   ├── parser.py             # AST generation (600+ lines)
│   ├── validator.py          # Syntax validation (200+ lines)
│   ├── signatures.py         # Function database (500+ lines)
│   ├── errors.py             # Error explanations (300+ lines)
│   ├── documentation.py      # Docs system (200+ lines)
│   ├── sandbox.py            # Testing environment (200+ lines)
│   ├── versions.py           # Version detection (400+ lines)
│   └── autocomplete.py       # Intelligent completion (300+ lines)

Function Signature Database

Comprehensive database of 50+ Pine Script built-in functions:

Technical Analysis (ta namespace):

• ta.sma, ta.ema, ta.rma, ta.wma
• ta.rsi, ta.macd, ta.stoch
• ta.bb (Bollinger Bands)
• ta.atr (Average True Range)
• And more...

Math Functions (math namespace):

• math.abs, math.max, math.min
• math.round, math.floor, math.ceil
• Trigonometric functions

String Functions (str namespace):

• str.tostring, str.tonumber
• str.length

Input Functions:

• input.int, input.float, input.bool
• input.string, input.color

Plotting Functions:

• plot, plotshape, plotchar
• hline, fill, bgcolor

Performance

• Validation Speed: <500ms for typical scripts
• Cache TTL: 3600s (1 hour) for documentation
• Memory: Lightweight, minimal overhead
• Concurrency: Supports concurrent requests

Limitations

1. Backtesting: Full strategy backtesting requires TradingView platform
2. Chart Rendering: Visual chart output not available in sandbox
3. Real-time Data: Sandbox uses simulated execution
4. Custom Libraries: v5 library imports not fully supported yet

Error Reference

Common Errors and Solutions

E001: Syntax Error

• Cause: Invalid syntax, missing brackets, typos
• Solution: Check matching parentheses, brackets, quotes

E101: Unknown Function

• Cause: Misspelled function, missing namespace
• Solution: Add namespace (ta.sma not sma in v5)

E102: Version Compatibility

• Cause: Using v5 features in v4 code
• Solution: Add //@version=5 or use v4 alternatives

E103: Invalid Arguments

• Cause: Wrong parameter types or count
• Solution: Check function documentation

W101: Deprecated Function

• Cause: Using old v4 function names
• Solution: Update to v5 namespaced functions

Pine Script v6 Features (NEW!)

Pine Script v6 introduces powerful new features based on official TradingView documentation:

1. User-Defined Types (Objects)

User-defined types (UDTs) allow you to create custom data structures. Objects are instances of UDTs.

//@version=6
indicator("UDT Example - Based on Official Docs")

// Define a custom type with the 'type' keyword
type pivotPoint
    int x
    float y
    string xloc = xloc.bar_time  // Optional default value

// Create instances using .new() method
foundPoint = pivotPoint.new()  // All fields default/na
foundPoint = pivotPoint.new(time, high)  // Positional args
foundPoint = pivotPoint.new(x = time, y = high)  // Named args

// Access fields
plot(foundPoint.y)

// Copy objects
copiedPoint = foundPoint.copy()  // Shallow copy

Key Features:

• Use type keyword to define UDTs
• Create instances with .new() method
• Fields can have default values
• Objects are assigned by reference
• Use .copy() for shallow copying

2. Enumerations

Enums represent a predefined set of named values with strict type checking.

//@version=6
indicator("Enum Example - Based on Official Docs")

// Define an enum with optional titles
enum Signal
    buy = "Buy signal"
    sell = "Sell signal"
    neutral

// Declare and use enum variables
var Signal currentSignal = Signal.neutral

if close > ta.sma(close, 50)
    currentSignal := Signal.buy
else if close < ta.sma(close, 50)
    currentSignal := Signal.sell

// Get title
signalText = str.tostring(currentSignal)  // Returns "Buy signal", "Sell signal", or "neutral"

Key Features:

• Use enum keyword to define enums
• Optional titles for each field
• Strict type checking (can't mix different enums)
• Can be used as map keys and in collections
• Use with comparison operators (==, !=)

3. Maps (Key-Value Collections)

Maps store up to 50,000 key-value pairs with unique keys.

//@version=6
indicator("Map Example - Based on Official Docs")

// Create a map (supports up to 50,000 entries)
var priceMap = map.new<string, float>()

// Add/update key-value pairs
map.put(priceMap, "high", high)
map.put(priceMap, "low", low)
map.put(priceMap, "close", close)

// Retrieve values
highPrice = map.get(priceMap, "high")

// Check existence
if map.contains(priceMap, "high")
    plot(highPrice)

// Iterate over map (maintains insertion order)
for [key, value] in priceMap
    log.info(str.format("{0}: {1}", key, value))

// Map operations
keysArray = map.keys(priceMap)  // Get all keys as array
valuesArray = map.values(priceMap)  // Get all values as array
mapSize = map.size(priceMap)  // Get entry count

// Copy and merge maps
newMap = map.copy(priceMap)  // Shallow copy
map.put_all(newMap, otherMap)  // Add all from another map
map.clear(priceMap)  // Remove all entries

Available Map Functions (13 total):

• map.new<K, V>() - Create new map
• map.put(map, key, value) - Add/update entry
• map.get(map, key) - Retrieve value
• map.contains(map, key) - Check if key exists
• map.remove(map, key) - Remove entry
• map.keys(map) - Get array of keys
• map.values(map) - Get array of values
• map.size(map) - Get entry count
• map.clear(map) - Remove all entries
• map.copy(map) - Shallow copy
• map.put_all(map, from_map) - Copy all from another map

4. Other v6 Features

Dynamic Request Calls

//@version=6
indicator("Dynamic Requests")

// Can now use series string in request.*() calls (inside loops/conditionals)
for i = 0 to 5
    symbolName = "AAPL" + str.tostring(i)
    data = request.security(symbolName, "D", close)

New Built-in Variables

//@version=6
indicator("New v6 Variables")

// Real-time market prices
bidPrice = bid  // Real-time bid price
askPrice = ask  // Real-time ask price

// Symbol information
minContract = syminfo.mincontract  // Minimum contract size
mainTicker = syminfo.main_tickerid  // Main ticker ID
mainPeriod = timeframe.main_period  // Main timeframe period

Negative Array Indexing

//@version=6
indicator("Negative Indexing")

var myArray = array.new_float()
array.push(myArray, close)

// Access from end of array
lastElement = array.get(myArray, -1)  // Get last element
secondLast = array.get(myArray, -2)   // Get second to last

Boolean Short-Circuit Evaluation

//@version=6
indicator("Short-Circuit Evaluation")

// 'and' and 'or' now use lazy evaluation for performance
if expensiveCheck() and cheapCheck()
    // cheapCheck() only runs if expensiveCheck() is true
    alert("Both conditions met")

Text Formatting

//@version=6
indicator("Text Formatting", overlay=true)

// Text can now be bold, italic, or both
label.new(bar_index, high, "Bold Text",
    textcolor=color.white,
    text_format_bold=true)

Best Practices

1. Always specify version: Start scripts with //@version=6 (latest)
2. Use v6 features: Leverage type, enum, and map for better code organization
3. Use type annotations: Help catch errors early
4. Validate before running: Use validate_pine_script before testing
5. Check deprecations: Update old code to v5
6. Use templates: Start with proven patterns
7. Test incrementally: Validate changes as you code

Integration with Trading Tools

The Pine Script tools integrate seamlessly with the existing TradingView MCP Server:

• Use Pine Script to develop custom indicators
• Test on real market data (Forex, Stocks, Crypto)
• Combine with 20+ built-in technical indicators
• Validate strategies before deploying to TradingView

Support

For issues or questions:

1. Check error explanations with explain_pine_error
2. Review function documentation with get_pine_documentation
3. See CONTRIBUTING.md for bug reports
4. Visit TradingView Pine Script Docs

Version History

v3.1.0 (Current)

• Pine Script v6 Support: Full support for latest Pine Script version
• New V6 Features: type, enum, map data structures
• Enhanced Function Database: 110+ built-in functions including map.* namespace
• Complete Pine Script MCP integration
• 8 comprehensive MCP tools
• Support for Pine Script v1-v6
• Intelligent validation and conversion
• 3000+ lines of Pine Script tooling code

v2.0.0

• Multi-asset trading support
• 20+ technical indicators
• Modular architecture

v1.0.0

• Initial release
• Basic forex support