@directus/api 30.0.0 → 31.0.0

package/dist/mcp/tools/prompts/relations.md

@@ -0,0 +1,386 @@
+Create and manage relationships between Directus Collections.
+
+<prerequisites>
+Before creating relations:
+✓ Collections must exist (use `collections` tool)
+✓ Fields must be created with correct types (use `fields` tool)
+✓ Junction collections must exist for M2M/M2A relationships
+✓ Optional system user fields (`user_created`/`user_updated`) require relations to `directus_users` (see `collections` tool `<system_fields>` section)
+</prerequisites>
+
+<actions>
+- `create`: Establish relationship between collections
+- `read`: View existing relationships
+- `update`: Modify relationship settings (only schema.on_delete/on_update and meta can be updated)
+- `delete`: Remove relationships
+</actions>
+
+<basic_relation> After creating relational fields, define the relationship:
+
+```json
+{
+	"action": "create",
+	"data": {
+		"collection": "articles",
+		"field": "author",
+		"related_collection": "directus_users",
+		"meta": { "sort_field": null },
+		"schema": { "on_delete": "SET NULL" }
+	}
+}
+```
+
+</basic_relation>
+
+<relationship_types> <m2o_workflow>
+
+### M2O (Many-to-One)
+
+Multiple items in one collection relate to one item in another.
+
+**Example**: Many articles → one author
+
+**Complete M2O Workflow**:
+
+1. **Add M2O field** to the "many" collection → Use `fields` tool with `type: "uuid"` and
+   `interface: "select-dropdown-m2o"` (see `fields` tool `<relationship_fields>` M2O example)
+
+2. **Create relation** (use `relations` tool):
+
+```json
+{
+	"action": "create",
+	"collection": "articles",
+	"field": "author",
+	"data": {
+		"collection": "articles",
+		"field": "author",
+		"related_collection": "directus_users",
+		"schema": { "on_delete": "SET NULL" }
+	}
+}
+```
+
+</m2o_workflow>
+
+<o2m_workflow>
+
+### O2M (One-to-Many)
+
+One item in a collection relates to many items in another collection.
+
+**Example**: One author → many articles
+
+**Complete O2M Workflow**:
+
+1. **Add O2M field** to the "one" collection → Use `fields` tool with `type: "alias"`, `special: ["o2m"]`, and
+   `interface: "list-o2m"`
+
+2. **Create relation** connecting to existing M2O field (use `relations` tool):
+
+```json
+{
+	"action": "create",
+	"collection": "articles",
+	"field": "author",
+	"data": {
+		"collection": "articles",
+		"field": "author",
+		"related_collection": "authors",
+		"meta": {
+			"one_field": "articles",
+			"sort_field": null
+		},
+		"schema": {
+			"on_delete": "SET NULL"
+		}
+	}
+}
+```
+
+</o2m_workflow>
+
+<m2m_workflow>
+
+### M2M (Many-to-Many)
+
+Items in both collections can relate to multiple items in the other.
+
+**Example**: Articles ↔ Tags
+
+**Complete M2M Workflow**:
+
+1. **Create junction collection** → Use `collections` tool to create `article_tags` with UUID primary key
+
+2. **Add alias fields** to both collections → Use `fields` tool with `type: "alias"`, `special: ["m2m"]`, and
+   `interface: "list-m2m"` (see `fields` tool `<relationship_fields>` M2M example)
+
+3. **Add junction fields** → Use `fields` tool to add `article_id` (UUID), `tag_id` (UUID), and optional `sort`
+   (integer) fields to junction collection
+
+4. **Create bidirectional relations** (use `relations` tool with CASCADE):
+
+```json
+// First relation
+{
+  "action": "create",
+  "collection": "article_tags",
+  "field": "article_id",
+  "data": {
+    "collection": "article_tags",
+    "field": "article_id",
+    "related_collection": "articles",
+    "meta": {
+      "one_field": "tags",
+      "junction_field": "tag_id",
+      "sort_field": "sort"
+    },
+    "schema": {"on_delete": "CASCADE"}
+  }
+}
+
+// Second relation
+{
+  "action": "create",
+  "collection": "article_tags",
+  "field": "tag_id",
+  "data": {
+    "collection": "article_tags",
+    "field": "tag_id",
+    "related_collection": "tags",
+    "meta": {
+      "one_field": "articles",
+      "junction_field": "article_id"
+    },
+    "schema": {"on_delete": "CASCADE"}
+  }
+}
+```
+
+</m2m_workflow>
+
+<m2a_workflow>
+
+### M2A (Many-to-Any)
+
+Items can relate to items from multiple different collections.
+
+**Example**: Page blocks (hero, text, gallery)
+
+**Complete M2A Workflow**:
+
+1. **Create block collections** → Use `collections` tool to create each block type (e.g., `block_hero`, `block_text`,
+   `block_gallery`) with UUID primary keys and specific fields
+
+2. **Create junction collection** → Use `collections` tool to create `page_blocks` junction (hidden collection with UUID
+   primary key)
+
+3. **Add M2A field** → Use `fields` tool with `type: "alias"`, `special: ["m2a"]`, and `interface: "list-m2a"`
+
+4. **Add junction fields** → Use `fields` tool to add `page` (UUID), `item` (string), `collection` (string), and `sort`
+   (integer) fields to junction
+
+5. **Create relations** (use `relations` tool):
+
+```json
+// Item relation (polymorphic)
+{
+  "action": "create",
+  "collection": "page_blocks",
+  "field": "item",
+  "data": {
+    "collection": "page_blocks",
+    "field": "item",
+    "related_collection": null,
+    "meta": {
+      "one_allowed_collections": ["block_hero", "block_text", "block_gallery"],
+      "one_collection_field": "collection",
+      "junction_field": "page_id"
+    }
+  }
+}
+
+// Page relation
+{
+  "action": "create",
+  "collection": "page_blocks",
+  "field": "page_id",
+  "data": {
+    "collection": "page_blocks",
+    "field": "page_id",
+    "related_collection": "pages",
+    "meta": {
+      "one_field": "blocks",
+      "junction_field": "item",
+      "sort_field": "sort"
+    },
+    "schema": {"on_delete": "CASCADE"}
+  }
+}
+```
+
+</m2a_workflow>
+
+<file_relationships>
+
+### File/Files Relationships
+
+**Single File (M2O)**:
+
+1. **Add file field** → Use `fields` tool with `type: "uuid"`, `special: ["file"]`, and `interface: "file"`
+
+2. **Create relation** (use `relations` tool):
+
+```json
+{
+	"action": "create",
+	"collection": "articles",
+	"field": "cover_image",
+	"data": {
+		"collection": "articles",
+		"field": "cover_image",
+		"related_collection": "directus_files",
+		"schema": { "on_delete": "SET NULL" }
+	}
+}
+```
+
+**Multiple Files (M2M)**:
+
+**Complete Files Workflow**:
+
+1. **Create junction collection** → Use `collections` tool to create junction with UUID primary key
+
+2. **Add files field** to main collection → Use `fields` tool with `type: "alias"`, `special: ["files"]`, and
+   `interface: "files"` (see `fields` tool `<relationship_fields>` Files example)
+
+3. **Add junction fields** → Use `fields` tool to add hidden `article_id` and `directus_files_id` (both UUID) fields to
+   junction
+
+4. **Create relations** (use `relations` tool):
+
+```json
+// Article relation
+{
+  "action": "create",
+  "collection": "article_images",
+  "field": "article_id",
+  "data": {
+    "collection": "article_images",
+    "field": "article_id",
+    "related_collection": "articles",
+    "meta": {
+      "one_field": "images",
+      "junction_field": "directus_files_id"
+    },
+    "schema": {"on_delete": "CASCADE"}
+  }
+}
+
+// File relation
+{
+  "action": "create",
+  "collection": "article_images",
+  "field": "directus_files_id",
+  "data": {
+    "collection": "article_images",
+    "field": "directus_files_id",
+    "related_collection": "directus_files",
+    "meta": {
+      "junction_field": "article_id"
+    },
+    "schema": {"on_delete": "CASCADE"}
+  }
+}
+```
+
+</file_relationships>
+
+<translations_workflow>
+
+### Translations
+
+Special M2M relationship with `languages` collection.
+
+**Complete Translations Workflow**:
+
+1. **Ensure languages collection exists** (use `schema` tool to check)
+
+2. **Create translations junction** → Use `collections` tool to create junction with UUID primary key
+
+3. **Add translations field** → Use `fields` tool with `type: "alias"`, `special: ["translations"]`, and
+   `interface: "translations"` (see `fields` tool `<relationship_fields>` Translations example)
+
+4. **Configure junction fields and relations** → Follow M2M pattern with languages collection </translations_workflow>
+   </relationship_types>
+
+<relation_settings>
+
+## Relation Settings
+
+### Schema Options
+
+- `on_delete`:
+  - `CASCADE` (default for M2M) - Delete related items
+  - `SET NULL` (default for M2O) - Set field to null
+  - `NO ACTION` - Prevent deletion
+  - `RESTRICT` - Prevent if related items exist
+  - `SET DEFAULT` - Set to default value
+
+- `on_update`:
+  - Same options as `on_delete`
+
+### Meta Options
+
+- `one_field`: Field name in related collection (for O2M side)
+- `junction_field`: Opposite field in junction table
+- `sort_field`: Enable manual sorting (typically an integer field)
+- `one_deselect_action`: `nullify` or `delete`
+- `one_allowed_collections`: Array of collection names for M2A
+- `one_collection_field`: Field that stores collection name in M2A </relation_settings>
+
+<common_patterns>
+
+## Common Patterns
+
+### Blog System
+
+1. `articles` M2O `directus_users` (author)
+2. `articles` M2M `tags`
+3. `articles` M2O `directus_files` (cover_image)
+4. `articles` M2M `directus_files` (gallery)
+5. `articles` O2M `comments`
+6. `comments` M2O `directus_users` (author)
+
+### E-commerce
+
+1. `products` M2M `categories`
+2. `products` M2O `brands`
+3. `products` O2M `reviews`
+4. `products` M2M `directus_files` (gallery)
+5. `orders` O2M `order_items`
+6. `order_items` M2O `products`
+7. `orders` M2O `directus_users` (customer)
+8. `reviews` M2O `directus_users` (reviewer)
+
+### Page Builder
+
+- `pages` M2A `blocks` field (`page_blocks` junction collection)
+- Collections: `block_hero`, `block_text`, `block_gallery` </common_patterns>
+
+<naming_conventions>
+
+## Naming Conventions
+
+- Junction collections: `{singular}_{plural}` (e.g., `product_categories`)
+- Junction fields: Singular form of related collection (e.g., `product_id`, `category_id`)
+- Alias fields: Plural form for many relations (e.g., `tags`, `categories`)
+- M2O fields: Singular form (e.g., `author`, `brand`) </naming_conventions>
+
+<related_tools>
+
+## Related Tools
+
+- `collections`: Create collections and junctions first
+- `fields`: Add relational fields before creating relations
+- `schema`: View complete relationship structure </related_tools>

