mcp-server-appwrite 0.8.0__tar.gz → 0.8.2__tar.gz

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/.github/workflows/ci.yml

@@ -33,6 +33,9 @@ jobs:
       - name: Check formatting
         run: uv run --group dev black --check src tests
 
+      - name: Type check
+        run: uv run --group dev pyright
+
   unit:
     name: Unit
     runs-on: ubuntu-latest

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/AGENTS.md

@@ -93,20 +93,27 @@ Run these locally before opening a PR. They mirror the `CI` workflow
    ```
    Run `uv run --group dev black src tests` (without `--check`) to auto-fix.
 
-3. **Unit tests** (`unit` job)
+3. **Type check** (`lint` job)
+   ```bash
+   uv run --group dev pyright
+   ```
+   Pyright config lives in `pyproject.toml` (`[tool.pyright]`): basic mode over
+   `src/`, Python 3.12, resolving against the project `.venv`.
+
+4. **Unit tests** (`unit` job)
    ```bash
    uv sync
    uv run python -m unittest discover -s tests/unit -v
    ```
    Fast, no external services or credentials required.
 
-4. **Docker build** (`docker` job)
+5. **Docker build** (`docker` job)
    ```bash
    docker build -t appwrite-mcp:ci .
    ```
    The hosted HTTP image must build cleanly.
 
-5. **Integration tests** (`integration` job) — *CI runs these only for pushes and
+6. **Integration tests** (`integration` job) — *CI runs these only for pushes and
    for PRs from branches on the same repo (not forks).* They create and delete
    **real** Appwrite resources, so they need live credentials and are skipped
    when absent:

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-server-appwrite
-Version: 0.8.0
+Version: 0.8.2
 Summary: MCP (Model Context Protocol) server for Appwrite
 License-File: LICENSE
 Requires-Python: >=3.12

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-server-appwrite"
-version = "0.8.0"
+version = "0.8.2"
 description = "MCP (Model Context Protocol) server for Appwrite"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -32,6 +32,7 @@ integration = [
 dev = [
     "black>=25.1.0",
     "ruff>=0.10.0",
+    "pyright>=1.1.390",
     # Only needed by scripts/build_docs_index.py to (re)build the docs index.
     "pyyaml>=6.0",
 ]
@@ -56,6 +57,13 @@ line-length = 88
 select = ["E", "F", "W", "I"]
 ignore = ["E501"]
 
+[tool.pyright]
+pythonVersion = "3.12"
+include = ["src"]
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "basic"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/src/mcp_server_appwrite/auth.py

@@ -19,16 +19,19 @@ import sys
 import time
 from urllib.parse import urlsplit, urlunsplit
 
-import anyio
 import httpx
 import jwt
+from anyio import to_thread
 from jwt import PyJWKClient
 from mcp.server.auth.provider import AccessToken, TokenVerifier
 
 from . import telemetry
-
-DEFAULT_ENDPOINT = "https://cloud.appwrite.io/v1"
-DEFAULT_PROJECT_ID = "console"
+from .constants import (
+    DEFAULT_ENDPOINT,
+    DEFAULT_PROJECT_ID,
+    DISCOVERY_TTL_SECONDS,
+    PREFERRED_SCOPES,
+)
 
 
 def _log(message: str) -> None:
@@ -69,10 +72,30 @@ def resource_metadata_url() -> str:
     return urlunsplit((parts.scheme, parts.netloc, path, "", ""))
 
 
-# Cache of scopes_supported, keyed by served project id (process lifetime; the
-# project OAuth config is effectively static). Failed lookups raise and are not
-# cached, so they retry.
-_discovery_cache: dict[str, dict] = {}
+def preferred_scopes() -> list[str]:
+    override = os.getenv("MCP_OAUTH_SCOPES", "").split()
+    return override or list(PREFERRED_SCOPES)
+
+
+# Discovery cache keyed by served project id: (monotonic fetch time, document).
+# Entries are refreshed after a TTL so authorization-server changes (issuer host,
+# scope model) propagate without a redeploy; if a refresh fails, the stale copy
+# keeps serving so an authorization-server blip doesn't take the MCP down.
+_discovery_cache: dict[str, tuple[float, dict]] = {}
+
+
+def _cached_discovery(project_id: str, *, allow_stale: bool = False) -> dict | None:
+    entry = _discovery_cache.get(project_id)
+    if entry is None:
+        return None
+    fetched_at, document = entry
+    if allow_stale or time.monotonic() - fetched_at < DISCOVERY_TTL_SECONDS:
+        return document
+    return None
+
+
+def _store_discovery(project_id: str, document: dict) -> None:
+    _discovery_cache[project_id] = (time.monotonic(), document)
 
 
 def discovery_url() -> str:
@@ -91,47 +114,68 @@ def _validate_discovery(doc: dict, url: str) -> dict:
 
 async def authorization_server_metadata() -> dict:
     project_id = configured_project_id()
-    cached = _discovery_cache.get(project_id)
+    cached = _cached_discovery(project_id)
     if cached is not None:
         return cached
 
     url = discovery_url()
-    async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
-        resp = await client.get(url)
-        resp.raise_for_status()
-        metadata = _validate_discovery(resp.json(), url)
-
-    _discovery_cache[project_id] = metadata
+    try:
+        async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
+            resp = await client.get(url)
+            resp.raise_for_status()
+            metadata = _validate_discovery(resp.json(), url)
+    except Exception as exc:
+        stale = _cached_discovery(project_id, allow_stale=True)
+        if stale is not None:
+            _log(f"Discovery refresh failed ({exc}); serving stale metadata.")
+            return stale
+        raise
+
+    _store_discovery(project_id, metadata)
     return metadata
 
 
 def authorization_server_metadata_sync() -> dict:
     project_id = configured_project_id()
-    cached = _discovery_cache.get(project_id)
+    cached = _cached_discovery(project_id)
     if cached is not None:
         return cached
 
     url = discovery_url()
-    resp = httpx.get(url, timeout=10.0, follow_redirects=True)
-    resp.raise_for_status()
-    metadata = _validate_discovery(resp.json(), url)
-    _discovery_cache[project_id] = metadata
+    try:
+        resp = httpx.get(url, timeout=10.0, follow_redirects=True)
+        resp.raise_for_status()
+        metadata = _validate_discovery(resp.json(), url)
+    except Exception as exc:
+        stale = _cached_discovery(project_id, allow_stale=True)
+        if stale is not None:
+            _log(f"Discovery refresh failed ({exc}); serving stale metadata.")
+            return stale
+        raise
+
+    _store_discovery(project_id, metadata)
     return metadata
 
 
-async def supported_scopes() -> list[str]:
-    """Scopes advertised in the protected-resource metadata, sourced live from the
-    served project's authorization-server discovery (`scopes_supported`). This is
-    exactly the set the project's OAuth server will grant, so it never drifts from
-    the tool surface. Raises if discovery is unreachable or malformed (the
-    authorization server is the same Appwrite deployment this MCP depends on)."""
-    metadata = await authorization_server_metadata()
-    scopes = metadata.get("scopes_supported")
-    if not isinstance(scopes, list):
+def _advertised_scopes(metadata: dict) -> list[str]:
+    """The scope set to advertise: the preferred scopes intersected with the
+    authorization server's live ``scopes_supported`` (so a renamed/removed scope
+    is never advertised). Falls back to mirroring the full discovery list when
+    none of the preferred scopes exist — e.g. a self-hosted project with a
+    custom, compact scope catalog."""
+    discovered = metadata.get("scopes_supported")
+    if not isinstance(discovered, list):
         raise ValueError(
             f"authorization server discovery missing scopes_supported: {discovery_url()}"
         )
-    return scopes
+    scopes = [scope for scope in preferred_scopes() if scope in discovered]
+    if scopes:
+        return scopes
+    _log(
+        "None of the preferred scopes are in the authorization server's "
+        "scopes_supported; advertising the full discovered list."
+    )
+    return discovered
 
 
 def build_resource_metadata(scopes: list[str], authorization_servers=None) -> dict:
@@ -145,14 +189,10 @@ def build_resource_metadata(scopes: list[str], authorization_servers=None) -> di
 
 
 async def protected_resource_metadata() -> dict:
-    """RFC 9728 Protected Resource Metadata, with scopes sourced from AS discovery."""
+    """RFC 9728 Protected Resource Metadata, with scopes validated against AS
+    discovery."""
     metadata = await authorization_server_metadata()
-    scopes = metadata.get("scopes_supported")
-    if not isinstance(scopes, list):
-        raise ValueError(
-            f"authorization server discovery missing scopes_supported: {discovery_url()}"
-        )
-    return build_resource_metadata(scopes, [metadata["issuer"]])
+    return build_resource_metadata(_advertised_scopes(metadata), [metadata["issuer"]])
 
 
 def project_id_from_issuer(iss: str | None) -> str | None:
@@ -286,7 +326,7 @@ class AppwriteTokenVerifier(TokenVerifier):
 
     async def verify_token(self, token: str) -> AccessToken | None:
         start = time.monotonic()
-        access_token = await anyio.to_thread.run_sync(self._verify_sync, token)
+        access_token = await to_thread.run_sync(self._verify_sync, token)
         duration = time.monotonic() - start
         if access_token is None:
             # The specific rejection reason was already counted in _verify_sync;

mcp_server_appwrite-0.8.2/src/mcp_server_appwrite/constants.py

@@ -0,0 +1,144 @@
+"""Single home for the package's constants, grouped by the module that uses them."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from appwrite.models.bucket import Bucket
+from appwrite.models.database import Database
+from appwrite.models.function import Function
+from appwrite.models.message import Message
+from appwrite.models.site import Site
+from appwrite.models.team import Team
+from appwrite.models.user import User
+
+# --- server ---------------------------------------------------------------
+
+SERVER_VERSION = "0.8.2"
+
+DEFAULT_ENDPOINT = "https://cloud.appwrite.io/v1"
+DEFAULT_TRANSPORT = "stdio"
+TRANSPORTS = {"stdio", "http"}
+VALIDATION_SERVICE_ORDER = (
+    "tables_db",
+    "users",
+    "teams",
+    "functions",
+    "sites",
+    "storage",
+    "messaging",
+    "locale",
+    "avatars",
+)
+
+# Service modules in the Appwrite SDK to skip (none by default — every service the
+# installed SDK ships is exposed). Add a module name here to hide a service.
+EXCLUDED_SERVICES: frozenset[str] = frozenset()
+
+MAX_FETCH_BYTES = 25 * 1024 * 1024  # 25 MB cap on server-fetched files
+MAX_INLINE_BYTES = 256 * 1024  # 256 KB cap on decoded inline content
+FETCH_TIMEOUT_SECONDS = 30.0
+FETCH_MAX_REDIRECTS = 5
+
+HOSTED_PATH_GUIDANCE = (
+    "The hosted Appwrite MCP server cannot read local file paths. For '{param}', pass a "
+    'public URL as {{"url": "https://..."}} (preferred), or a small file inline as '
+    '{{"filename": "...", "content": "<base64>", "encoding": "base64"}}.'
+)
+
+# --- auth -----------------------------------------------------------------
+
+DEFAULT_PROJECT_ID = "console"
+
+PREFERRED_SCOPES = [
+    "openid",
+    "profile",
+    "email",
+    "all",
+    "project:all",
+    "organization:all",
+]
+
+DISCOVERY_TTL_SECONDS = 300.0
+
+# --- http_app -------------------------------------------------------------
+
+CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version",
+    "Access-Control-Expose-Headers": "Mcp-Session-Id, WWW-Authenticate",
+}
+
+# --- operator -------------------------------------------------------------
+
+SEARCH_LIMIT = 8
+PREVIEW_THRESHOLD = 800
+RESULT_STORE_SIZE = 50
+CATALOG_URI = "appwrite://operator/catalog"
+RESULT_URI_TEMPLATE = "appwrite://operator/results/{result_id}"
+VERBS = {"list", "get", "create", "update", "delete"}
+READ_VERBS = {"list", "get"}
+CREATE_HINTS = {"add", "build", "create", "insert", "make", "new", "provision"}
+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
+DOCS_MAX_LIMIT = 10
+DOCS_DEFAULT_MIN_SCORE = 0.25
+DOCS_MIN_QUERY_LENGTH = 3
+
+DATA_DIR = Path(__file__).parent / "data"
+VECTORS_FILE = "docs_index.npz"
+META_FILE = "docs_index_meta.json"
+
+# --- context --------------------------------------------------------------
+
+SERVICE_PROBES = {
+    "tablesdb": {
+        "path": "/tablesdb",
+        "items_key": "databases",
+        "model": Database,
+    },
+    "users": {
+        "path": "/users",
+        "items_key": "users",
+        "model": User,
+    },
+    "storage": {
+        "path": "/storage/buckets",
+        "items_key": "buckets",
+        "model": Bucket,
+    },
+    "functions": {
+        "path": "/functions",
+        "items_key": "functions",
+        "model": Function,
+    },
+    "sites": {
+        "path": "/sites",
+        "items_key": "sites",
+        "model": Site,
+    },
+    "messaging": {
+        "path": "/messaging/messages",
+        "items_key": "messages",
+        "model": Message,
+    },
+    "teams": {
+        "path": "/teams",
+        "items_key": "teams",
+        "model": Team,
+    },
+}
+
+REDACTED_KEYS = {"password", "secret", "key", "token", "otp", "cookie", "session"}
+
+# --- telemetry ------------------------------------------------------------
+
+ACTIVE_WINDOW_SECONDS = 300.0  # rolling window for "active users/clients" gauges

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/src/mcp_server_appwrite/context.py

@@ -5,57 +5,14 @@ from typing import Any
 
 from appwrite.client import Client
 from appwrite.exception import AppwriteException
-from appwrite.models.bucket import Bucket
-from appwrite.models.database import Database
-from appwrite.models.function import Function
-from appwrite.models.message import Message
 from appwrite.models.project import Project
-from appwrite.models.site import Site
 from appwrite.models.team import Team
 from appwrite.models.user import User
 from appwrite.query import Query
 
-ContextClientFactory = Callable[[str | None, str | None], Client]
+from .constants import REDACTED_KEYS, SERVICE_PROBES
 
-SERVICE_PROBES = {
-    "tablesdb": {
-        "path": "/tablesdb",
-        "items_key": "databases",
-        "model": Database,
-    },
-    "users": {
-        "path": "/users",
-        "items_key": "users",
-        "model": User,
-    },
-    "storage": {
-        "path": "/storage/buckets",
-        "items_key": "buckets",
-        "model": Bucket,
-    },
-    "functions": {
-        "path": "/functions",
-        "items_key": "functions",
-        "model": Function,
-    },
-    "sites": {
-        "path": "/sites",
-        "items_key": "sites",
-        "model": Site,
-    },
-    "messaging": {
-        "path": "/messaging/messages",
-        "items_key": "messages",
-        "model": Message,
-    },
-    "teams": {
-        "path": "/teams",
-        "items_key": "teams",
-        "model": Team,
-    },
-}
-
-REDACTED_KEYS = {"password", "secret", "key", "token", "otp", "cookie", "session"}
+ContextClientFactory = Callable[[str | None, str | None], Client]
 
 
 def get_appwrite_context(

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/src/mcp_server_appwrite/docs_search.py

@@ -22,20 +22,20 @@ from typing import Any, Callable
 import mcp.types as types
 
 from . import telemetry
+from .constants import (
+    DATA_DIR,
+    DOCS_DEFAULT_LIMIT,
+    DOCS_DEFAULT_MIN_SCORE,
+    DOCS_MAX_LIMIT,
+    DOCS_MIN_QUERY_LENGTH,
+    DOCS_TOOL_NAME,
+    EMBED_MODEL,
+    META_FILE,
+    VECTORS_FILE,
+)
 
 ToolContent = types.TextContent | types.ImageContent | types.EmbeddedResource
 
-TOOL_NAME = "appwrite_search_docs"
-EMBED_MODEL = "text-embedding-3-small"
-DEFAULT_LIMIT = 5
-MAX_LIMIT = 10
-DEFAULT_MIN_SCORE = 0.25
-MIN_QUERY_LENGTH = 3
-
-DATA_DIR = Path(__file__).parent / "data"
-VECTORS_FILE = "docs_index.npz"
-META_FILE = "docs_index_meta.json"
-
 # An embedder maps a query string to its embedding vector.
 Embedder = Callable[[str], list[float]]
 
@@ -63,7 +63,7 @@ def _clamp_limit(value: Any, default: int) -> int:
     limit = int(value)
     if limit < 1:
         raise ValueError("limit must be at least 1.")
-    return min(limit, MAX_LIMIT)
+    return min(limit, DOCS_MAX_LIMIT)
 
 
 class DocsSearch:
@@ -80,14 +80,14 @@ class DocsSearch:
         data_dir: Path | None = None,
         embedder: Embedder | None = None,
         min_score: float | None = None,
-        default_limit: int = DEFAULT_LIMIT,
+        default_limit: int = DOCS_DEFAULT_LIMIT,
     ):
         self._data_dir = data_dir or DATA_DIR
         self._embedder = embedder if embedder is not None else _default_embedder()
         self._min_score = (
             min_score
             if min_score is not None
-            else float(os.getenv("DOCS_SEARCH_MIN_SCORE", DEFAULT_MIN_SCORE))
+            else float(os.getenv("DOCS_SEARCH_MIN_SCORE", DOCS_DEFAULT_MIN_SCORE))
         )
         self._default_limit = int(os.getenv("DOCS_SEARCH_LIMIT", default_limit))
         self._vectors = None  # np.ndarray [N, D], L2-normalized
@@ -118,7 +118,7 @@ class DocsSearch:
 
     def get_tool(self) -> types.Tool:
         return types.Tool(
-            name=TOOL_NAME,
+            name=DOCS_TOOL_NAME,
             description=(
                 "Search the Appwrite documentation with a natural-language query and "
                 "return the most relevant documentation pages with their full content. "
@@ -136,7 +136,7 @@ class DocsSearch:
                     "limit": {
                         "type": "integer",
                         "minimum": 1,
-                        "maximum": MAX_LIMIT,
+                        "maximum": DOCS_MAX_LIMIT,
                         "description": f"Maximum number of pages to return. Defaults to {self._default_limit}.",
                     },
                 },
@@ -148,9 +148,9 @@ class DocsSearch:
     def search(self, arguments: dict[str, Any] | None) -> list[ToolContent]:
         arguments = arguments or {}
         query = str(arguments.get("query", "")).strip()
-        if len(query) < MIN_QUERY_LENGTH:
+        if len(query) < DOCS_MIN_QUERY_LENGTH:
             raise ValueError(
-                f"query must be at least {MIN_QUERY_LENGTH} characters long."
+                f"query must be at least {DOCS_MIN_QUERY_LENGTH} characters long."
             )
         if not self.available:
             raise RuntimeError(
@@ -185,6 +185,12 @@ class DocsSearch:
         """Return the ranked pages and the embedding call's duration in seconds."""
         import numpy as np
 
+        # _rank is only reachable when the index is loaded and an embedder exists
+        # (guarded by `available`); narrow the optionals for the type checker.
+        assert self._embedder is not None
+        assert self._vectors is not None
+        assert self._chunk_page is not None
+
         embed_start = time.monotonic()
         embedding = np.asarray(self._embedder(query), dtype=np.float32)
         embedding_duration_s = time.monotonic() - embed_start

{mcp_server_appwrite-0.8.0 → mcp_server_appwrite-0.8.2}/src/mcp_server_appwrite/http_app.py

@@ -29,7 +29,7 @@ from starlette.middleware.authentication import AuthenticationMiddleware
 from starlette.requests import Request
 from starlette.responses import JSONResponse, PlainTextResponse
 from starlette.routing import Route
-from starlette.types import Receive, Scope, Send
+from starlette.types import ASGIApp, Receive, Scope, Send
 
 from . import telemetry
 from .auth import (
@@ -37,20 +37,13 @@ from .auth import (
     protected_resource_metadata,
     resource_metadata_url,
 )
+from .constants import CORS_HEADERS, SERVER_VERSION
 from .server import (
-    SERVER_VERSION,
     build_catalog_tools_manager,
     build_mcp_server,
     build_operator,
 )
 
-_CORS_HEADERS = {
-    "Access-Control-Allow-Origin": "*",
-    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
-    "Access-Control-Allow-Headers": "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version",
-    "Access-Control-Expose-Headers": "Mcp-Session-Id, WWW-Authenticate",
-}
-
 
 class HealthzAccessLogFilter(logging.Filter):
     """Drop noisy load-balancer health probes from uvicorn access logs."""
@@ -98,7 +91,7 @@ class RequireBearer:
     against the token's granted scopes), so the gate only requires a valid token.
     """
 
-    def __init__(self, app: object) -> None:
+    def __init__(self, app: ASGIApp) -> None:
         self.app = app
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
@@ -123,7 +116,7 @@ class RequireBearer:
         await self.app(scope, receive, send)
 
     async def _preflight(self, send: Send) -> None:
-        headers = [(k.lower().encode(), v.encode()) for k, v in _CORS_HEADERS.items()]
+        headers = [(k.lower().encode(), v.encode()) for k, v in CORS_HEADERS.items()]
         await send({"type": "http.response.start", "status": 204, "headers": headers})
         await send({"type": "http.response.body", "body": b""})
 
@@ -137,7 +130,7 @@ def _has_authorization_header(scope: Scope) -> bool:
 
 async def protected_resource_metadata_endpoint(request: Request) -> JSONResponse:
     metadata = await protected_resource_metadata()
-    return JSONResponse(metadata, headers=_CORS_HEADERS)
+    return JSONResponse(metadata, headers=CORS_HEADERS)
 
 
 async def health_endpoint(request: Request) -> PlainTextResponse:
@@ -147,7 +140,7 @@ async def health_endpoint(request: Request) -> PlainTextResponse:
 def build_app() -> Starlette:
     telemetry.init_telemetry("http", SERVER_VERSION)
     tools_manager = build_catalog_tools_manager()
-    operator = build_operator(tools_manager)
+    operator = build_operator(tools_manager, store_results=False)
     server = build_mcp_server(operator, transport="http")
 
     # Streamable HTTP with SSE responses (the MCP SDK/ecosystem default). Stateless,