# This file is automatically generated by ravepipeline::mcptool_build(). 
# Please never edit this file by hand!
name: ieegio-mcp_tool_surface_discover
description: Search a directory for neuroimaging surface files (GIfTI, STL, and FreeSurfer
  formats). Returns a list of found files with basic metadata including file paths.
  Useful for discovering available surface files before reading them with ieegio-mcp_tool_surface_read.
parameters:
  type: object
  properties:
    pattern:
      type: string
      description: 'Optional filename pattern to filter results. Empty string (default)
        returns all surface files. Otherwise, only files whose basename matches the
        pattern are included. Example values: "lh", "pial", "white", ""'
      default: ''
      examples:
      - lh
      - pial
      - white
    recursive:
      type: boolean
      description: 'Whether to search subdirectories recursively. Defaults to TRUE.
        Example values: TRUE, FALSE'
      default: yes
      examples:
      - 'TRUE'
      - 'FALSE'
    path:
      type: string
      description: 'Absolute or relative path to the directory to search. Example
        values: "/data/subjects/fs/surf", "~/imaging/surfaces"'
      examples:
      - /data/subjects/fs/surf
      - ~/imaging/surfaces
  required:
  - path
category: discovery
returns:
  type: object
  properties:
    error:
      type: string
      description: Character, error message if success is FALSE
    files:
      type: array
      description: Character vector, relative file paths
      items:
        type: string
    count:
      type: integer
      description: Integer, number of surface files found
    success:
      type: boolean
      description: Logical, whether the search completed successfully
implementation_example: |
  # Discover all surface files in sample data directory
  sample_dir <- dirname(ieegio_sample_data("gifti/GzipBase64/sujet01_Lwhite.surf.gii"))
  ieegio:::mcp_tool_surface_discover(sample_dir)
  # Search with a filename pattern
  ieegio:::mcp_tool_surface_discover(sample_dir, pattern = "shape")
  #
  #> $success
  #> [1] TRUE
  #> 
  #> $count
  #> [1] 1
  #> 
  #> $files
  #> [1] "sujet01_Lwhite.shape.gii"
  #>
execution_time: 0.011
