list_docs

Instructions

Implementation Reference

• src/pinescript_mcp/server.py:387-432 (handler)

  The main handler function for the 'list_docs' tool. It is decorated with @mcp.tool() and uses the _timed_tool context manager. It iterates over the DOCS dictionary (lines 180-222), categories each doc by path prefix, and returns a formatted markdown list of all available documentation files grouped by category (Concepts, Reference, Functions, Visuals, Writing Scripts, Migration).

  @mcp.tool(
      tags={"reference", "discovery"},
      annotations={"readOnlyHint": True, "idempotentHint": True, "openWorldHint": False}
  )
  async def list_docs():
      """List all available Pine Script v6 documentation files with descriptions.
  
      Returns files organised by category with descriptions.
      For small files use get_doc(path). For large files
      (ta.md, strategy.md, collections.md, drawing.md, general.md)
      use list_sections(path) then get_section(path, header).
      """
      with _timed_tool("list_docs"):
          output = ["# Pine Script v6 Documentation", ""]
  
          categories = {
              "Concepts": [],
              "Reference": [],
              "Functions": [],
              "Visuals": [],
              "Writing Scripts": [],
              "Migration": [],
          }
  
          for path, desc in DOCS.items():
              if path.startswith("concepts/"):
                  categories["Concepts"].append((path, desc))
              elif path.startswith("reference/functions/"):
                  categories["Functions"].append((path, desc))
              elif "migration" in path:
                  categories["Migration"].append((path, desc))
              elif path.startswith("reference/"):
                  categories["Reference"].append((path, desc))
              elif path.startswith("visuals/"):
                  categories["Visuals"].append((path, desc))
              elif path.startswith("writing_scripts/"):
                  categories["Writing Scripts"].append((path, desc))
  
          for category, docs in categories.items():
              if docs:
                  output.append(f"## {category}")
                  for path, desc in docs:
                      output.append(f"- `{path}`: {desc}")
                  output.append("")
  
          return "\n".join(output)

• src/pinescript_mcp/server.py:387-390 (schema)

  The tool decorator defines the schema: tags indicate 'reference' and 'discovery' categories, and annotations mark the tool as read-only (safe), idempotent (safe to retry), and not open-world (no external side effects). The function takes no parameters and returns a string.

  @mcp.tool(
      tags={"reference", "discovery"},
      annotations={"readOnlyHint": True, "idempotentHint": True, "openWorldHint": False}
  )

• src/pinescript_mcp/server.py:387-390 (registration)

  The tool is registered via the @mcp.tool() decorator on line 387, which registers the async function 'list_docs' as an MCP tool on the FastMCP server instance.

  @mcp.tool(
      tags={"reference", "discovery"},
      annotations={"readOnlyHint": True, "idempotentHint": True, "openWorldHint": False}
  )

• src/pinescript_mcp/server.py:180-222 (helper)

  The DOCS dictionary (lines 180-222) is the data source used by list_docs(). Each key is a file path and each value is a description. The handler iterates over this dictionary to build the categorized listing.

  DOCS = {
      # Concepts
      "concepts/execution_model.md": "Bar-by-bar execution, var, varip, history vs realtime",
      "concepts/timeframes.md": "Multi-timeframe data, request.security, repainting prevention",
      "concepts/colors_and_display.md": "Colors, gradients, transparency, color.new, bgcolor",
      "concepts/common_errors.md": "Runtime and compile-time error explanations",
      "concepts/methods.md": "User-defined methods, method declarations, extending types",
      "concepts/objects.md": "User-defined types (UDT), type keyword, object-oriented patterns",
      # Reference
      "reference/variables.md": "Built-in variables: open, high, low, close, volume, syminfo",
      "reference/constants.md": "Fixed constants: color.red, shape.*, plot.style_*, size.*",
      "reference/types.md": "Type system: int, float, bool, series, simple, const",
      "reference/keywords.md": "Language keywords: if, else, for, while, var, varip, switch",
      "reference/operators.md": "Arithmetic, comparison, logical, ternary operators",
      "reference/annotations.md": "Library annotations: @description, @function, @param, @returns, export",
      "reference/pine_v6_cheatsheet.md": "Compact v6 reference with common pitfalls",
      # Functions
      "reference/functions/ta.md": "Technical analysis: ta.rsi, ta.sma, ta.ema, ta.macd, ta.crossover",
      "reference/functions/strategy.md": "Backtesting: strategy.entry, strategy.exit, strategy.close",
      "reference/functions/request.md": "External data: request.security, request.financial",
      "reference/functions/drawing.md": "Visuals: plot, plotshape, line.new, box.new, label.new, table",
      "reference/functions/collections.md": "Arrays, maps, matrices: array.new, map.new, matrix.new",
      "reference/functions/general.md": "Math, strings, inputs: math.abs, str.format, input.int",
      # Visuals
      "visuals/overview.md": "Visual outputs overview, chart graphics concepts",
      "visuals/plots.md": "plot(), plotcandle(), plotbar() functions",
      "visuals/backgrounds.md": "bgcolor(), background coloring techniques",
      "visuals/bar_coloring.md": "barcolor(), coloring price bars",
      "visuals/bar_plotting.md": "plotcandle(), plotbar() for custom OHLC",
      "visuals/colors.md": "Color functions, color.new(), color.rgb()",
      "visuals/fills.md": "fill() between plots and hlines",
      "visuals/levels.md": "hline(), horizontal levels",
      "visuals/lines_and_boxes.md": "line.new(), box.new() drawing objects",
      "visuals/tables.md": "table.new(), table.cell() for data display",
      "visuals/texts_and_shapes.md": "label.new(), plotshape(), plotchar()",
      # Writing Scripts
      "writing_scripts/style_guide.md": "Naming conventions, code organization, best practices",
      "writing_scripts/debugging.md": "Debugging techniques, log.*, runtime.error()",
      "writing_scripts/limitations.md": "Pine Script limitations, max bars, memory limits",
      "writing_scripts/profiling_and_optimization.md": "Performance optimization, profiling tools",
      # Migration
      "reference/migration_v5_to_v6.md": "v5 to v6 migration guide, breaking changes, renamed functions",
  }