@directus/api 30.0.0 → 31.0.0

package/dist/mcp/tools/prompts/trigger-flow.md

@@ -0,0 +1,214 @@
+# Directus Trigger Flow Tool
+
+Execute flows programmatically. This tool allows you to trigger manual flows, pass data to flows, and chain flows
+together for complex automation.
+
+## 🔑 Key Concepts
+
+- **Prerequisite**: ALWAYS read the flow first using `flows` tool to get the full definition
+- **Manual Flows**: Flows with `trigger: "manual"` are designed to be triggered via UI or this tool
+- **Flow Chaining**: Any flow can be triggered, receiving data in `$trigger.body`
+- **Validation**: Tool validates collection support, required fields, and selection requirements
+
+## Required Parameters
+
+```json
+{
+	"flowDefinition": {}, // FULL flow object from flows.read
+	"flowId": "uuid", // Flow ID to trigger
+	"collection": "name", // Collection context
+	"keys": ["id1"], // Item IDs (required if flow needs selection)
+	"method": "POST", // GET or POST (default: GET)
+	"data": {}, // Optional payload data
+	"query": {}, // Optional query parameters
+	"headers": {} // Optional headers
+}
+```
+
+## 📋 Flow Types & Requirements
+
+### Manual Flow with Selection
+
+For flows with `requireSelection: true` or undefined:
+
+```json
+{
+	"flowDefinition": {
+		"id": "abc-123",
+		"trigger": "manual",
+		"options": {
+			"collections": ["products", "orders"],
+			"requireSelection": true,
+			"fields": [
+				{
+					"field": "reason",
+					"name": "Reason",
+					"meta": { "required": true }
+				}
+			]
+		}
+	},
+	"flowId": "abc-123",
+	"collection": "products",
+	"keys": ["prod-1", "prod-2"], // REQUIRED
+	"data": {
+		"reason": "Bulk update" // Required field
+	}
+}
+```
+
+### Manual Flow without Selection
+
+For flows with `requireSelection: false`:
+
+```json
+{
+	"flowDefinition": {
+		"id": "xyz-456",
+		"trigger": "manual",
+		"options": {
+			"collections": ["reports"],
+			"requireSelection": false
+		}
+	},
+	"flowId": "xyz-456",
+	"collection": "reports",
+	"keys": [], // Optional when requireSelection: false
+	"data": {
+		"type": "monthly"
+	}
+}
+```
+
+### Webhook/Operation Flows
+
+Flows with webhook or operation triggers:
+
+```json
+{
+	"flowDefinition": {
+		"id": "webhook-flow",
+		"trigger": "webhook",
+		"options": {
+			"collections": ["*"] // or specific collections
+		}
+	},
+	"flowId": "webhook-flow",
+	"collection": "any_collection",
+	"method": "POST",
+	"data": {
+		"custom": "payload"
+	},
+	"headers": {
+		"X-Custom-Header": "value"
+	}
+}
+```
+
+## 🔄 Validation Rules
+
+The tool validates:
+
+1. **Flow Definition**: Must provide complete flow object
+2. **Flow ID Match**: Definition ID must match flowId parameter
+3. **Collection Support**: Collection must be in flow's collections array
+4. **Selection Required**: Keys required when `requireSelection !== false`
+5. **Required Fields**: All required fields must be present in data
+
+## ⚡ Common Workflows
+
+### 1. Export Selected Items
+
+```json
+// Step 1: Get flow definition
+flows.read({ filter: { name: { _eq: "Export Items" }}})
+
+// Step 2: Trigger with selection
+{
+  "flowDefinition": { /* from step 1 */ },
+  "flowId": "export-flow-id",
+  "collection": "products",
+  "keys": ["1", "2", "3"],
+  "data": {
+    "format": "csv",
+    "email": "user@example.com"
+  }
+}
+```
+
+### 2. Process Batch Without Selection
+
+```json
+// For flows that process all items
+{
+	"flowDefinition": {
+		/* flow with requireSelection: false */
+	},
+	"flowId": "batch-process",
+	"collection": "orders",
+	"keys": [], // Empty when not required
+	"data": {
+		"status": "pending",
+		"date_range": "last_30_days"
+	}
+}
+```
+
+### 3. Chain Flows Together
+
+```json
+// Trigger a flow from another flow
+{
+	"flowDefinition": {
+		/* operation trigger flow */
+	},
+	"flowId": "child-flow",
+	"collection": "notifications",
+	"data": {
+		"parent_result": "{{ $last }}", // Data from parent flow
+		"step": 2
+	}
+}
+```
+
+## 📊 Data Access in Triggered Flow
+
+The triggered flow receives:
+
+- `$trigger.body` - The `data` parameter you send
+- `$trigger.query` - The `query` parameter
+- `$trigger.headers` - The `headers` parameter
+- `$trigger.collection` - The collection context
+- `$trigger.keys` - The selected item IDs
+- `$accountability` - User/permission context
+
+## ⚠️ Important Notes
+
+- **Read First**: ALWAYS read the flow definition before triggering
+- **Collection Wildcard**: `"*"` in collections means any collection is accepted
+- **Required Fields**: Check `options.fields` for required inputs
+- **For-Each**: If you pass an array, flow runs once per array item
+- **Response**: Flow can return data via its trigger's `return` option
+- **Permissions**: Respects flow's `accountability` setting
+
+## 🚨 Common Mistakes to Avoid
+
+1. **Don't** trigger without reading flow definition first
+2. **Don't** omit keys when flow requires selection
+3. **Don't** ignore required fields in flow configuration
+4. **Don't** use wrong collection not in flow's collections list
+5. **Don't** assume `requireSelection` - check explicitly
+6. **Don't** pass stringified JSON - use native objects
+
+## Decision Tree
+
+```
+1. Read flow definition using flows tool
+2. Check trigger type:
+   - manual → Check requireSelection
+   - webhook/operation → Keys optional
+3. Validate collection in flow.options.collections
+4. If requireSelection !== false → keys required
+5. Check flow.options.fields for required data fields
+6. Trigger with all validated parameters
+```

