<!-- Generated by crates/swarmops-cli/src/reference/mcp_page.rs from the code: do not edit. Change the code, then run SWARMOPS_REGEN_REFERENCE=1 with the regen_reference test. -->

# show

One changeset in full: its parents, author, message, changes and signatures; pass max\_changes of 100 or less, since clients limit long tool results.

```yaml
title: "show"
description: "Show a changeset."
since: "0.1.0"
mutates: false
identity_required: false
cli_command: "swarmops show"
envelope_op: "show"
request_type: "ShowReq"
annotations: {"destructiveHint":false,"idempotentHint":true,"openWorldHint":false,"readOnlyHint":true}
max_result_chars: null
```

## Input schema

`arguments` is a `ShowReq`: `swarmops schema ShowReq` prints the type. A field the type does not know is ignored.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `max_changes` | integer | no | `400` | The most entries of `changes` to return: at least 1 (0 is `E_INVALID_ARG`). |
| `rev` | string | yes |  | The changeset to show. A revision as the caller wrote it, for the store to resolve: a ref name (`main`, `release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits, optionally followed by `~N` for the N-th first-parent ancestor. |

### JSON Schema

As `tools/list` gives it: each `$ref` replaced by its definition, so that it stands alone.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "`show`: one changeset in full.",
  "properties": {
    "max_changes": {
      "default": 400,
      "description": "The most entries of `changes` to return: at least 1 (0 is `E_INVALID_ARG`).",
      "format": "uint",
      "minimum": 1,
      "type": "integer"
    },
    "rev": {
      "description": "The changeset to show. A revision as the caller wrote it, for the store to resolve: a ref name (`main`,\n`release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits,\noptionally followed by `~N` for the N-th first-parent ancestor.",
      "type": "string"
    }
  },
  "required": [
    "rev"
  ],
  "title": "ShowReq",
  "type": "object"
}
```

## Annotations

It only reads the store.

| Annotation | Value | Meaning |
| --- | --- | --- |
| `destructiveHint` | `false` | True: a tool that changes the store may overwrite or delete what is there, not only add to it. |
| `idempotentHint` | `true` | True: calling it again with the same arguments changes nothing more. |
| `openWorldHint` | `false` | True: it reaches beyond a closed set of things. Every tool here stays inside the store. |
| `readOnlyHint` | `true` | True: the tool does not change its environment, the store. |

Its entry in `tools/list` carries no `_meta`.

## CLI command

[`swarmops show`](../commands/show.md) runs the same operation and prints the same envelope.

## Examples

### MCP

```json
{
  "id": 13,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "rev": "[landed]"
    },
    "name": "show"
  }
}
```

```json
{
  "id": 13,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"show\",\"api\":1,\"result\":{\"id\":\"[landed]\",\"seq\":3,\"parents\":[\"[theirs]\"],\"root\":\"[id5]\",\"author\":{\"agent\":\"agent/worker-17\"},\"lander\":{\"agent\":\"agent/worker-17\"},\"created_at\":\"[created_at]\",\"message\":\"change f\",\"land_key\":\"land-7\",\"squashed_from\":[\"[head]\"],\"changes\":[{\"path\":\"src/lib.rs\",\"op\":\"put\",\"kind\":\"file\",\"blob\":\"[id6]\"}],\"files_changed\":1,\"changes_truncated\":false,\"metadata\":{\"agent\":\"agent/worker-17\",\"land_key\":\"land-7\",\"lander\":\"agent/worker-17\",\"squashed_from\":\"[head]\"},\"signatures\":{\"author\":{\"name\":\"agent/worker-17\",\"email\":\"worker-17@agent.swarmops.local\",\"secs\":\"[secs]\",\"offset_secs\":0},\"committer\":{\"name\":\"agent/worker-17\",\"email\":\"worker-17@agent.swarmops.local\",\"secs\":\"[secs]\",\"offset_secs\":0}}},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{\"[landed]\":\"[landed]\"},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {
          "[landed]": "[landed]"
        }
      },
      "ok": true,
      "op": "show",
      "result": {
        "author": {
          "agent": "agent/worker-17"
        },
        "changes": [
          {
            "blob": "[id6]",
            "kind": "file",
            "op": "put",
            "path": "src/lib.rs"
          }
        ],
        "changes_truncated": false,
        "created_at": "[created_at]",
        "files_changed": 1,
        "id": "[landed]",
        "land_key": "land-7",
        "lander": {
          "agent": "agent/worker-17"
        },
        "message": "change f",
        "metadata": {
          "agent": "agent/worker-17",
          "land_key": "land-7",
          "lander": "agent/worker-17",
          "squashed_from": "[head]"
        },
        "parents": [
          "[theirs]"
        ],
        "root": "[id5]",
        "seq": 3,
        "signatures": {
          "author": {
            "email": "worker-17@agent.swarmops.local",
            "name": "agent/worker-17",
            "offset_secs": 0,
            "secs": "[secs]"
          },
          "committer": {
            "email": "worker-17@agent.swarmops.local",
            "name": "agent/worker-17",
            "offset_secs": 0,
            "secs": "[secs]"
          }
        },
        "squashed_from": [
          "[head]"
        ]
      }
    }
  }
}
```

The server ran as `swarmops mcp --repo [tmp]/store --as agent/worker-17`, after `initialize`. Recorded by the MCP tests. A name in square brackets, such as `[tmp]` or `[c1]`, stands for what differs from run to run: the test's temporary directory, an id, a time, the version.

## Details

Pass `max_changes` of 100 or less: a changeset's change list can be long, and a result holds the
envelope twice.
The result gives the changeset's parents, author, message, changes and signatures.

## Return information

A tool result: the envelope, whose `op` is `show`, as `structuredContent` and again as the text of its one `content` block. `isError` is true exactly when the envelope's `ok` is false. On success the envelope's `result` is what [`swarmops show`](../commands/show.md#return-information) returns.

## Errors

A failed call is a tool result with `isError: true`; the envelope's `error.code` is one of the [error codes](../errors.md).

- [`E_INVALID_ARG`](../errors.md#e_invalid_arg): arguments that do not fit `ShowReq`, a field named twice among them included, or that break one of the server's own rules.
- [`E_NOT_A_REPO`](../errors.md#e_not_a_repo): the server's store is not there; the server serves on.
- [`E_INTERNAL`](../errors.md#e_internal): the operation panicked, a bug.

Then the errors of the operation, as [`swarmops show`](../commands/show.md#errors) lists them.

## See also

- [`swarmops show`](../commands/show.md)
- [MCP tools](README.md)
- [MCP integration](../../develop/mcp.md)
- [Error codes](../errors.md)