FileSystem

Install

dotnet add package Ansight.Tools.FileSystem --prerelease

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 only read tools are enabled.
• files.push_file, files.copy_file, and files.move_file are write-scoped and require WithReadWriteToolAccess(), WithAllToolAccess(), or a custom write-enabled ToolGuard.
• files.delete_file is delete-scoped and requires WithAllToolAccess() or a custom delete-enabled ToolGuard.
• 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.
• The app SDK also does not read host-local paths directly. For push flows, Ansight Studio and the Ansight host MCP bridge read the host file, encode it, and call the app’s files.push_file tool with contentBase64.
• 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

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"
  }
}

Get File Checksum

Arguments:

• root: optional root alias
• path: required file path
• algorithms: optional comma-separated list of md5, sha1, sha256, sha384, sha512, crc32, or all; defaults to sha256

Returns:

• resolved file metadata
• fileName, fileExtension, mimeType
• sizeBytes, lastModifiedUtc, version
• checksums

Example:

{
  "toolId": "files.get_file_checksum",
  "arguments": {
    "root": "appData",
    "path": "exports/session.json",
    "algorithms": "sha256,crc32"
  }
}

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:

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

Push File

files.push_file writes content into a destination folder under an approved sandbox root. Use contentBase64 for arbitrary files or text for UTF-8 text payloads. Provide exactly one content field.

Arguments:

• root: optional root alias
• directoryPath: required destination folder path relative to the root
• fileName: required destination file name, not a path
• contentBase64: base64-encoded file content
• text: UTF-8 text content
• overwrite: replace an existing destination file
• createDirectory: create the destination folder when missing

Returns:

• resolved destination file metadata
• sizeBytes
• operation
• overwritten
• createdDirectory
• capturedAtUtc

Example:

{
  "toolId": "files.push_file",
  "arguments": {
    "root": "appData",
    "directoryPath": "imports",
    "fileName": "config.json",
    "contentBase64": "eyJkZWJ1ZyI6dHJ1ZX0=",
    "overwrite": true,
    "createDirectory": true
  }
}

Ansight Studio and Host Push Flow

Ansight Studio exposes a host-friendly push flow for files.push_file because the app SDK cannot read files from the host computer. When you select files.push_file in Ansight Studio, the argument template uses localFilePath; Ansight Studio reads that file on the host, encodes it, and sends contentBase64 to the paired app.

Ansight Studio argument template:

{
  "localFilePath": "/Users/example/Desktop/config.json",
  "root": "appData",
  "directoryPath": "imports",
  "fileName": "config.json",
  "overwrite": true,
  "createDirectory": true
}

The Ansight host MCP server also exposes ansight_push_file_to_app for external MCP clients. It accepts the same host-local file fields, plus optional sessionId or appId when more than one app session is live.

Example:

{
  "name": "ansight_push_file_to_app",
  "arguments": {
    "localFilePath": "/Users/example/Desktop/config.json",
    "root": "appData",
    "directoryPath": "imports",
    "fileName": "config.json",
    "overwrite": true,
    "createDirectory": true
  }
}

The paired app must have Ansight.Tools.FileSystem registered and must allow write-scoped tools.

Copy File

Arguments:

• root: optional source root alias
• sourcePath: required source file path relative to the source root
• destinationRoot: optional destination root alias
• destinationPath: required destination file path relative to the destination root
• overwrite: replace an existing destination file
• createDirectory: create the destination folder when missing

Returns:

• resolved source and destination metadata
• sizeBytes
• operation
• overwritten
• createdDirectory
• capturedAtUtc

Example:

{
  "toolId": "files.copy_file",
  "arguments": {
    "root": "appData",
    "sourcePath": "imports/config.json",
    "destinationRoot": "cache",
    "destinationPath": "debug/config-copy.json",
    "overwrite": true,
    "createDirectory": true
  }
}

Move File

Arguments:

• root: optional source root alias
• sourcePath: required source file path relative to the source root
• destinationRoot: optional destination root alias
• destinationPath: required destination file path relative to the destination root
• overwrite: replace an existing destination file
• createDirectory: create the destination folder when missing

Returns:

• resolved source and destination metadata
• sizeBytes
• operation
• overwritten
• createdDirectory
• capturedAtUtc

Example:

{
  "toolId": "files.move_file",
  "arguments": {
    "root": "appData",
    "sourcePath": "imports/config.json",
    "destinationPath": "imports/config.active.json",
    "overwrite": true,
    "createDirectory": false
  }
}

Delete File

Arguments:

• root: optional root alias
• path: required file path relative to the root

Returns:

• resolved deleted file metadata
• deleted
• capturedAtUtc

Example:

{
  "toolId": "files.delete_file",
  "arguments": {
    "root": "cache",
    "path": "debug/config-copy.json"
  }
}