mcp-server-appwrite 2.1.3__tar.gz → 2.2.1__tar.gz

{mcp_server_appwrite-2.1.3 → mcp_server_appwrite-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-server-appwrite
-Version: 2.1.3
+Version: 2.2.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.2.1/docs/apps.md

@@ -0,0 +1,101 @@
+# 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. `view=executions`: a Function's executions, newest first, optionally one `status`, with `cursor` paging; `execution_id` also opens one with its request and response headers, status code, duration, and the last 200 lines of logs and of errors. `view=files`: a Storage bucket's files, newest first, with `search` (file name) and `cursor` paging; `file_id` also opens one. `view=users`: the project's Auth users, newest first, with `search` (name, email, phone or ID) and `cursor` paging; `user_id` also opens one with their ten newest sessions. `view=usage`: a project's requests, bandwidth (in and out) and executions per interval over `range` (`24h` hourly, `7d` or `30d` daily), with totals and the newest snapshot of its users, resource counts and storage. Read-only. |
+| `appwrite_view_write` | view only (`visibility: ["app"]`) | Runs one of `tables_db_update_row`, `functions_update_deployment_status`, `sites_update_deployment_status`, `users_update_status`, `users_update_labels`, `users_update_email_verification`, only with `confirm_write=true`. |
+| `ui://appwrite/view` | host | One HTML document (`assets/view.html`) that renders every 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), and to follow executions
+while any on the page, or the opened one, is waiting or processing. Appwrite
+keeps an execution's response body only for the synchronous call that ran it,
+so the view shows it only when present. An edited row or a cancelled
+build goes through a confirmation dialog in the view, and only then through
+`appwrite_view_write`, as do blocking or unblocking a user, marking their
+email verified or not, and changing their labels. A successful change and a
+finished build are passed to the model with `ui/update-model-context` when the
+host supports it.
+
+The files view has no network access, so it cannot load a file's preview
+URL. It calls `appwrite_show` again with `thumbnails: true`, and the server
+renders the page's images through Appwrite's image transformations
+(`storage_get_file_preview`, eight at a time) and returns them as data URIs.
+The model's own call leaves them out, since some hosts put
+`structuredContent` in the model's context.
+
+The usage view reads the Usage API (`usage_list_events` and
+`usage_list_gauges`). Appwrite keeps usage history for as long as the plan
+allows; a range past it returns Appwrite's own error, which the view shows in
+place of the chart it was switching to.
+
+## 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.
+
+## Telemetry
+
+On the hosted transport, two counters show which views people use:
+
+- `mcp.apps.views` counts `appwrite_show` calls by `view` (`invalid` for a name
+  that is not one), `status` (`success` or `error`), `client_id`, and `origin`:
+  `model` when the model opens a view, `view` when the view refreshes, pages,
+  polls a build or opens a row on its own. Views opened per view type is
+  `origin="model"`; how much people then use each view is `origin="view"`.
+- `mcp.apps.writes` counts `appwrite_view_write` calls by `action` (the
+  allowlisted write, or `invalid`), `status` and `client_id`.
+
+The view marks its own calls with `"io.appwrite/origin": "view"` in the
+request's `_meta`. Hosts forward a view's `tools/call` params as sent; a host
+that drops `_meta` makes those calls count as `origin="model"`. Both counters
+feed the MCP Apps row of the MCP dashboard (appwrite-labs/monitoring
+`dashboards/Cloud/mcp.json`).
+
+## 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`.
+- User documents carry the password hash, prefs and messaging targets, and
+  sessions carry OAuth provider tokens. The users view, and the user writes'
+  results, carry only the fields the view shows.
+
+## 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.2.1/src/mcp_server_appwrite/apps/executions.py

