---
name: skape
description: Understand and build Skape experiences (location-based audio and interactive screens) through the Skape MCP server. Use when a user mentions Skape, an audio walk, a soundscape, blueprints, geo-triggered audio, or asks to explore or edit a Skape project.
---

# Skape

Skape is a tool for making experiences that run on a phone outdoors: audio walks, sound installations and interactive maps where what the listener hears and sees depends on where they are and what they do. A Skape project is a document you read and edit through the Skape MCP server at https://skap.es/mcp. You never edit files; every change is a tool call that the user has authorized.

## Vocabulary

Use these words exactly. They match what the user sees in the editor.

- **Team**: owns projects and audio. A connection is approved per team.
- **Project**: one experience. It has a map with features, blueprints with nodes, screens with elements, and assets.
- **Feature**: something on the map. A GeoJSON point, polygon or line, or an image placed over the map, optionally inside a group. Features carry a name and a color. Nodes reference features by id to react to the listener's position.
- **Asset**: an uploaded file: audio, an image or a video. Nodes and image features reference assets by id.
- **Blueprint**: a graph of nodes and edges. Each screen names the blueprint that runs while it is open; a project can have several, and a blueprint can be instantiated as a node inside another.
- **Node**: an instance of a handler inside a blueprint, with a position on the canvas. Each node has input and output ports.
- **Handler**: a code-defined node type with a versioned id such as `audio-player@v1`. The handler decides the node's ports. Read the catalog with `scapes_list_handlers` or the resource `scapes://handlers/catalog`; one handler's full schema is `scapes://handlers/<handler-id>/schema`.
- **Port**: a named input or output on a node. Inputs take either an edge or a literal value (a node property). Some inputs accept several edges (multi capacity), most accept one.
- **Edge**: a connection from an output port to an input port. Values flow along edges reactively: when an output changes, dependent nodes recompute.
- **Node property**: a literal value set on an input port instead of an edge, for example an asset id, a feature id, a number or an enum.
- **Screen**: a page of the phone app, built from elements (stacks, scroll areas, text, images, video and component instances; any of them can carry a click workflow). The entry screen is the one the published app opens on.
- **Element**: a node in a screen's layout tree. Its fields can be expressions that read engine outputs and state.
- **Publish**: compiles the saved project into a release the phone app loads. Publishing is the user's action in the editor; the MCP server does not publish.

## How the graph works

Everything the listener experiences is a signal path through nodes.

- `user-location@v1` is the device's GPS. It is a source node: no inputs, emits `coordinate` and `heading`.
- `geo-coordinate@v1` reads a point feature's coordinate. It needs a feature input. Do not confuse it with `user-location@v1`.
- `geo-sampler@v1` takes a coordinate and a polygon feature and emits a level: full inside the polygon, fading across the polygon's soft edge, silent outside. It usually drives a player's volume.
- `audio-player@v1` plays an asset, and only while its `play` input is true. With `behaviour` `sync` it loops in phase with the other players in its `group`; the default plays the clip once. Its volume input usually comes from a sampler. It outputs an audio node.
- `audio-destination@v1` is the speaker. Every audible chain ends in it. It is a terminal sink.

A minimal audio walk is one path: user location, a sampler over a polygon, a player with an asset, the destination. Several stems are several sampler and player pairs fanning out from the same location node and fanning in to the same destination.

## Working through the MCP tools

The server is the only way to read or change a project. Read before you build, and carry the revisions it gives you.

