# Directus CMS Plugin Design - Phase J

> **MCP Plugin برای مدیریت Directus Self-Hosted روی Coolify**

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

---

## Overview

پلاگین Directus برای مدیریت **Directus Self-Hosted** روی Coolify طراحی شده است. Directus یک Headless CMS متن‌باز و قدرتمند است که به صورت خودکار REST و GraphQL API برای هر دیتابیس SQL ایجاد می‌کند.

### مقایسه با سایر پلاگین‌ها

```
┌─────────────────────────────────────────────────────────────────┐
│           Directus vs Appwrite vs Supabase                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Directus:                                                       │
│  ├── SQL-based (PostgreSQL, MySQL, SQLite, etc.)                │
│  ├── Auto-generated REST + GraphQL APIs                         │
│  ├── Built-in Admin UI (Data Studio)                            │
│  ├── Flows & Operations (automation)                            │
│  ├── Version control for content                                │
│  ├── Granular permissions & policies                            │
│  ├── Dashboards & Insights                                      │
│  └── Multi-language content (Translations)                      │
│                                                                  │
│  Appwrite:                                                       │
│  ├── Document-based (NoSQL-like)                                │
│  ├── Built-in Messaging (Email, SMS, Push)                      │
│  ├── Functions with 11+ runtimes                                │
│  └── Teams management                                           │
│                                                                  │
│  Supabase:                                                       │
│  ├── PostgreSQL only                                            │
│  ├── Realtime subscriptions                                     │
│  ├── Edge Functions (Deno)                                      │
│  └── Row Level Security (RLS)                                   │
│                                                                  │
│  همه: Self-Hosted، Open Source، Coolify-compatible              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### ویژگی‌های Self-Hosted Directus

```
✅ موجود در Self-Hosted:
├── Items API (CRUD for any collection)
├── Collections API (schema management)
├── Fields API (column definitions)
├── Relations API (foreign keys)
├── Files API (asset management)
├── Users API (user management)
├── Roles & Permissions API
├── Flows & Operations API (automation)
├── Webhooks API
├── Dashboards & Panels API
├── Activity & Revisions API
├── Settings API
├── Schema API
├── Server Info API
├── GraphQL API (alternative to REST)
└── Extensions API

❌ محدودیت‌ها:
├── Cloud-specific features (not applicable)
├── Rate limiting بستگی به تنظیمات سرور دارد
└── بعضی features نیاز به extensions دارند
```

---

## Authentication

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

```
┌─────────────────────────────────────────────────────────────────┐
│               Directus Self-Hosted Authentication                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Static Token (Recommended for Server-to-Server):                │
│  ├── Set in directus_users.token column                         │
│  ├── Never expires                                               │
│  ├── Pass via Authorization: Bearer {token}                      │
│  ├── Or via ?access_token={token} query param                   │
│  └── Best for MCP integration                                    │
│                                                                  │
│  JWT (Temporary Token):                                          │
│  ├── POST /auth/login with email/password                       │
│  ├── Returns access_token + refresh_token                        │
│  ├── access_token expires (default 15m)                          │
│  ├── refresh_token expires (default 7d)                          │
│  └── Use for user-facing applications                            │
│                                                                  │
│  Session (Cookie-based):                                         │
│  ├── POST /auth/login?mode=session                               │
│  ├── Cookie-based authentication                                 │
│  └── For browser-based applications                              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### Environment Variables

```bash
# Directus Self-Hosted Instance (Required)
DIRECTUS_SITE1_URL=https://directus.example.com
DIRECTUS_SITE1_TOKEN=your-static-admin-token
DIRECTUS_SITE1_ALIAS=mycms

# Multiple Instances
DIRECTUS_SITE2_URL=https://directus-staging.example.com
DIRECTUS_SITE2_TOKEN=staging-static-token
DIRECTUS_SITE2_ALIAS=staging
```

### Static Token Setup

```sql
-- Set static token for admin user in database
UPDATE directus_users
SET token = 'your-secure-static-token'
WHERE email = 'admin@example.com';
```

Or via Directus Admin UI:
1. Go to User Directory
2. Select user
3. Scroll to Token field
4. Generate or set token

---

## API Endpoints

### Base URL Structure

