Files

airano cf62e65c55 Initial commit: MCP Hub Community Edition v3.0.0

Community edition generated from private repo via sync pipeline.
Includes 9 plugins (WordPress, WooCommerce, WP Advanced, Gitea, n8n,
Supabase, OpenPanel, Appwrite, Directus) with ~587 tools.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-17 08:34:44 +03:30

37 KiB

Raw Blame History

Appwrite Plugin Design - Phase I

MCP Plugin برای مدیریت Appwrite Self-Hosted روی Coolify

Version: v1.0.0 (طراحی) Priority: High (جایگزین Phase J) Estimated Tools: 85-95

Overview

پلاگین Appwrite برای مدیریت Appwrite Self-Hosted روی Coolify طراحی شده است. Appwrite یک پلتفرم Backend-as-a-Service متن‌باز است که امکانات جامعی برای Database، Authentication، Storage، Functions و Messaging ارائه می‌دهد.

مقایسه با Supabase

┌─────────────────────────────────────────────────────────────────┐
│              Appwrite vs Supabase Self-Hosted                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Appwrite:                                                       │
│  ├── Document-based Database (NoSQL-like)                       │
│  ├── Built-in Users & Teams management                          │
│  ├── Messaging (Email, SMS, Push) built-in                      │
│  ├── 30+ OAuth providers                                         │
│  ├── Multi-runtime Functions (Node, Python, PHP, etc.)          │
│  ├── Database Transactions (v1.8+)                              │
│  └── GraphQL + REST APIs                                         │
│                                                                  │
│  Supabase:                                                       │
│  ├── PostgreSQL (relational)                                    │
│  ├── GoTrue for Auth                                            │
│  ├── No built-in messaging                                      │
│  ├── Deno-only Edge Functions                                   │
│  └── PostgREST for REST API                                     │
│                                                                  │
│  هر دو: Self-Hosted، Open Source، Coolify-compatible            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

ویژگی‌های Self-Hosted Appwrite

✅ موجود در Self-Hosted:
├── Database API (Collections, Documents, Queries)
├── Users API (Users, Sessions, Teams, Memberships)
├── Storage API (Buckets, Files, Image Transformation)
├── Functions API (Deployments, Executions, Variables)
├── Messaging API (Email, SMS, Push Notifications)
├── Health API (Service status, Queue monitoring)
├── Avatars API (Image utilities)
├── Realtime API (WebSocket subscriptions)
├── GraphQL API (Alternative to REST)
└── Webhooks & Events

❌ محدودیت‌ها:
├── Console API (Project management) - نیاز به Console access
├── Rate limiting بالا (پیش‌فرض 60/دقیقه) - قابل تنظیم
└── بعضی features نیاز به تنظیمات اضافی دارند

Authentication

روش‌های احراز هویت

┌─────────────────────────────────────────────────────────────────┐
│               Appwrite Self-Hosted Authentication                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  API Key:                                                        │
│  ├── X-Appwrite-Key header                                       │
│  ├── Server-side only                                            │
│  ├── Scoped permissions                                          │
│  ├── Bypasses rate limits                                        │
│  └── Admin mode (bypasses permissions)                           │
│                                                                  │
│  JWT Token:                                                       │
│  ├── Authorization: Bearer {token}                               │
│  ├── 15-minute expiration                                        │
│  ├── Respects user permissions                                   │
│  └── Rate limited (10 tokens/60min/user)                         │
│                                                                  │
│  Session (Client):                                                │
│  ├── Cookie-based                                                │
│  ├── For client SDKs                                             │
│  └── Subject to rate limiting                                    │
│                                                                  │
│  Project ID:                                                      │
│  ├── X-Appwrite-Project header (required)                        │
│  └── Identifies which project to access                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Environment Variables

# Appwrite Self-Hosted Instance (Required)
APPWRITE_SITE1_URL=https://appwrite.example.com/v1
APPWRITE_SITE1_PROJECT_ID=your-project-id
APPWRITE_SITE1_API_KEY=your-api-key-with-scopes
APPWRITE_SITE1_ALIAS=myappwrite

# Multiple Instances
APPWRITE_SITE2_URL=https://appwrite-staging.example.com/v1
APPWRITE_SITE2_PROJECT_ID=staging-project-id
APPWRITE_SITE2_API_KEY=staging-api-key
APPWRITE_SITE2_ALIAS=staging