1. **Orient.** `scapes_list_teams` and `scapes_list_projects` show what you may touch. Ask the user which project if more than one fits.
2. **Load.** `scapes_load_project` returns the project plus an `editContextId`, `contextRevision` and `documentRevision`. Document edits need those and an `idempotencyKey`; project creation and deletion use their own listed controls. If a write reports a stale revision, call `scapes_refresh_project` and continue from its values. Never retry old history.
3. **Understand.** `scapes_describe_state` gives counts, blueprints, nodes, edges and node properties in one call. Go deeper with `scapes_inspect_blueprint`, `scapes_inspect_node`, `scapes_inspect_feature` and `scapes_inspect_element`. `scapes_search` finds nodes and blueprints by name, handler or id. `scapes_list_assets` lists the project's assets (audio, images, video). `scapes_show_map` and `scapes_show_screen` render previews the user can see.
4. **Explain.** When the user asks how something works, follow the edges from `user-location@v1` to `audio-destination@v1` and describe each node in the user's words: which area, which sound, what controls the volume.
5. **Build.** Small edits use one tool each: `scapes_add_node`, `scapes_update_node_property`, `scapes_connect_ports`, `scapes_disconnect_ports`, `scapes_move_node`, `scapes_rename_node`, `scapes_duplicate_node`, `scapes_delete_node`, and `scapes_create_feature`, `scapes_update_feature`, `scapes_delete_feature` for the map. Reset a stored value with `scapes_delete_node_property`; organize map layers with `scapes_group_features` and `scapes_ungroup_features`. Saved designs use `scapes_create_elements`, `scapes_update_elements`, `scapes_delete_elements`, `scapes_duplicate_element` and `scapes_detach_instances`. Each call is its own undo step; create, update and delete element tools can handle several elements of that operation together.
6. **Idempotency.** Every write takes an `idempotencyKey`. Use a fresh key for each new change and the same key only when retrying the identical call after a network failure.
7. **Undo.** `scapes_undo` and `scapes_redo` work on your own edit context. Use undo when a step produced something other than what you intended, instead of patching around it.

When creating a screen subtree in one call, supply caller-minted UUIDs for new parents referenced by children; otherwise omit element ids and let the server mint them. Elements can be supplied in any order. Detachment preserves stateless components with literal props or direct value bindings and saved click actions. Components with local state and expressions that need their component scope must stay linked.

### Access

A connection is read-only or read and build. With read-only access a write is refused with an authorization error, and most hosts then ask the user to approve read and build access in Skape. If yours does not, ask the user to reconnect Skape in this app and choose Read & build. After re-authorizing, call `scapes_load_project` again before writing: the new connection needs a new `editContextId`. Your host's own tool-approval settings do not change what Skape allows.

### Before you change anything

- Describe the intended change and project. Act within the user's authorized task, and use the host's confirmation prompts for destructive actions.
- Use ids from the tools, never ids you guessed. Handler ids come from `scapes_list_handlers` or the catalog resource.
- Check the handler's ports before connecting: output to input, matching types, capacity respected. The server rejects invalid edges; read the error and fix the shape rather than retrying blindly.
- Deleting a node removes its edges and properties. Deleting a feature leaves nodes that referenced it without a target. Confirm deletions.
- Place new nodes near the nodes they connect to so the user's canvas stays readable.

## Worked examples

**Explain an experience.** Load the project. Describe state. For each `audio-player@v1`, inspect the node, follow its volume input back to the sampler and its polygon feature, and report: "Near the fountain (polygon 'Fountain'), 'stem-3.mp3' fades in as you walk into the area." End with how many areas and sounds there are and which screen the app opens on.

**Add a sound area.** Confirm the asset and the location with the user. Create a polygon feature with `scapes_create_feature`, or ask the user to draw it with `scapes_show_map` and confirm. Use `scapes_add_node` to add a `geo-sampler@v1` and an `audio-player@v1`, use `scapes_update_node_property` to set the sampler's `feature` and the player's `asset` as node properties, set the player's `play` to true and copy `behaviour` and `group` from the walk's existing players (a player without `play` stays silent), use `scapes_connect_ports` to connect the existing `user-location@v1` output `coordinate` to the sampler's input `coordinate`, the sampler's output `value` to the player's input `volume`, and the player's output `node` to the existing `audio-destination@v1` input `nodes`. Carry the returned revisions from each change into the next, and report the feature, nodes, file and connections created. Undo reverses one call at a time.

**Rename and tidy.** The user says node names are confusing. Describe state, propose a naming scheme that uses the feature or asset name, confirm, then `scapes_rename_node` each one and `scapes_move_node` to line up each sampler above its player.

## What this document does not cover

Handler-specific ports and ranges, which `scapes_list_handlers` and `scapes://handlers/catalog` provide; screen layout and expression syntax in depth, which `scapes_inspect_element` and `scapes_show_screen` expose on demand; and publishing, billing and team membership, which stay in the Skape web app.