```
Self-Hosted: https://[DIRECTUS_HOST]

Items (Dynamic Collections):
  GET/POST        /items/{collection}
  GET/PATCH/DEL   /items/{collection}/{id}

Collections (Schema):
  GET/POST        /collections
  GET/PATCH/DEL   /collections/{collection}

Fields:
  GET/POST        /fields
  GET/POST        /fields/{collection}
  GET/PATCH/DEL   /fields/{collection}/{field}

Relations:
  GET/POST        /relations
  GET/PATCH/DEL   /relations/{id}

Files & Folders:
  GET/POST        /files
  GET/PATCH/DEL   /files/{id}
  GET/POST        /folders
  GET/PATCH/DEL   /folders/{id}

Users:
  GET/POST        /users
  GET/PATCH/DEL   /users/{id}
  GET             /users/me

Roles:
  GET/POST        /roles
  GET/PATCH/DEL   /roles/{id}

Permissions:
  GET/POST        /permissions
  GET/PATCH/DEL   /permissions/{id}
  GET             /permissions/me

Policies:
  GET/POST        /policies
  GET/PATCH/DEL   /policies/{id}

Flows:
  GET/POST        /flows
  GET/PATCH/DEL   /flows/{id}
  POST            /flows/trigger/{flow_uuid}

Operations:
  GET/POST        /operations
  GET/PATCH/DEL   /operations/{id}

Webhooks:
  GET/POST        /webhooks
  GET/PATCH/DEL   /webhooks/{id}

Activity:
  GET             /activity
  GET             /activity/{id}
  POST            /activity/comment

Revisions:
  GET             /revisions
  GET             /revisions/{id}

Versions:
  GET/POST        /versions
  GET/PATCH/DEL   /versions/{id}
  POST            /versions/{id}/promote

Dashboards:
  GET/POST        /dashboards
  GET/PATCH/DEL   /dashboards/{id}

Panels:
  GET/POST        /panels
  GET/PATCH/DEL   /panels/{id}

Settings:
  GET/PATCH       /settings

Server:
  GET             /server/info
  GET             /server/health
  GET             /server/specs/oas
  GET             /server/specs/graphql

Schema:
  GET             /schema/snapshot
  POST            /schema/diff
  POST            /schema/apply

Presets:
  GET/POST        /presets
  GET/PATCH/DEL   /presets/{id}

Shares:
  GET/POST        /shares
  GET/PATCH/DEL   /shares/{id}
  POST            /shares/info

Notifications:
  GET/POST        /notifications
  GET/PATCH/DEL   /notifications/{id}

Translations:
  GET/POST        /translations
  GET/PATCH/DEL   /translations/{id}

Comments:
  GET/POST        /comments
  GET/PATCH/DEL   /comments/{id}

Extensions:
  GET             /extensions
```

---

## Architecture

### Project Structure

```
plugins/directus/
├── __init__.py              # Export: DirectusPlugin, DirectusClient
├── plugin.py                # کلاس اصلی DirectusPlugin
├── client.py                # DirectusClient (REST client)
└── handlers/
    ├── __init__.py
    ├── items.py             # Items CRUD (12 tools)
    ├── collections.py       # Collections & Fields (14 tools)
    ├── files.py             # Files & Folders (12 tools)
    ├── users.py             # Users management (10 tools)
    ├── access.py            # Roles, Permissions, Policies (12 tools)
    ├── automation.py        # Flows, Operations, Webhooks (12 tools)
    ├── content.py           # Revisions, Versions, Comments (10 tools)
    ├── dashboards.py        # Dashboards & Panels (8 tools)
    └── system.py            # Settings, Server, Schema, Activity (10 tools)
```

### Client Architecture

```python
class DirectusClient:
    """
    REST API Client for Directus Self-Hosted

    Uses static token authentication for server-to-server communication.
    """
    def __init__(
        self,
        base_url: str,           # e.g., https://directus.example.com
        token: str,              # Static admin token
    ):
        self.base_url = base_url.rstrip('/')
        self.token = token

    def _get_headers(self, additional_headers: Optional[Dict] = None) -> Dict[str, str]:
        """Get request headers with authentication."""
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.token}",
        }
        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 Directus API"""
        url = f"{self.base_url}{endpoint}"
        headers = self._get_headers(headers_override)
        # ... request logic
```

---

## Tool Categories

### 1. Items Handler (12 tools)