@@ -0,0 +1,188 @@
+"""``view=executions``: a Function's executions, and one execution in full.
+
+The list is a page of executions, newest first, optionally narrowed to one
+status. With ``execution_id`` the payload also carries that execution's
+request, response headers, logs and errors (Appwrite keeps a response body
+only for the synchronous call that ran it), so "why did the last run fail?" opens on
+the answer. The view polls while an execution on the page or the opened one
+is still waiting or running.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from appwrite_console.query import Query
+
+from ..constants import SHOW_TOOL_NAME
+
+Read = Callable[[str, Any, dict[str, Any]], dict[str, Any]]
+"""Runs a hidden read tool: ``(tool name, project ID, arguments)``."""
+
+PAGE_SIZE = 25
+
+STATUSES = ("waiting", "processing", "completed", "failed", "scheduled")
+RUNNING = frozenset({"waiting", "processing"})
+
+LOG_LINES = 200
+"""Lines of logs and of errors an execution carries."""
+
+BODY_LIMIT = 8192
+"""Characters of the response body an execution carries."""
+
+SUMMARY_ROWS = 10
+SUMMARY_LOG_LINES = 20
+
+
+def read(read: Read, arguments: dict[str, Any]) -> dict[str, Any]:
+    project_id = arguments.get("project_id")
+    function_id = arguments.get("function_id")
+    if not isinstance(function_id, str) or not function_id:
+        raise ValueError("function_id is required for view=executions.")
+    status = arguments.get("status") or None
+    if status is not None and status not in STATUSES:
+        raise ValueError(f"status must be one of: {', '.join(STATUSES)}.")
+    cursor = arguments.get("cursor") or None
+    execution_id = arguments.get("execution_id") or None
+    target = {"function_id": function_id}
+
+    function = read("functions_get", project_id, target)
+    # One past the page tells whether another page follows.
+    queries = [Query.order_desc("$createdAt"), Query.limit(PAGE_SIZE + 1)]
+    if status:
+        queries.append(Query.equal("status", status))
+    if cursor:
+        queries.append(Query.cursor_after(str(cursor)))
+    page = read("functions_list_executions", project_id, {**target, "queries": queries})
+    executions = page.get("executions") or []
+    more = len(executions) > PAGE_SIZE
+    executions = executions[:PAGE_SIZE]
+
+    execution = None
+    if execution_id:
+        execution = _detail(
+            read(
+                "functions_get_execution",
+                project_id,
+                {**target, "execution_id": execution_id},
+            )
+        )
+    rows = [_summary(each) for each in executions]
+    return {
+        "view": "executions",
+        "projectId": project_id,
+        "functionId": function_id,
+        "name": function.get("name") or function_id,
+        "runtime": function.get("runtime"),
+        "status": status,
+        "executions": rows,
+        "total": int(page.get("total", len(rows))),
+        "cursor": cursor,
+        "next": rows[-1]["id"] if more else None,
+        "execution": execution,
+        "running": any(each["status"] in RUNNING for each in rows)
+        or bool(execution and execution["status"] in RUNNING),
+    }
+
+
+def _summary(execution: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": execution.get("$id"),
+        "status": execution.get("status") or "unknown",
+        "trigger": execution.get("trigger"),
+        "method": execution.get("requestMethod") or None,
+        "path": execution.get("requestPath") or None,
+        "statusCode": int(execution.get("responseStatusCode") or 0),
+        "duration": execution.get("duration"),
+        "createdAt": execution.get("$createdAt"),
+        "scheduledAt": execution.get("scheduledAt") or None,
+    }
+
+
+def _detail(execution: dict[str, Any]) -> dict[str, Any]:
+    body = execution.get("responseBody") or ""
+    logs = (execution.get("logs") or "").splitlines()
+    errors = (execution.get("errors") or "").splitlines()
+    return {
+        **_summary(execution),
+        "deploymentId": execution.get("deploymentId") or None,
+        "requestHeaders": _headers(execution.get("requestHeaders")),
+        "responseHeaders": _headers(execution.get("responseHeaders")),
+        "responseBody": body[:BODY_LIMIT],
+        "bodyTruncated": len(body) > BODY_LIMIT,
+        "logs": logs[-LOG_LINES:],
+        "logsTruncated": len(logs) > LOG_LINES,
+        "errors": errors[-LOG_LINES:],
+        "errorsTruncated": len(errors) > LOG_LINES,
+    }
+
+
+def _headers(headers: Any) -> list[dict[str, str]]:
+    return [
+        {"name": str(each.get("name", "")), "value": str(each.get("value", ""))}
+        for each in headers or []
+        if isinstance(each, dict)
+    ]
+
+
+def _request(execution: dict[str, Any]) -> str:
+    if not execution["method"]:
+        return execution["trigger"] or ""
+    return f"{execution['method']} {execution['path'] or '/'}"
+
+
+def summary(data: dict[str, Any]) -> str:
+    rows: list[dict[str, Any]] = data["executions"]
+    scope = f" {data['status']}" if data["status"] else ""
+    lines = [
+        f"Function {data['name']} ({data['functionId']}): {data['total']}"
+        f"{scope} executions, showing {len(rows)} newest"
+        + (" after the cursor." if data["cursor"] else ".")
+    ]
+    if rows:
+        lines.append("id | status | trigger | request | code | duration | created")
+        for each in rows[:SUMMARY_ROWS]:
+            lines.append(
+                " | ".join(
+                    [
+                        each["id"],
+                        each["status"],
+                        each["trigger"] or "",
+                        _request(each),
+                        str(each["statusCode"] or ""),
+                        _duration(each["duration"]),
+                        each["createdAt"] or "",
+                    ]
+                )
+            )
+        if len(rows) > SUMMARY_ROWS:
+            lines.append(f"… {len(rows) - SUMMARY_ROWS} more shown in the view.")
+    if data["next"]:
+        lines.append(
+            f"Next page: {SHOW_TOOL_NAME} with view=executions and "
+            f"cursor={data['next']}."
+        )
+    execution = data["execution"]
+    if execution:
+        lines.append(
+            f"Execution {execution['id']}: {execution['status']}, "
+            f"{_request(execution)} → {execution['statusCode'] or 'no response'} "
+            f"in {_duration(execution['duration'])}."
+        )
+        for label, key in (("Errors", "errors"), ("Logs", "logs")):
+            if execution[key]:
+                lines.append(f"{label} (last lines):")
+                lines.extend(execution[key][-SUMMARY_LOG_LINES:])
+        if execution["responseBody"]:
+            lines.append("Response body: " + execution["responseBody"][:500])
+    return "\n".join(lines)
+
+
+def _duration(seconds: Any) -> str:
+    # Executions that have not run yet report 0.
+    if not isinstance(seconds, (int, float)) or seconds <= 0:
+        return "–"
+    if seconds < 1:
+        return f"{seconds * 1000:.0f}ms"
+    return f"{seconds:.2f}s"

mcp_server_appwrite-2.2.1/src/mcp_server_appwrite/apps/files.py

@@ -0,0 +1,210 @@
+"""``view=files``: a Storage bucket's files, with image previews.
+
+The list is a page of a bucket's files, newest first, optionally narrowed by a
+search over file names. With ``file_id`` the payload also carries that file in
+full.
+
+The view has no network access, so it cannot load a file's preview URL. With
+``thumbnails`` the payload carries small previews of the page's images (and a
+larger one of the opened file) as data URIs, rendered by Appwrite's image
+transformations through the same hidden catalog read the model could make.
+The model's own call leaves them out, since some hosts put
+``structuredContent`` in the model's context; the view asks for them itself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from contextvars import copy_context
+from typing import Any
+
+from appwrite_console.query import Query
+
+from ..constants import SHOW_TOOL_NAME
+
+Read = Callable[[str, Any, dict[str, Any]], dict[str, Any]]
+"""Runs a hidden read tool: ``(tool name, project ID, arguments)``."""
+
+Preview = Callable[[Any, dict[str, Any]], str | None]
+"""Renders ``storage_get_file_preview`` for ``(project ID, arguments)`` as a
+data URI, ``None`` when Appwrite cannot."""
+
+PAGE_SIZE = 24
+"""Files per page: fills the grid's rows of two, three, four and six."""
+
+THUMBNAIL = 240
+"""Thumbnail edge in pixels: twice the grid's cell, for dense screens."""
+
+PREVIEW = 960
+"""Width of the opened file's preview in pixels."""
+
+PREVIEWABLE = frozenset(
+    {
+        "image/jpeg",
+        "image/png",
+        "image/gif",
+        "image/webp",
+        "image/avif",
+        "image/heic",
+        "image/bmp",
+    }
+)
+"""Types Appwrite's image transformations accept."""
+
+PARALLEL = 8
+"""Previews rendered at once. Each is one Appwrite request of a few hundred
+milliseconds, so a page of 24 takes about three rounds."""
+
+SUMMARY_ROWS = 10
+
+
+def read(read: Read, preview: Preview, arguments: dict[str, Any]) -> dict[str, Any]:
+    project_id = arguments.get("project_id")
+    bucket_id = arguments.get("bucket_id")
+    if not isinstance(bucket_id, str) or not bucket_id:
+        raise ValueError("bucket_id is required for view=files.")
+    search = arguments.get("search") or None
+    cursor = arguments.get("cursor") or None
+    file_id = arguments.get("file_id") or None
+    thumbnails = arguments.get("thumbnails") is True
+    target = {"bucket_id": bucket_id}
+
+    bucket = read("storage_get_bucket", project_id, target)
+    # One 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)))
+    listing: dict[str, Any] = {**target, "queries": queries}
+    if search:
+        listing["search"] = str(search)
+    page = read("storage_list_files", project_id, listing)
+    rows = [_file(each) for each in page.get("files") or []]
+    more = len(rows) > PAGE_SIZE
+    rows = rows[:PAGE_SIZE]
+    transforms = bool(bucket.get("transformations", True))
+
+    opened = None
+    if file_id:
+        opened = _file(
+            read("storage_get_file", project_id, {**target, "file_id": file_id})
+        )
+
+    if thumbnails and transforms:
+        # (file, key, preview arguments) for every image preview to render.
+        wanted = [
+            (
+                row,
+                "thumbnail",
+                {"width": THUMBNAIL, "height": THUMBNAIL, "quality": 70},
+            )
+            for row in rows
+            if row["mimeType"] in PREVIEWABLE
+        ]
+        if opened and opened["mimeType"] in PREVIEWABLE:
+            wanted.append((opened, "preview", {"width": PREVIEW, "quality": 80}))
+        with ThreadPoolExecutor(max_workers=PARALLEL) as pool:
+            # Each render runs in a copy of this request's context, which holds
+            # the caller's credentials.
+            futures = [
+                pool.submit(
+                    copy_context().run,
+                    preview,
+                    project_id,
+                    {**target, "file_id": each["id"], "output": "webp", **options},
+                )
+                for each, _, options in wanted
+            ]
+        for (each, key, _), future in zip(wanted, futures):
+            each[key] = future.result()
+    return {
+        "view": "files",
+        "projectId": project_id,
+        "bucketId": bucket_id,
+        "bucket": {
+            "name": bucket.get("name") or bucket_id,
+            "maximumFileSize": bucket.get("maximumFileSize"),
+            "allowedFileExtensions": bucket.get("allowedFileExtensions") or [],
+            "encryption": bool(bucket.get("encryption")),
+            "antivirus": bool(bucket.get("antivirus")),
+            "compression": bucket.get("compression") or "none",
+            "fileSecurity": bool(bucket.get("fileSecurity")),
+            "transformations": transforms,
+        },
+        "search": search,
+        "files": rows,
+        "total": int(page.get("total", len(rows))),
+        "cursor": cursor,
+        "next": rows[-1]["id"] if more else None,
+        "file": opened,
+        "thumbnails": thumbnails,
+    }
+
+
+def _file(document: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": document.get("$id"),
+        "name": document.get("name") or "",
+        "mimeType": document.get("mimeType") or "",
+        "size": int(document.get("sizeOriginal") or 0),
+        "createdAt": document.get("$createdAt"),
+        "updatedAt": document.get("$updatedAt"),
+        "folder": document.get("folder") or "",
+        "encryption": bool(document.get("encryption")),
+        "compression": document.get("compression") or "none",
+        "chunksTotal": int(document.get("chunksTotal") or 0),
+        "chunksUploaded": int(document.get("chunksUploaded") or 0),
+        "permissions": [str(each) for each in document.get("$permissions") or []],
+        "thumbnail": None,
+        "preview": None,
+    }
+
+
+def size(value: int) -> str:
+    if value < 1024:
+        return f"{value} B"
+    amount = value / 1024
+    for unit in ("KB", "MB"):
+        if amount < 1024:
+            return f"{amount:.1f} {unit}"
+        amount /= 1024
+    return f"{amount:.1f} GB"
+
+
+def summary(data: dict[str, Any]) -> str:
+    rows: list[dict[str, Any]] = data["files"]
+    scope = f" matching {data['search']!r}" if data["search"] else ""
+    lines = [
+        f"Bucket {data['bucket']['name']} ({data['bucketId']}): {data['total']} "
+        f"files{scope}, showing {len(rows)} newest"
+        + (" after the cursor." if data["cursor"] else ".")
+    ]
+    if rows:
+        lines.append("id | name | type | size | uploaded")
+        for row in rows[:SUMMARY_ROWS]:
+            lines.append(
+                " | ".join(
+                    [
+                        row["id"],
+                        row["name"],
+                        row["mimeType"],
+                        size(row["size"]),
+                        row["createdAt"] or "",
+                    ]
+                )
+            )
+        if len(rows) > SUMMARY_ROWS:
+            lines.append(f"… {len(rows) - SUMMARY_ROWS} more shown in the view.")
+    if data["next"]:
+        lines.append(
+            f"Next page: {SHOW_TOOL_NAME} with view=files and cursor={data['next']}."
+        )
+    opened = data["file"]
+    if opened:
+        lines.append(
+            f"File {opened['id']} ({opened['name']}): {opened['mimeType']}, "
+            f"{size(opened['size'])}, uploaded {opened['createdAt']}"
+            + (", encrypted" if opened["encryption"] else "")
+            + "."
+        )
+    return "\n".join(lines)

