FileSystem

Register the file-system tool suite to list sandbox roots, read files, and download sandboxed content from a paired .NET app.

Install

dotnet add package Ansight.Tools.FileSystem

Register the Suite

using Ansight;
using Ansight.Tools.FileSystem;

var options = Options.CreateBuilder()
    .WithFileSystemTools(fileSystem =>
    {
        fileSystem.AddRoot("logs", "/absolute/path/to/logs");
    })
    .WithReadOnlyToolAccess()
    .Build();

Registration API

WithFileSystemTools(): registers the suite with the default sandbox roots only.
WithFileSystemTools(fileSystem => ...): configures additional tagged roots.
AddRoot(tag, path): exposes an extra sandboxed directory under a stable root alias.

Specific Concerns

All access is constrained to approved sandbox roots.
The suite exposes file contents, so it is sensitive even when it is read-only.
files.begin_binary_download is the preferred path when the caller can consume binary WebSocket frames.
The app SDK does not choose the local temp file path for files.begin_binary_download; the consuming bridge owns that path and maps it by transferId.
files.download_file remains available as a JSON fallback for chunked text or base64 transfers.

Default roots:

Android: appData, cache, temp
iOS and Mac Catalyst: appData, documents, cache, temp
Additional roots can be tagged with AddRoot(tag, path)

Tool Matrix

Name	Id	Scope	Description	Security
`List Directory`	`files.list_directory`	`Read`	Lists files and folders inside the app sandbox.	Moderate
`Read File`	`files.read_file`	`Read`	Reads a file from the app sandbox using a constrained path.	High
`Download File`	`files.download_file`	`Read`	Downloads a sandboxed file in resumable chunks with text or base64 payloads.	High
`Begin Binary Download`	`files.begin_binary_download`	`Read`	Starts a binary WebSocket download for a sandboxed file.	High

List Directory

Arguments:

root: optional root alias
path: optional relative directory path
includeHidden
recursive
maxDepth
maxEntries

Returns:

resolved root and directory metadata
availableRoots
entries
truncated
capturedAtUtc

Example:

{
  "toolId": "files.list_directory",
  "arguments": {
    "root": "appData",
    "path": "databases",
    "recursive": true,
    "maxDepth": 2,
    "maxEntries": 200
  }
}

Read File

Arguments:

root: optional root alias
path: required file path
maxBytes
encoding: auto, utf8, or base64

Returns:

resolved file metadata
bytesRead
truncated
contentType
encoding
text or base64

Example:

{
  "toolId": "files.read_file",
  "arguments": {
    "root": "logs",
    "path": "latest.log",
    "maxBytes": 65536,
    "encoding": "utf8"
  }
}

Download File

Arguments:

root: optional root alias
path: required file path
offsetBytes
maxBytes
encoding: auto, utf8, or base64
expectedVersion

Returns:

chunk metadata
fileName, fileExtension, mimeType
sizeBytes, lastModifiedUtc, version
hasMore
nextOffsetBytes
nextRequest
encoded chunk content

Example:

{
  "toolId": "files.download_file",
  "arguments": {
    "root": "appData",
    "path": "exports/session.json",
    "offsetBytes": 0,
    "maxBytes": 262144,
    "encoding": "utf8"
  }
}

Begin Binary Download

Arguments:

root: optional root alias
path: required file path
chunkBytes
downloadId: optional caller correlation id

Returns:

resolved file metadata
downloadId
transferId
fileName, fileExtension, mimeType
sizeBytes, lastModifiedUtc, version
deliveryMode = websocket_binary
wireProtocol = ansight.file-transfer.v1
status
chunkBytes

Example:

{
  "toolId": "files.begin_binary_download",
  "arguments": {
    "root": "appData",
    "path": "exports/archive.zip",
    "chunkBytes": 65536,
    "downloadId": "session-archive"
  }
}

Binary Download Notes

For files.begin_binary_download, the host-side MCP bridge is expected to:

choose the local temp file path
call files.begin_binary_download
map transferId to that file
write incoming ASFT binary frames until completion