mcp-server-appwrite 0.4__tar.gz → 0.7.0__tar.gz

mcp_server_appwrite-0.7.0/.dockerignore

@@ -0,0 +1,12 @@
+.git
+.github
+.ruff_cache
+.venv
+__pycache__
+*.pyc
+.env
+.env.*
+!.env.example
+deploy
+images
+tests

mcp_server_appwrite-0.7.0/.env.example

@@ -0,0 +1,27 @@
+# Appwrite Cloud base endpoint. The served project's OAuth authorization server
+# lives under it at <APPWRITE_ENDPOINT>/oauth2/<APPWRITE_PROJECT_ID>.
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+
+# External URL clients use to reach THIS MCP server. Used to build the canonical
+# resource URI (<MCP_PUBLIC_URL>/mcp) and RFC 9728 metadata. For hosted
+# deployment, set this to your public HTTPS origin, for example
+# https://mcp.appwrite.io.
+MCP_PUBLIC_URL=http://localhost:8000
+
+# The single Appwrite project this MCP serves. Defaults to the Cloud console
+# project; override only for non-console deployments. Tokens issued by any other
+# project's OAuth server are rejected.
+# APPWRITE_PROJECT_ID=console
+
+# HTTP bind address.
+HOST=0.0.0.0
+PORT=8000
+
+# Optional. Enables appwrite_search_docs by embedding incoming docs queries.
+# OPENAI_API_KEY=sk-...
+
+# ── Integration tests only (not used by the running server) ─────────────────
+# The live integration suite authenticates to the Appwrite API with an API key
+# and runs against APPWRITE_PROJECT_ID (above).
+# APPWRITE_PROJECT_ID=your-project-id
+# APPWRITE_API_KEY=your-api-key

{mcp_server_appwrite-0.4 → mcp_server_appwrite-0.7.0}/.github/workflows/ci.yml

@@ -3,26 +3,33 @@ name: CI
 on:
   pull_request:
   push:
+    branches:
+      - main
 
 jobs:
-  format:
-    name: Format
+  lint:
+    name: Lint & format
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: "0.11.22"
 
       - name: Install dev dependencies
         run: uv sync --group dev
 
+      - name: Lint
+        run: uv run --group dev ruff check src tests
+
       - name: Check formatting
         run: uv run --group dev black --check src tests
 
@@ -31,15 +38,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: "0.11.22"
 
       - name: Install dependencies
         run: uv sync
@@ -47,6 +56,16 @@ jobs:
       - name: Run unit tests
         run: uv run python -m unittest discover -s tests/unit -v
 
+  docker:
+    name: Docker build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Build hosted HTTP image
+        run: docker build -t appwrite-mcp:ci .
+
   integration:
     name: Integration
     runs-on: ubuntu-latest
@@ -57,15 +76,17 @@ jobs:
       APPWRITE_ENDPOINT: ${{ secrets.APPWRITE_ENDPOINT }}
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: "0.11.22"
 
       - name: Install dependencies
         run: uv sync --extra integration

mcp_server_appwrite-0.7.0/.github/workflows/production.yml

@@ -0,0 +1,88 @@
+name: Production deployment
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  ENVIRONMENT: production
+  PROJECT: mcp
+  DECLARATIVE_OWNER: appwrite-labs
+  DECLARATIVE_REPOSITORY: assets-applications
+  REGISTRY_GITHUB: ghcr.io
+  REGISTRY_DOCKERHUB: docker.io
+  IMAGE_NAME: appwrite/mcp
+  TAG: ${{ github.event.release.tag_name || github.sha }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ${{ env.REGISTRY_GITHUB }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ${{ env.REGISTRY_DOCKERHUB }}
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ env.REGISTRY_GITHUB }}/${{ env.IMAGE_NAME }}:${{ env.TAG }}
+            ${{ env.REGISTRY_DOCKERHUB }}/${{ env.IMAGE_NAME }}:${{ env.TAG }}
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get token for ${{ env.DECLARATIVE_REPOSITORY }}
+        id: app-token
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
+        with:
+          app-id: ${{ vars.DECLARATIVE_DEPLOYMENT_GITHUB_APP_ID }}
+          private-key: ${{ secrets.DECLARATIVE_DEPLOYMENT_GITHUB_APP_PRIVATE_KEY }}
+          owner: ${{ env.DECLARATIVE_OWNER }}
+          repositories: ${{ env.DECLARATIVE_REPOSITORY }}
+
+      - name: Checkout ${{ env.DECLARATIVE_REPOSITORY }}
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          repository: ${{ env.DECLARATIVE_OWNER }}/${{ env.DECLARATIVE_REPOSITORY }}
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Update image tag
+        run: yq -i '.["mcp"].image.tag = strenv(TAG)' ${{ env.ENVIRONMENT }}/${{ env.PROJECT }}/fra1.yaml
+
+      - name: Commit and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add ${{ env.ENVIRONMENT }}/${{ env.PROJECT }}/fra1.yaml
+          if git diff --cached --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "chore(${{ env.ENVIRONMENT }}): ${{ env.PROJECT }} image tag to ${{ env.TAG }}"
+            git push
+          fi