{mcp_server_appwrite-2.1.3 → mcp_server_appwrite-2.2.1}/src/mcp_server_appwrite/apps/protocol.py

@@ -19,6 +19,8 @@ Apps are offered behind the ``apps`` flag (``MCP_APPS``); see :func:`enabled`.
 from __future__ import annotations
 
 from collections.abc import Mapping
+from contextvars import ContextVar
+from enum import StrEnum
 from typing import Any
 
 from mcp.server import Server, ServerRequestContext
@@ -34,6 +36,22 @@ MIME_TYPE = "text/html;profile=mcp-app"
 
 SETTINGS: dict[str, Any] = {"mimeTypes": [MIME_TYPE]}
 
+ORIGIN_META_KEY = "io.appwrite/origin"
+"""The request ``_meta`` key the view sets to ``"view"`` on its own calls, so
+telemetry can tell a view refreshing and paging itself from the model opening
+one. Hosts forward a view's ``tools/call`` params as sent; a host that drops
+``_meta`` makes those calls count as the model's."""
+
+
+class Origin(StrEnum):
+    MODEL = "model"
+    VIEW = "view"
+
+
+_origin: ContextVar[Origin] = ContextVar(
+    "appwrite_mcp_apps_origin", default=Origin.MODEL
+)
+
 
 def enabled() -> bool:
     """Whether this server offers MCP Apps."""