package/dist/mcp/tools/relations.d.ts

@@ -0,0 +1,73 @@
+export declare const relations: import("../types.js").ToolConfig<{
+    action: "create";
+    collection: string;
+    data: {
+        collection: string;
+        field: string;
+        related_collection: string | null;
+        meta: {
+            id?: number | undefined;
+            many_collection?: string | undefined;
+            many_field?: string | undefined;
+            one_collection?: string | null | undefined;
+            one_field?: string | null | undefined;
+            one_collection_field?: string | null | undefined;
+            one_allowed_collections?: string[] | null | undefined;
+            one_deselect_action?: "nullify" | "delete" | undefined;
+            junction_field?: string | null | undefined;
+            sort_field?: string | null | undefined;
+            system?: boolean | undefined;
+        } | null;
+        schema?: {
+            table?: string | undefined;
+            column?: string | undefined;
+            foreign_key_table?: string | undefined;
+            foreign_key_column?: string | undefined;
+            foreign_key_schema?: string | undefined;
+            constraint_name?: string | null | undefined;
+            on_update?: "NO ACTION" | "RESTRICT" | "CASCADE" | "SET NULL" | "SET DEFAULT" | null | undefined;
+            on_delete?: "NO ACTION" | "RESTRICT" | "CASCADE" | "SET NULL" | "SET DEFAULT" | null | undefined;
+        } | null | undefined;
+    };
+    field?: string | undefined;
+} | {
+    action: "read";
+    collection?: string | undefined;
+    field?: string | undefined;
+} | {
+    action: "update";
+    collection: string;
+    field: string;
+    data?: {
+        collection: string;
+        field: string;
+        related_collection?: string | null | undefined;
+        schema?: {
+            table?: string | undefined;
+            column?: string | undefined;
+            foreign_key_table?: string | undefined;
+            foreign_key_column?: string | undefined;
+            foreign_key_schema?: string | undefined;
+            constraint_name?: string | null | undefined;
+            on_update?: "NO ACTION" | "RESTRICT" | "CASCADE" | "SET NULL" | "SET DEFAULT" | null | undefined;
+            on_delete?: "NO ACTION" | "RESTRICT" | "CASCADE" | "SET NULL" | "SET DEFAULT" | null | undefined;
+        } | null | undefined;
+        meta?: {
+            id?: number | undefined;
+            many_collection?: string | undefined;
+            many_field?: string | undefined;
+            one_collection?: string | null | undefined;
+            one_field?: string | null | undefined;
+            one_collection_field?: string | null | undefined;
+            one_allowed_collections?: string[] | null | undefined;
+            one_deselect_action?: "nullify" | "delete" | undefined;
+            junction_field?: string | null | undefined;
+            sort_field?: string | null | undefined;
+            system?: boolean | undefined;
+        } | null | undefined;
+    } | undefined;
+} | {
+    action: "delete";
+    collection: string;
+    field: string;
+}>;