{mcp_server_appwrite-0.4 → mcp_server_appwrite-0.7.0}/.github/workflows/publish.yml

@@ -10,17 +10,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 
       - name: Install build dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install build twine
+          pip install build==1.5.0 twine==6.2.0
 
       - name: Build package
         run: python -m build

mcp_server_appwrite-0.7.0/.github/workflows/staging.yml

@@ -0,0 +1,89 @@
+name: Staging deployment
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  ENVIRONMENT: staging
+  PROJECT: mcp
+  DECLARATIVE_OWNER: appwrite-labs
+  DECLARATIVE_REPOSITORY: assets-applications
+  REGISTRY_GITHUB: ghcr.io
+  REGISTRY_DOCKERHUB: docker.io
+  IMAGE_NAME: appwrite/mcp
+  TAG: ${{ github.sha }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ${{ env.REGISTRY_GITHUB }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ${{ env.REGISTRY_DOCKERHUB }}
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ env.REGISTRY_GITHUB }}/${{ env.IMAGE_NAME }}:${{ env.TAG }}
+            ${{ env.REGISTRY_DOCKERHUB }}/${{ env.IMAGE_NAME }}:${{ env.TAG }}
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get token for ${{ env.DECLARATIVE_REPOSITORY }}
+        id: app-token
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
+        with:
+          app-id: ${{ vars.DECLARATIVE_DEPLOYMENT_GITHUB_APP_ID }}
+          private-key: ${{ secrets.DECLARATIVE_DEPLOYMENT_GITHUB_APP_PRIVATE_KEY }}
+          owner: ${{ env.DECLARATIVE_OWNER }}
+          repositories: ${{ env.DECLARATIVE_REPOSITORY }}
+
+      - name: Checkout ${{ env.DECLARATIVE_REPOSITORY }}
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          repository: ${{ env.DECLARATIVE_OWNER }}/${{ env.DECLARATIVE_REPOSITORY }}
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Update image tag
+        run: yq -i '.["mcp"].image.tag = strenv(TAG)' ${{ env.ENVIRONMENT }}/${{ env.PROJECT }}/fra1.yaml
+
+      - name: Commit and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add ${{ env.ENVIRONMENT }}/${{ env.PROJECT }}/fra1.yaml
+          if git diff --cached --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "chore(${{ env.ENVIRONMENT }}): ${{ env.PROJECT }} image tag to ${{ env.TAG }}"
+            git push
+          fi

mcp_server_appwrite-0.7.0/AGENTS.md