API Key Scopes

Authentication & Users:
├── sessions.read / sessions.write
├── users.read / users.write
└── teams.read / teams.write

Database:
├── databases.read / databases.write
├── collections.read / collections.write (tables)
├── attributes.read / attributes.write (columns)
├── indexes.read / indexes.write
└── documents.read / documents.write (rows)

Storage:
├── buckets.read / buckets.write
└── files.read / files.write

Functions:
├── functions.read / functions.write
└── execution.read / execution.write

Messaging:
├── messages.read / messages.write
├── providers.read / providers.write
├── topics.read / topics.write
└── subscribers.read / subscribers.write

Other:
├── health.read
├── locale.read
└── avatars.read

API Endpoints

Base URL Structure

Self-Hosted: https://[SERVER_HOSTNAME]/v1

Database:
  GET/POST        /databases
  GET/PUT/DELETE  /databases/{databaseId}
  GET/POST        /databases/{databaseId}/collections
  GET/POST        /databases/{databaseId}/collections/{collectionId}/documents
  ...

Users:
  GET/POST        /users
  GET/PUT/DELETE  /users/{userId}
  GET/DELETE      /users/{userId}/sessions
  ...

Storage:
  GET/POST        /storage/buckets
  GET/POST        /storage/buckets/{bucketId}/files
  GET             /storage/buckets/{bucketId}/files/{fileId}/preview
  ...

Functions:
  GET/POST        /functions
  POST            /functions/{functionId}/executions
  ...

Messaging:
  GET/POST        /messaging/providers
  GET/POST        /messaging/topics
  POST            /messaging/messages
  ...

Health:
  GET             /health
  GET             /health/db
  GET             /health/queue
  ...

Architecture

Project Structure

plugins/appwrite/
├── __init__.py              # Export: AppwritePlugin, AppwriteClient
├── plugin.py                # کلاس اصلی AppwritePlugin
├── client.py                # AppwriteClient (REST client)
└── handlers/
    ├── __init__.py
    ├── databases.py         # Database & Collections (18 tools)
    ├── documents.py         # Document CRUD & Queries (12 tools)
    ├── users.py             # User management (12 tools)
    ├── teams.py             # Teams & Memberships (10 tools)
    ├── storage.py           # Buckets & Files (14 tools)
    ├── functions.py         # Functions & Executions (14 tools)
    ├── messaging.py         # Email, SMS, Push (12 tools)
    └── system.py            # Health & Avatars (8 tools)

Client Architecture

class AppwriteClient:
    """
    REST API Client for Appwrite Self-Hosted

    All requests include Project ID and API Key headers.
    """
    def __init__(
        self,
        base_url: str,           # e.g., https://appwrite.example.com/v1
        project_id: str,         # Appwrite project ID
        api_key: str,            # API key with required scopes
    ):
        self.base_url = base_url.rstrip('/')
        self.project_id = project_id
        self.api_key = api_key

    def _get_headers(self, additional_headers: Optional[Dict] = None) -> Dict[str, str]:
        """Get request headers with authentication."""
        headers = {
            "Content-Type": "application/json",
            "X-Appwrite-Project": self.project_id,
            "X-Appwrite-Key": self.api_key,
        }
        if additional_headers:
            headers.update(additional_headers)
        return headers

    async def request(
        self,
        method: str,
        endpoint: str,
        params: Optional[Dict] = None,
        json_data: Optional[Dict] = None,
        headers_override: Optional[Dict] = None
    ) -> Any:
        """Make authenticated request to Appwrite API"""
        url = f"{self.base_url}{endpoint}"
        headers = self._get_headers(headers_override)
        # ... request logic

Tool Categories

1. Databases Handler (18 tools)

مدیریت Databases و Collections