عملیات CRUD روی هر collection

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_items` | GET | read | لیست items با فیلتر و pagination |
| `get_item` | GET | read | دریافت یک item |
| `create_item` | POST | write | ایجاد item جدید |
| `create_items` | POST | write | ایجاد چندین item |
| `update_item` | PATCH | write | به‌روزرسانی item |
| `update_items` | PATCH | write | به‌روزرسانی چندین item |
| `delete_item` | DELETE | write | حذف item |
| `delete_items` | DELETE | write | حذف چندین item |
| `search_items` | GET | read | جستجوی full-text |
| `aggregate_items` | GET | read | محاسبات aggregate |
| `export_items` | GET | read | خروجی JSON/CSV |
| `import_items` | POST | write | وارد کردن items |

```python
# List Items Example
{
    "name": "list_items",
    "method_name": "list_items",
    "description": "List items from any collection with filters, sorting, and pagination",
    "schema": {
        "type": "object",
        "properties": {
            "collection": {
                "type": "string",
                "description": "Collection name (e.g., 'posts', 'products')"
            },
            "fields": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Fields to return (e.g., ['id', 'title', 'author.*'])"
            },
            "filter": {
                "type": "object",
                "description": "Filter object (e.g., {\"status\": {\"_eq\": \"published\"}})"
            },
            "sort": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Sort fields (e.g., ['-date_created', 'title'])"
            },
            "limit": {
                "type": "integer",
                "description": "Maximum items to return",
                "default": 100
            },
            "offset": {
                "type": "integer",
                "description": "Items to skip",
                "default": 0
            },
            "search": {
                "type": "string",
                "description": "Full-text search query"
            },
            "deep": {
                "type": "object",
                "description": "Deep filter for relational fields"
            }
        },
        "required": ["collection"]
    },
    "scope": "read"
}
```

### 2. Collections & Fields Handler (14 tools)

مدیریت schema

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_collections` | GET | read | لیست collections |
| `get_collection` | GET | read | جزئیات collection |
| `create_collection` | POST | admin | ایجاد collection |
| `update_collection` | PATCH | admin | به‌روزرسانی collection |
| `delete_collection` | DELETE | admin | حذف collection |
| `list_fields` | GET | read | لیست fields |
| `get_field` | GET | read | جزئیات field |
| `create_field` | POST | admin | ایجاد field |
| `update_field` | PATCH | admin | به‌روزرسانی field |
| `delete_field` | DELETE | admin | حذف field |
| `list_relations` | GET | read | لیست relations |
| `get_relation` | GET | read | جزئیات relation |
| `create_relation` | POST | admin | ایجاد relation |
| `delete_relation` | DELETE | admin | حذف relation |

```python
# Create Collection Example
{
    "name": "create_collection",
    "method_name": "create_collection",
    "description": "Create a new collection (table) in Directus",
    "schema": {
        "type": "object",
        "properties": {
            "collection": {
                "type": "string",
                "description": "Collection name (table name)"
            },
            "meta": {
                "type": "object",
                "properties": {
                    "icon": {"type": "string", "description": "Material icon name"},
                    "note": {"type": "string", "description": "Description"},
                    "hidden": {"type": "boolean", "default": False},
                    "singleton": {"type": "boolean", "default": False},
                    "translations": {"type": "array"},
                    "sort_field": {"type": "string"},
                    "archive_field": {"type": "string"},
                    "archive_value": {"type": "string"},
                    "unarchive_value": {"type": "string"}
                }
            },
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "comment": {"type": "string"}
                }
            },
            "fields": {
                "type": "array",
                "description": "Initial fields to create with collection",
                "items": {
                    "type": "object",
                    "properties": {
                        "field": {"type": "string"},
                        "type": {"type": "string"},
                        "meta": {"type": "object"},
                        "schema": {"type": "object"}
                    }
                }
            }
        },
        "required": ["collection"]
    },
    "scope": "admin"
}
```

### 3. Files & Folders Handler (12 tools)

