mcp-server-appwrite 2.0.2__tar.gz → 2.1.1__tar.gz

{mcp_server_appwrite-2.0.2 → mcp_server_appwrite-2.1.1}/AGENTS.md

@@ -36,6 +36,7 @@ Source lives in `src/mcp_server_appwrite/`:
 | `docs_source.py` | Fetches the published docs (`/docs/llms.txt` + per-page `.md` exports on appwrite.io) and chunks them for the index build. |
 | `docs_index.py` | Writes the index artifact deterministically and atomically: page and chunk hashes, reuse of cached chunk vectors, build lock, and the added/changed/removed page report. |
 | `events/` | MCP Events (behind `flags.EVENTS`, HTTP only): `catalog.py` (event catalog), `protocol.py` (capability, `events/list` and the subscribe methods), `subscriptions.py` + `webhooks.py` (`events/subscribe` / `events/unsubscribe`: one managed Appwrite webhook per subscription), `envelope.py` (subscription state sealed with the `mcp-event-subscriptions` JWE profile), `egress.py` + `delivery.py` (SSRF-safe signed delivery), `projection.py` + `ingress.py` (Appwrite webhook ingress at `/appwrite/webhooks/{id}`), `streams.py` + `bus.py` (push delivery: `events/stream`, behind `flags.EVENTS_PUSH`, with events routed between replicas over Redis pub/sub). See [docs/events.md](docs/events.md). |
+| `apps/` | MCP Apps (behind `flags.APPS`): `protocol.py` (the `io.modelcontextprotocol/ui` extension and per-client gating), `views.py` (`appwrite_show` and the view-only `appwrite_view_write`), `resource.py` (`ui://appwrite/view`, served from `assets/view.html`: plain JavaScript, no build step). See [docs/apps.md](docs/apps.md). |
 | `telemetry.py` | OpenTelemetry metrics layer (OTLP/HTTP). No-op unless an OTLP endpoint is configured and the transport is `http`. |
 | `data/` | Committed docs index artifact (`docs_index.npz`: vectors, chunk map, chunk hashes, embedded `meta.json`), shipped in the wheel/image. |
 
@@ -62,6 +63,11 @@ services) stays internal and is searched at runtime. API-key stdio uses a filter
 tool's annotations match every call it accepts. Large outputs are stored as MCP
 resources and returned as a preview + resource URI.
 
