Sasha MCP reference

listAppFiles

List the source files of a Sasha App you manage

List every source file in the app package with its byte size and version, plus the package status. The result carries status: when status.ok is false the app is NOT usable until the listed diagnostics are fixed. Each names the package file, the line when known, the error code and a reason token. Fix the file and check again; the app is live as soon as it validates.

Arguments

ArgumentTypeRequiredDescription
appstringrequiredThe app id (lowercase kebab-case), as shown by open_app__<id> or listAppFiles.

Scopes

apps:invoke, apps:write

Annotations

  • Read only: yes
  • Destructive: no

When to use

Call listAppFiles before you change a Sasha App. It shows the files in the app package and tells you whether the app validates now.

The six app source tools (listAppFiles, readAppFile, writeAppFile, editAppFile, deleteAppFile and checkApp) all need three things:

  • The connection holds both apps:invoke and apps:write. Only admin and staff can hold apps:write, so a member's connection never has these tools.
  • The person who connected is an admin or staff user.
  • That person has manage access on the app. When Sasha first finds an app, it gives manage to each admin and staff user who exists at that moment. A user added later needs a grant. An admin can narrow a grant later.

The app argument is the app id in lowercase kebab-case, for example timesheet or expense-claims. The app's opener tool uses the same id with _ for -: the app expense-claims opens with open_app__expense_claims. The source tools take the id, not a tool name. An app that breaks after Sasha has seen it loses its opener tool, but the source tools still work on it, so you can use them to repair the app. A package that has never validated has no access grants yet, so it answers APP_ACCESS_DENIED.

The result has these fields:

  • files lists each regular file in the package, sorted by path, with path, bytes, version and editable. Files and folders whose name starts with . are not listed, and neither are symbolic links or paths with more than four segments.
  • version is a 64-character hex value for the exact bytes of the file. Pass it as expectedVersion to writeAppFile, editAppFile or deleteAppFile. It is null only for a file larger than 1 MiB.
  • editable is false for a file that the write tools refuse, for example a file type that is not allowed or a file larger than 1 MiB.
  • status.ok is true when the app validates. Then status.revision is the live revision.
  • When status.ok is false, the app cannot be used until you fix each entry in status.diagnostics. Each entry has file, line when it is known, code and reason. status.revision can be null.

The text part of the result lists the same files, one per line, and ends with a sentence that says whether the app validates.

Example

{ "app": "timesheet" }

The structured result (structuredContent):

{
  "app": "timesheet",
  "files": [
    { "path": "APP.md", "bytes": 912, "version": "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb", "editable": true },
    { "path": "actions/log-hours.action.yaml", "bytes": 640, "version": "3e23e8160039594a33894f6564e1b1348bbd7a0088d42c4acb73eeaed59c009d", "editable": true },
    { "path": "app.js", "bytes": 4210, "version": "2e7d2c03a9507ae265ecf5b5356885a53393a2029d241394997265a1a25aefc6", "editable": true },
    { "path": "index.html", "bytes": 1388, "version": "18ac3e7343f016890c510e93f935261169d9e3f565436429830faf0934f4f8e4", "editable": true },
    { "path": "migrations/001-create-entries.sql", "bytes": 199, "version": "3f79bb7b435b05321651daefd374cdc681dc06faa65e374e38337b88ca046dea", "editable": true },
    { "path": "schema.sql", "bytes": 199, "version": "3f79bb7b435b05321651daefd374cdc681dc06faa65e374e38337b88ca046dea", "editable": true }
  ],
  "status": {
    "ok": true,
    "revision": "252f10c83610ebca1a059c0bae8255eba2f95be4d1d7bcfa89d7248a82d9f111",
    "diagnostics": []
  }
}

Refusals and what to do

An app source tool refuses with an error result. The text is the error message, and structuredContent.error holds code, message, retryable and a diagnosticId to quote when you report a problem.

  • APP_ACCESS_DENIED (app_access_denied): this person does not have manage access on the app (use access is not enough), or is not an admin or staff user. An app id that does not exist gets the same answer. Check the id with the app's open_app__<app> tool name, or ask an admin for manage access.
  • APP_INPUT_INVALID (app_input_invalid): the arguments do not match the schema, for example an app that is not lowercase kebab-case or an extra argument. Send only app.
  • APP_NOT_READY (app_not_ready): the app source service is not available on this instance. Report it with suggestImprovement.
  • 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 listAppFiles not found. Read the permissions section of getDocs. A scope is never added to an existing connection: the person must reconnect, or mint a new token, with apps:write. Only admin and staff can hold it.
  • A status.ok of false is not a refusal. It describes the package. Read the diagnostics, fix the named file, then call checkApp.

Related

  • readAppFile reads one file and returns its version.
  • writeAppFile, editAppFile and deleteAppFile change files.
  • checkApp validates the package again.
  • The open-app family opens the app.
  • getDocs has an apps-authoring section with the full authoring loop.
made with bernard

Cookie settings