مدیریت assets

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_files` | GET | read | لیست فایل‌ها |
| `get_file` | GET | read | جزئیات فایل |
| `upload_file` | POST | write | آپلود فایل |
| `update_file` | PATCH | write | به‌روزرسانی metadata |
| `delete_file` | DELETE | write | حذف فایل |
| `delete_files` | DELETE | write | حذف چندین فایل |
| `list_folders` | GET | read | لیست پوشه‌ها |
| `get_folder` | GET | read | جزئیات پوشه |
| `create_folder` | POST | write | ایجاد پوشه |
| `update_folder` | PATCH | write | به‌روزرسانی پوشه |
| `delete_folder` | DELETE | write | حذف پوشه |
| `import_file_url` | POST | write | وارد کردن از URL |

```python
# Upload File Example
{
    "name": "upload_file",
    "method_name": "upload_file",
    "description": "Upload a file to Directus storage",
    "schema": {
        "type": "object",
        "properties": {
            "file_content_base64": {
                "type": "string",
                "description": "File content as base64 encoded string"
            },
            "filename_download": {
                "type": "string",
                "description": "Download filename"
            },
            "title": {
                "type": "string",
                "description": "File title"
            },
            "description": {
                "type": "string",
                "description": "File description"
            },
            "folder": {
                "type": "string",
                "description": "Folder UUID to upload to"
            },
            "storage": {
                "type": "string",
                "description": "Storage adapter (default: local)",
                "default": "local"
            },
            "tags": {
                "type": "array",
                "items": {"type": "string"},
                "description": "File tags"
            }
        },
        "required": ["file_content_base64", "filename_download"]
    },
    "scope": "write"
}
```

### 4. Users Handler (10 tools)

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

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_users` | GET | read | لیست کاربران |
| `get_user` | GET | read | جزئیات کاربر |
| `get_current_user` | GET | read | کاربر فعلی |
| `create_user` | POST | admin | ایجاد کاربر |
| `update_user` | PATCH | admin | به‌روزرسانی کاربر |
| `delete_user` | DELETE | admin | حذف کاربر |
| `delete_users` | DELETE | admin | حذف چندین کاربر |
| `invite_user` | POST | admin | دعوت کاربر |
| `accept_invite` | POST | write | پذیرش دعوت |
| `update_current_user` | PATCH | write | به‌روزرسانی پروفایل |

```python
# Create User Example
{
    "name": "create_user",
    "method_name": "create_user",
    "description": "Create a new user in Directus",
    "schema": {
        "type": "object",
        "properties": {
            "email": {
                "type": "string",
                "format": "email",
                "description": "User email address"
            },
            "password": {
                "type": "string",
                "minLength": 8,
                "description": "User password"
            },
            "first_name": {
                "type": "string",
                "description": "First name"
            },
            "last_name": {
                "type": "string",
                "description": "Last name"
            },
            "role": {
                "type": "string",
                "description": "Role UUID"
            },
            "status": {
                "type": "string",
                "enum": ["draft", "invited", "active", "suspended", "archived"],
                "default": "active"
            },
            "language": {
                "type": "string",
                "description": "User language preference"
            },
            "token": {
                "type": "string",
                "description": "Static API token"
            }
        },
        "required": ["email", "password", "role"]
    },
    "scope": "admin"
}
```

### 5. Access Control Handler (12 tools)

Roles, Permissions, Policies

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_roles` | GET | read | لیست roles |
| `get_role` | GET | read | جزئیات role |
| `create_role` | POST | admin | ایجاد role |
| `update_role` | PATCH | admin | به‌روزرسانی role |
| `delete_role` | DELETE | admin | حذف role |
| `list_permissions` | GET | read | لیست permissions |
| `get_permission` | GET | read | جزئیات permission |
| `create_permission` | POST | admin | ایجاد permission |
| `update_permission` | PATCH | admin | به‌روزرسانی permission |
| `delete_permission` | DELETE | admin | حذف permission |
| `list_policies` | GET | read | لیست policies |
| `get_my_permissions` | GET | read | permissions کاربر فعلی |

```python
# Create Permission Example
{
    "name": "create_permission",
    "method_name": "create_permission",
    "description": "Create a new permission rule",
    "schema": {
        "type": "object",
        "properties": {
            "role": {
                "type": "string",
                "description": "Role UUID (null for public)"
            },
            "collection": {
                "type": "string",
                "description": "Collection name"
            },
            "action": {
                "type": "string",
                "enum": ["create", "read", "update", "delete", "share"],
                "description": "Permission action"
            },
            "permissions": {
                "type": "object",
                "description": "Filter rules (JSON filter)"
            },
            "validation": {
                "type": "object",
                "description": "Validation rules for create/update"
            },
            "presets": {
                "type": "object",
                "description": "Default values for create"
            },
            "fields": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Allowed fields (* for all)"
            }
        },
        "required": ["collection", "action"]
    },
    "scope": "admin"
}
```

### 6. Automation Handler (12 tools)

Flows, Operations, Webhooks

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_flows` | GET | read | لیست flows |
| `get_flow` | GET | read | جزئیات flow |
| `create_flow` | POST | admin | ایجاد flow |
| `update_flow` | PATCH | admin | به‌روزرسانی flow |
| `delete_flow` | DELETE | admin | حذف flow |
| `trigger_flow` | POST | write | اجرای manual flow |
| `list_operations` | GET | read | لیست operations |
| `create_operation` | POST | admin | ایجاد operation |
| `list_webhooks` | GET | read | لیست webhooks |
| `create_webhook` | POST | admin | ایجاد webhook |
| `update_webhook` | PATCH | admin | به‌روزرسانی webhook |
| `delete_webhook` | DELETE | admin | حذف webhook |