Tool	Method	Scope	Description
`list_databases`	GET	read	لیست databases
`get_database`	GET	read	جزئیات database
`create_database`	POST	write	ایجاد database
`update_database`	PUT	write	به‌روزرسانی database
`delete_database`	DELETE	admin	حذف database
`list_collections`	GET	read	لیست collections
`get_collection`	GET	read	جزئیات collection
`create_collection`	POST	write	ایجاد collection
`update_collection`	PUT	write	به‌روزرسانی collection
`delete_collection`	DELETE	admin	حذف collection
`list_attributes`	GET	read	لیست attributes
`create_string_attribute`	POST	write	attribute متنی
`create_integer_attribute`	POST	write	attribute عددی
`create_boolean_attribute`	POST	write	attribute boolean
`create_enum_attribute`	POST	write	attribute enum
`create_datetime_attribute`	POST	write	attribute تاریخ
`delete_attribute`	DELETE	admin	حذف attribute
`list_indexes`	GET	read	لیست indexes
`create_index`	POST	write	ایجاد index
`delete_index`	DELETE	admin	حذف index

# Create Collection Example
{
    "name": "create_collection",
    "method_name": "create_collection",
    "description": "Create a new collection in database",
    "schema": {
        "type": "object",
        "properties": {
            "database_id": {
                "type": "string",
                "description": "Database ID"
            },
            "collection_id": {
                "type": "string",
                "description": "Unique collection ID (use 'unique()' for auto)"
            },
            "name": {
                "type": "string",
                "description": "Collection name"
            },
            "permissions": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Array of permission strings",
                "default": []
            },
            "document_security": {
                "type": "boolean",
                "description": "Enable document-level permissions",
                "default": true
            },
            "enabled": {
                "type": "boolean",
                "default": true
            }
        },
        "required": ["database_id", "collection_id", "name"]
    },
    "scope": "write"
}

2. Documents Handler (12 tools)

عملیات CRUD روی Documents

Tool	Method	Scope	Description
`list_documents`	GET	read	لیست documents با فیلتر
`get_document`	GET	read	دریافت یک document
`create_document`	POST	write	ایجاد document
`update_document`	PATCH	write	به‌روزرسانی document
`delete_document`	DELETE	write	حذف document
`bulk_create_documents`	POST	write	ایجاد دسته‌ای
`bulk_update_documents`	PATCH	write	به‌روزرسانی دسته‌ای
`bulk_delete_documents`	DELETE	write	حذف دسته‌ای
`count_documents`	GET	read	شمارش documents
`search_documents`	GET	read	جستجوی full-text
`create_transaction`	POST	admin	شروع transaction (v1.8+)
`commit_transaction`	PUT	admin	commit/rollback transaction

# List Documents with Queries
{
    "name": "list_documents",
    "method_name": "list_documents",
    "description": "List documents with queries, filters, and pagination",
    "schema": {
        "type": "object",
        "properties": {
            "database_id": {
                "type": "string",
                "description": "Database ID"
            },
            "collection_id": {
                "type": "string",
                "description": "Collection ID"
            },
            "queries": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Query strings (e.g., 'equal(\"status\", \"active\")')",
                "examples": [
                    "equal(\"status\", [\"active\"])",
                    "greaterThan(\"price\", 100)",
                    "search(\"title\", \"keyword\")",
                    "orderDesc(\"createdAt\")",
                    "limit(25)",
                    "offset(0)"
                ]
            }
        },
        "required": ["database_id", "collection_id"]
    },
    "scope": "read"
}

3. Users Handler (12 tools)

مدیریت کاربران

Tool	Method	Scope	Description
`list_users`	GET	read	لیست کاربران
`get_user`	GET	read	جزئیات کاربر
`create_user`	POST	write	ایجاد کاربر
`update_user`	PATCH	write	به‌روزرسانی کاربر
`delete_user`	DELETE	admin	حذف کاربر
`update_user_email`	PATCH	write	تغییر ایمیل
`update_user_phone`	PATCH	write	تغییر تلفن
`update_user_status`	PATCH	admin	فعال/غیرفعال کردن
`update_user_labels`	PUT	admin	تنظیم labels
`list_user_sessions`	GET	read	لیست sessions
`delete_user_sessions`	DELETE	admin	حذف همه sessions
`delete_user_session`	DELETE	admin	حذف یک session

