mcp-server-appwrite 1.0.28__tar.gz → 2.0.0__tar.gz

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/AGENTS.md

@@ -29,7 +29,7 @@ Source lives in `src/mcp_server_appwrite/`:
 | `flags.py` | Central registry of tester/testing flags (CLI arg + env var per flag). Enabling and testing them is documented in [docs/flags.md](docs/flags.md). |
 | `service.py` | `Service` base class: introspects an Appwrite SDK service and turns its methods into MCP tool definitions. |
 | `tool_manager.py` | Registry of all services and their generated tools. |
-| `operator.py` | The compact "operator" surface — `appwrite_search_tools`, `appwrite_call_tool`, result/resource storage, write confirmation. |
+| `operator.py` | The compact "operator" surface — `appwrite_search_tools`, `appwrite_call_tool` / `appwrite_call_write_tool`, tool annotations, result/resource storage, write confirmation. |
 | `instructions.py` | `serverInfo.description` and the server instructions sent on initialize, rendered from `assets/instructions.json` (a description plus ordered, transport/docs-conditional Markdown sections). Edit the JSON to change the wording; keep the `pyproject.toml` description in sync (a test enforces it). |
 | `context.py` | `appwrite_get_context` — workspace summary (project, services, account/org for OAuth). |
 | `docs_search.py` | In-process semantic docs search (`appwrite_search_docs`) over a prebuilt index. |
@@ -47,17 +47,20 @@ Source lives in `src/mcp_server_appwrite/`:
 no-op unless the transport is `http` and `OTEL_EXPORTER_OTLP_ENDPOINT` is set, so
 `stdio` and unconfigured servers stay silent. In the cluster that endpoint is the
 Alloy collector, which adds the `deployment.*` labels and forwards upstream — the app
-needs no credentials. Dashboards live in the `dashboards` repo under `MCP/`.
+needs no credentials. The MCP dashboard lives in `appwrite-labs/monitoring` at
+`dashboards/Cloud/mcp.json`, synced to monitoring.appwrite.systems by Grafana Git Sync.
 
 ### Tool surface (key design point)
 
-The server boots in a compact workflow: the client sees up to 4 tools
-(`appwrite_get_context`, `appwrite_search_tools`, `appwrite_call_tool`, and
-optionally `appwrite_search_docs`), while the full OAuth Appwrite catalog (41
+The server boots in a compact workflow: the client sees up to 5 tools
+(`appwrite_get_context`, `appwrite_search_tools`, `appwrite_call_tool` for
+reads, `appwrite_call_write_tool` for everything else, and optionally
+`appwrite_search_docs`), while the full OAuth Appwrite catalog (41
 services) stays internal and is searched at runtime. API-key stdio uses a filtered
-27-service catalog. Mutating hidden tools require
-`confirm_write=true`. Large outputs are stored as MCP resources and returned as a
-preview + resource URI.
+27-service catalog. Mutating hidden tools run only through
+`appwrite_call_write_tool` and require `confirm_write=true`, so each exposed
+tool's annotations match every call it accepts. Large outputs are stored as MCP
+resources and returned as a preview + resource URI.
 
 ## Local development
 

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-server-appwrite
-Version: 1.0.28
+Version: 2.0.0
 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-1.0.28 → mcp_server_appwrite-2.0.0}/docs/tool-surface.md

@@ -8,15 +8,17 @@ searched at runtime.
 flowchart LR
     M[Model] -->|sees| E
 
-    subgraph E[Exposed surface — up to 4 tools]
+    subgraph E[Exposed surface — up to 5 tools]
         C[appwrite_get_context]
         ST[appwrite_search_tools]
         CT[appwrite_call_tool]
+        WT[appwrite_call_write_tool]
         SD[appwrite_search_docs *]
     end
 
     ST -.searches.-> CAT
-    CT -.invokes.-> CAT
+    CT -.reads.-> CAT
+    WT -.mutates.-> CAT
 
     subgraph CAT[Internal catalog — authentication-aware]
         direction LR
@@ -35,14 +37,23 @@ flowchart LR
 | --- | --- |
 | `appwrite_get_context` | Workspace summary. API key → project + readable service totals/samples. OAuth → also account, organization, discovered projects. |
 | `appwrite_search_tools` | Searches the internal catalog at runtime. |