```python
# Create Flow Example
{
    "name": "create_flow",
    "method_name": "create_flow",
    "description": "Create a new automation flow",
    "schema": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "Flow name"
            },
            "icon": {
                "type": "string",
                "description": "Material icon"
            },
            "status": {
                "type": "string",
                "enum": ["active", "inactive"],
                "default": "active"
            },
            "trigger": {
                "type": "string",
                "enum": ["event", "schedule", "operation", "webhook", "manual"],
                "description": "Trigger type"
            },
            "options": {
                "type": "object",
                "description": "Trigger-specific options"
            },
            "accountability": {
                "type": "string",
                "enum": ["all", "activity", null],
                "description": "Accountability tracking"
            },
            "description": {
                "type": "string",
                "description": "Flow description"
            }
        },
        "required": ["name", "trigger"]
    },
    "scope": "admin"
}
```

### 7. Content Management Handler (10 tools)

Revisions, Versions, Comments

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_revisions` | GET | read | لیست revisions |
| `get_revision` | GET | read | جزئیات revision |
| `list_versions` | GET | read | لیست content versions |
| `get_version` | GET | read | جزئیات version |
| `create_version` | POST | write | ایجاد version |
| `update_version` | PATCH | write | به‌روزرسانی version |
| `delete_version` | DELETE | write | حذف version |
| `promote_version` | POST | write | ترویج version به main |
| `list_comments` | GET | read | لیست comments |
| `create_comment` | POST | write | ایجاد comment |

```python
# Create Version Example
{
    "name": "create_version",
    "method_name": "create_version",
    "description": "Create a new content version (draft)",
    "schema": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "Version name"
            },
            "collection": {
                "type": "string",
                "description": "Collection name"
            },
            "item": {
                "type": "string",
                "description": "Item ID"
            },
            "key": {
                "type": "string",
                "description": "Version key (unique identifier)"
            },
            "delta": {
                "type": "object",
                "description": "Changes from main content"
            }
        },
        "required": ["name", "collection", "item"]
    },
    "scope": "write"
}
```

### 8. Dashboards Handler (8 tools)

Dashboards & Panels

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_dashboards` | GET | read | لیست dashboards |
| `get_dashboard` | GET | read | جزئیات dashboard |
| `create_dashboard` | POST | write | ایجاد dashboard |
| `update_dashboard` | PATCH | write | به‌روزرسانی dashboard |
| `delete_dashboard` | DELETE | write | حذف dashboard |
| `list_panels` | GET | read | لیست panels |
| `create_panel` | POST | write | ایجاد panel |
| `delete_panel` | DELETE | write | حذف panel |

```python
# Create Dashboard Example
{
    "name": "create_dashboard",
    "method_name": "create_dashboard",
    "description": "Create a new insights dashboard",
    "schema": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "Dashboard name"
            },
            "icon": {
                "type": "string",
                "description": "Material icon",
                "default": "dashboard"
            },
            "note": {
                "type": "string",
                "description": "Dashboard description"
            },
            "color": {
                "type": "string",
                "description": "Accent color"
            }
        },
        "required": ["name"]
    },
    "scope": "write"
}
```

### 9. System Handler (10 tools)

Settings, Server, Schema, Activity

| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `get_settings` | GET | read | تنظیمات سیستم |
| `update_settings` | PATCH | admin | به‌روزرسانی تنظیمات |
| `get_server_info` | GET | read | اطلاعات سرور |
| `health_check` | GET | read | بررسی سلامت |
| `get_schema_snapshot` | GET | admin | export schema |
| `apply_schema_diff` | POST | admin | apply schema changes |
| `list_activity` | GET | read | لیست activity log |
| `get_activity` | GET | read | جزئیات activity |
| `list_notifications` | GET | read | لیست اعلان‌ها |
| `list_presets` | GET | read | لیست presets |

```python
# Health Check Example
{
    "name": "health_check",
    "method_name": "health_check",
    "description": "Check Directus server health status",
    "schema": {
        "type": "object",
        "properties": {}
    },
    "scope": "read"
}

# Get Schema Snapshot Example
{
    "name": "get_schema_snapshot",
    "method_name": "get_schema_snapshot",
    "description": "Get complete schema snapshot for migration/backup",
    "schema": {
        "type": "object",
        "properties": {
            "format": {
                "type": "string",
                "enum": ["json", "yaml"],
                "default": "json"
            }
        }
    },
    "scope": "admin"
}
```

