# This file is automatically generated by ravepipeline::mcptool_build(). 
# Please never edit this file by hand!
name: ieegio-mcp_tool_surface_write
description: 'Write a previously cached surface (identified by its digest ID) to a
  temporary file. The surface is retrieved from session state and written in the specified
  format. A temporary file is created using format-specific naming: geometry data
  uses {id.{ext}}, other data types use {id__{type}.{ext}}. Format-specific extensions:
  \itemize{ \item GIfTI (.gii): Supports all data types \item STL (.stl): Only geometry
  supported \item FreeSurfer: geometry (no extension), annotations (.annot), measurements
  (.curv) }'
parameters:
  type: object
  properties:
    type:
      type: string
      description: 'Data type to write: "geometry", "annotations", "measurements",
        "color", or "time_series". Defaults to "geometry". Each call writes one type;
        make separate calls for multiple types. Example values: "geometry", "annotations",
        "measurements"'
      default: geometry
      examples:
      - geometry
      - annotations
      - measurements
    format:
      type: string
      description: 'Output file format. Must be "gifti", "stl", or "freesurfer". Defaults
        to "gifti". Example values: "gifti", "stl", "freesurfer"'
      enum:
      - gifti
      - stl
      - freesurfer
      default: gifti
      examples:
      - gifti
      - stl
      - freesurfer
    id:
      type: string
      description: 'The digest-based identifier of the cached surface. This ID is
        returned by ieegio-mcp_tool_surface_read. Example values: "a3f5e8d9c1b2",
        "f7e4b2a1c6d8"'
      examples:
      - a3f5e8d9c1b2
      - f7e4b2a1c6d8
  required:
  - id
category: execution
returns:
  type: object
  properties:
    error:
      type: string
      description: Character, error message if success is FALSE
    output_path:
      type: string
      description: Character, absolute path to the temporary file
    id:
      type: string
      description: Character, the surface identifier that was written
    success:
      type: boolean
      description: Logical, whether the surface was successfully written
implementation_example: |
  # Read a surface, then write it to a temporary file
  # Note: .state_env is automatically provided when called via MCP.
  # AI does not need to specify this argument. The examples only use
  # .state_env to make the code runnable for demonstration purposes.
  sample_file <- ieegio_sample_data("gifti/GzipBase64/sujet01_Lwhite.surf.gii")
  state_env <- fastmap::fastmap()
  read_result <- ieegio:::mcp_tool_surface_read(sample_file, .state_env = state_env)
  # Write to temporary file
  ieegio:::mcp_tool_surface_write(
    id = read_result$id,
    .state_env = state_env
  )
  #
  #> $success
  #> [1] TRUE
  #> 
  #> $id
  #> [1] "87405ad0bc7df5262dadebee27bf4c3b"
  #> 
  #> $output_path
  #> [1] "/private/var/folders/fm/6y447x213qxc2z95klwj20h40000gn/T/RtmpnCnMgT/ieegio/87405ad0bc7df5262dadebee27bf4c3b.gii"
  #>
execution_time: 0.267
