> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations: stories

> The story builder: nodes, links, references and sharing. For each operation: what it does, whether it asks you first, its inputs and an example call.

The story builder: nodes, links, references and sharing. 12 operations. How to call them, and what the answers mean: [Operations reference](https://docs.summerengine.com/mcp/operations.md).

> [!NOTE]
>
> Generated from the `summer-engine` npm package `4.8.0`: its public operation catalog (`registry/operations/public-catalog.json`) and its engine and local operations. If something here is wrong, the operation's definition is wrong.

| Operation | What it does | Asks you first |
| - | - | - |
| [`stories.add_reference`](#add_reference) | Add a new reference (a picture, a link, a note) to a story node: it joins the workspace's references and is attached to the node. | Not by default |
| [`stories.archive_node`](#archive_node) | Ask the person to archive a story node: it leaves the story builder for everyone in the workspace. | Yes, by default |
| [`stories.attach_reference`](#attach_reference) | Attach one of the workspace's existing references to a story node. | Not by default |
| [`stories.create_node`](#create_node) | Create a story node in a workspace: a world, character, place, faction, arc, quest or scene, with its title and optional text and tags. | Not by default |
| [`stories.detach_reference`](#detach_reference) | Ask the person to detach a reference from a story node (linkId from stories.get references); the reference stays in the workspace. | Yes, by default |
| [`stories.get`](#get) | Read one story node: its text, kind, tags and status, its links to other nodes (with their link ids) and its references (with their link ids). | Never |
| [`stories.link_nodes`](#link_nodes) | Link two story nodes in a workspace (a character to a place, an arc to a quest) with a link type and an optional label. | Not by default |
| [`stories.list`](#list) | List the story builder's nodes in a workspace (world, characters, places, factions, arcs, quests, scenes): id, kind, title, summary and tags. | Never |
| [`stories.save_view`](#save_view) | Save where each story node sits on the graph and its kind filter, as a named view of the workspace (a new one, or viewId to replace one). | Not by default |
| [`stories.share`](#share) | Ask the person to move their story builder content into a team the members see: an existing team (targetWorkspaceId) or a new one (newTeamName). | Not by default |
| [`stories.unlink_nodes`](#unlink_nodes) | Ask the person to remove a link between two story nodes (linkId from stories.get of one of them). | Yes, by default |
| [`stories.update_node`](#update_node) | Change a story node's title, kind, summary, text, status or tags; fields left out stay as they are. | Not by default |

***

### add\_reference

`stories.add_reference`: **Add a reference to a story node**

Add a new reference (a picture, a link, a note) to a story node: it joins the workspace's references and is attached to the node. Returns the reference. Next: stories.get.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.add_reference"` |
| **CLI** | `summer stories add-reference` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | Yes | The workspace (the person's own or a team, from team.list) the story is in. |
| `nodeId` | string | Yes | A story node, from stories.list. |
| `title` | string | Yes | Length 1 to 160. |
| `referenceType` | string | No | image, link, note, audio, video... Default `"image"`. Length 1 to 80. |
| `sourceUrl` | string | No | Length 0 to 2048. |
| `notesMarkdown` | string | No | Length 0 to 20000. |
| `tags` | string\[] | No | Items 0 to 50. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "workspaceId": {
>       "description": "The workspace (the person's own or a team, from team.list) the story is in.",
>       "type": "string",
>       "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)$"
>     },
>     "nodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     },
>     "title": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 160
>     },
>     "referenceType": {
>       "description": "image, link, note, audio, video...",
>       "default": "image",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 80
>     },
>     "sourceUrl": {
>       "type": "string",
>       "maxLength": 2048
>     },
>     "notesMarkdown": {
>       "type": "string",
>       "maxLength": 20000
>     },
>     "tags": {
>       "maxItems": 50,
>       "type": "array",
>       "items": {
>         "type": "string",
>         "minLength": 1,
>         "maxLength": 64
>       }
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "workspaceId",
>     "nodeId",
>     "title"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "reference": {
>       "type": "object",
>       "additionalProperties": {}
>     },
>     "attachment": {
>       "anyOf": [
>         {
>           "type": "object",
>           "additionalProperties": {}
>         },
>         {
>           "type": "null"
>         }
>       ]
>     }
>   },
>   "required": [
>     "reference",
>     "attachment"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Pin a picture to Mira.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.add_reference",
    "input": {
      "workspaceId": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "nodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182",
      "title": "Lantern sketch",
      "sourceUrl": "https://www.summerengine.com/examples/lantern.png"
    }
  }
}
```

```bash CLI theme={null}
summer stories add-reference --workspace-id 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d --node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182 --title 'Lantern sketch' --source-url https://www.summerengine.com/examples/lantern.png
```

***

### archive\_node

`stories.archive_node`: **Archive a story node**

Ask the person to archive a story node: it leaves the story builder for everyone in the workspace. Returns a link; nothing changes until they confirm. Next: jobs.wait.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.archive_node"` |
| **CLI** | `summer stories archive-node` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Removes or stops something for good. |
| **Asks you first** | Yes: **Delete for good** is off by default in Agent permissions. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `nodeId` | string | Yes | A story node, from stories.list. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "nodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "nodeId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "nodeId": {
>       "type": "string"
>     },
>     "archived": {
>       "type": "boolean"
>     }
>   },
>   "required": [
>     "nodeId",
>     "archived"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** A character that was cut.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.archive_node",
    "input": {
      "nodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182"
    }
  }
}
```

```bash CLI theme={null}
summer stories archive-node --node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182
```

***

### attach\_reference

`stories.attach_reference`: **Attach a reference to a story node**

Attach one of the workspace's existing references to a story node. Returns the attachment. Next: stories.get.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.attach_reference"` |
| **CLI** | `summer stories attach-reference` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | Yes | The workspace (the person's own or a team, from team.list) the story is in. |
| `nodeId` | string | Yes | A story node, from stories.list. |
| `referenceId` | string | Yes | A reference of the workspace (stories.get references, or one added with stories.add\_reference). |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "workspaceId": {
>       "description": "The workspace (the person's own or a team, from team.list) the story is in.",
>       "type": "string",
>       "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)$"
>     },
>     "nodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     },
>     "referenceId": {
>       "description": "A reference of the workspace (stories.get references, or one added with stories.add_reference).",
>       "type": "string",
>       "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)$"
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "workspaceId",
>     "nodeId",
>     "referenceId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "attachment": {
>       "type": "object",
>       "additionalProperties": {}
>     }
>   },
>   "required": [
>     "attachment"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Reuse the harbor picture.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.attach_reference",
    "input": {
      "workspaceId": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "nodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182",
      "referenceId": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d"
    }
  }
}
```

```bash CLI theme={null}
summer stories attach-reference --workspace-id 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d --node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182 --reference-id 5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d
```

***

### create\_node

`stories.create_node`: **Create a story node**

Create a story node in a workspace: a world, character, place, faction, arc, quest or scene, with its title and optional text and tags. Returns the node. Next: stories.link\_nodes or stories.add\_reference.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.create_node"` |
| **CLI** | `summer stories create-node` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | Yes | The workspace (the person's own or a team, from team.list) the story is in. |
| `title` | string | Yes | Length 1 to 160. |
| `kind` | string | Yes | world, character, location, faction, arc, quest, scene or reference (or a kind of their own). Length 1 to 64. |
| `summary` | string | No | Length 0 to 1000. |
| `bodyMarkdown` | string | No | Length 0 to 50000. |
| `tags` | string\[] | No | Items 0 to 50. |
| `templateKey` | string | No | A story template the story builder offers. Length 1 to 120. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "workspaceId": {
>       "description": "The workspace (the person's own or a team, from team.list) the story is in.",
>       "type": "string",
>       "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)$"
>     },
>     "title": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 160
>     },
>     "kind": {
>       "description": "world, character, location, faction, arc, quest, scene or reference (or a kind of their own).",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 64
>     },
>     "summary": {
>       "type": "string",
>       "maxLength": 1000
>     },
>     "bodyMarkdown": {
>       "type": "string",
>       "maxLength": 50000
>     },
>     "tags": {
>       "maxItems": 50,
>       "type": "array",
>       "items": {
>         "type": "string",
>         "minLength": 1,
>         "maxLength": 64
>       }
>     },
>     "templateKey": {
>       "description": "A story template the story builder offers.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 120
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "workspaceId",
>     "title",
>     "kind"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "node": {
>       "type": "object",
>       "additionalProperties": {}
>     },
>     "studioUrl": {
>       "type": "string"
>     }
>   },
>   "required": [
>     "node",
>     "studioUrl"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Add a character.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.create_node",
    "input": {
      "workspaceId": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "title": "Mira the lantern keeper",
      "kind": "character"
    }
  }
}
```

```bash CLI theme={null}
summer stories create-node --workspace-id 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d --title 'Mira the lantern keeper' --kind character
```

***

### detach\_reference

`stories.detach_reference`: **Detach a reference from a story node**

Ask the person to detach a reference from a story node (linkId from stories.get references); the reference stays in the workspace. Returns a link; nothing changes until they confirm. Next: jobs.wait.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.detach_reference"` |
| **CLI** | `summer stories detach-reference` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Removes or stops something for good. |
| **Asks you first** | Yes: **Delete for good** is off by default in Agent permissions. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `nodeId` | string | Yes | A story node, from stories.list. |
| `linkId` | string | Yes | The reference's link id, from stories.get references. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "nodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     },
>     "linkId": {
>       "description": "The reference's link id, from stories.get references.",
>       "type": "string",
>       "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)$"
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "nodeId",
>     "linkId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "linkId": {
>       "type": "string"
>     },
>     "detached": {
>       "type": "boolean"
>     }
>   },
>   "required": [
>     "linkId",
>     "detached"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** That picture is not Mira any more.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.detach_reference",
    "input": {
      "nodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182",
      "linkId": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e"
    }
  }
}
```

```bash CLI theme={null}
summer stories detach-reference --node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182 --link-id 6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e
```

***

### get

`stories.get`: **Read a story node**

Read one story node: its text, kind, tags and status, its links to other nodes (with their link ids) and its references (with their link ids). Next: stories.update\_node.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.get"` |
| **CLI** | `summer stories get` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `nodeId` | string | Yes | A story node, from stories.list. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "nodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     }
>   },
>   "required": [
>     "nodeId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "node": {
>       "type": "object",
>       "additionalProperties": {}
>     },
>     "links": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "additionalProperties": {}
>       }
>     },
>     "linkedNodes": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "additionalProperties": {}
>       }
>     },
>     "references": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "additionalProperties": {}
>       }
>     }
>   },
>   "required": [
>     "node",
>     "links",
>     "linkedNodes",
>     "references"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Read the hero's node.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.get",
    "input": {
      "nodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182"
    }
  }
}
```

```bash CLI theme={null}
summer stories get --node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182
```

***

### link\_nodes

`stories.link_nodes`: **Link two story nodes**

Link two story nodes in a workspace (a character to a place, an arc to a quest) with a link type and an optional label. Returns the link. Next: stories.get.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.link_nodes"` |
| **CLI** | `summer stories link-nodes` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | Yes | The workspace (the person's own or a team, from team.list) the story is in. |
| `fromNodeId` | string | Yes | A story node, from stories.list. |
| `toNodeId` | string | Yes | A story node, from stories.list. |
| `edgeType` | string | No | What the link means: relatedTo, memberOf, locatedIn, leadsTo... Default `"relatedTo"`. Length 1 to 80. |
| `label` | string | No | Length 0 to 160. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "workspaceId": {
>       "description": "The workspace (the person's own or a team, from team.list) the story is in.",
>       "type": "string",
>       "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)$"
>     },
>     "fromNodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     },
>     "toNodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     },
>     "edgeType": {
>       "description": "What the link means: relatedTo, memberOf, locatedIn, leadsTo...",
>       "default": "relatedTo",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 80
>     },
>     "label": {
>       "type": "string",
>       "maxLength": 160
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "workspaceId",
>     "fromNodeId",
>     "toNodeId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "link": {
>       "type": "object",
>       "additionalProperties": {}
>     }
>   },
>   "required": [
>     "link"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Mira lives in the harbor.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.link_nodes",
    "input": {
      "workspaceId": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "fromNodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182",
      "toNodeId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "edgeType": "locatedIn"
    }
  }
}
```

```bash CLI theme={null}
summer stories link-nodes --workspace-id 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d --from-node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182 --to-node-id 7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d --edge-type locatedIn
```

***

### list

`stories.list`: **List story nodes**

List the story builder's nodes in a workspace (world, characters, places, factions, arcs, quests, scenes): id, kind, title, summary and tags. Filter by kind or words. Next: stories.get with a nodeId.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.list"` |
| **CLI** | `summer stories list` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Reads only. Changes nothing. |
| **Asks you first** | No. It changes nothing. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | Yes | The workspace (the person's own or a team, from team.list) the story is in. |
| `kind` | string | No | Only one kind: world, character, location, faction, arc, quest, scene, reference. Length 1 to 64. |
| `search` | string | No | Words to find in titles and text. Length 0 to 200. |
| `limit` | integer | No | Default `10`. Range 1 to 50. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "workspaceId": {
>       "description": "The workspace (the person's own or a team, from team.list) the story is in.",
>       "type": "string",
>       "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)$"
>     },
>     "kind": {
>       "description": "Only one kind: world, character, location, faction, arc, quest, scene, reference.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 64
>     },
>     "search": {
>       "description": "Words to find in titles and text.",
>       "type": "string",
>       "maxLength": 200
>     },
>     "limit": {
>       "default": 10,
>       "type": "integer",
>       "minimum": 1,
>       "maximum": 50
>     }
>   },
>   "required": [
>     "workspaceId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "items": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "additionalProperties": {}
>       }
>     },
>     "studioUrl": {
>       "type": "string"
>     }
>   },
>   "required": [
>     "items",
>     "studioUrl"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Who are the characters?

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.list",
    "input": {
      "workspaceId": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "kind": "character"
    }
  }
}
```

```bash CLI theme={null}
summer stories list --workspace-id 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d --kind character
```

***

### save\_view

`stories.save_view`: **Save a story graph view**

Save where each story node sits on the graph and its kind filter, as a named view of the workspace (a new one, or viewId to replace one). Returns the view. Next: stories.list.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.save_view"` |
| **CLI** | `summer stories save-view` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | Yes | The workspace (the person's own or a team, from team.list) the story is in. |
| `viewId` | string | No | A saved view to replace. |
| `name` | string | No | Default `"Default graph"`. Length 1 to 160. |
| `positions` | object | Yes | Node id to its graph position. |
| `kind` | string | No | Show only this kind of node. Length 1 to 64. |
| `isDefault` | boolean | No | Default `true`. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "workspaceId": {
>       "description": "The workspace (the person's own or a team, from team.list) the story is in.",
>       "type": "string",
>       "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)$"
>     },
>     "viewId": {
>       "description": "A saved view to replace.",
>       "type": "string",
>       "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)$"
>     },
>     "name": {
>       "default": "Default graph",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 160
>     },
>     "positions": {
>       "description": "Node id to its graph position.",
>       "type": "object",
>       "additionalProperties": {
>         "type": "object",
>         "properties": {
>           "x": {
>             "type": "number"
>           },
>           "y": {
>             "type": "number"
>           }
>         },
>         "required": [
>           "x",
>           "y"
>         ]
>       }
>     },
>     "kind": {
>       "description": "Show only this kind of node.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 64
>     },
>     "isDefault": {
>       "default": true,
>       "type": "boolean"
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "workspaceId",
>     "positions"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "view": {
>       "type": "object",
>       "additionalProperties": {}
>     }
>   },
>   "required": [
>     "view"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Keep the layout.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.save_view",
    "input": {
      "workspaceId": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "positions": {
        "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182": {
          "x": 120,
          "y": 80
        }
      }
    }
  }
}
```

```bash CLI theme={null}
summer stories save-view --workspace-id 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d --input '{"positions":{"2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182":{"x":120,"y":80}}}'
```

***

### share

`stories.share`: **Share a story with a team**

Ask the person to move their story builder content into a team the members see: an existing team (targetWorkspaceId) or a new one (newTeamName). Returns a link; nothing moves until they confirm. Next: jobs.wait.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.share"` |
| **CLI** | `summer stories share` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `workspaceId` | string | Yes | Where the story is now. |
| `targetWorkspaceId` | string | No | The team to move it into (from team.list). |
| `newTeamName` | string | No | Or a new team to make for it. Length 1 to 120. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "workspaceId": {
>       "description": "Where the story is now.",
>       "type": "string",
>       "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)$"
>     },
>     "targetWorkspaceId": {
>       "description": "The team to move it into (from team.list).",
>       "type": "string",
>       "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)$"
>     },
>     "newTeamName": {
>       "description": "Or a new team to make for it.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 120
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "workspaceId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "targetWorkspaceId": {
>       "type": "string"
>     },
>     "movedNodeCount": {
>       "type": "number"
>     }
>   },
>   "required": [
>     "targetWorkspaceId",
>     "movedNodeCount"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** The team should see the story.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.share",
    "input": {
      "workspaceId": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "targetWorkspaceId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
    }
  }
}
```

```bash CLI theme={null}
summer stories share --workspace-id 9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d --target-workspace-id 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
```

***

### unlink\_nodes

`stories.unlink_nodes`: **Remove a link between story nodes**

Ask the person to remove a link between two story nodes (linkId from stories.get of one of them). Returns a link to approve; nothing changes until they confirm. Next: jobs.wait.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.unlink_nodes"` |
| **CLI** | `summer stories unlink-nodes` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Removes or stops something for good. |
| **Asks you first** | Yes: **Delete for good** is off by default in Agent permissions. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `nodeId` | string | Yes | One of the two linked nodes (the one stories.get was read for). |
| `linkId` | string | Yes | From stories.get links. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "nodeId": {
>       "description": "One of the two linked nodes (the one stories.get was read for).",
>       "type": "string",
>       "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)$"
>     },
>     "linkId": {
>       "description": "From stories.get links.",
>       "type": "string",
>       "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)$"
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "nodeId",
>     "linkId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "linkId": {
>       "type": "string"
>     },
>     "removed": {
>       "type": "boolean"
>     }
>   },
>   "required": [
>     "linkId",
>     "removed"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Mira no longer lives in the harbor.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.unlink_nodes",
    "input": {
      "nodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182",
      "linkId": "0f1e2d3c-4b5a-4987-a6b5-c4d3e2f1a0b9"
    }
  }
}
```

```bash CLI theme={null}
summer stories unlink-nodes --node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182 --link-id 0f1e2d3c-4b5a-4987-a6b5-c4d3e2f1a0b9
```

***

### update\_node

`stories.update_node`: **Change a story node**

Change a story node's title, kind, summary, text, status or tags; fields left out stay as they are. Returns the node. Next: stories.get.

| | |
| - | - |
| **MCP** | `summer_call` with `"op": "stories.update_node"` |
| **CLI** | `summer stories update-node` |
| **Runs** | On Summer's servers: the hosted MCP, or the npm MCP after `summer login`. Needs your Summer sign-in. |
| **Effect** | Changes your own drafts, files or settings. Nobody else sees it yet. |
| **Asks you first** | No: **Make and build** is on by default in Agent permissions. When it is off, your agent asks you first. |

**Inputs:**

| Input | Type | Required | Description |
| - | - | - | - |
| `nodeId` | string | Yes | A story node, from stories.list. |
| `title` | string | No | Length 1 to 160. |
| `kind` | string | No | Length 1 to 64. |
| `summary` | string | No | Length 0 to 1000. |
| `bodyMarkdown` | string | No | Length 0 to 50000. |
| `status` | string | No | Length 1 to 64. |
| `tags` | string\[] | No | Items 0 to 50. |
| `dryRun` | boolean | No | Check and describe the call without doing it: nothing changes, nothing is spent. |
| `idempotencyKey` | string | No | Retry key. Reuse it only to retry the identical request, so it never happens twice. Length 1 to 128. |

> [accordion] Input JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "nodeId": {
>       "description": "A story node, from stories.list.",
>       "type": "string",
>       "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)$"
>     },
>     "title": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 160
>     },
>     "kind": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 64
>     },
>     "summary": {
>       "type": "string",
>       "maxLength": 1000
>     },
>     "bodyMarkdown": {
>       "type": "string",
>       "maxLength": 50000
>     },
>     "status": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 64
>     },
>     "tags": {
>       "maxItems": 50,
>       "type": "array",
>       "items": {
>         "type": "string",
>         "minLength": 1,
>         "maxLength": 64
>       }
>     },
>     "dryRun": {
>       "description": "Check and describe the call without doing it: nothing changes, nothing is spent.",
>       "type": "boolean"
>     },
>     "idempotencyKey": {
>       "description": "Retry key. Reuse it only to retry the identical request, so it never happens twice.",
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128
>     }
>   },
>   "required": [
>     "nodeId"
>   ]
> }
> ```

> [accordion] Result JSON schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "node": {
>       "type": "object",
>       "additionalProperties": {}
>     }
>   },
>   "required": [
>     "node"
>   ],
>   "additionalProperties": false
> }
> ```

**Example:** Rewrite a summary.

```json MCP theme={null}
{
  "name": "summer_call",
  "arguments": {
    "op": "stories.update_node",
    "input": {
      "nodeId": "2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182",
      "summary": "Keeps the last lantern lit."
    }
  }
}
```

```bash CLI theme={null}
summer stories update-node --node-id 2b3c4d5e-6f70-4a81-9b2c-3d4e5f607182 --summary 'Keeps the last lantern lit.'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.