# Create User Example
{
    "name": "create_user",
    "method_name": "create_user",
    "description": "Create a new user",
    "schema": {
        "type": "object",
        "properties": {
            "user_id": {
                "type": "string",
                "description": "Unique user ID (use 'unique()' for auto)"
            },
            "email": {
                "type": "string",
                "format": "email",
                "description": "User email"
            },
            "phone": {
                "type": "string",
                "description": "Phone number (E.164 format)"
            },
            "password": {
                "type": "string",
                "minLength": 8,
                "description": "Password (min 8 chars)"
            },
            "name": {
                "type": "string",
                "description": "User display name"
            }
        },
        "required": ["user_id"]
    },
    "scope": "write"
}

4. Teams Handler (10 tools)

مدیریت Teams و Memberships

Tool	Method	Scope	Description
`list_teams`	GET	read	لیست teams
`get_team`	GET	read	جزئیات team
`create_team`	POST	write	ایجاد team
`update_team`	PUT	write	به‌روزرسانی team
`delete_team`	DELETE	admin	حذف team
`list_team_memberships`	GET	read	لیست اعضا
`create_team_membership`	POST	write	دعوت عضو
`update_membership`	PATCH	write	به‌روزرسانی عضویت
`delete_membership`	DELETE	write	حذف عضو
`update_membership_status`	PATCH	write	تایید/رد عضویت

5. Storage Handler (14 tools)

مدیریت Buckets و Files

Tool	Method	Scope	Description
`list_buckets`	GET	read	لیست buckets
`get_bucket`	GET	read	جزئیات bucket
`create_bucket`	POST	write	ایجاد bucket
`update_bucket`	PUT	write	به‌روزرسانی bucket
`delete_bucket`	DELETE	admin	حذف bucket
`list_files`	GET	read	لیست فایل‌ها
`get_file`	GET	read	جزئیات فایل
`create_file`	POST	write	آپلود فایل
`update_file`	PUT	write	به‌روزرسانی فایل
`delete_file`	DELETE	write	حذف فایل
`get_file_download`	GET	read	دانلود فایل
`get_file_preview`	GET	read	پیش‌نمایش تصویر
`get_file_view`	GET	read	مشاهده در browser
`move_file`	PUT	write	انتقال فایل

# Get File Preview with Transformations
{
    "name": "get_file_preview",
    "method_name": "get_file_preview",
    "description": "Get image preview with transformations",
    "schema": {
        "type": "object",
        "properties": {
            "bucket_id": {"type": "string"},
            "file_id": {"type": "string"},
            "width": {
                "type": "integer",
                "minimum": 0,
                "maximum": 4000,
                "description": "Preview width (0-4000)"
            },
            "height": {
                "type": "integer",
                "minimum": 0,
                "maximum": 4000,
                "description": "Preview height (0-4000)"
            },
            "gravity": {
                "type": "string",
                "enum": ["center", "top", "top-left", "top-right",
                         "left", "right", "bottom", "bottom-left", "bottom-right"],
                "default": "center"
            },
            "quality": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100,
                "default": 90
            },
            "output": {
                "type": "string",
                "enum": ["jpeg", "jpg", "png", "gif", "webp", "avif"],
                "default": "webp"
            },
            "rotation": {
                "type": "integer",
                "minimum": 0,
                "maximum": 360
            },
            "background": {
                "type": "string",
                "description": "Background color (hex without #)"
            },
            "border_width": {"type": "integer"},
            "border_color": {"type": "string"},
            "border_radius": {"type": "integer"}
        },
        "required": ["bucket_id", "file_id"]
    },
    "scope": "read"
}

6. Functions Handler (14 tools)

مدیریت Serverless Functions

Tool	Method	Scope	Description
`list_functions`	GET	read	لیست functions
`get_function`	GET	read	جزئیات function
`create_function`	POST	write	ایجاد function
`update_function`	PUT	write	به‌روزرسانی function
`delete_function`	DELETE	admin	حذف function
`list_deployments`	GET	read	لیست deployments
`get_deployment`	GET	read	جزئیات deployment
`create_deployment`	POST	write	deploy کد جدید
`delete_deployment`	DELETE	write	حذف deployment
`update_deployment`	PATCH	write	فعال کردن deployment
`list_executions`	GET	read	لیست executions
`get_execution`	GET	read	جزئیات execution
`create_execution`	POST	write	اجرای function
`delete_execution`	DELETE	write	حذف execution log

