Get App Source
MCP contract for get_app_source.
MCP name: get_app_source
Tool contract
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true,
"title": "Get App Source"
},
"description": "Return an app's stored source: the package tree as `source.files`, with `source.module`, `source.ui`, and `source.styles` mirroring server.js, ui.js, and styles.css, each mirrored bucket's size in characters (`sourceSize`), and the current revision for optimistic-concurrency edits. Pass that revision through update_app's `expected_revision` input. Use this when you need the source to inspect, debug, or edit an app the caller owns. Without `bucket`, the whole source comes back in `source`. When the source is too large for your client (check `sourceSize`), read one bucket at a time instead: `bucket` returns up to 20000 characters of whole lines in `chunk`; pass `chunk.next_offset` as `offset` until it is null, and pass `expected_revision` on each page so every page comes from one revision.",
"execution": {
"taskSupport": "forbidden"
},
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"app_id": {
"description": "The app ID (UUID)",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"bucket": {
"description": "Read one source bucket in chunks of up to 20000 characters instead of the whole source. Use it when the whole source is too large for your client. An absent bucket reads as empty text.",
"enum": [
"module",
"ui",
"styles"
],
"type": "string"
},
"expected_revision": {
"description": "Revision from your first read. The read fails with revision_mismatch if the app has changed since, so paged chunks all come from one revision.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"offset": {
"description": "Character offset into `bucket`, from the prior read's `chunk.next_offset`. Defaults to 0. Requires `bucket`.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"app_id"
],
"type": "object"
},
"name": "get_app_source",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"$schema": {
"description": "Exact manifest schema URL. Omitted for legacy apps.",
"type": "string"
},
"activeRevision": {
"description": "The revision visitors are served. Equal to `revision` once the latest save is live. When lower, the source in this response is not live yet; `build` says why. While `build.state` is queued, resolving, building, or validating, wait for it to finish. When it is failed or expired, read `build.error`, then fix that save and save again, or restore the active revision. When it is canceled, save again to build it, or restore the active revision. When it is superseded, read the source again. When `build` is null, the App was saved before packages and Charming stored that save without validating it because the executor was unavailable: save it again to validate and publish it. `activeRevision` and `build` are read separately, so a build that publishes between them can show a lower `activeRevision` with `build.state` published; the next read agrees.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"advisories": {
"description": "Structured non-fatal advisories, including authoring issues and unread staff feedback responses. Each advisory.summary is also appended to the text content for the LLM path.",
"items": {
"additionalProperties": false,
"properties": {
"data": {
"additionalProperties": {},
"description": "Kind-specific structured payload. Shape varies per advisory kind.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"doc_url": {
"description": "Optional docs pointer for this advisory kind.",
"type": "string"
},
"kind": {
"description": "Stable advisory identifier (e.g. \"legacy-bridge\").",
"type": "string"
},
"severity": {
"description": "Severity; omitted advisories are treated as 'info'.",
"enum": [
"info",
"warn"
],
"type": "string"
},
"summary": {
"description": "Agent-facing summary. Self-sufficient; no extra context required.",
"type": "string"
},
"userSummary": {
"description": "End-user-facing summary. Set when the advisory should render in-app.",
"type": "string"
}
},
"required": [
"kind",
"summary"
],
"type": "object"
},
"type": "array"
},
"appVersion": {
"description": "Canonical apps return decimal String(revision). Legacy apps return their stored effective SemVer.",
"type": "string"
},
"build": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"buildId": {
"description": "Build ID. Pass it to get_app_build for the full status.",
"type": "string"
},
"error": {
"additionalProperties": false,
"description": "Why the build ended without publishing. Present when it failed or expired.",
"properties": {
"column": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"details": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"execution": {
"enum": [
"not_started",
"may_have_run"
],
"type": "string"
},
"operationId": {
"minLength": 1,
"type": "string"
},
"reservationId": {
"minLength": 1,
"type": "string"
}
},
"required": [
"execution",
"operationId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"execution": {
"const": "may_have_run",
"type": "string"
}
},
"required": [
"execution"
],
"type": "object"
}
]
},
"kind": {
"type": "string"
},
"line": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"specifier": {
"type": "string"
},
"target": {
"type": "string"
}
},
"required": [
"kind",
"message",
"retryable"
],
"type": "object"
},
"state": {
"enum": [
"queued",
"resolving",
"building",
"validating",
"published",
"failed",
"superseded",
"canceled",
"expired"
],
"type": "string"
},
"statusUrl": {
"description": "Authenticated HTTP status URL for this build.",
"type": "string"
}
},
"required": [
"buildId",
"state",
"statusUrl"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "The build a save accepted for `revision`. Null when no build is recorded against this revision: a save made before packages, a revision that a create, copy, or migration published, or a live revision whose build record has expired. The build behind a revision that is not live yet is kept until a later save or publish."
},
"capabilities": {
"additionalProperties": false,
"description": "Capability declarations parsed from the app manifest.",
"properties": {
"connectOrigins": {
"description": "Exact https and wss origins injected into the app CSP connect-src so browser fetch, WebSocket, and EventSource can reach them (e.g. [\"https://api.example.com\", \"wss://stream.example.com\"]). Omitted when the app declares none.",
"items": {
"type": "string"
},
"type": "array"
},
"exports": {
"description": "WIT-style capability ids the app exposes for cross-app calls.",
"items": {
"type": "string"
},
"type": "array"
},
"frameHosts": {
"description": "External https origins the app may embed, added to the app CSP frame-src (e.g. [\"https://www.youtube.com\"]). Omitted when the app declares none.",
"items": {
"type": "string"
},
"type": "array"
},
"imageHosts": {
"description": "External https image hosts injected into the app CSP img-src (e.g. [\"covers.openlibrary.org\"]). Omitted when the app declares none.",
"items": {
"type": "string"
},
"type": "array"
},
"imports": {
"description": "WIT-style capability ids the app requests (e.g. \"charming:storage/[email protected]\"). Empty if the app declares none.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"imports",
"exports"
],
"type": "object"
},
"chunk": {
"additionalProperties": false,
"description": "Present only when `bucket` was requested.",
"properties": {
"bucket": {
"description": "The bucket this chunk was read from.",
"enum": [
"module",
"ui",
"styles"
],
"type": "string"
},
"next_offset": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Offset for the next read of this bucket. Null when this chunk reaches the end."
},
"offset": {
"description": "Character offset where this chunk starts.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"text": {
"description": "Up to 20000 characters of the bucket, ending on a line boundary when the window holds one. Empty for an absent bucket.",
"type": "string"
}
},
"required": [
"bucket",
"offset",
"text",
"next_offset"
],
"type": "object"
},
"claimed": {
"description": "True if the app is owned by an authenticated account. False for anonymous apps still in the unclaimed grace window.",
"type": "boolean"
},
"description": {
"description": "Search-friendly summary set by the creating agent. Null on apps created before descriptions existed.",
"type": [
"string",
"null"
]
},
"displayName": {
"description": "Human-readable name from the manifest.",
"type": "string"
},
"expiresAt": {
"description": "ISO timestamp when an unclaimed app will be hard-deleted. Null for claimed apps.",
"type": [
"string",
"null"
]
},
"id": {
"description": "UUID of the inspected app.",
"type": "string"
},
"manifestId": {
"description": "Effective manifest id. May differ from `sourceManifestId` when a conflicting id was rewritten on save.",
"type": "string"
},
"manifestVersion": {
"description": "Deprecated public contract marker. Canonical apps return null; legacy apps return their stored contract date.",
"type": [
"string",
"null"
]
},
"ok": {
"const": true,
"description": "Indicates success. Errors arrive as content with isError:true.",
"type": "boolean"
},
"revision": {
"description": "The latest saved revision: the source returned here. Pass it as `expected_revision` to update_app. A save is stored before it goes live, so this can be ahead of `activeRevision`.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"source": {
"additionalProperties": false,
"description": "Persisted source bundle. The same fields accepted by create_app/update_app. Present unless `bucket` was requested; a bucket read returns `chunk` instead.",
"properties": {
"files": {
"additionalProperties": {
"type": "string"
},
"description": "The authored tree of a package App: package.json, server.js, and every file they import. module, ui, and styles mirror server.js, ui.js, and styles.css.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"module": {
"description": "Backend ES module source.",
"type": "string"
},
"styles": {
"description": "Optional CSS for the rendered app. Null if not set.",
"type": [
"string",
"null"
]
},
"ui": {
"description": "Frontend JavaScript rendered into the #app mount point. Null if not set.",
"type": [
"string",
"null"
]
}
},
"required": [
"module",
"ui",
"styles"
],
"type": "object"
},
"sourceManifestId": {
"description": "Manifest id as authored in the persisted module source.",
"type": "string"
},
"sourceSize": {
"additionalProperties": false,
"description": "Length of each source bucket in characters.",
"properties": {
"module": {
"description": "Characters in the module.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"styles": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Characters in the styles. Null if not set."
},
"ui": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
{
"type": "null"
}
],
"description": "Characters in the ui script. Null if not set."
}
},
"required": [
"module",
"ui",
"styles"
],
"type": "object"
},
"url": {
"description": "Public app URL without an access token, built from the OWNER's handle when available (friendly form) and the UUID form otherwise. Safe to show the user. Browsers open via session cookie; agents should call get_app to mint a per-app token for write access.",
"type": "string"
}
},
"required": [
"ok",
"id",
"url",
"manifestId",
"sourceManifestId",
"displayName",
"description",
"revision",
"activeRevision",
"build",
"appVersion",
"manifestVersion",
"capabilities",
"claimed",
"expiresAt",
"sourceSize"
],
"type": "object"
}
}