> ## 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](/mcp/operations).

<Note>
  Generated from the `summer-engine` npm package `4.2.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.
</Note>

| 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 title="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>

<Accordion title="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
  }
  ```
</Accordion>

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

**Example:** Reuse the harbor picture.

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

**Example:** Add a character.

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

<Accordion title="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
  }
  ```
</Accordion>

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

**Example:** Who are the characters?

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

**Example:** Keep the layout.

<CodeGroup>
  ```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}}}'
  ```
</CodeGroup>

***

### 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 title="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>

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

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

***

### 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 title="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>

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

**Example:** Rewrite a summary.

<CodeGroup>
  ```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.'
  ```
</CodeGroup>


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