mcphub/docs/directus-plugin-design.md

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

# 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

-- 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

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

# 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

# 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

# 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	به‌روزرسانی پروفایل

# 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 کاربر فعلی

# 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

# 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

# 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

# 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

# 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 قدرتمندی استفاده می‌کند:

// 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)

// 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

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

# 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

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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

# 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

# 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
• Directus REST API Reference
• Directus Self-Hosting Guide
• Directus SDK
• Directus GitHub Repository
• Directus Flows & Operations
• Directus Permissions

---

Sources:

• Directus Docs
• Directus API Reference
• Directus Authentication
• Directus Token Authentication Guide

---

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