Merge pull request #40 from appwrite/operator-hardening-and-ci

Introduce the Appwrite operator workflow and refresh CI

Author: ChiragAgg5k

.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dev dependencies
+        run: uv sync --group dev
+
+      - name: Check formatting
+        run: uv run --group dev black --check src tests
+
+  unit:
+    name: Unit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run unit tests
+        run: uv run python -m unittest discover -s tests/unit -v
+
+  integration:
+    name: Integration
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    env:
+      APPWRITE_PROJECT_ID: ${{ secrets.APPWRITE_PROJECT_ID }}
+      APPWRITE_API_KEY: ${{ secrets.APPWRITE_API_KEY }}
+      APPWRITE_ENDPOINT: ${{ secrets.APPWRITE_ENDPOINT }}
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --extra integration
+
+      - name: Run integration tests
+        run: uv run --extra integration python -m unittest discover -s tests/integration -v

.github/workflows/publish.yml

@@ -1,4 +1,5 @@
-name: Publish to PyPI
+name: Publish
+
 on:
   release:
     types: [published]
@@ -14,7 +15,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: "3.12"
 
       - name: Install build dependencies
         run: |
@@ -29,28 +30,3 @@ jobs:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: twine upload dist/*
-
-  publish-mcp:
-    name: Publish to MCP Registry
-    runs-on: ubuntu-latest
-    needs: publish
-    permissions:
-      id-token: write
-      contents: read
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v4
-      
-      - name: Wait for PyPI propagation
-        run: sleep 10
-
-      - name: Install MCP Publisher
-        run: |
-          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
-          chmod +x mcp-publisher
-
-      - name: Login to MCP Registry
-        run: ./mcp-publisher login github-oidc
-
-      - name: Publish to MCP Registry
-        run: ./mcp-publisher publish

README.md

@@ -2,7 +2,7 @@
 
 mcp-name: io.github.appwrite/mcp-for-api
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=appwrite&config=eyJjb21tYW5kIjoidXZ4IG1jcC1zZXJ2ZXItYXBwd3JpdGUgLS11c2VycyIsImVudiI6eyJBUFBXUklURV9BUElfS0VZIjoiPHlvdXItYXBpLWtleT4iLCJBUFBXUklURV9QUk9KRUNUX0lEIjoiPHlvdXItcHJvamVjdC1pZD4iLCJBUFBXUklURV9FTkRQT0lOVCI6Imh0dHBzOi8vPFJFR0lPTj4uY2xvdWQuYXBwd3JpdGUuaW8vdjEifX0%3D)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=appwrite&config=%7B%22command%22%3A%22uvx%20mcp-server-appwrite%22%2C%22env%22%3A%7B%22APPWRITE_API_KEY%22%3A%22%3Cyour-api-key%3E%22%2C%22APPWRITE_PROJECT_ID%22%3A%22%3Cyour-project-id%3E%22%2C%22APPWRITE_ENDPOINT%22%3A%22https%3A//%3CREGION%3E.cloud.appwrite.io/v1%22%7D%7D)
 
 ## Overview
 
@@ -23,6 +23,8 @@ A Model Context Protocol server for interacting with Appwrite's API. This server
 
 > Before launching the MCP server, you must setup an [Appwrite project](https://cloud.appwrite.io/) and create an API key with the necessary scopes enabled.
 
+The server validates the credentials and scopes required for its built-in Appwrite service set during startup. If the endpoint, project ID, API key, or scopes are wrong, the MCP server will fail to start instead of waiting for the first tool call to fail.
+
 Create a `.env` file in your working directory and add the following:
 
 ```env
@@ -64,7 +66,7 @@ When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed
 use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-server-appwrite*.
 
 ```bash
-uvx mcp-server-appwrite [args]
+uvx mcp-server-appwrite
 ```
 
 ### Using pip
@@ -75,30 +77,22 @@ pip install mcp-server-appwrite
 Then run the server using 
 
 ```bash
-python -m mcp_server_appwrite [args]
+python -m mcp_server_appwrite
 ```
 
-### Command-line arguments
+### Tool surface
 
-Both the `uv` and `pip` setup processes require certain arguments to enable MCP tools for various Appwrite APIs.
+The server no longer accepts service-selection or mode flags. It always starts in a compact workflow so the MCP client only sees a small operator-style surface while the full Appwrite catalog stays internal.
 
-> When an MCP tool is enabled, the tool's definition is passed to the LLM, using up tokens from the model's available context window. As a result, the effective context window is reduced.  
->  
-> The default Appwrite MCP server ships with only the Databases tools (our most commonly used API) enabled to stay within these limits. Additional tools can be enabled by using the flags below.
+- Only 2 MCP tools are exposed to the model:
+  - `appwrite_search_tools`
+  - `appwrite_call_tool`
+- The full Appwrite tool catalog stays internal and is searched at runtime.
+- Large tool outputs are stored as MCP resources and returned as preview text plus a resource URI.
+- Mutating hidden tools require `confirm_write=true`.
+- The server automatically registers all supported Appwrite services except the legacy Databases API.
 
-| Argument | Description |
-| --- | --- |
-| `--tablesdb` | Enables the TablesDB API |
-| `--users` | Enables the Users API |
-| `--teams` | Enables the Teams API |
-| `--storage` | Enables the Storage API |
-| `--functions` | Enables the Functions API |
-| `--messaging` | Enables the Messaging API |
-| `--locale` | Enables the Locale API |
-| `--avatars` | Enables the Avatars API |
-| `--sites` | Enables the Sites API |
-| `--all` | Enables all Appwrite APIs |
-| `--databases` | Enables the Legacy Databases API |
+If you still have older MCP configs that pass flags such as `--mode` or `--users`, remove them.
 
 ## Usage with Claude Desktop
 
@@ -184,7 +178,7 @@ Head to Windsurf `Settings > Cascade > Model Context Protocol (MCP) Servers` and
   "servers": {
     "appwrite": {
       "command": "uvx",
-      "args": ["mcp-server-appwrite", "--users"],
+      "args": ["mcp-server-appwrite"],
       "env": {
         "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
         "APPWRITE_API_KEY": "<YOUR_API_KEY>",
@@ -206,7 +200,7 @@ Head to Windsurf `Settings > Cascade > Model Context Protocol (MCP) Servers` and
 ### Clone the repository
 
 ```bash
-git clone https://github.com/appwrite/mcp.git
+git clone https://github.com/appwrite/mcp-for-api.git
 ```
 
 ### Install `uv`
@@ -251,6 +245,22 @@ source .venv/bin/activate
 uv run -v --directory ./ mcp-server-appwrite
 ```
 
+## Testing
+
+### Unit tests
+
+```bash
+uv run python -m unittest discover -s tests/unit -v
+```
+
+### Live integration tests
+
+These tests create and delete real Appwrite resources against a real Appwrite project. They run automatically when valid Appwrite credentials are available in the environment or `.env`.
+
+```bash
+uv run --extra integration python -m unittest discover -s tests/integration -v
+```
+
 ## Debugging
 
 You can use the MCP inspector to debug the server. 

pyproject.toml

@@ -1,18 +1,35 @@
 [project]
 name = "mcp-server-appwrite"
-version = "0.3.3"
+version = "0.4"
 description = "MCP (Model Context Protocol) server for Appwrite"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "appwrite>=13.4.1",
     "docstring-parser>=0.16",
     "mcp[cli]>=1.3.0",
+    "python-dotenv>=1.0.1",
+]
+
+[project.optional-dependencies]
+integration = [
+    "argon2-cffi>=23.1.0",
+    "bcrypt>=4.1.2",
+    "passlib>=1.7.4",
+    "pycryptodome>=3.20.0",
+]
+
+[dependency-groups]
+dev = [
+    "black>=25.1.0",
 ]
 
 [project.scripts]
 mcp-server-appwrite = "mcp_server_appwrite.__main__:main"
 
+[tool.black]
+target-version = ["py312"]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

server.json

@@ -2,14 +2,14 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "io.github.appwrite/mcp-for-api",
   "description": "MCP (Model Context Protocol) server for Appwrite",
-  "version": "0.3.3",
+  "version": "0.4",
   "repository": {
     "url": "https://github.com/appwrite/mcp-for-api",
     "source": "github"
   },
   "packages": [
     {
-      "version": "0.3.3",
+      "version": "0.4",
       "registryType": "pypi",
       "identifier": "mcp-server-appwrite",
       "transport": {

src/mcp_server_appwrite/__init__.py

@@ -1,11 +1,16 @@
-from . import server
 import asyncio
+import sys
 
 
 def main():
     """Main entry point for the package."""
-    asyncio.run(server._run())
+    from .server import _run
 
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        print("[appwrite-mcp] Shutdown requested", file=sys.stderr, flush=True)
+        return 0
 
-# Optionally expose other important items at package level
-__all__ = ["main", "server"]
+
+__all__ = ["main"]

src/mcp_server_appwrite/__main__.py

@@ -1,4 +1,4 @@
 from mcp_server_appwrite import main
 
 if __name__ == "__main__":
-    main()
+    main()