@directus/api 30.0.0 → 31.0.0

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

@@ -0,0 +1,521 @@
+Perform CRUD operations on Directus Fields.
+
+<actions>
+- `create`: Add one or multiple fields to a collection
+- `read`: View field configurations
+- `update`: Update one or multiple fields
+- `delete`: Remove fields
+</actions>
+
+<field_types>
+
+- **Text**: `string` (max 255 chars), `text` (unlimited), `uuid` (relations/IDs), `hash` (passwords)
+- **Numeric**: `integer`, `bigInteger`, `float`, `decimal` (for financial precision)
+- **Date/Time**: `timestamp`, `datetime`, `date`, `time`
+- **Boolean**: `boolean` for toggles/flags
+- **Structured**: `json` (complex data), `csv` (tags/lists)
+- **Alias**: Virtual fields for relations (`o2m`, `m2m`, `m2a`, `files`, `translations`)
+- **Geospatial**: `point`, `lineString`, `polygon` for maps </field_types>
+
+<adding_fields>
+
+**Important**: When using the `fields` tool, `data` must always be an array of field objects, even for single fields.
+Make sure you include `meta` and `schema` objects for each field.
+
+Add fields to existing collections:
+
+```json
+{
+	"action": "create",
+	"collection": "articles",
+	"data": [
+		{
+			"field": "excerpt",
+			"type": "text",
+			"meta": {
+				"interface": "input-rich-text-md",
+				"special": null,
+				"note": "Article excerpt for previews and SEO. Supports markdown formatting.",
+				"translations": [
+					{
+						"language": "en-US",
+						"translation": "Excerpt"
+					}
+				],
+				"options": {
+					"placeholder": null,
+					"customSyntax": null
+				},
+				"display": "formatted-value",
+				"display_options": { "format": true }
+			},
+			"schema": {
+				"name": "test",
+				"table": "random_collection",
+				"data_type": "text"
+			}
+		}
+	]
+}
+```
+
+**Multiple Fields Example:**
+
+```json
+{
+	"action": "create",
+	"collection": "articles",
+	"data": [
+		{
+			"field": "title",
+			"type": "string"
+			// Rest of field data
+		},
+		{
+			"field": "content",
+			"type": "text"
+			// Rest of field data
+		}
+	]
+}
+```
+
+**Note**: You can omit `null` or `false` values from the schema object. </adding_fields>
+
+<relationship_fields>
+
+**CRITICAL**: Field type and meta.special determine relationship behavior.
+
+- **M2O**: `type: "uuid"`, `special: ["m2o"]`, interface: `select-dropdown-m2o` → then create relation
+- **O2M**: `type: "alias"`, `special: ["o2m"]`, interface: `list-o2m` → auto-created with M2O
+- **M2M**: `type: "alias"`, `special: ["m2m"]`, interface: `list-m2m` → needs junction collection
+- **M2A**: `type: "alias"`, `special: ["m2a"]`, interface: `list-m2a` → polymorphic, needs junction
+- **File**: `type: "uuid"`, `special: ["file"]`, interface: `file` or `file-image` → single file relation
+- **Files**: `type: "alias"`, `special: ["files"]`, interface: `files` → multiple files via M2M
+- **Translations**: `type: "alias"`, `special: ["translations"]`, interface: `translations` → special M2M
+
+### M2O Field Example
+
+```json
+{
+	"collection": "posts",
+	"field": "author",
+	"type": "uuid",
+	"schema": {
+		"name": "author",
+		"table": "posts",
+		"data_type": "uuid",
+		"is_nullable": true,
+		"foreign_key_schema": "public",
+		"foreign_key_table": "team",
+		"foreign_key_column": "id"
+	},
+	"meta": {
+		"collection": "posts",
+		"field": "author",
+		"special": ["m2o"],
+		"interface": "select-dropdown-m2o",
+		"options": {
+			"template": "{{image.$thumbnail}} {{name}}"
+		},
+		"display": "related-values",
+		"display_options": {
+			"template": "{{image.$thumbnail}} {{name}}"
+		},
+		"sort": 15,
+		"width": "half"
+	}
+}
+```
+
+### O2M Field Example
+
+```json
+{
+	"collection": "posts",
+	"field": "comments",
+	"type": "alias",
+	"schema": null,
+	"meta": {
+		"collection": "posts",
+		"field": "comments",
+		"special": ["o2m"],
+		"interface": "list-o2m",
+		"options": {
+			"template": "{{author}} - {{content}} ({{status}})"
+		},
+		"display": "related-values",
+		"display_options": {
+			"template": "{{author}} - {{content}} ({{status}})"
+		},
+		"sort": 10,
+		"width": "full",
+		"required": false,
+		"group": null
+	}
+}
+```
+
+### M2M Field Example
+
+```json
+{
+	"collection": "posts",
+	"field": "categories",
+	"type": "alias",
+	"schema": null,
+	"meta": {
+		"collection": "posts",
+		"field": "categories",
+		"special": ["m2m"],
+		"interface": "list-m2m",
+		"options": {
+			"template": "{{categories_id.name}} ({{categories_id.slug}})"
+		},
+		"display": "related-values",
+		"display_options": {
+			"template": "{{categories_id.name}} ({{categories_id.slug}})"
+		},
+		"sort": 9,
+		"width": "full"
+	}
+}
+```
+
+### M2A Field Example
+
+```json
+{
+	"collection": "pages",
+	"field": "blocks",
+	"type": "alias",
+	"schema": null,
+	"meta": {
+		"collection": "pages",
+		"field": "blocks",
+		"special": ["m2a"],
+		"interface": "list-m2a",
+		"options": {},
+		"display": "related-values",
+		"display_options": {
+			"template": "{{collection}}"
+		},
+		"sort": 8,
+		"width": "full"
+	}
+}
+```
+
+### File Field Example
+
+```json
+{
+	"collection": "posts",
+	"field": "featured_image",
+	"type": "uuid",
+	"schema": {
+		"name": "featured_image",
+		"table": "posts",
+		"data_type": "uuid",
+		"is_nullable": true,
+		"foreign_key_schema": "public",
+		"foreign_key_table": "directus_files",
+		"foreign_key_column": "id"
+	},
+	"meta": {
+		"collection": "posts",
+		"field": "featured_image",
+		"special": ["file"],
+		"interface": "file-image",
+		"options": {
+			"folder": "post-images"
+		},
+		"display": "image",
+		"display_options": null,
+		"sort": 1,
+		"width": "half",
+		"required": false,
+		"group": "media"
+	}
+}
+```
+
+### Files Field Example
+
+```json
+{
+	"collection": "posts",
+	"field": "gallery",
+	"type": "alias",
+	"schema": null,
+	"meta": {
+		"collection": "posts",
+		"field": "gallery",
+		"special": ["files"],
+		"interface": "files",
+		"options": null,
+		"display": "related-values",
+		"display_options": null,
+		"sort": 4,
+		"width": "full"
+	}
+}
+```
+
+### Translations Field Example
+
+```json
+{
+	"collection": "posts",
+	"field": "translations",
+	"type": "alias",
+	"schema": null,
+	"meta": {
+		"collection": "posts",
+		"field": "translations",
+		"special": ["translations"],
+		"interface": "translations",
+		"options": {
+			"userLanguage": true,
+			"defaultOpenSplitView": true
+		},
+		"display": "translations",
+		"display_options": {
+			"template": "{{title}}", // Field to display from the translated collection (ie post title)
+			"languageField": "name" // Name of the language field from the languages collection
+		},
+		"sort": 22,
+		"width": "full"
+	}
+}
+```
+
+**Note**: Alias fields don't need a schema object since they're virtual. </relationship_fields>
+
+<primary_keys> **🎯 ALWAYS use UUID as primary keys for new collections unless integers or manually entered strings ares
+specifically requested by the user.**
+
+**UUID Primary Key Template:**
+
+```json
+{
+	"field": "id",
+	"type": "uuid",
+	"meta": { "hidden": true, "readonly": true, "interface": "input", "special": ["uuid"] },
+	"schema": { "is_primary_key": true, "length": 36, "has_auto_increment": false }
+}
+```
+
+</primary_keys>
+
+<interfaces>
+## Common Interfaces
+
+**Text**: `input`, `input-multiline`, `input-rich-text-md`, `input-rich-text-html`, `input-hash`, `translations`
+**Selection**: `select-dropdown`, `select-multiple-dropdown`, `select-radio`, `select-multiple-checkbox`, `tags`,
+`boolean`, `slider` **Date/Time**: `datetime`, `date`, `time` **Relational**: `select-dropdown-m2o`, `list-o2m`,
+`list-m2m`, `list-m2a` **Files**: `file`, `files`, `file-image` **Advanced**: `input-code`, `map`, `group-raw`,
+`group-detail` </interfaces>
+
+<field_configuration>
+
+### Layout
+
+- **width**: `"half"` (380px max), `"full"` (760px max, default), `"fill"` (no limit)
+- **sort**: Field order in forms
+- **group**: Group related fields into collapsible sections (must be used with `alias` group fields)
+
+### Schema Properties
+
+- **default_value**: Default for new items
+- **is_nullable**: Can be null
+- **is_unique**: Must be unique
+- **length**: Max length for strings
+
+### Meta Properties
+
+- **required**: Must have value
+- **readonly**: Cannot edit after creation
+- **hidden**: Hidden from UI (still in API)
+- **validation**: Custom validation rules
+- **validation_message**: Custom error messages
+- **note**: Context for non-obvious fields
+
+### Conditions
+
+Dynamically control field behavior based on other field values:
+
+```json
+{
+	"conditions": [
+		{
+			"name": "Hide If Author Is Null",
+			"rule": {
+				"_and": [
+					{
+						"author": {
+							"_null": true
+						}
+					}
+				]
+			},
+			"hidden": true
+		},
+		{
+			"name": "Required If Published",
+			"rule": {
+				"status": {
+					"_eq": "published"
+				}
+			},
+			"required": true
+		}
+	]
+}
+```
+
+**Condition Properties**:
+
+- `name`: Description of the condition
+- `rule`: Filter rules using Directus filter syntax
+- Can set: `hidden`, `readonly`, `required`, or interface-specific options
+
+**Common Rules**:
+
+- `_null`: Check if field is null
+- `_eq`: Equals specific value
+- `_neq`: Not equals
+- `_in`: Value in array
+- `_and`/`_or`: Combine multiple conditions
+
+### Special Fields
+
+- `special: ["uuid"]`: Auto-generate UUID
+- `special: ["user-created"]`: Track creating user
+- `special: ["date-created"]`: Track creation time
+- `special: ["user-updated"]`: Track last editor
+- `special: ["date-updated"]`: Track last edit time
+- `special: ["cast-json"]`: Cast JSON strings to objects </field_configuration>
+
+<translations>
+Field names can (and should be) translated for editors using the app.
+Check for `languages` collection first, then add field translations based on which languages are stored in DB. IF not 99% sure, confirm with user first.
+
+```json
+"translations": [
+  {"language": "en-US", "translation": "Title"},
+  {"language": "es-ES", "translation": "Título"}
+]
+```
+
+</translations>
+
+<display_templates> Display templates can be customized used to enhance the UX for editors.
+
+```json
+"display": "related-values",
+"display_options": {
+  "template": "{{first_name}} {{last_name}}"
+}
+```
+
+**Display types**: `raw`, `formatted-value`, `labels`, `datetime`, `user`, `file`, `related-values` </display_templates>
+
+<complete_example>
+
+#### Complete Field Example with Advanced Features
+
+This shows a real field configuration with validation, conditions, and all metadata (as returned from a read operation):
+
+```json
+{
+	"collection": "block_button",
+	"field": "url",
+	"type": "string",
+	"schema": {
+		"name": "url",
+		"table": "block_button",
+		"data_type": "character varying", // Database-specific type
+		"default_value": null,
+		"generation_expression": null,
+		"max_length": 255, // String length limit
+		"numeric_precision": null,
+		"numeric_scale": null,
+		"is_generated": false,
+		"is_nullable": true,
+		"is_unique": false,
+		"is_indexed": false,
+		"is_primary_key": false,
+		"has_auto_increment": false,
+		"foreign_key_schema": null, // Would contain relation info for M2O fields
+		"foreign_key_table": null,
+		"foreign_key_column": null,
+		"comment": null
+	},
+	"meta": {
+		"id": 811, // Auto-generated field ID (not used in create)
+		"collection": "block_button",
+		"field": "url",
+		"special": null, // No special behavior for this field
+		"interface": "input",
+		"options": {
+			"iconLeft": "link", // Icon displayed in the input
+			"trim": true // Remove whitespace on save
+		},
+		"display": "formatted-value",
+		"display_options": {
+			"format": true // Apply auto formatting based on field type
+		},
+		"readonly": false,
+		"hidden": true, // Hidden by default, shown conditionally
+		"sort": 11, // Field order in forms
+		"width": "half",
+		"translations": null, // No field name translations
+		"note": "The URL to link to. Could be relative (ie `/my-page`) or a full external URL (ie `https://docs.directus.io`)",
+		"conditions": [
+			{
+				"hidden": false, // Show field when condition is met
+				"name": "If type = external",
+				"options": {
+					"clear": false,
+					"font": "sans-serif",
+					"masked": false,
+					"slug": false,
+					"trim": false
+				},
+				"rule": {
+					"_and": [
+						{
+							"type": {
+								// Show when 'type' field equals 'url'
+								"_eq": "url"
+							}
+						}
+					]
+				}
+			}
+		],
+		"required": false,
+		"group": null,
+		"validation": {
+			"_and": [
+				{
+					"url": {
+						"_regex": "^(?:\\/[A-Za-z0-9\\-._~%!$&'()*+,;=:@\\/]*|https?:\\/\\/[^\\s/$.?#].[^\\s]*)$"
+					}
+				}
+			]
+		}, // Regex validation for URLs (relative or absolute)
+		"validation_message": "Invalid URL. Check your URL and try again. Properly formatted relative URLs (`/pages/test` ) and absolute URLs (`https://example.com`) are supported."
+	}
+}
+```
+
+</complete_example>
+
+<related_tools>
+
+## Related Tools
+
+- `collections`: Create containers for fields
+- `relations`: Connect fields between collections </related_tools>

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

@@ -0,0 +1,180 @@
+Perform CRUD operations on files in Directus.
+
+## Actions
+
+- **`read`**: List/query metadata or get specific items by ID
+- **`update`**: Modify existing metadata
+- **`delete`**: Remove files by keys
+- **`import`**: Import a file from a URL and create or update its file data
+
+## Example Operations
+
+### Reading File Metadata
+
+```json
+{
+	"action": "read",
+	"query": {
+		"fields": ["id", "title", "type", "filesize", "width", "height"],
+		"filter": { "type": { "_starts_with": "image/" } },
+		"limit": 10
+	}
+}
+```
+
+### Get Single File Metadata
+
+```json
+{
+	"action": "read",
+	"keys": ["file-uuid-here"]
+}
+```
+
+### Import a File via URL
+
+```json
+{
+	"action": "import",
+	"data": [
+		{
+			"url": "file-url",
+			"file": {
+				"title": "New Title",
+				"description": "Updated description",
+				"tags": ["tag1", "tag2", "category"],
+				"folder": "folder-uuid"
+			}
+		}
+	]
+}
+```
+
+### Update File Metadata
+
+**Single file:**
+
+```json
+{
+	"action": "update",
+	"keys": ["file-uuid"],
+	"data": {
+		"title": "New Title",
+		"description": "Updated description",
+		"tags": ["tag1", "tag2", "category"],
+		"folder": "folder-uuid"
+	}
+}
+```
+
+**Batch update:**
+
+```json
+{
+	"action": "update",
+	"data": [
+		{ "id": "file-uuid-1", "title": "New Title 1" },
+		{ "id": "file-uuid-2", "title": "New Title 2" }
+	]
+}
+```
+
+### Common Filters
+
+```json
+{
+	"query": {
+		"filter": {
+			"_and": [
+				{ "type": { "_icontains": "/png" } }, // PNG files only
+				{ "folder": { "_eq": "folder-uuid" } }, // Specific folder
+				{ "filesize": { "_lt": 5000000 } }, // Under 5MB
+				{ "uploaded_on": { "_gte": "$NOW(-7 days)" } } // Within last week
+			]
+		}
+	}
+}
+```
+
+## File Metadata Fields
+
+- `id`: Unique identifier
+- `storage`: Storage adapter used
+- `filename_disk`: Actual filename on disk
+- `filename_download`: Suggested download filename
+- `title`: Display title
+- `type`: MIME type (e.g., "image/jpeg", "application/pdf")
+- `folder`: Parent folder ID
+- `uploaded_by`: User who uploaded
+- `uploaded_on`: Upload timestamp
+- `modified_by`: Last modifier
+- `modified_on`: Last modification time
+- `filesize`: Size in bytes
+- `width`/`height`: Dimensions for images (in pixels)
+- `duration`: Length for video/audio
+- `description`: File description
+- `location`: Geo-location data
+- `tags`: Array of tag strings (e.g., ["product", "red", "handbag"])
+- `metadata`: Additional metadata object
+- `focal_point_x`: Horizontal focal point (in pixels from left edge)
+- `focal_point_y`: Vertical focal point (in pixels from top edge)
+
+## Real-World Use Cases
+
+### Asset Selection for Content
+
+Find appropriate images for articles, pages, or products:
+
+_Example: "Find images in our asset library related to customer support for our new help center article."_
+
+```json
+{
+	"action": "read",
+	"query": {
+		"fields": ["id", "title", "description", "tags", "type"],
+		"search": "help center"
+	}
+}
+```
+
+### Asset Organization & Cleanup
+
+Transform generic files into well-organized, searchable assets:
+
+1. **Find files needing metadata:**
+
+```json
+{
+	"action": "read",
+	"query": {
+		"fields": ["id", "filename_disk", "title", "description"],
+		"filter": { "description": { "_null": true } }
+	}
+}
+```
+
+2. **Analyze with vision (use `assets` tool for base64):** Get image content for AI analysis
+
+3. **Update with descriptive metadata:**
+
+```json
+{
+	"action": "update",
+	"keys": ["image-uuid"],
+	"data": {
+		"title": "Red leather handbag product photo",
+		"description": "Professional e-commerce photo with white background",
+		"tags": ["handbag", "leather", "red", "product-photo", "accessories"],
+		"focal_point_x": 512,
+		"focal_point_y": 300 // Focal points ensure that when images are cropped for different aspect ratios (thumbnails, hero images, etc.), the important subject remains visible. Coordinates are in pixels from the top-left corner of the original image.
+	}
+}
+```
+
+## Key Points
+
+- **ALWAYS pass data as native objects**, NOT stringified JSON
+- **Metadata only**: This tool manages file metadata, not file content or uploads
+- **Permissions**: Respects Directus access control
+- **Arrays required**: `keys` and `tags` must be arrays: `["item"]` not `"item"`
+- **Performance**: Large files handled automatically but may impact performance