# Create Execution (Run Function)
{
    "name": "create_execution",
    "method_name": "create_execution",
    "description": "Execute a function",
    "schema": {
        "type": "object",
        "properties": {
            "function_id": {
                "type": "string",
                "description": "Function ID"
            },
            "body": {
                "type": "string",
                "description": "Request body (string or JSON string)"
            },
            "async": {
                "type": "boolean",
                "default": false,
                "description": "Run asynchronously"
            },
            "path": {
                "type": "string",
                "description": "Custom execution path"
            },
            "method": {
                "type": "string",
                "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
                "default": "POST"
            },
            "headers": {
                "type": "object",
                "description": "Custom headers"
            }
        },
        "required": ["function_id"]
    },
    "scope": "write"
}

7. Messaging Handler (12 tools)

ارسال پیام از طریق Email, SMS, Push

Tool	Method	Scope	Description
`list_providers`	GET	read	لیست providers
`get_provider`	GET	read	جزئیات provider
`create_email_provider`	POST	admin	ایجاد email provider
`create_sms_provider`	POST	admin	ایجاد SMS provider
`create_push_provider`	POST	admin	ایجاد push provider
`delete_provider`	DELETE	admin	حذف provider
`list_topics`	GET	read	لیست topics
`create_topic`	POST	write	ایجاد topic
`delete_topic`	DELETE	write	حذف topic
`create_subscriber`	POST	write	اضافه کردن subscriber
`delete_subscriber`	DELETE	write	حذف subscriber
`send_message`	POST	write	ارسال پیام

# Send Email Message
{
    "name": "send_message",
    "method_name": "send_message",
    "description": "Send email, SMS, or push notification",
    "schema": {
        "type": "object",
        "properties": {
            "message_id": {
                "type": "string",
                "description": "Unique message ID"
            },
            "type": {
                "type": "string",
                "enum": ["email", "sms", "push"],
                "description": "Message type"
            },
            "topics": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Target topic IDs"
            },
            "targets": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Target user IDs"
            },
            "subject": {
                "type": "string",
                "description": "Email subject"
            },
            "content": {
                "type": "string",
                "description": "Message content (HTML for email)"
            },
            "scheduled_at": {
                "type": "string",
                "format": "date-time",
                "description": "Schedule delivery time"
            }
        },
        "required": ["message_id", "type", "content"]
    },
    "scope": "write"
}

8. System Handler (8 tools)

سلامت سیستم و Utilities

Tool	Method	Scope	Description
`health_check`	GET	read	وضعیت کلی سرور
`health_db`	GET	read	وضعیت database
`health_cache`	GET	read	وضعیت cache
`health_queue`	GET	read	وضعیت queue
`health_storage`	GET	read	وضعیت storage
`health_time`	GET	read	همزمانی ساعت
`get_avatar_initials`	GET	read	آواتار از initials
`get_avatar_image`	GET	read	آواتار از URL

Query System

Query Operators

Appwrite از سیستم Query مخصوص خود استفاده می‌کند:

// Comparison
Query.equal("status", ["active"])
Query.notEqual("status", ["deleted"])
Query.lessThan("price", 100)
Query.lessThanOrEqual("price", 100)
Query.greaterThan("price", 50)
Query.greaterThanOrEqual("price", 50)
Query.between("price", 50, 100)

// String
Query.startsWith("name", "John")
Query.endsWith("email", "@example.com")
Query.search("title", "keyword")          // Requires fulltext index

// Array
Query.contains("tags", ["featured"])
Query.isNull("deleted_at")
Query.isNotNull("published_at")

// Sorting & Pagination
Query.orderAsc("created_at")
Query.orderDesc("created_at")
Query.limit(25)
Query.offset(0)
Query.cursorAfter("document_id")
Query.cursorBefore("document_id")

// Selection
Query.select(["id", "name", "email"])

Query در REST API

# Example: List active users, sorted by creation date
GET /databases/{dbId}/collections/{colId}/documents?queries[]=equal("status",["active"])&queries[]=orderDesc("$createdAt")&queries[]=limit(25)

Tool Summary

Handler	Tools	Description
Databases	18	Database, Collections, Attributes, Indexes
Documents	12	Document CRUD, Bulk ops, Transactions
Users	12	User management
Teams	10	Teams & Memberships
Storage	14	Buckets, Files, Image transformation
Functions	14	Functions, Deployments, Executions
Messaging	12	Email, SMS, Push notifications
System	8	Health checks, Avatars
Total	100

