mcp-server-appwrite 2.3.1__tar.gz → 2.4.0__tar.gz

{mcp_server_appwrite-2.3.1 → mcp_server_appwrite-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-server-appwrite
-Version: 2.3.1
+Version: 2.4.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-2.3.1 → mcp_server_appwrite-2.4.0}/docs/documentation-search.md

@@ -20,6 +20,18 @@ otherwise the server boots without it.
 | `DOCS_SEARCH_MIN_SCORE` | No | `0.25` | Minimum cosine score for a match. |
 | `DOCS_SEARCH_LIMIT` | No | `5` (max `10`) | Default max pages returned. |
 
+## Search route
+
+The deprecated docs MCP server at `mcp-for-docs.appwrite.io` has no OAuth session to use, so it searches through this public route instead of the MCP endpoint:
+
+```bash
+curl -X POST https://mcp.appwrite.io/docs/search \
+  -H 'content-type: application/json' \
+  -d '{"query": "create a row"}'
+```
+
+It answers `{"results": [{"path", "title", "description", "score", "content"}]}` with up to 5 pages, `400` for an invalid query or one over 500 characters, `413` for a body over 16 KiB, and `502` when the embedding request fails. The route exists only when documentation search is available.
+
 ## Rebuilding the index
 
 Re-run when the docs change, then commit the refreshed artifact:

{mcp_server_appwrite-2.3.1 → mcp_server_appwrite-2.4.0}/src/mcp_server_appwrite/constants.py

@@ -114,6 +114,8 @@ DOCS_DEFAULT_LIMIT = 5
 DOCS_MAX_LIMIT = 10
 DOCS_DEFAULT_MIN_SCORE = 0.25
 DOCS_MIN_QUERY_LENGTH = 3
+DOCS_MAX_QUERY_LENGTH = 500
+DOCS_MAX_BODY_BYTES = 16 * 1024
 
 DATA_DIR = Path(__file__).parent / "data"
 INDEX_FILE = "docs_index.npz"

{mcp_server_appwrite-2.3.1 → mcp_server_appwrite-2.4.0}/src/mcp_server_appwrite/data/docs_index.npz

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
-name: mcp_server_appwrite-2.3.1/src/mcp_server_appwrite/data/docs_index.npz
+name: mcp_server_appwrite-2.4.0/src/mcp_server_appwrite/data/docs_index.npz
 size: 35820220 bytes
 sha256: 1d70caae9062ecf77513f23cee05e5c9c0c0213d0db8258316cd94b73ae20f38

{mcp_server_appwrite-2.3.1 → mcp_server_appwrite-2.4.0}/src/mcp_server_appwrite/docs_search.py

@@ -178,7 +178,10 @@ class DocsSearch:
             },
         )
 
-    def search(self, arguments: dict[str, Any] | None) -> list[ToolContent]:
+    def find(
+        self, arguments: dict[str, Any] | None
+    ) -> tuple[str, list[dict[str, Any]]]:
+        """Return the normalized query and its ranked pages."""
         arguments = arguments or {}
         query = str(arguments.get("query", "")).strip()
         if len(query) < DOCS_MIN_QUERY_LENGTH:
@@ -198,6 +201,10 @@ class DocsSearch:
                 "Documentation search embedding request failed. "
                 "Check OPENAI_API_KEY and outbound connectivity to OpenAI."
             ) from exc
+        return query, results
+
+    def search(self, arguments: dict[str, Any] | None) -> list[ToolContent]:
+        query, results = self.find(arguments)
 
         if not results:
             return [

{mcp_server_appwrite-2.3.1 → mcp_server_appwrite-2.4.0}/src/mcp_server_appwrite/http_app.py

@@ -13,6 +13,9 @@ Builds a single-tenant Starlette ASGI app for the served Appwrite project:
   following ``resource_metadata`` from the 401 challenge. Mirrors the Appwrite
   authorization server's discovery document verbatim.
 * ``/healthz`` — liveness probe.
+* ``/docs/search`` — public documentation search for the deprecated docs MCP
+  server, whose clients have no user to sign in. Results and limits are fixed, so
+  a call costs one small embedding.
 * ``/.well-known/openai-apps-challenge`` — public domain verification token.
 * ``/appwrite/webhooks/{id}`` — MCP Events ingress for Appwrite webhooks, only
   with the events flag on. Unauthenticated by bearer token: the Appwrite
@@ -39,6 +42,7 @@ from importlib.resources import files
 from types import FrameType
 from urllib.parse import urlsplit
 
+import anyio.to_thread
 import httpx
 import uvicorn
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
@@ -71,7 +75,14 @@ from .auth import (
     public_base_url,
     resource_metadata_url,
 )
-from .constants import CORS_HEADERS, SERVER_VERSION
+from .constants import (
+    CORS_HEADERS,
+    DOCS_DEFAULT_LIMIT,
+    DOCS_MAX_BODY_BYTES,
+    DOCS_MAX_QUERY_LENGTH,
+    SERVER_VERSION,
+)
+from .docs_search import DocsSearch
 from .events import protocol as events_protocol
 from .events.ingress import Ingress
 from .events.streams import Settings, Streams
@@ -449,6 +460,34 @@ async def oauth_authorize_proxy_endpoint(request: Request) -> Response:
     )
 
 