---

## Query System

### Filter Operators

Directus از filter operators قدرتمندی استفاده می‌کند:

```javascript
// Comparison
{"field": {"_eq": "value"}}           // Equal
{"field": {"_neq": "value"}}          // Not equal
{"field": {"_lt": 10}}                // Less than
{"field": {"_lte": 10}}               // Less than or equal
{"field": {"_gt": 10}}                // Greater than
{"field": {"_gte": 10}}               // Greater than or equal

// String
{"field": {"_contains": "text"}}      // Contains
{"field": {"_ncontains": "text"}}     // Not contains
{"field": {"_starts_with": "text"}}   // Starts with
{"field": {"_nstarts_with": "text"}}  // Not starts with
{"field": {"_ends_with": "text"}}     // Ends with
{"field": {"_nends_with": "text"}}    // Not ends with

// Array
{"field": {"_in": ["a", "b"]}}        // In array
{"field": {"_nin": ["a", "b"]}}       // Not in array

// Null
{"field": {"_null": true}}            // Is null
{"field": {"_nnull": true}}           // Is not null

// Empty
{"field": {"_empty": true}}           // Is empty
{"field": {"_nempty": true}}          // Is not empty

// Between
{"field": {"_between": [1, 10]}}      // Between
{"field": {"_nbetween": [1, 10]}}     // Not between

// Logical
{"_and": [{...}, {...}]}              // AND
{"_or": [{...}, {...}]}               // OR

// Relational
{"author": {"name": {"_eq": "John"}}} // Related field
```

### Deep Parameter (Relational Queries)

```javascript
// Filter related items
{
    "deep": {
        "translations": {
            "_filter": {
                "languages_code": {"_eq": "en-US"}
            }
        }
    }
}
```

---

## Tool Summary

| Handler | Tools | Description |
|---------|-------|-------------|
| Items | 12 | CRUD برای همه collections |
| Collections & Fields | 14 | مدیریت schema |
| Files & Folders | 12 | مدیریت assets |
| Users | 10 | مدیریت کاربران |
| Access Control | 12 | Roles, Permissions, Policies |
| Automation | 12 | Flows, Operations, Webhooks |
| Content | 10 | Revisions, Versions, Comments |
| Dashboards | 8 | Dashboards & Panels |
| System | 10 | Settings, Server, Schema, Activity |
| **Total** | **100** | |

---

## Implementation Phases

### Phase J.1: Core (Items + Schema) - 26 tools

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

1. **DirectusPlugin** class
2. **DirectusClient** (REST client)
3. **Items Handler** (12 tools)
4. **Collections & Fields Handler** (14 tools)

### Phase J.2: Assets & Users - 22 tools

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

1. **Files & Folders Handler** (12 tools)
2. **Users Handler** (10 tools)

**جمع**: 48 tools

### Phase J.3: Access & Automation - 24 tools

**هدف**: امنیت و اتوماسیون

1. **Access Control Handler** (12 tools)
2. **Automation Handler** (12 tools)

**جمع**: 72 tools

### Phase J.4: Advanced - 28 tools

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

1. **Content Handler** (10 tools)
2. **Dashboards Handler** (8 tools)
3. **System Handler** (10 tools)

**جمع**: 100 tools

---

## Error Handling

### HTTP Status Codes

```python
async def handle_directus_error(response):
    """Handle Directus API errors"""
    data = await response.json()

    errors = data.get("errors", [])
    message = errors[0].get("message", "Unknown error") if errors else "Unknown error"

    if response.status == 400:
        raise ValidationError(f"Bad Request: {message}")
    elif response.status == 401:
        raise AuthError("Invalid token 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 == 503:
        raise ServiceUnavailableError("Service temporarily unavailable")
    elif response.status >= 500:
        raise ServerError(f"Server error: {message}")
    else:
        raise DirectusError(f"Error: {message}")
```

### Common Error Codes

```
FORBIDDEN                - دسترسی غیرمجاز
INVALID_CREDENTIALS      - اطلاعات ورود نادرست
INVALID_TOKEN           - توکن نامعتبر
TOKEN_EXPIRED           - توکن منقضی شده
RECORD_NOT_UNIQUE       - رکورد تکراری
FAILED_VALIDATION       - خطای validation
ILLEGAL_ASSET_TRANSFORMATION - تبدیل فایل غیرمجاز
CONTENT_TOO_LARGE       - فایل بزرگتر از حد مجاز
```

