Read a file from the granted folder
readRead files from a granted local folder in byte-bounded slices; follow next_offset to retrieve truncated content and get clear refusals for out-of-folder paths.
Instructions
Read a byte-bounded slice of one file from the single folder this server was granted.
Paths are relative to the granted folder, for example Mage/projects/legend.md. Absolute
paths, Windows drive-relative paths such as C:notes, and any path that climbs out with
.. are refused.
Reads are byte-oriented, never character-oriented. offset and limit are byte counts
into the file's UTF-8 encoding. A returned slice may be up to 3 bytes shorter than limit
so that it ends on a whole codepoint.
If the file is longer than the slice, the response says truncated: true and gives
next_offset. Call again with that offset to continue; following next_offset to
exhaustion reconstructs the UTF-8 text byte for byte. This server never returns a silently
shortened file — if content is missing, the response says so.
Every path is validated against the granted folder before anything is opened, and a refusal names the rule that fired rather than pretending the file is absent.
WHAT IS IN SCOPE, since the boundary is a folder and not a file type: EVERY file inside the
granted folder can be requested, including hidden files and directories such as .git,
.env and .ssh. There is no extension filter, no ignore-file support, and no cap on how
much may be read in total. The granted folder is the whole of the restriction.
What comes BACK is text. A requested slice that is not valid UTF-8 is refused with
NOT_TEXT rather than returned with substituted characters — a file that comes back altered
but looks complete is worse than one that is refused. Note this is a property of the BYTES,
not the file extension: a .bin whose contents happen to be valid UTF-8 is returned, and a
.md saved in Latin-1 is refused. Nothing here is a filter on what may be reached.
KNOWN LIMITS of that restriction, stated because a containment claim without them would be false: a hard link created inside the folder can reach a file outside it; a folder or path component swapped after validation may be read instead of the one checked; and some filesystem reparse points are invisible to this runtime and are not detected at all — that last one needs no attacker and can occur in an ordinary cloud-synced folder. This list is what is known, not a proof that nothing else exists.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file, relative to the granted folder. Forward or back slashes both work. | |
| limit | No | Maximum bytes to return. Defaults to 32768, capped at 262144. | |
| offset | No | Byte offset to start at. Defaults to 0. Use the `next_offset` from a truncated response. |