@@ -0,0 +1,140 @@
+# AGENTS.md
+
+Guidance for AI agents and human contributors working in this repository.
+
+## What this repo is
+
+`mcp-server-appwrite` is a [Model Context Protocol](https://modelcontextprotocol.io)
+server for Appwrite. It exposes Appwrite's API to MCP clients as a small set of
+operator-style tools, supporting two deployments from one codebase:
+
+- **Cloud (hosted HTTP):** a Starlette ASGI app that acts as an OAuth 2.1
+  Resource Server. It validates the client's bearer token and forwards it to the
+  Appwrite REST API. Served at `mcp.appwrite.io/mcp`.
+- **Self-hosted (`stdio`):** runs locally and authenticates with a project API
+  key (`APPWRITE_PROJECT_ID`, `APPWRITE_API_KEY`, `APPWRITE_ENDPOINT`).
+
+Python ≥ 3.12, packaged with `hatchling`, managed with `uv`.
+
+## Architecture
+
+Source lives in `src/mcp_server_appwrite/`:
+
+| File | Responsibility |
+| --- | --- |
+| `__main__.py` / `server.py` | Entry point, CLI args, transport selection (`--transport stdio\|http`), service registration, low-level MCP server. |
+| `http_app.py` | Hosted Streamable-HTTP transport: `/mcp`, RFC 9728 protected-resource metadata, `/healthz`. |
+| `auth.py` | OAuth 2.1 resource-server layer — bearer-token validation against the project's Appwrite authorization server. |
+| `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. |
+| `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. |
+| `data/` | Committed docs index artifact (`docs_index.npz`, `docs_index_meta.json`), shipped in the wheel/image. |
+
+`scripts/build_docs_index.py` rebuilds the docs index (requires `OPENAI_API_KEY`).
+
+### 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 Appwrite catalog (25 services)
+stays internal and is searched at runtime. Mutating hidden tools require
+`confirm_write=true`. Large outputs are stored as MCP resources and returned as a
+preview + resource URI.
+
+## Local development
+
+```bash
+# Install uv, then sync deps
+uv sync                      # runtime deps
+uv sync --group dev          # + black, ruff (lint/format)
+uv sync --extra integration  # + integration-test deps
+
+# Run hosted HTTP transport
+MCP_PUBLIC_URL=http://localhost:8000 APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1 \
+  uv run mcp-server-appwrite --transport http
+
+# Run self-hosted stdio transport
+APPWRITE_ENDPOINT=http://localhost:9501/v1 \
+APPWRITE_PROJECT_ID=<id> APPWRITE_API_KEY=<key> \
+  uv run mcp-server-appwrite
+
+# Or via Docker (hosted HTTP/OAuth)
+docker compose up --build    # compose.yaml; endpoint at http://localhost:8000/mcp
+```
+
+## Pre-PR checklist
+
+Run these locally before opening a PR. They mirror the `CI` workflow
+(`.github/workflows/ci.yml`), which runs on every pull request and on pushes to
+`main`. **All four jobs must pass.**
+
+1. **Lint** (`lint` job)
+   ```bash
+   uv sync --group dev
+   uv run --group dev ruff check src tests
+   ```
+   Ruff config: `target-version = py312`, rules `E`, `F`, `W`, `I` (import
+   sorting), with `E501` (line length) delegated to black.
+
+2. **Format** (`lint` job)
+   ```bash
+   uv run --group dev black --check src tests
+   ```
+   Run `uv run --group dev black src tests` (without `--check`) to auto-fix.
+
+3. **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)
+   ```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
+   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:
+   ```bash
+   uv sync --extra integration
+   APPWRITE_PROJECT_ID=<id> APPWRITE_API_KEY=<key> APPWRITE_ENDPOINT=<url> \
+     uv run --extra integration python -m unittest discover -s tests/integration -v
+   ```
+
+### CI environment versions
+
+CI pins Python `3.12` and `uv` `0.11.22`. Match these locally if you hit
+version-specific differences.
+
+### If you change the docs index
+
+Rebuilding `src/mcp_server_appwrite/data/` requires `OPENAI_API_KEY`. Re-run the
+build script and commit the refreshed artifact:
+```bash
+OPENAI_API_KEY=sk-... uv run python scripts/build_docs_index.py
+```
+
+## Other workflows
+
+- `publish.yml` — package publishing.
+- `staging.yml` / `production.yml` — deployment (publishes images to Docker Hub).
+
+These are not gated on PRs the way `ci.yml` is, but be mindful when touching the
+`Dockerfile`, `pyproject.toml` version, or deployment config.
+
+## Conventions
+
+- Keep the exposed tool surface small — new Appwrite capabilities should flow
+  through the operator/catalog mechanism, not become top-level tools.
+- New SDK services are registered automatically; you generally don't hand-write
+  tool definitions.
+- Match existing style: black formatting, ruff-clean imports, type hints, module
+  docstrings explaining intent (see `auth.py`, `http_app.py`, `docs_search.py`).
+- Add unit tests under `tests/unit/` for any non-trivial logic; add integration
+  coverage under `tests/integration/` when touching real API behavior.

mcp_server_appwrite-0.7.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

mcp_server_appwrite-0.7.0/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim AS base
+
+ENV PYTHONUNBUFFERED=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /app
+
+COPY --from=ghcr.io/astral-sh/uv:0.11.22 /uv /usr/local/bin/uv
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+
+RUN uv sync --frozen --no-dev
+
+ENV HOST=0.0.0.0 \
+    PORT=8000 \
+    MCP_TRANSPORT=http \
+    APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+
+EXPOSE 8000
+
+CMD ["uv", "run", "mcp-server-appwrite", "--transport", "http"]

mcp_server_appwrite-0.7.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: mcp-server-appwrite
+Version: 0.7.0
+Summary: MCP (Model Context Protocol) server for Appwrite
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: appwrite<22,>=21.0.0
+Requires-Dist: docstring-parser>=0.16
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.12.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: openai>=1.40
+Requires-Dist: pyjwt[crypto]>=2.9.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: starlette>=0.40.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: integration
+Requires-Dist: argon2-cffi>=23.1.0; extra == 'integration'
+Requires-Dist: bcrypt>=4.1.2; extra == 'integration'
+Requires-Dist: passlib>=1.7.4; extra == 'integration'
+Requires-Dist: pycryptodome>=3.20.0; extra == 'integration'
+Description-Content-Type: text/markdown
+
+# Appwrite MCP server
+
+mcp-name: io.github.appwrite/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for Appwrite.
+It exposes Appwrite's API — databases, users, functions, teams, storage, and more
+— as tools your MCP client can call.
+
+Connect to the hosted server at **`https://mcp.appwrite.io/mcp`** and authenticate
+through your browser. The first time you connect, your client opens an Appwrite
+consent screen; approve the scopes and you're connected. There are no keys to
+copy.
+
+## Connect your client
+
+Pick your client below. Each adds the hosted Appwrite Cloud server.
+
+<details open>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add --transport http appwrite https://mcp.appwrite.io/mcp
+```
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Go to **Settings → Connectors → Add custom connector** and paste
+`https://mcp.appwrite.io/mcp`.
+
+On the free plan, bridge the remote server through stdio instead (requires
+Node.js) by editing your config via **Settings → Developer → Edit Config**:
+
+```json
+{
+  "mcpServers": {
+    "appwrite": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.appwrite.io/mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project).
+
+```json
+{
+  "mcpServers": {
+    "appwrite": {
+      "url": "https://mcp.appwrite.io/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>VS Code</b> (GitHub Copilot)</summary>
+
+Edit `.vscode/mcp.json` (workspace) or your user configuration via the Command
+Palette → **MCP: Open User Configuration**.
+
+```json
+{
+  "servers": {
+    "appwrite": {
+      "type": "http",
+      "url": "https://mcp.appwrite.io/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Codex</b></summary>
+
+Edit `~/.codex/config.toml`.
+
+```toml
+[mcp_servers.appwrite]
+url = "https://mcp.appwrite.io/mcp"
+```
+
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
+
+Edit `opencode.json` (project) or `~/.config/opencode/opencode.json` (global).
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "appwrite": {
+      "type": "remote",
+      "url": "https://mcp.appwrite.io/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Edit `~/.codeium/windsurf/mcp_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "appwrite": {
+      "serverUrl": "https://mcp.appwrite.io/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+## Self-hosted Appwrite
+
+Running your own Appwrite instance? Run the MCP server locally over `stdio` and
+authenticate with a project API key. See [docs/self-hosted.md](docs/self-hosted.md)
+for per-client setup.
+
+## Documentation
+
+- [Tool surface](docs/tool-surface.md) — the tools exposed to the model and the
+  internal Appwrite catalog.
+- [How Cloud authentication works](docs/authentication.md) — the OAuth 2.1 flow.
+- [Documentation search](docs/documentation-search.md) — the in-process
+  `appwrite_search_docs` tool and how to rebuild its index.
+- [Self-hosted Appwrite](docs/self-hosted.md) — run the server locally with a
+  project API key.
+- [Local development](docs/development.md) — running, testing, and debugging the
+  server locally.
+- [AGENTS.md](AGENTS.md) — full contributor guide and pre-PR checklist.
+
+## License
+
+This MCP server is licensed under the MIT License. See the [LICENSE](LICENSE) file
+for details.