---

## Security Considerations

### Token Security

```
┌─────────────────────────────────────────────────────────────────┐
│                    Token Best Practices                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ✅ Best Practices:                                              │
│  ├── Use static tokens for server-to-server (MCP)               │
│  ├── Store tokens in environment variables                       │
│  ├── Create dedicated service user with minimal permissions      │
│  ├── Rotate tokens periodically                                  │
│  └── Use HTTPS always                                            │
│                                                                  │
│  ⚠️ Scope Recommendations:                                       │
│  ├── Read operations: read-only role                            │
│  ├── Write operations: content editor role                       │
│  └── Admin operations: admin role (careful monitoring)           │
│                                                                  │
│  ❌ Never Do:                                                    │
│  ├── Log tokens (even partially)                                │
│  ├── Commit tokens to version control                           │
│  ├── Use admin token for public operations                       │
│  └── Share tokens across different services                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### Permission System

```python
# Create restricted role for MCP
role = {
    "name": "MCP Service",
    "icon": "smart_toy",
    "description": "Service role for MCP integration",
    "admin_access": False,
    "app_access": False
}

# Permission examples
permissions = [
    # Read all posts
    {"collection": "posts", "action": "read", "fields": ["*"]},

    # Create/update own posts only
    {"collection": "posts", "action": "create", "fields": ["*"]},
    {"collection": "posts", "action": "update", "permissions": {"user_created": {"_eq": "$CURRENT_USER"}}},

    # Read published only
    {"collection": "articles", "action": "read", "permissions": {"status": {"_eq": "published"}}}
]
```

---

## Example Usage

### Query Items with Filters

```json
{
    "tool": "list_items",
    "args": {
        "site": "mycms",
        "collection": "posts",
        "fields": ["id", "title", "date_created", "author.email"],
        "filter": {
            "_and": [
                {"status": {"_eq": "published"}},
                {"date_created": {"_gte": "$NOW(-30 days)"}}
            ]
        },
        "sort": ["-date_created"],
        "limit": 20
    }
}
```

### Create Item

```json
{
    "tool": "create_item",
    "args": {
        "site": "mycms",
        "collection": "posts",
        "data": {
            "title": "New Blog Post",
            "content": "<p>Hello World!</p>",
            "status": "draft",
            "tags": ["news", "featured"],
            "author": "user-uuid-here"
        }
    }
}
```

### Upload File

```json
{
    "tool": "upload_file",
    "args": {
        "site": "mycms",
        "file_content_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
        "filename_download": "cover-image.png",
        "title": "Blog Cover Image",
        "folder": "folder-uuid-here",
        "tags": ["blog", "cover"]
    }
}
```

### Create Automation Flow

```json
{
    "tool": "create_flow",
    "args": {
        "site": "mycms",
        "name": "Send Welcome Email",
        "trigger": "event",
        "options": {
            "type": "action",
            "scope": ["items.create"],
            "collections": ["users"]
        },
        "status": "active"
    }
}
```

### Trigger Manual Flow

```json
{
    "tool": "trigger_flow",
    "args": {
        "site": "mycms",
        "flow_uuid": "flow-uuid-here",
        "data": {
            "email": "user@example.com",
            "template": "welcome"
        }
    }
}
```

---

## Coolify Deployment Notes

### Finding Directus Credentials

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

1. **URL**: از Coolify dashboard → Project → Directus → Domain
   - معمولاً: `https://directus.yourdomain.com`

2. **Admin Email/Password**:
   - در Environment Variables:
     - `ADMIN_EMAIL`
     - `ADMIN_PASSWORD`

3. **Static Token**:
   - Login به Directus Admin
   - Settings → User Directory → Admin User
   - Token field → Generate

### Docker Compose Environment

```yaml
# Key Directus environment variables
services:
  directus:
    environment:
      # Database
      DB_CLIENT: 'pg'           # or mysql, sqlite, etc.
      DB_HOST: 'database'
      DB_PORT: '5432'
      DB_DATABASE: 'directus'
      DB_USER: 'directus'
      DB_PASSWORD: 'secure-password'

      # Auth
      SECRET: 'your-random-secret-key'
      ADMIN_EMAIL: 'admin@example.com'
      ADMIN_PASSWORD: 'secure-admin-password'

      # URLs
      PUBLIC_URL: 'https://directus.example.com'

      # Token settings
      ACCESS_TOKEN_TTL: '15m'
      REFRESH_TOKEN_TTL: '7d'

      # CORS
      CORS_ENABLED: 'true'
      CORS_ORIGIN: 'true'
```