package/dist/mcp/tools/relations.js

@@ -0,0 +1,93 @@
+import { InvalidPayloadError } from '@directus/errors';
+import { z } from 'zod';
+import { RelationsService } from '../../services/relations.js';
+import { defineTool } from '../define.js';
+import { RelationItemInputSchema, RelationItemValidateCreateSchema, RelationItemValidateUpdateSchema, } from '../schema.js';
+import prompts from './prompts/index.js';
+const RelationsValidateSchema = z.discriminatedUnion('action', [
+    z.object({
+        action: z.literal('create'),
+        collection: z.string(),
+        field: z.string().optional(),
+        data: RelationItemValidateCreateSchema,
+    }),
+    z.object({
+        action: z.literal('read'),
+        collection: z.string().optional(),
+        field: z.string().optional(),
+    }),
+    z.object({
+        action: z.literal('update'),
+        collection: z.string(),
+        field: z.string(),
+        data: RelationItemValidateUpdateSchema,
+    }),
+    z.object({
+        action: z.literal('delete'),
+        collection: z.string(),
+        field: z.string(),
+    }),
+]);
+const RelationsInputSchema = z.object({
+    action: z.enum(['create', 'read', 'update', 'delete']).describe('The operation to perform'),
+    collection: z.string().describe('The name of the collection (required for create, update, delete)').optional(),
+    field: z.string().describe('The name of the field (required for create, update, delete)').optional(),
+    data: RelationItemInputSchema.optional().describe('The relation data. (required for create, update)'),
+});
+export const relations = defineTool({
+    name: 'relations',
+    admin: true,
+    description: prompts.relations,
+    annotations: {
+        title: 'Directus - Relations',
+    },
+    inputSchema: RelationsInputSchema,
+    validateSchema: RelationsValidateSchema,
+    async handler({ args, schema, accountability }) {
+        const service = new RelationsService({
+            schema,
+            accountability,
+        });
+        if (args.action === 'create') {
+            await service.createOne(args.data);
+            const result = await service.readOne(args.collection, args.field || args.data.field);
+            return {
+                type: 'text',
+                data: result || null,
+            };
+        }
+        if (args.action === 'read') {
+            let result = null;
+            if (args.field && args.collection) {
+                result = await service.readOne(args.collection, args.field);
+            }
+            else if (args.collection) {
+                result = await service.readAll(args.collection);
+            }
+            else {
+                result = await service.readAll();
+            }
+            return {
+                type: 'text',
+                data: result || null,
+            };
+        }
+        if (args.action === 'update') {
+            await service.updateOne(args.collection, args.field, args.data);
+            const result = await service.readOne(args.collection, args.field);
+            return {
+                type: 'text',
+                data: result || null,
+            };
+        }
+        if (args.action === 'delete') {
+            const { collection, field } = args;
+            await service.deleteOne(collection, field);
+            return {
+                type: 'text',
+                data: { collection, field },
+            };
+        }
+        throw new InvalidPayloadError({ reason: 'Invalid action' });
+    },
+});

package/dist/mcp/tools/schema.d.ts

@@ -0,0 +1,54 @@
+import type { Field, Relation } from '@directus/types';
+import { z } from 'zod';
+import type { Collection } from '../../types/collection.js';
+export interface fieldOverviewOutput {
+    type: string;
+    primary_key?: boolean;
+    required?: boolean;
+    readonly?: boolean;
+    note?: string;
+    interface?: {
+        type: string;
+        choices?: Array<string | number>;
+    };
+    relation?: {
+        type: string;
+        related_collection?: string;
+        many_collection?: string;
+        many_field?: string;
+        one_allowed_collections?: string[];
+        junction?: {
+            collection: string;
+            many_field: string;
+            junction_field: string;
+            one_collection_field?: string;
+            sort_field?: string;
+        };
+    };
+    fields?: Record<string, fieldOverviewOutput>;
+    value?: string;
+}
+export interface OverviewOutput {
+    [collection: string]: {
+        [field: string]: fieldOverviewOutput;
+    };
+}
+export interface LightweightOverview {
+    collections: string[];
+    collection_folders: string[];
+    notes: Record<string, string>;
+}
+export interface SchemaToolSnapshot {
+    collections: Collection[];
+    fields: Field[];
+    relations: Relation[];
+}
+export declare const SchemaValidateSchema: z.ZodObject<{
+    keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const SchemaInputSchema: z.ZodObject<{
+    keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const schema: import("../types.js").ToolConfig<{
+    keys?: string[] | undefined;
+}>;