package/dist/mcp/tools/prompts/schema.md

@@ -0,0 +1,130 @@
+Retrieve essential Directus schema information to understand the data structure - collections, fields, and
+relationships. This is a **READ-ONLY discovery tool** designed to help you explore and comprehend existing schema. It is
+for schema exploration and understanding only. For schema modifications, use the dedicated `collections`, `fields`, and
+`relations` tools.
+
+**Note**: This tool provides an extremly curated response optimized for LLM understanding, not the raw Directus API
+schema response.
+
+## Operation Modes
+
+### Discovery Mode (Default)
+
+**Usage**: Call without parameters or with empty `keys` array
+
+```json
+{}
+```
+
+**Returns**: Lightweight schema overview
+
+- `collections`: Alphabetically sorted array of real collection names (database tables)
+- `collection_folders`: Alphabetically sorted array of folder names (UI-only, not real tables). Distinct from file
+  folders. They are used for grouping different collections together in the UI.
+- `notes`: Descriptions for both collections and folders (where available)
+
+**Important**: Folders share the same namespace as collections. Before creating a new collection, check the `folders`
+array to avoid naming conflicts (e.g., can't create a 'website' collection if a 'website' folder exists).
+
+**Sample Response**:
+
+```json
+{
+	"collections": ["categories", "contacts", "organizations", "pages", "posts", "products"],
+	"collection_folders": ["content", "marketing", "website"],
+	"notes": {
+		"contacts": "People at the organizations you work with",
+		"organizations": "Your clients and customers",
+		"pages": "Static pages with page builder blocks",
+		"posts": "Blog posts and articles",
+		"content": "Content management folder"
+	}
+}
+```
+
+**Use case**: Initial exploration, getting oriented with available data structures
+
+### Detailed Mode
+
+**Usage**: Specify collections to examine
+
+```json
+{ "keys": ["products", "categories", "users"] }
+```
+
+**Returns**: Object of collections with field and relation details
+
+- Field definitions (type, validation, defaults)
+- Relationship mappings (foreign keys, junction tables)
+- Interface configurations and display options
+- Field metadata and constraints
+- **Nested field structures** for JSON fields with repeaters/lists (includes recursive nesting)
+
+**Sample Response**:
+
+```json
+{
+	"posts": {
+		"id": {
+			"type": "uuid",
+			"primary_key": true,
+			"readonly": true
+		},
+		"title": {
+			"type": "string",
+			"required": true
+		},
+		"status": {
+			"type": "string",
+			"interface": {
+				"type": "select-dropdown",
+				"choices": ["draft", "published", "archived"]
+			}
+		},
+		"category": {
+			"type": "uuid",
+			"relation": {
+				"type": "m2o",
+				"related_collections": ["categories"]
+			}
+		}
+	},
+	"block_faqs": {
+		"headline": {
+			"type": "text",
+			"interface": {
+				"type": "input-rich-text-html"
+			}
+		},
+		"faqs": {
+			"type": "json",
+			"interface": {
+				"type": "list"
+			},
+			"fields": {
+				"title": {
+					"type": "text",
+					"interface": {
+						"type": "input-multiline"
+					}
+				},
+				"answer": {
+					"type": "text",
+					"interface": {
+						"type": "input-multiline"
+					}
+				}
+			}
+		}
+	}
+}
+```
+
+**Use case**: Deep-dive analysis of specific collections before working with data or schema.
+
+## Recommended Workflow
+
+1. **Discover**: Call without `keys` to see all available collections
+2. **Analyze**: Based on user requirements, identify relevant collections
+3. **Detail**: Call with specific collection names to understand field structures
+4. **Implement**: Use appropriate CRUD tools with schema knowledge

package/dist/mcp/tools/prompts/system-prompt-description.md

@@ -0,0 +1 @@
+IMPORTANT! Always call this tool first. It will retrieve important information about your role.

package/dist/mcp/tools/prompts/system-prompt.md

@@ -0,0 +1,44 @@
+You are **Directus Assistant**, an expert in Directus CMS with direct access to a Directus instance through specialized
+tools.
+
+## Core Expertise
+
+- **Content Specialist**: Content management, editing, and optimization
+- **Schema Architect**: Database design, relationships, and data modeling
+- **Automation Expert**: Flows, webhooks, and workflow configuration
+- **API Integration**: REST/GraphQL patterns and system integration
+
+## Communication Style
+
+- **Be concise**: Users prefer short, direct responses. One-line confirmations: "Created collection 'products'"
+- **Match the audience**: Technical for developers, plain language for content editors
+- **NEVER guess**: If not at least 99% about field values or user intent, ask for clarification
+
+## Critical Operations
+
+### Schema & Data Changes
+
+- **Confirm before modifying**: Collections, fields, relations always need approval from the user.
+- **Check namespace conflicts**: Collection folders and regular collections share namespace. Collection folders are
+  distinct from file folders. Collection folders are just collection entries without a corresponding table in the
+  database used for grouping.
+- **Respect workflows**: Check draft/published states before modifications
+
+### Safety Rules
+
+- **Deletions require confirmation**: ALWAYS ask before deleting anything
+- **Warn on bulk operations**: Alert when affecting many items ("This updates 500 items")
+- **Avoid duplicates**: Never create duplicates if you can't modify existing items
+- **Use semantic HTML**: No classes, IDs, or inline styles in content fields (unless explictly asked for by the user)
+
+### Error Recovery
+
+- **Auto-fix clear errors**: Retry once for obvious issues like "field X required"
+- **Stop after 2 attempts**: Consult user if errors persist or are unclear
+- **Optimize queries**: Use `fields` param to minimize overfetching and pagination for large datasets
+
+## Workflow
+
+1. Start with `schema()` to discover collections
+2. Use `schema(keys: ["collection_name"])` for field details relevant to the user task
+3. Perform operations based on user needs and permissions