Skip to content

Indicator Contract System

Purpose

The indicator contract is the formal specification that governs how the strategy layer interprets visual elements produced by custom ICT Pine Script indicators on TradingView. Each indicator communicates its state exclusively through Pine graphics primitives -- labels, lines, boxes, and tables -- which are read by the TradingView MCP's Pine graphics tools. There are no plot-based readings. No indicator source code modifications are required.

Every contract serves as the single source of truth for the corresponding interpreter module. If the contract says a bullish bias is encoded as a table cell bgcolor, then the interpreter reads that cell's bgcolor. Nothing else. No heuristics, no inference, no fallback assumptions.

Why Contracts Matter

Without a formal contract, the strategy layer would rely on fragile heuristics: string matching that breaks when label text changes, color detection that fails when a user customizes themes, or positional assumptions that collapse when indicators are reordered. The contract eliminates this class of bugs by defining:

  1. Exactly which visual elements carry signal data (and which are cosmetic noise).
  2. The precise encoding scheme -- what each color, style, position, and text pattern means.
  3. The state machine that governs how raw visual observations are converted into discrete strategy states.
  4. Edge cases and failure modes -- what happens when elements are missing, duplicated, or ambiguous.

The contract is a binding agreement: if the indicator produces elements that conform to the contract, the interpreter will produce correct state. If the indicator changes in a way that violates the contract, the interpreter will fail explicitly rather than silently producing wrong state.

Contract Structure

Every indicator contract follows the same five-section structure.

1. Identity

How to locate the indicator on a chart. This includes:

Field Description
pine_title The exact string passed to indicator(title=...) in Pine Script
study_filter The string used to filter this indicator when querying MCP for chart studies
short_title The short name displayed in the chart legend (if different from title)

The identity section ensures the interpreter never accidentally reads elements from the wrong indicator.

2. Visual Channels

The complete inventory of Pine graphics types the indicator uses:

Channel Pine Function MCP Read Method
Labels label.new() get_pine_labels
Lines line.new() get_pine_lines
Boxes box.new() get_pine_boxes
Tables table.new() + table.cell() get_pine_tables

Each contract specifies which channels carry signal data (required for strategy decisions) vs. informational data (useful but not required) vs. cosmetic data (ignored by the interpreter).

3. Element Dictionary

A comprehensive catalog of every distinct visual element the indicator can produce. For each element:

  • Identifier: How to recognize it (color, text pattern, position, style).
  • Meaning: What strategy state it represents.
  • Mutability: Whether the element can change after creation (color shifts, style changes, deletion).
  • Pairing rules: How elements relate to each other (e.g., two lines forming an order block zone).

4. State Machine

The finite state machine that maps raw visual observations to discrete strategy states. This includes:

  • States: The complete set of possible states the indicator can be in.
  • Transitions: What visual changes trigger state transitions.
  • Initial state: What to assume when no elements are present.
  • Reset conditions: When the state machine resets (e.g., daily reset, new session).

The state machine is the core of the contract. It transforms the continuous, mutable visual output of the indicator into clean, discrete signals that the strategy layer can reason about.

5. Edge Cases

Explicit handling for situations that fall outside the normal state machine flow:

  • Missing elements (indicator not loaded, no data for current session).
  • Duplicate elements (multiple signals on the same bar).
  • Ambiguous elements (elements that could match multiple dictionary entries).
  • Timing issues (elements appearing mid-bar vs. bar close).
  • User configuration variations (custom colors, disabled features).

Reading Model

All four indicators are read through the same pipeline:

TradingView Chart
    |
    v
MCP Pine Graphics Tools (get_pine_labels, get_pine_lines, get_pine_boxes, get_pine_tables)
    |
    v
Raw Visual Elements (JSON arrays of labels/lines/boxes/table cells)
    |
    v
Indicator-Specific Interpreter (applies contract rules)
    |
    v
Typed Strategy State (bias direction, hunt state, OB levels, SMT signals)

What MCP Returns

Each MCP graphics tool returns structured data about the visual elements currently rendered on the chart:

  • Labels: position (x, y), text, text color, background color, style (label_up/label_down/etc.), size
  • Lines: start (x1, y1), end (x2, y2), color, style (solid/dashed/dotted), width, extend mode
  • Boxes: bounds (left, top, right, bottom), border color, background color, border style, border width
  • Tables: position, cell values (row, column, text, bgcolor, text_color)

Key Constraints

  1. No plot values. MCP's Pine graphics tools cannot read plot() output. All indicator state must be encoded in labels, lines, boxes, or tables.
  2. No indicator modifications. The indicators are used as-is. The contract documents their existing visual output; it does not prescribe changes.
  3. Snapshot reading. MCP returns the current state of all visible elements. The interpreter must derive state from this snapshot, not from a time series of changes.
  4. Color matching uses hex or RGB. Colors returned by MCP are compared against known values from the contract. User-customizable colors must be accounted for in the interpreter configuration.

Indicators Covered

Indicator Primary Signal Key Channels Contract
Bias AI Daily directional bias (bullish/bearish/neutral) Tables, Lines bias-ai.md
Session Hunt AI Session sweep state and hunt targets Boxes, Lines, Labels session-hunt-ai.md
OB AI Order block zones with FVG association Lines, Boxes, Labels, Tables ob-ai.md
SMT Divergences Smart money divergence signals Lines, Labels smt-divergences.md

Versioning

Contracts are versioned implicitly by the indicator's Pine Script version. If an indicator update changes visual output in a way that breaks the contract, the corresponding interpreter must be updated and the contract document revised. The strategy layer should detect contract violations (unexpected colors, missing elements, malformed text) and raise explicit errors rather than silently degrading.

Future Direction

For indicators designed specifically for MCP consumption, structured payload encoding (delimiter-based or JSON) can replace natural visual encoding. See Payload Format for guidelines.