+With MCP Apps on (`flags.APPS`), hosts that render them also see
+`appwrite_show`, whose result the host renders as an interactive view
+(`ui://appwrite/view`), and the view can call `appwrite_view_write`, which the
+model never sees. See [docs/apps.md](docs/apps.md).
+
 ## Local development
 
 ```bash

{mcp_server_appwrite-2.0.2 → mcp_server_appwrite-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-server-appwrite
-Version: 2.0.2
+Version: 2.1.1
 Summary: Build and deploy application backends. Add authentication, PostgreSQL/MySQL databases, vector databases, storage, serverless functions, realtime, messaging, hosting, domains, CDN and firewall.
 License-File: LICENSE
 Requires-Python: >=3.12

mcp_server_appwrite-2.1.1/docs/apps.md

@@ -0,0 +1,63 @@
+# MCP Apps
+
+[MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) (SEP-1865,
+extension `io.modelcontextprotocol/ui`) let a tool result render as an
+interactive view inside the chat. This server offers one view,
+`ui://appwrite/view`, behind the `apps` flag (`MCP_APPS=1`, both transports).
+
+## Surface
+
+| Name | Seen by | What it does |
+| --- | --- | --- |
+| `appwrite_show` | model and view | `view=table`: a page of a table's rows, newest first, with `cursor` paging. `view=deployment`: a Function or Site deployment (the latest unless `deployment_id` is given) with the last 200 build log lines. Read-only. |
+| `appwrite_view_write` | view only (`visibility: ["app"]`) | Runs one of `tables_db_update_row`, `functions_update_deployment_status`, `sites_update_deployment_status`, only with `confirm_write=true`. |
+| `ui://appwrite/view` | host | One HTML document (`assets/view.html`) that renders either view. |
+
+`appwrite_show` returns a text summary in `content`, which is what the model and
+hosts without MCP Apps see, and the data in `structuredContent` for the view.
+The view calls `appwrite_show` again to page, refresh and follow a build (every
+3 seconds until it is ready, failed or canceled). An edited row or a cancelled
+build goes through a confirmation dialog in the view, and only then through
+`appwrite_view_write`. A successful edit and a finished build are passed to the
+model with `ui/update-model-context` when the host supports it.
+
+## Who is offered the view
+
+Hosts that declare the extension in their client capabilities get the two tools
+and the resource. Hosts that declare capabilities without it do not. The
+hosted transport is stateless, so a 2025-era client's `tools/list` carries no
+capabilities; it is offered the view, and a host that cannot render it uses the
+text summary. 2026-07-28 clients send `clientCapabilities` with every request,
+and stdio has the handshake, so both are gated exactly. `tools/call` is not
+gated, because the view's own calls reach the server through the host.
+
+## Security
+
+- The resource declares no CSP domains, so hosts apply the spec's restrictive
+  default: no network access, inline script and style only. The view never
+  holds a token; every Appwrite call is a `tools/call` the host proxies to this
+  server with the user's own credentials.
+- Everything the view renders comes from Appwrite. It builds the DOM with
+  `textContent` and `createElement` only (the e2e flow fails on `innerHTML`),
+  because a script injected through that data could call `appwrite_view_write`.
+  The allowlist bounds what such a script could do, and `confirm_write` is
+  required as for `appwrite_call_write_tool`.
+
+## Trying it in a real host
+
+The ext-apps repository ships `basic-host`, the reference host. It connects
+without auth, so point it at a local server whose requests carry a token, for
+example the e2e harness (`tests/e2e/support.py`) with its fake Appwrite:
+
+```bash
+git clone --depth 1 https://github.com/modelcontextprotocol/ext-apps.git
+cd ext-apps/examples/basic-host && npm install
+NODE_ENV=development npx cross-env INPUT=index.html vite build
+NODE_ENV=development npx cross-env INPUT=sandbox.html vite build
+SERVERS='["http://localhost:3001/mcp"]' bun serve.ts   # host on :8080
+```
+
+Pick `appwrite_show`, call it with
+`{"view":"table","project_id":"…","database_id":"…","table_id":"…"}`, and the
+view renders under the tool call. The host's theme toggle switches the view
+between light and dark.

{mcp_server_appwrite-2.0.2 → mcp_server_appwrite-2.1.1}/docs/flags.md