### Database Support

```
Directus supports:
├── PostgreSQL (recommended)
├── MySQL / MariaDB
├── SQLite (development only)
├── MS SQL Server
├── OracleDB
└── CockroachDB
```

---

## Endpoint Registration

### Endpoint Config

```python
# core/endpoints/config.py

EndpointType.DIRECTUS: EndpointConfig(
    path="/directus",
    name="Directus CMS",
    description="Directus Self-Hosted CMS management (items, collections, files, users, flows)",
    endpoint_type=EndpointType.DIRECTUS,
    plugin_types=["directus"],
    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: Directus vs Appwrite Tools

| Feature | Directus | Appwrite |
|---------|----------|----------|
| Items/Documents Tools | 12 | 12 |
| Schema Tools | 14 | 18 |
| Files/Storage Tools | 12 | 14 |
| Users Tools | 10 | 12 |
| Access Control Tools | 12 | 10 (Teams) |
| Automation Tools | 12 | 14 (Functions) |
| Content Versioning | 10 | 0 |
| Dashboards Tools | 8 | 0 |
| System Tools | 10 | 8 |
| Messaging Tools | 0 | 12 |
| **Total** | **100** | **100** |

**تفاوت‌های کلیدی:**
- Directus: Content versioning و Dashboards دارد
- Appwrite: Built-in Messaging و Functions runtime دارد
- Directus: SQL-based (flexible)
- Appwrite: Document-based (NoSQL-like)

---

## Testing Checklist

### Unit Tests

- [ ] DirectusClient authentication
- [ ] Items CRUD operations
- [ ] Filter operators
- [ ] Relational queries (deep)
- [ ] File upload/download
- [ ] User management
- [ ] Permission enforcement
- [ ] Flow triggering
- [ ] Error handling

### Integration Tests

- [ ] Create collection with fields
- [ ] CRUD items with relations
- [ ] Upload and retrieve files
- [ ] Create user with role
- [ ] Set permissions and verify access
- [ ] Create and trigger flow
- [ ] Create content version and promote
- [ ] Schema snapshot and restore
- [ ] Health check

---

## Field Types Reference

### Supported Field Types

| Type | Description | Interface |
|------|-------------|-----------|
| `string` | Single line text | Input |
| `text` | Multi-line text | Textarea |
| `integer` | Whole number | Input Numeric |
| `bigInteger` | Large whole number | Input |
| `float` | Decimal number | Input |
| `decimal` | Precise decimal | Input |
| `boolean` | True/False | Toggle |
| `json` | JSON object | Code (JSON) |
| `csv` | Comma-separated | Tags |
| `uuid` | UUID | Input |
| `hash` | Hashed value | Input Hash |
| `date` | Date only | DateTime |
| `time` | Time only | DateTime |
| `dateTime` | Date and time | DateTime |
| `timestamp` | Unix timestamp | DateTime |
| `geometry` | GeoJSON | Map |
| `alias` | Virtual field | Multiple |

### Special Field Types

| Type | Description |
|------|-------------|
| `file` | Foreign key to files |
| `files` | Many-to-many files |
| `m2o` | Many-to-one relation |
| `o2m` | One-to-many relation |
| `m2m` | Many-to-many relation |
| `m2a` | Many-to-any relation |
| `translations` | Translation links |
| `presentation` | UI-only (divider, notice) |
| `group` | Field group |

---

## References

- [Directus Documentation](https://docs.directus.io/)
- [Directus REST API Reference](https://docs.directus.io/reference/introduction)
- [Directus Self-Hosting Guide](https://docs.directus.io/self-hosted/quickstart)
- [Directus SDK](https://docs.directus.io/guides/sdk/getting-started)
- [Directus GitHub Repository](https://github.com/directus/directus)
- [Directus Flows & Operations](https://docs.directus.io/configuration/flows)
- [Directus Permissions](https://docs.directus.io/configuration/users-roles-permissions)

---

**Sources:**
- [Directus Docs](https://docs.directus.io/)
- [Directus API Reference](https://directus.io/docs/api)
- [Directus Authentication](https://directus.io/docs/api/authentication)
- [Directus Token Authentication Guide](https://www.restack.io/docs/directus-knowledge-directus-token-authentication)

---

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