# This file is automatically generated by ravepipeline::mcptool_build(). 
# Please never edit this file by hand!
name: ieegio-mcp_tool_surface_read
description: 'Read a neuroimaging surface file (GIfTI, STL, or FreeSurfer format)
  and cache it in memory with a unique digest-based ID. Internally the tool calls
  function ieegio::read_surface. The surface is stored in session state for efficient
  reuse by other MCP tools. Returns surface metadata and the ID to reference this
  surface in subsequent operations. Use the returned ID with other tools: ieegio-mcp_tool_surface_write
  to save the surface to a file, ieegio-mcp_tool_surface_info to get detailed information,
  ieegio-mcp_tool_surface_list to see all cached surfaces, or ieegio-mcp_tool_surface_clear
  to remove surfaces from cache.'
parameters:
  type: object
  properties:
    file_path:
      type: string
      description: 'Absolute or relative path to the surface file. Supported formats:
        .gii, .gii.gz (GIfTI), .stl (STL), FreeSurfer geometry, annotations, measurements.
        Example values: "/path/to/lh.pial.gii", "data/lh.pial"'
      examples:
      - /path/to/lh.pial.gii
      - data/lh.pial
  required:
  - file_path
category: info
returns:
  type: object
  properties:
    error:
      type: string
      description: Character, error message if success is FALSE
    n_faces:
      type: integer
      description: Integer, number of faces (if geometry present)
    n_vertices:
      type: integer
      description: Integer, number of vertices (if geometry present)
    contains:
      type: array
      description: Character vector, what data the surface contains (e.g., "geometry",
        "measurements")
      items:
        type: string
    format:
      type: string
      description: Character, file format ("gifti", "stl", or "freesurfer")
    file_path:
      type: string
      description: Character, the original file path that was read
    id:
      type: string
      description: Character, unique digest-based identifier for this surface
    success:
      type: boolean
      description: Logical, whether the surface was successfully read and cached
implementation_example: |
  # Read a GIfTI surface file
  # Note: .state_env is automatically provided when called via MCP.
  # The example includes it only to make the code runnable for documentation.
  sample_file <- ieegio_sample_data("gifti/GzipBase64/sujet01_Lwhite.surf.gii")
  ieegio:::mcp_tool_surface_read(sample_file)
  #
  #> $success
  #> [1] TRUE
  #> 
  #> $id
  #> [1] "87405ad0bc7df5262dadebee27bf4c3b"
  #> 
  #> $file_path
  #> [1] "/Users/dipterix/Library/Caches/org.R-project.R/R/ieegio/sample_data/gifti/GzipBase64/sujet01_Lwhite.surf.gii"
  #> 
  #> $format
  #> [1] "gifti"
  #> 
  #> $contains
  #> [1] "geometry"
  #> 
  #>  [ reached 'max' / getOption("max.print") -- omitted 2 entries ]
execution_time: 0.051