+def docs_search_endpoint(docs_search: DocsSearch):
+    async def endpoint(request: Request) -> JSONResponse:
+        try:
+            raw = b""
+            async for chunk in request.stream():
+                raw += chunk
+                if len(raw) > DOCS_MAX_BODY_BYTES:
+                    return JSONResponse({"error": "body_too_large"}, status_code=413)
+            body = json.loads(raw)
+            query = body.get("query") if isinstance(body, dict) else None
+            if not isinstance(query, str) or len(query) > DOCS_MAX_QUERY_LENGTH:
+                raise ValueError(
+                    f"query must be a string of at most {DOCS_MAX_QUERY_LENGTH} characters."
+                )
+            _query, results = await anyio.to_thread.run_sync(
+                docs_search.find,
+                {"query": query, "limit": DOCS_DEFAULT_LIMIT},
+                abandon_on_cancel=True,
+            )
+        except ValueError as error:
+            return JSONResponse({"error": str(error)}, status_code=400)
+        except RuntimeError as error:
+            return JSONResponse({"error": str(error)}, status_code=502)
+        return JSONResponse({"results": results})
+
+    return endpoint
+
+
 async def health_endpoint(request: Request) -> PlainTextResponse:
     return PlainTextResponse(f"appwrite-mcp {SERVER_VERSION} ok")
 
@@ -560,6 +599,17 @@ def build_app(
         Route("/favicon.ico", endpoint=favicon_ico_endpoint, methods=["GET"]),
         Route("/healthz", endpoint=health_endpoint, methods=["GET"]),
         *([ingress.route] if ingress is not None else []),
+        *(
+            [
+                Route(
+                    "/docs/search",
+                    endpoint=docs_search_endpoint(operator.docs_search),
+                    methods=["POST"],
+                )
+            ]
+            if operator.docs_search is not None
+            else []
+        ),
         Route(
             "/",
             endpoint=mcp_endpoint,

{mcp_server_appwrite-2.3.1 → mcp_server_appwrite-2.4.0}/src/mcp_server_appwrite/operator.py

@@ -182,6 +182,10 @@ class Operator:
     def docs_enabled(self) -> bool:
         return self._docs_search is not None
 
+    @property
+    def docs_search(self) -> DocsSearch | None:
+        return self._docs_search
+
     def get_public_tools(self, *, apps: bool = False) -> list[types.Tool]:
         """The exposed tools, with the MCP Apps view tools when ``apps``."""
         return [public.tool for public in self._tools(apps).values()]

{mcp_server_appwrite-2.3.1 → mcp_server_appwrite-2.4.0}/tests/e2e/test_tools.py

@@ -19,10 +19,14 @@ import base64
 import json
 import unittest
 from typing import Any
+from unittest import mock
 from urllib.parse import unquote
 
+import httpx
 from support import PNG, SCOPES, TOKEN, Client, Cloud, Project, Server, collector
 
+from mcp_server_appwrite import docs_search
+
 PROJECT = "6630f1a2b3c4d5e6f7a8"
 STAGING = Project("internal-staging", buckets={"photos"}, name="Staging")
 """The project's ``staging`` environment, a project whose own ID is internal."""
@@ -63,6 +67,61 @@ def tearDownModule() -> None:
     cloud.close()
 
 
+class DocsSearchRoute(unittest.TestCase):
+    """``POST /docs/search``, which the deprecated docs MCP server calls without a
+    user. Only the OpenAI query embedding is stubbed; the index is the real one."""
+
+    def setUp(self) -> None:
+        patch = mock.patch.object(
+            docs_search,
+            "_default_embedder",
+            lambda: lambda _query: [1.0] + [0.0] * 1535,
+        )
+        patch.start()
+        self.addCleanup(patch.stop)
+
+    def server(self) -> Server:
+        return Server(
+            {
+                "APPWRITE_ENDPOINT": cloud.endpoint,
+                "DOCS_SEARCH_MIN_SCORE": "-1",
+                "OPENAI_API_KEY": "stubbed",
+            }
+        )
+
+    def test_returns_a_fixed_number_of_pages_without_auth(self):
+        with self.server() as server:
+            found = httpx.post(
+                f"{server.url}/docs/search",
+                json={"query": "create a row", "limit": 10},
+            )
+            self.assertEqual(found.status_code, 200)
+            results = found.json()["results"]
+            self.assertTrue(1 <= len(results) <= 5)
+            self.assertEqual(
+                set(results[0]), {"path", "title", "description", "score", "content"}
+            )
+
+    def test_rejects_invalid_queries_before_embedding_them(self):
+        with self.server() as server:
+            for invalid in (
+                {"query": "x"},
+                {"query": None},
+                {"query": "x" * 501},
+                ["create a row"],
+            ):
+                refused = httpx.post(f"{server.url}/docs/search", json=invalid)
+                self.assertEqual(refused.status_code, 400, invalid)
+
+            malformed = httpx.post(f"{server.url}/docs/search", content="nope")
+            self.assertEqual(malformed.status_code, 400)
+
+            oversized = httpx.post(
+                f"{server.url}/docs/search", content=b"x" * (16 * 1024 + 1)
+            )
+            self.assertEqual(oversized.status_code, 413)
+
+
 class ToolsFlow(unittest.TestCase):
     server: Server
     client: Client