Implementation Phases

Phase I.1: Core (Database + System) - 38 tools

هدف: دسترسی اولیه به Appwrite Self-Hosted

AppwritePlugin class
AppwriteClient (REST client)
Databases Handler (18 tools)
Documents Handler (12 tools)
System Handler (8 tools)

Phase I.2: Auth & Teams - 22 tools

هدف: مدیریت کاربران و تیم‌ها

Users Handler (12 tools)
Teams Handler (10 tools)

جمع: 60 tools

Phase I.3: Storage - 14 tools

هدف: مدیریت فایل‌ها

Storage Handler (14 tools)

جمع: 74 tools

Phase I.4: Functions & Messaging - 26 tools

هدف: قابلیت‌های پیشرفته

Functions Handler (14 tools)
Messaging Handler (12 tools)

جمع: 100 tools

Error Handling

HTTP Status Codes

async def handle_appwrite_error(response):
    """Handle Appwrite API errors"""
    data = await response.json()

    message = data.get("message", "Unknown error")
    code = data.get("code", response.status)
    error_type = data.get("type", "general_error")

    if response.status == 400:
        raise ValidationError(f"Bad Request: {message}")
    elif response.status == 401:
        raise AuthError("Invalid API key or missing authentication")
    elif response.status == 403:
        raise PermissionError(f"Permission denied: {message}")
    elif response.status == 404:
        raise NotFoundError(f"Resource not found: {message}")
    elif response.status == 409:
        raise ConflictError(f"Conflict: {message}")
    elif response.status == 429:
        raise RateLimitError("Rate limit exceeded. Try again later.")
    elif response.status >= 500:
        raise ServerError(f"Server error ({code}): {message}")
    else:
        raise AppwriteError(f"Error ({code}): {message}")

Common Error Types

user_not_found          - کاربر پیدا نشد
document_not_found      - document پیدا نشد
collection_not_found    - collection پیدا نشد
database_not_found      - database پیدا نشد
storage_bucket_not_found - bucket پیدا نشد
storage_file_not_found  - فایل پیدا نشد
document_already_exists - document تکراری
user_already_exists     - کاربر تکراری
attribute_already_exists - attribute تکراری

Security Considerations

API Key Security

┌─────────────────────────────────────────────────────────────────┐
│                    API Key Best Practices                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ✅ Best Practices:                                              │
│  ├── Create separate keys for different purposes                │
│  ├── Use minimal required scopes                                │
│  ├── Rotate keys periodically                                   │
│  ├── Never expose keys in client-side code                      │
│  └── Use environment variables for storage                      │
│                                                                  │
│  ⚠️ Scope Recommendations:                                       │
│  ├── Read operations: *.read scopes only                        │
│  ├── Write operations: specific *.write scopes                  │
│  └── Admin operations: all scopes + careful monitoring          │
│                                                                  │
│  ❌ Never Do:                                                    │
│  ├── Log API keys (even partially)                              │
│  ├── Commit keys to version control                             │
│  ├── Share keys across different services                       │
│  └── Use single key for all operations                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Permission System

# Document-level permissions
permissions = [
    "read(\"user:123\")",      # Specific user can read
    "write(\"user:123\")",     # Specific user can write
    "read(\"team:456\")",      # Team members can read
    "read(\"any\")",           # Anyone can read (public)
    "create(\"users\")",       # Any authenticated user
    "update(\"label:admin\")", # Users with admin label
]

Example Usage

Query Documents

{
    "tool": "list_documents",
    "args": {
        "site": "myappwrite",
        "database_id": "main",
        "collection_id": "posts",
        "queries": [
            "equal(\"status\", [\"published\"])",
            "greaterThan(\"views\", 100)",
            "orderDesc(\"$createdAt\")",
            "limit(20)"
        ]
    }
}

Create User

{
    "tool": "create_user",
    "args": {
        "site": "myappwrite",
        "user_id": "unique()",
        "email": "user@example.com",
        "password": "securePassword123",
        "name": "John Doe"
    }
}

Upload File

