@directus/api 30.0.0 → 31.0.0

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

@@ -0,0 +1,495 @@
+Manage automation flows that enable event-driven data processing and task automation. Flows consist of a trigger and a
+series of operations forming a data chain.
+
+<flow_concepts>
+
+## Key Concepts
+
+**Flow** = Trigger + Operations + Data Chain
+
+- Each flow has ONE trigger that starts execution
+- Operations execute sequentially, passing data through the chain
+- Data chain accumulates results from each step
+
+After creating a flow, use the `operations` tool to add individual operations with detailed operation syntax,
+positioning, and data chain usage. </flow_concepts>
+
+<core_fields>
+
+## Flow Data Structure
+
+All flows share these core fields for creation:
+
+- `name` (required) - Flow display name
+- `trigger` (required) - Trigger type: `event`, `webhook`, `schedule`, `operation`, `manual`
+- `status` - `active` or `inactive` (default: `active`)
+- `accountability` - `all`, `activity`, or `null` (default: `all`)
+- `icon` - Icon identifier (optional)
+- `color` - Hex color code (optional)
+- `description` - Flow description (optional)
+- `options` - Trigger-specific configuration object (optional)
+- `operation` - UUID of first operation (optional, set after creating operations) </core_fields>
+
+<crud_actions>
+
+## Actions
+
+- ALWAYS show the flow URL if it is present in the result
+
+### `read` - List/Query Flows
+
+```json
+{
+	"action": "read",
+	"query": {
+		"fields": ["id", "name", "status", "trigger", "operations"],
+		"filter": { "status": { "_eq": "active" } },
+		"limit": 10
+	}
+}
+```
+
+### `create` - Create New Flow
+
+**Required**: `name`, `trigger`
+
+```json
+{
+	"action": "create",
+	"data": {
+		"name": "Send email when new post is published",
+		"icon": "bolt", // Optional icon
+		"color": "#FFA439", // Optional hex color
+		"description": "checks if new post is published and emails admin",
+		"status": "active", // active|inactive
+		"accountability": "all", // all|activity|null
+		"trigger": "event", // event|webhook|schedule|operation|manual
+		"options": {
+			// Trigger-specific configuration
+			"type": "action",
+			"scope": ["items.create"],
+			"collections": ["posts"]
+		}
+	}
+}
+```
+
+### `update` - Modify Existing Flow
+
+```json
+{
+	"action": "update",
+	"key": "flow-uuid",
+	"data": {
+		"status": "inactive",
+		"description": "Updated description"
+	}
+}
+```
+
+### `delete` - Remove Flow
+
+```json
+{
+	"action": "delete",
+	"key": "flow-uuid"
+}
+```
+
+</crud_actions>
+
+<trigger_types>
+
+## Trigger Types & Options
+
+### Event Hook Trigger
+
+Responds to data changes and system events
+
+```json
+{
+	"trigger": "event",
+	"options": {
+		"type": "filter", // filter (blocking) | action (non-blocking)
+		"scope": ["items.create", "items.update"],
+		"collections": ["orders", "products"],
+		"return": "process_data" // For filter only: <operationKey>|$all|$last (avoid $last)
+	}
+}
+```
+
+**Common Scopes**:
+
+- `items.create`, `items.update`, `items.delete` - Data operations
+- `auth.login` - User authentication
+- **Note**: Multiple scopes trigger flow for ANY matching event
+
+### Webhook Trigger
+
+```json
+{
+	"trigger": "webhook",
+	"options": {
+		"method": "POST", // GET|POST
+		"async": false, // true = immediate response, false = wait for completion
+		"return": "transform_result", // Response body: <operationKey>|$all|$last (avoid $last)
+		"cache": false // Cache GET responses
+	}
+}
+```
+
+### Schedule Trigger (CRON)
+
+```json
+{
+	"trigger": "schedule",
+	"options": {
+		"cron": "0 */15 * * * *" // Every 15 minutes
+	}
+}
+```
+
+**CRON Format**: `second minute hour day month weekday` **Examples**:
+
+- `"0 0 9 * * *"` - Daily at 9 AM
+- `"0 30 * * * *"` - Every 30 minutes (note: runs at :30 of each hour)
+- `"0 */15 * * * *"` - Every 15 minutes
+
+### Manual Trigger
+
+UI button that users click to start flows
+
+```json
+{
+	"trigger": "manual",
+	"options": {
+		"collections": ["posts", "products"],
+		"location": "item", // item|collection|both
+		"requireSelection": false, // Default true - requires item selection
+		"requireConfirmation": true,
+		"confirmationDescription": "AI Ghostwriter",
+		"async": true, // Run in background
+		"fields": [
+			{
+				"field": "prompt",
+				"type": "text",
+				"name": "Prompt",
+				"meta": {
+					"interface": "input-multiline",
+					"note": "Describe what you want to create.",
+					"width": "full",
+					"required": true
+				}
+			},
+			{
+				"field": "voice",
+				"type": "json",
+				"name": "Tone Of Voice",
+				"meta": {
+					"interface": "tags",
+					"options": {
+						"presets": ["friendly", "professional", "casual"]
+					}
+				}
+			},
+			{
+				"field": "colors",
+				"type": "json",
+				"name": "Color Palette",
+				"meta": {
+					"interface": "list",
+					"options": {
+						"fields": [
+							{
+								"field": "color",
+								"type": "string",
+								"meta": { "interface": "select-color" }
+							},
+							{
+								"field": "name",
+								"type": "string",
+								"meta": { "interface": "input" }
+							}
+						]
+					}
+				}
+			}
+		]
+	}
+}
+// Access confirmation inputs: {{ $trigger.body.prompt }}, {{ $trigger.body.voice }}
+```
+
+**Field Options**: Supports non-relational Directus interfaces - `input`, `input-multiline`, `input-rich-text-md`,
+`tags`, `list`, `select-color`, `select-radio`, `collection-item-dropdown`, etc.
+
+### Operation Trigger (Another Flow)
+
+```json
+{
+	"trigger": "operation",
+	"options": {
+		"return": "final_result" // Data to return to calling flow: <operationKey>|$all|$last (avoid $last)
+	}
+}
+```
+
+</trigger_types>
+
+<operations_integration>
+
+## Working with Operations
+
+**Use the `operations` tool for complete details on:**
+
+- Creating and linking operations
+- 14x14 grid positioning system
+- Data chain variable syntax
+- Operation-specific configuration
+
+**Workflow Process:**
+
+1. Create flow first to get flow ID
+2. Use `operations` tool to add/manage operations
+3. Operations execute in sequence based on resolve/reject paths
+4. Link operations via UUIDs in resolve/reject fields </operations_integration>
+
+<flow_chaining>
+
+## 🔗 Flow Chaining
+
+**When to Chain**: Reusable utilities, complex multi-step workflows, conditional branching
+
+**How to Chain**:
+
+1. Child flow: `"trigger": "operation"`, `"return": "final_key"` or `"$last"`
+2. Parent flow: Use `trigger` operation with child flow UUID and payload
+3. Access child results: `{{ trigger_operation_key }}`
+
+**Common Utility Patterns**:
+
+```json
+// Utils → Get Globals (called by multiple flows)
+{
+  "name": "Utils → Get Globals",
+  "trigger": "operation",
+  "options": { "return": "$last" }
+}
+
+// Utils → Send Email (reusable email sender)
+{
+  "name": "Utils → Send Email",
+  "trigger": "operation",
+  "options": { "return": "$last" }
+}
+
+// Main flow calls utility
+{
+  "type": "trigger",
+  "key": "globals",
+  "options": {
+    "flow": "utils-globals-uuid"
+  }
+}
+// Access: {{ globals.openai_api_key }}
+```
+
+**Multi-Chain Example** (Form Notifications):
+
+```json
+// Chains: Read Form → Format → Render Template → Send Email
+{
+	"type": "trigger",
+	"key": "render",
+	"options": {
+		"flow": "utils-render-template-uuid",
+		"payload": "{{ format }}"
+	}
+}
+```
+
+**Best Practices**:
+
+- Name utilities with "Utils →" prefix for clarity
+- Use `$last` return for simple utilities, specific keys for complex ones
+- Chain utilities together for modular, reusable workflows
+- Keep each utility focused on single responsibility </flow_chaining>
+
+<data_chain_warning>
+
+## Data Chain Access
+
+**See the `operations` tool for complete data chain syntax and examples.**
+
+Operations can access:
+
+- `$trigger` - Initial trigger data
+- `$accountability` - User/permission context
+- `$env` - Environment variables
+- `<operationKey>` - Result of specific operation (recommended)
+- `$last` - Result of previous operation (avoid - breaks when reordered) </data_chain_warning>
+
+<real_world_examples>
+
+## Real-World Examples
+
+### Post Approval Email (Event-Driven)
+
+```json
+{
+	"action": "create",
+	"data": {
+		"name": "[Website] Post Approval",
+		"icon": "mark_email_read",
+		"color": "#18222F",
+		"description": "Send email when posts are ready for review",
+		"status": "active",
+		"trigger": "event",
+		"accountability": "all",
+		"options": {
+			"type": "action", // Non-blocking
+			"scope": ["items.update"],
+			"collections": ["posts"]
+		}
+	}
+}
+// Then add operations: Check Status → Send Email
+```
+
+### Auto-Generate Slugs (Event-Driven)
+
+```json
+{
+	"action": "create",
+	"data": {
+		"name": "[Website] Slugify",
+		"icon": "link",
+		"color": "#18222F",
+		"description": "Generate slugs for pages, posts, and categories",
+		"status": "active",
+		"trigger": "event",
+		"accountability": "all",
+		"options": {
+			"type": "action",
+			"scope": ["items.create"],
+			"collections": ["pages", "posts", "categories"]
+		}
+	}
+}
+```
+
+### Create Scheduled Task
+
+```json
+{
+	"action": "create",
+	"data": {
+		"name": "Daily Report",
+		"trigger": "schedule",
+		"status": "active",
+		"options": {
+			"cron": "0 0 9 * * *" // 9 AM daily
+		}
+	}
+}
+```
+
+### Project Creator with Template (Manual + Confirmation)
+
+```json
+{
+	"action": "create",
+	"data": {
+		"name": "[Projects] Create Project",
+		"trigger": "manual",
+		"status": "active",
+		"options": {
+			"collections": ["os_projects", "organizations"],
+			"requireSelection": false, // Can trigger without selection
+			"requireConfirmation": true,
+			"confirmationDescription": "Create a New Project 🚀",
+			"fields": [
+				{
+					"field": "name",
+					"type": "string",
+					"name": "Project Name",
+					"meta": {
+						"interface": "input",
+						"required": true
+					}
+				},
+				{
+					"field": "organization",
+					"type": "json",
+					"name": "Organization",
+					"meta": {
+						"interface": "collection-item-dropdown",
+						"required": true,
+						"options": {
+							"selectedCollection": "organizations"
+						}
+					}
+				}
+			]
+		}
+	}
+}
+```
+
+### Utility Flow (Operation Trigger)
+
+````json
+{
+  "action": "create",
+  "data": {
+    "name": "[Util] Get Globals",
+    "trigger": "operation",
+    "accountability": "all",
+    "options": {
+      "return": "global_data"  // Returns data to calling flow: <operationKey>|$all|$last
+    }
+  }
+}
+// Called by other flows using trigger operation
+```
+</real_world_examples>
+
+<important_notes>
+## Important Notes
+
+- **Admin Required**: This tool requires admin permissions
+- **Data Format**: Pass `data` as native objects, NOT stringified JSON
+- **Flow Execution**: Flows with `operations` array will include their operations
+- **Webhook URL**: After creating webhook trigger, URL is `/flows/trigger/<flow-id>`
+- **Event Blocking**: Filter events pause transaction until flow completes
+- **Logs**: Flow executions are logged (check `accountability` setting)
+</important_notes>
+
+<common_mistakes>
+## Common Mistakes to Avoid
+
+1. **DO NOT** create operations here - use the `operations` tool
+2. **DO NOT** trigger flows here - use the `trigger-flow` tool
+3. **DO NOT** pass stringified JSON in data parameter
+4. **DO NOT** forget required fields: `name` and `trigger` for creation
+5. **DO NOT** put options outside of data - it goes inside the flow object:
+   ```json
+   // ✅ CORRECT
+   {
+     "action": "create",
+     "data": {
+       "name": "My Flow",
+       "trigger": "event",
+       "options": { "type": "action" }
+     }
+   }
+
+   // ❌ WRONG
+   {
+     "action": "create",
+     "data": { "name": "My Flow", "trigger": "event" },
+     "options": { "type": "action" }
+   }
+   ```
+</common_mistakes>
+````

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

@@ -0,0 +1,34 @@
+Perform CRUD operations on Directus Folders. Folders are used to organize files in Directus.
+
+## Available Actions
+
+- `create`: Add new folders records
+- `read`: List/query metadata or get specific items by ID
+- `update`: Modify existing metadata (title, description, tags, folder)
+- `delete`: Remove folders by keys
+
+## Common Operations
+
+### Create Folder
+
+```json
+{
+	"action": "create",
+	"data": {
+		"name": "Product Images",
+		"parent": "parent-folder-uuid"
+	}
+}
+```
+
+## Important Notes
+
+- **Folders are virtual**: Folders are not mirrored with the storage adaptor, only stored in the database.
+- **Permissions**: Respects Directus access control - only accessible files are returned. If you don't see something
+  that the user says you should have access to, it could be a permissions issue.
+- **Folder Hierarchy**: Deleting a folder requires it to be empty or will cascade based on settings
+
+## Mistakes to Avoid
+
+1. **Remember** that `keys` expects an array even for single items
+2. **Tags must be arrays**: Use `["tag1", "tag2"]` not `"tag1, tag2"`

package/dist/mcp/tools/prompts/index.d.ts

@@ -0,0 +1,16 @@
+declare const _default: {
+    assets: string;
+    collections: string;
+    fields: string;
+    files: string;
+    folders: string;
+    flows: string;
+    items: string;
+    operations: string;
+    relations: string;
+    schema: string;
+    systemPrompt: string;
+    systemPromptDescription: string;
+    triggerFlow: string;
+};
+export default _default;

package/dist/mcp/tools/prompts/index.js

@@ -0,0 +1,19 @@
+import fse from 'fs-extra';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default {
+    assets: fse.readFileSync(join(__dirname, 'assets.md'), 'utf8'),
+    collections: fse.readFileSync(join(__dirname, 'collections.md'), 'utf8'),
+    fields: fse.readFileSync(join(__dirname, 'fields.md'), 'utf8'),
+    files: fse.readFileSync(join(__dirname, 'files.md'), 'utf8'),
+    folders: fse.readFileSync(join(__dirname, 'folders.md'), 'utf8'),
+    flows: fse.readFileSync(join(__dirname, 'flows.md'), 'utf8'),
+    items: fse.readFileSync(join(__dirname, 'items.md'), 'utf8'),
+    operations: fse.readFileSync(join(__dirname, 'operations.md'), 'utf8'),
+    relations: fse.readFileSync(join(__dirname, 'relations.md'), 'utf8'),
+    schema: fse.readFileSync(join(__dirname, 'schema.md'), 'utf8'),
+    systemPrompt: fse.readFileSync(join(__dirname, 'system-prompt.md'), 'utf8'),
+    systemPromptDescription: fse.readFileSync(join(__dirname, 'system-prompt-description.md'), 'utf8'),
+    triggerFlow: fse.readFileSync(join(__dirname, 'trigger-flow.md'), 'utf8'),
+};