@directus/api 30.0.0 → 31.0.0

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

@@ -0,0 +1,336 @@
+Perform CRUD operations on Directus Collections.
+
+<actions>
+
+- `create`: Add new collections
+- `read`: Retrieve available collections
+- `update`: Modify existing collections
+- `delete`: Remove collections </actions>
+
+<collection_structure>
+
+### Collection Structure
+
+```json
+{
+	"collection": "products",
+	"meta": {
+		"collection": "ai_prompts",
+		"icon": "inventory_2", // Any Material Symbols icons
+		"note": "Main product catalog with inventory tracking" // Helpful 1 sentence description
+		"color": "#6366F1", // Color shown in content module sidebar
+		"singleton": false, // Single-item collections (settings, globals)
+		"hidden": false, // Hide from navigation
+		"accountability": "all", // Track who activity and revisions (`"all"`, `"activity"`, `null`)
+		"sort_field": "sort", // Default sorting field (auto-creates if needed)
+		"archive_app_filter": true, // Enable soft delete in the app
+		"archive_field": "status", // Field used for archiving (status, deleted_at, etc.)
+		"archive_value": "archived", // Value that marks items as archived
+		"unarchive_value": "published", // Value that marks items as active
+		"display_template": "{{name}} - ${{price}}",
+		"versioning": false, // Enable content versioning for this collection
+		"sort": 2, // Sort order for this collection
+		"group": null, // Parent collection (use to group and nest collections in data model)
+		"collapse": "open" // Default collection to expanded or collapsed if child collections
+		"preview_url": "https://store.example.com/products/{{slug}}", // Live preview URL to view items within collection - supports using template variables
+		"translations": [
+			{
+				"language": "en-US",
+				"translation": "Products",
+				"singular": "product",
+				"plural": "products"
+			},
+			{
+				"language": "es-ES",
+				"translation": "Productos",
+				"singular": "producto",
+				"plural": "productos"
+			}
+		],
+	}
+}
+```
+
+</collection_structure>
+
+<creating_collections>
+
+- **Primary Keys**: Use UUID primary keys (see `fields` tool `<primary_keys>` section for detailed guidance)
+- **System Fields**: Include system fields for content collections (see `<system_fields>` section below for complete
+  template) unless specifically asked by user to omit them.
+- ALWAYS show the collection URL to the user if it is present in the result.
+- When creating a new collection, include both collection settings and initial fields (see `fields` tool for complete
+  examples).
+
+### Basic Collection Example
+
+```json
+{
+	"action": "create",
+	"data": {
+		"collection": "articles",
+		"fields": [
+			{
+				"field": "id",
+				"type": "uuid",
+				"meta": { "special": ["uuid"], "hidden": true, "readonly": true, "interface": "input" },
+				"schema": { "is_primary_key": true, "length": 36, "has_auto_increment": false }
+			},
+			{
+				"field": "title",
+				"type": "string",
+				"meta": { "interface": "input", "required": true },
+				"schema": { "is_nullable": false }
+			}
+		],
+		"schema": {}, // Always send empty object for new collection unless creating a folder collection
+		"meta": {
+			"singleton": false,
+			"display_template": "{{title}}"
+		}
+	}
+}
+```
+
+</creating_collections>
+
+<system_fields>
+
+### Complete System Fields Template
+
+For content collections (blogs, products, pages), include these optional system fields for full CMS functionality:
+
+```json
+{
+	"action": "create",
+	"data": {
+		"collection": "articles",
+		"fields": [
+			{
+				"field": "id",
+				"type": "uuid",
+				"meta": {
+					"hidden": true,
+					"readonly": true,
+					"interface": "input",
+					"special": ["uuid"]
+				},
+				"schema": {
+					"is_primary_key": true,
+					"length": 36,
+					"has_auto_increment": false
+				}
+			},
+			{
+				"field": "status",
+				"type": "string",
+				"meta": {
+					"width": "full",
+					"options": {
+						// You might choose to customize these options based on the users request
+						"choices": [
+							{
+								"text": "$t:published",
+								"value": "published",
+								"color": "var(--theme--primary)"
+							},
+							{
+								"text": "$t:draft",
+								"value": "draft",
+								"color": "var(--theme--foreground)"
+							},
+							{
+								"text": "$t:archived",
+								"value": "archived",
+								"color": "var(--theme--warning)"
+							}
+						]
+					},
+					"interface": "select-dropdown",
+					"display": "labels",
+					"display_options": {
+						"showAsDot": true,
+						"choices": [
+							{
+								"text": "$t:published",
+								"value": "published",
+								"color": "var(--theme--primary)",
+								"foreground": "var(--theme--primary)",
+								"background": "var(--theme--primary-background)"
+							},
+							{
+								"text": "$t:draft",
+								"value": "draft",
+								"color": "var(--theme--foreground)",
+								"foreground": "var(--theme--foreground)",
+								"background": "var(--theme--background-normal)"
+							},
+							{
+								"text": "$t:archived",
+								"value": "archived",
+								"color": "var(--theme--warning)",
+								"foreground": "var(--theme--warning)",
+								"background": "var(--theme--warning-background)"
+							}
+						]
+					}
+				},
+				"schema": {
+					"default_value": "draft",
+					"is_nullable": false
+				}
+			},
+			{
+				"field": "sort",
+				"type": "integer",
+				"meta": {
+					"interface": "input",
+					"hidden": true
+				},
+				"schema": {}
+			},
+			{
+				"field": "user_created",
+				"type": "uuid",
+				"meta": {
+					"special": ["user-created"],
+					"interface": "select-dropdown-m2o",
+					"options": {
+						"template": "{{avatar}} {{first_name}} {{last_name}}"
+					},
+					"display": "user",
+					"readonly": true,
+					"hidden": true,
+					"width": "half"
+				},
+				"schema": {}
+			},
+			{
+				"field": "date_created",
+				"type": "timestamp",
+				"meta": {
+					"special": ["date-created"],
+					"interface": "datetime",
+					"readonly": true,
+					"hidden": true,
+					"width": "half",
+					"display": "datetime",
+					"display_options": {
+						"relative": true
+					}
+				},
+				"schema": {}
+			},
+			{
+				"field": "user_updated",
+				"type": "uuid",
+				"meta": {
+					"special": ["user-updated"],
+					"interface": "select-dropdown-m2o",
+					"options": {
+						"template": "{{avatar}} {{first_name}} {{last_name}}"
+					},
+					"display": "user",
+					"readonly": true,
+					"hidden": true,
+					"width": "half"
+				},
+				"schema": {}
+			},
+			{
+				"field": "date_updated",
+				"type": "timestamp",
+				"meta": {
+					"special": ["date-updated"],
+					"interface": "datetime",
+					"readonly": true,
+					"hidden": true,
+					"width": "half",
+					"display": "datetime",
+					"display_options": {
+						"relative": true
+					}
+				},
+				"schema": {}
+			}
+		],
+		"schema": {}, // Always send empty object for new collection unless creating a folder collection
+		"meta": {
+			"sort_field": "sort",
+			"archive_field": "status",
+			"archive_value": "archived",
+			"unarchive_value": "draft",
+			"singleton": false
+		}
+	}
+}
+```
+
+**System Fields Explained:**
+
+- `status` - Content workflow (draft/published/archived) with visual indicators
+- `sort` - Manual ordering capability (used with `sort_field` in collection meta)
+- `user_created`/`user_updated` - Track content authors and editors (requires relations to `directus_users`)
+- `date_created`/`date_updated` - Automatic timestamps for content lifecycle tracking
+
+**Required Relations for User Fields:** After creating the collection, add relations for user tracking fields (use
+`relations` tool):
+
+```json
+// User created relation
+{
+	"action": "create",
+	"data": {
+		"collection": "articles",
+		"field": "user_created",
+		"related_collection": "directus_users",
+		"schema": {}
+	}
+}
+
+// User updated relation
+{
+	"action": "create",
+	"data": {
+		"collection": "articles",
+		"field": "user_updated",
+		"related_collection": "directus_users",
+		"schema": {}
+	}
+}
+```
+
+</system_fields>
+
+<translations>
+For collection name translations, check for `languages` collection first, then provide collection names in available languages (similar to field translations - see `fields` tool `<translations>` section for translation workflow).
+
+```json
+{
+	"meta": {
+		"translations": [
+			{ "language": "en-US", "translation": "Products", "singular": "product", "plural": "products" },
+			{ "language": "es-ES", "translation": "Productos", "singular": "producto", "plural": "productos" }
+		]
+	}
+}
+```
+
+</translations>
+
+<display_templates>
+
+Control how collection items appear in relationships and lists:
+
+```json
+{
+	"meta": {
+		"display_template": "{{name}} - {{category}} ({{status}})"
+	}
+}
+```
+
+**Template Variables:**
+
+- `{{field_name}}` - Any field from the collection
+- `{{field_name.nested}}` - Access nested object properties </display_templates>