@@ -56,6 +74,20 @@ def supported(context: ServerRequestContext[Any, Any]) -> bool:
     return not isinstance(mime_types, list) or MIME_TYPE in mime_types
 
 
+def bind_origin(context: ServerRequestContext[Any, Any]) -> None:
+    """Remember who made this ``tools/call``: the view, when its ``_meta``
+    says so, else the model. Contextvars reach the worker thread that runs the
+    tool."""
+    meta = context.meta
+    from_view = isinstance(meta, Mapping) and meta.get(ORIGIN_META_KEY) == Origin.VIEW
+    _origin.set(Origin.VIEW if from_view else Origin.MODEL)
+
+
+def origin() -> Origin:
+    """Who made the ``tools/call`` being served."""
+    return _origin.get()
+
+
 def register(server: Server[Any]) -> None:
     """Advertise the extension in ``server``'s capabilities."""
     server.extensions[EXTENSION] = dict(SETTINGS)

{mcp_server_appwrite-2.1.3 → mcp_server_appwrite-2.2.1}/src/mcp_server_appwrite/apps/resource.py

@@ -54,7 +54,8 @@ def resource() -> types.Resource:
         uri=uri(),
         name="Appwrite view",
         description=(
-            "Interactive Appwrite view: table rows and deployment build logs."
+            "Interactive Appwrite view: table rows, deployment build logs, "
+            "function executions, Storage files, Auth users and project usage."
         ),
         mime_type=MIME_TYPE,
         size=len(html().encode("utf-8")),