Sasha MCP reference

readAppFile

Read one source file of a Sasha App you manage

Return the full text of one package file and its version. Pass that version as expectedVersion to editAppFile, writeAppFile or deleteAppFile.

Arguments

Scopes

apps:invoke, apps:write

Annotations

• Read only: yes
• Destructive: no

When to use

Call readAppFile before you change a file, and before you retry a change that returned an error. Read APP.md first: it declares the app's tables, actions and entry file.

The tool needs the same access as listAppFiles: the scopes apps:invoke and apps:write, an admin or staff user, and manage access on the app.

• path is relative to the package, for example APP.md, index.html, app.js, schema.sql, migrations/002-add-code.sql or actions/log-hours.action.yaml.
• The result is the whole file. There is no paging. A file is at most 1 MiB.
• version is a 64-character hex value for the bytes you read. Pass it as expectedVersion to editAppFile, writeAppFile or deleteAppFile. The change is refused if the file changed after your read.
• The text part of the result is the file content only.

Example

{ "app": "timesheet", "path": "schema.sql" }

The structured result (structuredContent):

{
  "app": "timesheet",
  "path": "schema.sql",
  "content": "CREATE TABLE entries (\n  id INTEGER PRIMARY KEY,\n  created_by INTEGER NOT NULL,\n  date TEXT NOT NULL,\n  project TEXT NOT NULL,\n  hours REAL NOT NULL CHECK (hours > 0 AND hours <= 24),\n  note TEXT\n);\n",
  "version": "3f79bb7b435b05321651daefd374cdc681dc06faa65e374e38337b88ca046dea"
}

Refusals and what to do

The error result's text is the message. structuredContent.error holds code, message, retryable and diagnosticId.

• APP_NOT_FOUND (app_not_found): there is no file at that path. Call listAppFiles and use a path from its result.
• APP_PATH_INVALID (app_path_invalid): the path is not a valid package path, for example it has more than four segments, a segment that starts with ., or ... Use a path from listAppFiles.
• APP_SOURCE_FILE_INVALID: the file type is not one that these tools handle. The allowed extensions are .md, .html, .css, .js, .sql, .yaml, .yml, .json, .txt and .svg.
• APP_RESOURCE_LIMIT (app_resource_limit): the file is larger than 1 MiB, so it cannot be read here.
• APP_ACCESS_DENIED (app_access_denied): this person does not have manage access on the app, or is not an admin or staff user. An app id that does not exist gets the same answer.
• APP_INPUT_INVALID (app_input_invalid): the arguments do not match the schema. Send only app and path.
• If the connection does not hold both apps:invoke and apps:write, the tool is not in your tool list, and a call to it returns MCP error -32602: Tool readAppFile not found. Read the permissions section of getDocs. The person must reconnect, or mint a new token, with apps:write. Only admin and staff can hold it.

Related

• listAppFiles lists the paths and the package status.
• editAppFile changes one passage, and writeAppFile replaces the whole file. Both take the version from this tool as expectedVersion.
• deleteAppFile removes a file.
• checkApp validates the package.