{
    "tool": "create_file",
    "args": {
        "site": "myappwrite",
        "bucket_id": "avatars",
        "file_id": "unique()",
        "file_content_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
        "file_name": "avatar.png",
        "permissions": ["read(\"any\")"]
    }
}

Execute Function

{
    "tool": "create_execution",
    "args": {
        "site": "myappwrite",
        "function_id": "send-welcome-email",
        "body": "{\"userId\": \"123\", \"template\": \"welcome\"}",
        "async": false
    }
}

Send Email

{
    "tool": "send_message",
    "args": {
        "site": "myappwrite",
        "message_id": "unique()",
        "type": "email",
        "targets": ["user-123"],
        "subject": "Welcome to our platform!",
        "content": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
    }
}

Coolify Deployment Notes

Finding Appwrite Credentials

در Coolify، بعد از deploy کردن Appwrite:

URL: از Coolify dashboard → Project → Appwrite → Domain
- معمولاً: https://appwrite.yourdomain.com/v1
Project ID:
- در Appwrite Console → Settings → Project ID
- یا از URL بعد از login
API Key:
- Appwrite Console → Project → Settings → API Keys → Create
- Scopes مورد نیاز را انتخاب کنید

Docker Compose Services

# Appwrite services on Coolify
services:
  appwrite:           # Main API - port 80
  appwrite-realtime:  # Realtime WebSocket
  appwrite-executor:  # Function execution
  appwrite-worker-*:  # Background workers
  mariadb:           # Database
  redis:             # Cache
  influxdb:          # Metrics (optional)

Environment Variables (Appwrite Server)

# Key settings in Appwrite .env
_APP_ENV=production
_APP_DOMAIN=appwrite.yourdomain.com
_APP_DOMAIN_TARGET=appwrite.yourdomain.com
_APP_OPTIONS_ABUSE=enabled     # Rate limiting
_APP_FUNCTIONS_RUNTIMES=node-18.0,python-3.9,php-8.0

Endpoint Registration

Endpoint Config

# core/endpoints/config.py

EndpointType.APPWRITE: EndpointConfig(
    path="/appwrite",
    name="Appwrite Manager",
    description="Appwrite Self-Hosted management (database, auth, storage, functions, messaging)",
    endpoint_type=EndpointType.APPWRITE,
    plugin_types=["appwrite"],
    require_master_key=False,
    allowed_scopes={"read", "write", "admin"},
    tool_blacklist={
        "manage_api_keys_create",
        "manage_api_keys_delete",
        "manage_api_keys_rotate",
        "oauth_register_client",
        "oauth_revoke_client",
    },
    max_tools=110,
),

Comparison: Appwrite vs Supabase Tools

Feature	Appwrite	Supabase
Database Tools	30 (Documents + Databases)	18 (PostgREST)
Auth Tools	22 (Users + Teams)	14 (GoTrue)
Storage Tools	14	12
Functions Tools	14	8
Messaging Tools	12	0 (not built-in)
System Tools	8	6
Admin Tools	-	12 (postgres-meta)
Total	100	70

نکته: Appwrite ابزارهای بیشتری دارد چون:

Messaging built-in دارد
Teams management جداگانه دارد
Document/Collection model متفاوت است
Image transformation پیشرفته‌تر است

Testing Checklist

Unit Tests

AppwriteClient authentication
Database CRUD operations
Document queries with all operators
User management operations
Team operations
File upload/download
Function execution
Message sending
Error handling

Integration Tests

Create database and collection
CRUD documents with queries
Create user and authenticate
Upload and preview image
Execute serverless function
Send email through messaging
Health check all services
Rate limit handling

Function Runtimes

Supported Runtimes (v1.8+)

Runtime	Versions
Node.js	18.x, 20.x
Python	3.9, 3.10, 3.11, 3.12
PHP	8.0, 8.1, 8.2, 8.3
Ruby	3.0, 3.1, 3.2, 3.3
Java	11, 17, 21
Go	1.18, 1.19, 1.20, 1.21
Dart	3.0, 3.1, 3.2, 3.3
Rust	1.60, 1.65, 1.70, 1.75
C#	8, 11, 12
Swift	5.5, 5.8, 5.9
Kotlin	1.8

References

Created: 2025-12-02 Author: Claude AI Assistant Status: Design Phase (Ready for Implementation)

37 KiB Raw Blame History