@@ -36,6 +36,7 @@ Flags are for testing overrides only — permanent configuration belongs in
 | `--console-url` | `MCP_CONSOLE_URL` | Send OAuth login/consent to an alternative Appwrite Console (HTTP transport only). |
 | `--events` | `MCP_EVENTS` | Advertise MCP Events, serve `events/list` and mount the Appwrite webhook ingress (HTTP transport only; needs `MCP_EVENTS_SEALING_KEYS`). See [events.md](events.md). |
 | `--events-push` | `MCP_EVENTS_PUSH` | Also offer push delivery (`events/stream`) for MCP Events (needs `--events` and `MCP_EVENTS_REDIS_URL`). See [events.md](events.md#push-delivery). |
+| `--apps` | `MCP_APPS` | Offer MCP Apps: the `appwrite_show` tool and its interactive `ui://appwrite/view`, rendered in the chat by hosts that support MCP Apps. See [apps.md](apps.md). |
 
 ### `--console-url` — test OAuth against a pre-release console
 
@@ -175,3 +176,21 @@ curl -sN http://localhost:8000/ \
 
 With the flag off, `events/list` advertises webhook only and `events/stream`
 returns `-32601` (method not found).
+
+### `--apps` — MCP Apps
+
+Adds `appwrite_show` (model and view), the view-only `appwrite_view_write`, and
+the `ui://appwrite/view` resource, and advertises the
+`io.modelcontextprotocol/ui` extension. Clients that declare their
+capabilities without the extension are not offered them. See
+[apps.md](apps.md) for the design and for driving it from a real host.
+
+**Enable it:**
+
+```bash
+MCP_PUBLIC_URL=http://localhost:8000 \
+  uv run mcp-server-appwrite --transport http --apps 1
+```
+
+With the flag off, `tools/list` is unchanged and `resources/read` of
+`ui://appwrite/view` is an error.

mcp_server_appwrite-2.1.1/src/mcp_server_appwrite/apps/__init__.py

@@ -0,0 +1 @@
+"""MCP Apps: interactive Appwrite views rendered in the chat by the host."""

mcp_server_appwrite-2.1.1/src/mcp_server_appwrite/apps/protocol.py

@@ -0,0 +1,80 @@
+"""MCP Apps (SEP-1865) negotiation on the low-level SDK server.
+
+The extension is ``io.modelcontextprotocol/ui``. A host that supports it reads
+``_meta.ui.resourceUri`` on a tool, fetches that ``ui://`` resource with
+``resources/read`` and renders it in a sandboxed iframe next to the tool call.
+Hosts without it ignore ``_meta`` and show the tool's text content, so the
+tools stay usable everywhere.
+
+The spec asks servers to offer UI tools only to hosts that declared the
+extension. Whether a host did is known on stdio (the ``initialize`` handshake)
+and on the 2026-07-28 protocol (``clientCapabilities`` in every request's
+``_meta``). The hosted 2025-era transport is stateless, so its ``tools/list``
+arrives without either; there the tools are offered, since a host that cannot
+render them still gets a text answer. See :func:`supported`.
+
+Apps are offered behind the ``apps`` flag (``MCP_APPS``); see :func:`enabled`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from mcp.server import Server, ServerRequestContext
+from mcp.types import CLIENT_CAPABILITIES_META_KEY
+
+from .. import flags
+
+EXTENSION = "io.modelcontextprotocol/ui"
+"""SEP-1865 extension identifier under ``capabilities.extensions``."""
+
+MIME_TYPE = "text/html;profile=mcp-app"
+"""The only UI resource type the extension defines."""
+
+SETTINGS: dict[str, Any] = {"mimeTypes": [MIME_TYPE]}
+
+
+def enabled() -> bool:
+    """Whether this server offers MCP Apps."""
+    return flags.enabled(flags.APPS)
+
+
+def supported(context: ServerRequestContext[Any, Any]) -> bool:
+    """Whether the host behind ``context`` may render MCP Apps: ``False`` only
+    when its capabilities are known and lack the extension."""
+    capabilities = _capabilities(context)
+    if capabilities is None:
+        return True
+    extensions = capabilities.get("extensions")
+    if not isinstance(extensions, Mapping):
+        return False
+    settings = extensions.get(EXTENSION)
+    if not isinstance(settings, Mapping):
+        return False
+    mime_types = settings.get("mimeTypes")
+    return not isinstance(mime_types, list) or MIME_TYPE in mime_types
+
+
+def register(server: Server[Any]) -> None:
+    """Advertise the extension in ``server``'s capabilities."""
+    server.extensions[EXTENSION] = dict(SETTINGS)
+
+
+def _capabilities(
+    context: ServerRequestContext[Any, Any],
+) -> Mapping[str, Any] | None:
+    """The client capabilities of this request's ``_meta`` (2026-07-28) or of
+    the session's handshake, ``None`` when neither is known."""
+    meta = context.meta
+    if isinstance(meta, Mapping):
+        capabilities = meta.get(CLIENT_CAPABILITIES_META_KEY)
+        if isinstance(capabilities, Mapping):
+            return capabilities
+    try:
+        params = context.session.client_params
+    except Exception:
+        return None
+    if params is None:
+        return None
+    return params.capabilities.model_dump(by_alias=True, exclude_none=True)

mcp_server_appwrite-2.1.1/src/mcp_server_appwrite/apps/resource.py

@@ -0,0 +1,45 @@
+"""The Appwrite view's UI resource, ``ui://appwrite/view``.
+
+One HTML document (``assets/view.html``, plain JavaScript with no build step)
+renders every view; it picks one from the tool result's ``structuredContent``.
+It declares no CSP domains, so hosts apply SEP-1865's restrictive default: no
+network access and no external scripts. Every Appwrite read and write it makes
+is a ``tools/call`` the host proxies to this server under the user's own
+credentials.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from importlib.resources import files
+from typing import Any
+
+import mcp.types as types
+from mcp.server.lowlevel.helper_types import ReadResourceContents
+
+from ..constants import VIEW_URI
+from .protocol import MIME_TYPE
+
+META: dict[str, Any] = {"ui": {"csp": {}, "prefersBorder": True}}
+
+
+@cache
+def html() -> str:
+    return files("mcp_server_appwrite.assets").joinpath("view.html").read_text()
+
+
+def resource() -> types.Resource:
+    return types.Resource(
+        uri=VIEW_URI,
+        name="Appwrite view",
+        description=(
+            "Interactive Appwrite view: table rows and deployment build logs."
+        ),
+        mime_type=MIME_TYPE,
+        size=len(html().encode("utf-8")),
+        _meta=META,
+    )
+
+
+def read() -> ReadResourceContents:
+    return ReadResourceContents(html(), MIME_TYPE, META)

mcp_server_appwrite-2.1.1/src/mcp_server_appwrite/apps/views.py

@@ -0,0 +1,396 @@
+"""The tools behind the Appwrite view (``ui://appwrite/view``).
+
+``appwrite_show`` is the one tool the model sees. It reads what a view shows
+(a page of a table's rows, or a Function or Site deployment with its build
+logs) through the hidden catalog, and returns it twice: a text summary in
+``content`` for the model and for hosts without MCP Apps, and the data in
+``structuredContent`` for the view. The view calls it again to page, refresh
+and follow a build, so every read it makes is one the model could make too.
+
+``appwrite_view_write`` is visible to the view only (``visibility: ["app"]``).
+It runs a short allowlist of catalog writes the view offers buttons for, and
+like ``appwrite_call_write_tool`` it refuses to run without
+``confirm_write=true``, which the view sends only after the user confirms the
+change in a dialog. Anything the view renders comes from Appwrite, so a
+script injected through that data could call this tool; the allowlist bounds
+what such a script could do.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from enum import StrEnum
+from typing import Any
+
+import mcp.types as types
+from appwrite_console.query import Query
+
+from ..constants import SHOW_TOOL_NAME, VIEW_URI, VIEW_WRITE_TOOL_NAME
+
+Run = Callable[[dict[str, Any], bool], list[Any]]
+"""Runs a hidden catalog tool from raw call arguments (``tool_name``,
+``arguments``, ``project_id``, ``confirm_write``), as a write or a read."""
+
+Handler = Callable[[dict[str, Any]], types.CallToolResult]
+
+PAGE_SIZE = 25
+"""Rows per page: Appwrite's default list limit."""
+
+LOG_LINES = 200
+"""Build log lines a view carries. Hosts may put ``structuredContent`` in the
+model's context, and a build log can run to megabytes."""
+
+SUMMARY_LOG_LINES = 20
+SUMMARY_ROWS = 10
+SUMMARY_COLUMNS = 4
+SUMMARY_CELL = 24
+
+ANSI = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+"""Terminal escape sequences (colors, cursor moves) in build logs: the view
+renders the colors, the model's summary drops them."""
+
+TERMINAL_STATUSES = frozenset({"ready", "failed", "canceled"})
+
+WRITES = (
+    "tables_db_update_row",
+    "functions_update_deployment_status",
+    "sites_update_deployment_status",
+)
+"""The writes the view offers: editing a row and cancelling a build."""
+
+_SHOW_TITLE = "Show Appwrite view"
+_WRITE_TITLE = "Run Appwrite view action"
+
+
+class View(StrEnum):
+    TABLE = "table"
+    DEPLOYMENT = "deployment"
+
+
+class Views:
+    def __init__(self, run: Run):
+        self._run = run
+
+    def tools(self) -> list[tuple[types.Tool, Handler]]:
+        return [(_show_tool(), self.show), (_write_tool(), self.write)]
+
+    def show(self, arguments: dict[str, Any]) -> types.CallToolResult:
+        view = arguments.get("view")
+        if view == View.TABLE:
+            data = self._table(arguments)
+            text = _table_summary(data)
+        elif view == View.DEPLOYMENT:
+            data = self._deployment(arguments)
+            text = _deployment_summary(data)
+        else:
+            raise ValueError(f"view must be one of: {', '.join(View)}. Got {view!r}.")
+        return types.CallToolResult(
+            content=[types.TextContent(type="text", text=text)],
+            structured_content=data,
+        )
+
+    def write(self, arguments: dict[str, Any]) -> types.CallToolResult:
+        tool_name = arguments.get("tool_name")
+        if tool_name not in WRITES:
+            raise ValueError(
+                f"{VIEW_WRITE_TOOL_NAME} runs only {', '.join(WRITES)}. "
+                f"Got {tool_name!r}."
+            )
+        # Only the literal true confirms: a string such as "false" is truthy.
+        if arguments.get("confirm_write") is not True:
+            raise ValueError(
+                f"{VIEW_WRITE_TOOL_NAME} runs {tool_name} only with confirm_write=true."
+            )
+        result = _json(self._run(arguments, True))
+        if isinstance(result, dict) and tool_name == "tables_db_update_row":
+            result = _row(result)
+        return types.CallToolResult(
+            content=[types.TextContent(type="text", text=f"{tool_name} succeeded.")],
+            structured_content=result if isinstance(result, dict) else None,
+        )
+
+    def _read(
+        self, tool_name: str, project_id: Any, arguments: dict[str, Any]
+    ) -> dict[str, Any]:
+        result = _json(
+            self._run(
+                {
+                    "tool_name": tool_name,
+                    "project_id": project_id,
+                    "arguments": arguments,
+                },
+                False,
+            )
+        )
+        if not isinstance(result, dict):
+            raise ValueError(f"{tool_name} returned an unexpected response.")
+        return result
+
+    def _table(self, arguments: dict[str, Any]) -> dict[str, Any]:
+        project_id = arguments.get("project_id")
+        database_id = _required(arguments, "database_id")
+        table_id = _required(arguments, "table_id")
+        cursor = arguments.get("cursor")
+        target = {"database_id": database_id, "table_id": table_id}
+
+        table = self._read("tables_db_get_table", project_id, target)
+        # One row past the page tells whether another page follows.
+        queries = [Query.order_desc("$createdAt"), Query.limit(PAGE_SIZE + 1)]
+        if cursor:
+            queries.append(Query.cursor_after(str(cursor)))
+        page = self._read(
+            "tables_db_list_rows", project_id, {**target, "queries": queries}
+        )
+        rows = [_row(each) for each in page.get("rows") or []]
+        more = len(rows) > PAGE_SIZE
+        rows = rows[:PAGE_SIZE]
+        columns = [
+            {"key": column.get("key"), "type": column.get("type")}
+            for column in table.get("columns") or []
+            if column.get("status", "available") == "available"
+        ]
+        return {
+            "view": View.TABLE.value,
+            "projectId": project_id,
+            "databaseId": database_id,
+            "tableId": table_id,
+            "name": table.get("name") or table_id,
+            "columns": columns,
+            "rows": rows,
+            "total": int(page.get("total", len(rows))),
+            "cursor": cursor,
+            "next": rows[-1].get("$id") if more else None,
+        }
+
+    def _deployment(self, arguments: dict[str, Any]) -> dict[str, Any]:
+        project_id = arguments.get("project_id")
+        function_id = arguments.get("function_id")
+        site_id = arguments.get("site_id")
+        if bool(function_id) == bool(site_id):
+            raise ValueError("Pass exactly one of function_id or site_id.")
+        kind, resource_key, resource_id = (
+            ("function", "function_id", function_id)
+            if function_id
+            else ("site", "site_id", site_id)
+        )
+        service = "functions" if function_id else "sites"
+        target = {resource_key: resource_id}
+
+        deployment_id = arguments.get("deployment_id")
+        if deployment_id:
+            deployment = self._read(
+                f"{service}_get_deployment",
+                project_id,
+                {**target, "deployment_id": deployment_id},
+            )
+        else:
+            latest = self._read(
+                f"{service}_list_deployments",
+                project_id,
+                {
+                    **target,
+                    "queries": [Query.order_desc("$createdAt"), Query.limit(1)],
+                },
+            )
+            deployments = latest.get("deployments") or []
+            if not deployments:
+                raise ValueError(f"The {kind} {resource_id} has no deployments.")
+            deployment = deployments[0]
+
+        logs = (deployment.get("buildLogs") or "").splitlines()
+        status = deployment.get("status") or "unknown"
+        return {
+            "view": View.DEPLOYMENT.value,
+            "projectId": project_id,
+            "kind": kind,
+            "resourceId": resource_id,
+            "deployment": {
+                "id": deployment.get("$id"),
+                "status": status,
+                "createdAt": deployment.get("$createdAt"),
+                "updatedAt": deployment.get("$updatedAt"),
+                "buildDuration": deployment.get("buildDuration"),
+                "sourceSize": deployment.get("sourceSize"),
+                "buildSize": deployment.get("buildSize"),
+                "activate": deployment.get("activate"),
+                "branch": deployment.get("providerBranch") or None,
+                "commit": deployment.get("providerCommitHash") or None,
+                "commitMessage": deployment.get("providerCommitMessage") or None,
+                "logs": logs[-LOG_LINES:],
+                "truncated": len(logs) > LOG_LINES,
+            },
+            "done": status in TERMINAL_STATUSES,
+        }
+
+
+def _show_tool() -> types.Tool:
+    return types.Tool(
+        name=SHOW_TOOL_NAME,
+        title=_SHOW_TITLE,
+        annotations=_annotations(_SHOW_TITLE, read_only=True),
+        description=(
+            "Show an interactive Appwrite view in the chat: view=table pages "
+            "through a table's rows and lets the user edit one; view=deployment "
+            "follows a Function or Site deployment's status and build logs live. "
+            "Use it when the user wants to see or browse this data rather than "
+            "reason over it; the result also carries a short text summary. Calls "
+            "the Appwrite REST API."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "view": {"type": "string", "enum": [view.value for view in View]},
+                "project_id": {
+                    "type": "string",
+                    "description": "Appwrite project ID the data lives in.",
+                },
+                "database_id": {
+                    "type": "string",
+                    "description": "view=table: the TablesDB database ID.",
+                },
+                "table_id": {
+                    "type": "string",
+                    "description": "view=table: the table ID.",
+                },
+                "cursor": {
+                    "type": "string",
+                    "description": (
+                        "view=table: continue after this row ID (the previous "
+                        "page's `next`). Omit for the newest rows."
+                    ),
+                },
+                "function_id": {
+                    "type": "string",
+                    "description": "view=deployment: the Function ID (or site_id).",
+                },
+                "site_id": {
+                    "type": "string",
+                    "description": "view=deployment: the Site ID (or function_id).",
+                },
+                "deployment_id": {
+                    "type": "string",
+                    "description": "view=deployment: omit for the latest deployment.",
+                },
+            },
+            "required": ["view"],
+            "additionalProperties": False,
+        },
+        _meta={
+            "ui": {"resourceUri": VIEW_URI, "visibility": ["model", "app"]},
+            # The flat key hosts read before ``ui.resourceUri``; SEP-1865 drops
+            # it at GA.
+            "ui/resourceUri": VIEW_URI,
+        },
+    )
+
+
+def _write_tool() -> types.Tool:
+    return types.Tool(
+        name=VIEW_WRITE_TOOL_NAME,
+        title=_WRITE_TITLE,
+        annotations=_annotations(_WRITE_TITLE, read_only=False),
+        description=(
+            "Used by the Appwrite view after the user confirms a change in it. "
+            "Runs one of a fixed set of Appwrite writes; requires "
+            "confirm_write=true. Calls the Appwrite REST API."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "tool_name": {"type": "string", "enum": list(WRITES)},
+                "arguments": {"type": "object"},
+                "project_id": {"type": "string"},
+                "confirm_write": {"type": "boolean"},
+            },
+            "required": ["tool_name", "arguments", "confirm_write"],
+            "additionalProperties": False,
+        },
+        _meta={"ui": {"resourceUri": VIEW_URI, "visibility": ["app"]}},
+    )
+
+
+def _annotations(title: str, *, read_only: bool) -> types.ToolAnnotations:
+    return types.ToolAnnotations(
+        title=title,
+        read_only_hint=read_only,
+        destructive_hint=not read_only,
+        idempotent_hint=read_only,
+        open_world_hint=True,
+    )
+
+
+def _required(arguments: dict[str, Any], key: str) -> str:
+    value = arguments.get(key)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{key} is required for view={arguments.get('view')}.")
+    return value
+
+
+def _row(row: dict[str, Any]) -> dict[str, Any]:
+    """A row with its column values beside the system fields. The SDK's ``Row``
+    model moves column values into ``data``."""
+    values = row.get("data")
+    if not isinstance(values, dict):
+        return row
+    return {key: value for key, value in row.items() if key != "data"} | values
+
+
+def _json(content: list[Any]) -> Any:
+    text = "\n".join(
+        item.text for item in content if isinstance(item, types.TextContent)
+    )
+    try:
+        return json.loads(text)
+    except ValueError as error:
+        raise ValueError("Appwrite returned a response that is not JSON.") from error
+
+
+def _cell(value: Any) -> str:
+    text = value if isinstance(value, str) else json.dumps(value, default=str)
+    text = text.replace("\n", " ")
+    if len(text) > SUMMARY_CELL:
+        return text[: SUMMARY_CELL - 1] + "…"
+    return text
+
+
+def _table_summary(data: dict[str, Any]) -> str:
+    rows: list[dict[str, Any]] = data["rows"]
+    keys = ["$id"] + [
+        column["key"] for column in data["columns"][: SUMMARY_COLUMNS - 1]
+    ]
+    lines = [
+        f"Table {data['name']} ({data['databaseId']}/{data['tableId']}): "
+        f"{data['total']} rows, showing {len(rows)} newest"
+        + (" after the cursor." if data["cursor"] else ".")
+    ]
+    if rows:
+        lines.append(" | ".join(keys))
+        for row in rows[:SUMMARY_ROWS]:
+            lines.append(" | ".join(_cell(row.get(key, "")) for key in keys))
+        if len(rows) > SUMMARY_ROWS:
+            lines.append(f"… {len(rows) - SUMMARY_ROWS} more rows shown in the view.")
+    if data["next"]:
+        lines.append(
+            f"Next page: {SHOW_TOOL_NAME} with view=table and cursor={data['next']}."
+        )
+    return "\n".join(lines)
+
+
+def _deployment_summary(data: dict[str, Any]) -> str:
+    deployment = data["deployment"]
+    lines = [
+        f"Deployment {deployment['id']} of {data['kind']} {data['resourceId']} "
+        f"is {deployment['status']}."
+    ]
+    if deployment["commit"]:
+        lines.append(
+            f"Source: {deployment['branch'] or 'unknown branch'} @ "
+            f"{deployment['commit'][:7]}."
+        )
+    logs = deployment["logs"][-SUMMARY_LOG_LINES:]
+    if logs:
+        lines.append("Last build log lines:")
+        lines.extend(ANSI.sub("", line) for line in logs)
+    return "\n".join(lines)