-| `appwrite_call_tool` | Invokes a catalog tool. Mutating calls require `confirm_write=true`. |
+| `appwrite_call_tool` | Runs a read catalog tool (`list`, `get`). |
+| `appwrite_call_write_tool` | Runs every other catalog tool (create, update, delete, upsert, unknown verbs). Requires `confirm_write=true`. |
 | `appwrite_search_docs` | Semantic search over Appwrite docs (conditional — see above). |
 
 ## Behavior
 
 - **Large outputs** are stored as an MCP resource and returned as preview text
   plus a resource URI.
-- **Writes** through hidden mutating tools require `confirm_write=true`.
+- **Reads and writes** go through separate tools so each tool's annotations
+  match every call it accepts: `appwrite_call_tool` is read-only and
+  idempotent, `appwrite_call_write_tool` is destructive. Each search result
+  names its `call_tool`, and calling a tool through the other one returns an
+  error naming the right one.
+- **Writes** require `confirm_write=true`.
+- **Annotations**: every exposed tool sets a `title` and all four hints
+  (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`)
+  explicitly, as the Anthropic and OpenAI connector directories require.
 - **Target context** is included in search results as `context=console`,
   `context=organization`, or `context=project`. Hosted calls enforce the required
   top-level `organization_id` or `project_id` before making a request.

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/src/mcp_server_appwrite/assets/instructions.json

@@ -79,8 +79,8 @@
     {
       "lines": [
         "Using these tools",
-        "- Use appwrite_get_context to understand the current connection and available project resources, then use appwrite_search_tools and appwrite_call_tool for specific operations.",
-        "- Mutating hidden tools require confirm_write=true."
+        "- Use appwrite_get_context to understand the current connection and available project resources, then use appwrite_search_tools to find the operation you need.",
+        "- Run read operations (list, get) with appwrite_call_tool. Run every other operation (create, update, delete, upsert) with appwrite_call_write_tool and confirm_write=true; each search result names its call_tool."
       ]
     },
     {
@@ -101,7 +101,7 @@
       "transports": ["http"],
       "lines": [
         "- You authenticate against the Appwrite console, which can list your organizations and projects but stores no project data itself.",
-        "- Project-scoped tools (every database type, users, teams, storage, functions, sites, messaging, firewall, advisor) need a target project: use appwrite_get_context first, then pass the selected project id as project_id to appwrite_call_tool.",
+        "- Project-scoped tools (every database type, users, teams, storage, functions, sites, messaging, firewall, advisor) need a target project: use appwrite_get_context first, then pass the selected project id as project_id to appwrite_call_tool or appwrite_call_write_tool.",
         "- Organization-scoped console tools (e.g. creating a project or managing domains) need organization_id.",
         "- File/image uploads: pass a public URL as the file argument (e.g. {\"url\": \"https://...\"}) so the server downloads it directly; for very small files you may pass inline base64 ({\"filename\": ..., \"content\": ..., \"encoding\": \"base64\"}).",
         "- Hosted HTTP returns tool results inline, including images and other binary payloads."

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/src/mcp_server_appwrite/constants.py

@@ -13,8 +13,6 @@ from appwrite_console.models.site import Site
 from appwrite_console.models.team import Team
 from appwrite_console.models.user import User
 
-# --- server ---------------------------------------------------------------
-
 
 def _resolve_server_version() -> str:
     try:
@@ -64,8 +62,6 @@ HOSTED_PATH_GUIDANCE = (
     '{{"filename": "...", "content": "<base64>", "encoding": "base64"}}.'
 )
 
-# --- auth -----------------------------------------------------------------
-
 DEFAULT_PROJECT_ID = "console"
 
 # Curated scope allowlist. Empty means "no curation": the MCP mirrors the
@@ -77,8 +73,6 @@ PREFERRED_SCOPES: list[str] = []
 # Shared TTL for cached upstream lookups (OAuth discovery, project regions).
 CACHE_TTL_SECONDS = 300.0
 
-# --- http_app -------------------------------------------------------------
-
 CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
@@ -90,8 +84,10 @@ CORS_HEADERS = {
     "Access-Control-Expose-Headers": "Mcp-Session-Id, WWW-Authenticate, Link",
 }
 
-# --- operator -------------------------------------------------------------
-
+CONTEXT_TOOL_NAME = "appwrite_get_context"
+SEARCH_TOOL_NAME = "appwrite_search_tools"
+CALL_TOOL_NAME = "appwrite_call_tool"
+WRITE_TOOL_NAME = "appwrite_call_write_tool"
 SEARCH_LIMIT = 8
 # A page of rows does not fit in 800 characters, so the model paid a
 # resources/read for every list call. Only stdio stores results at all.
@@ -106,8 +102,6 @@ UPDATE_HINTS = {"change", "edit", "modify", "rename", "set", "update"}
 DELETE_HINTS = {"delete", "destroy", "drop", "remove"}
 READ_HINTS = {"fetch", "find", "get", "list", "read", "search", "show", "view"}
 
-# --- docs_search ----------------------------------------------------------
-
 DOCS_TOOL_NAME = "appwrite_search_docs"
 EMBED_MODEL = "text-embedding-3-small"
 DOCS_DEFAULT_LIMIT = 5
@@ -119,8 +113,6 @@ DATA_DIR = Path(__file__).parent / "data"
 INDEX_FILE = "docs_index.npz"
 META_MEMBER = "meta.json"
 
-# --- context --------------------------------------------------------------
-
 SERVICE_PROBES = {
     "tablesdb": {
         "path": "/tablesdb",
@@ -161,8 +153,6 @@ SERVICE_PROBES = {
 
 REDACTED_KEYS = {"password", "secret", "key", "token", "otp", "cookie", "session"}
 
-# --- telemetry ------------------------------------------------------------
-
 ACTIVE_WINDOW_SECONDS = 300.0  # rolling window for "active users/clients" gauges
 
 # Known MCP clients (normalized: lowercase, whitespace -> "-"). Client names are

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/src/mcp_server_appwrite/data/docs_index.npz

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
-name: mcp_server_appwrite-1.0.28/src/mcp_server_appwrite/data/docs_index.npz
+name: mcp_server_appwrite-2.0.0/src/mcp_server_appwrite/data/docs_index.npz
 size: 35539301 bytes
 sha256: 5a6a4cef977b909050f1980567781c16720ec7eff17320fd7811a3c386b38a4e

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/src/mcp_server_appwrite/docs_search.py

@@ -144,10 +144,13 @@ class DocsSearch:
     def get_tool(self) -> types.Tool:
         return types.Tool(
             name=DOCS_TOOL_NAME,
+            title="Search Appwrite docs",
             annotations=types.ToolAnnotations(
+                title="Search Appwrite docs",
                 read_only_hint=True,
-                open_world_hint=True,
                 destructive_hint=False,
+                idempotent_hint=True,
+                open_world_hint=True,
             ),
             description=(
                 "Search the Appwrite documentation with a natural-language query and "

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/src/mcp_server_appwrite/error_classification.py

@@ -15,6 +15,7 @@ from appwrite_console.exception import AppwriteException
 
 ErrorCategory = Literal[
     "write_confirmation",
+    "wrong_call_tool",
     "appwrite_4xx",
     "appwrite_5xx",
     "sdk_validation",
@@ -25,6 +26,7 @@ ErrorCategory = Literal[
 ERROR_CATEGORIES: frozenset[str] = frozenset(
     {
         "write_confirmation",
+        "wrong_call_tool",
         "appwrite_4xx",
         "appwrite_5xx",
         "sdk_validation",
@@ -38,6 +40,12 @@ class WriteConfirmationRequired(RuntimeError):
     """A mutating hidden tool was called without explicit confirmation."""
 
 
+class WrongCallTool(ValueError):
+    """A hidden tool was called through the public tool for the other
+    classification: a mutation through the read-only call tool, or a read
+    through the write call tool."""
+
+
 class HostedBinaryResponseTooLarge(ValueError):
     """A binary Appwrite response exceeded the hosted MCP memory-safe limit."""
 
@@ -72,6 +80,9 @@ def classify_tool_error(exc: BaseException) -> ErrorCategory:
     if any(isinstance(item, WriteConfirmationRequired) for item in chain):
         return "write_confirmation"
 
+    if any(isinstance(item, WrongCallTool) for item in chain):
+        return "wrong_call_tool"
+
     if any(isinstance(item, HostedBinaryResponseTooLarge) for item in chain):
         return "response_too_large"
 

{mcp_server_appwrite-1.0.28 → mcp_server_appwrite-2.0.0}/src/mcp_server_appwrite/error_monitoring.py

@@ -171,7 +171,7 @@ def _should_capture(exc: BaseException) -> bool:
         return False
 
     category = classify_tool_error(exc)
-    if category in {"write_confirmation", "appwrite_4xx"}:
+    if category in {"write_confirmation", "wrong_call_tool", "appwrite_4xx"}:
         return False
     # Pydantic validation errors are ValueError subclasses, but SDK response
     # validation is actionable model drift and must remain visible.