@directus/api 30.0.0 → 31.0.0

package/dist/mcp/schema.js

@@ -0,0 +1,219 @@
+import { z } from 'zod';
+// PK
+export const PrimaryKeyInputSchema = z.union([z.number(), z.string()]);
+export const PrimaryKeyValidateSchema = z.union([z.number(), z.string()]);
+// item
+export const ItemInputSchema = z.record(z.string(), z.any());
+export const ItemValidateSchema = z.record(z.string(), z.any());
+// query
+export const QueryInputSchema = z
+    .object({
+    fields: z.array(z.string()),
+    sort: z.array(z.string()),
+    filter: z.record(z.string(), z.any()),
+    limit: z.number(),
+    offset: z.number(),
+    page: z.number(),
+    search: z.string(),
+    deep: z.record(z.string(), z.any()),
+    alias: z.record(z.string(), z.string()),
+    aggregate: z.object({
+        count: z.array(z.string()),
+        sum: z.array(z.string()),
+        avg: z.array(z.string()),
+        min: z.array(z.string()),
+        max: z.array(z.string()),
+    }),
+    backlink: z.boolean(),
+    version: z.string(),
+    versionRaw: z.boolean(),
+    export: z.string(),
+    group: z.array(z.string()),
+})
+    .partial();
+export const QueryValidateSchema = QueryInputSchema;
+// field
+export const RawFieldItemInputSchema = z.object({
+    field: z.string(),
+    type: z.string(),
+    name: z.string().optional(),
+    children: z.union([z.array(z.record(z.string(), z.any())), z.null()]).optional(),
+    collection: z.string().optional(),
+    schema: z.union([z.record(z.string(), z.any()), z.null()]).optional(),
+    meta: z.union([z.record(z.string(), z.any()), z.null()]).optional(),
+});
+export const RawFieldItemValidateSchema = RawFieldItemInputSchema;
+export const FieldItemInputSchema = z.object({
+    field: z.string(),
+    type: z.string().nullable(),
+    name: z.string().optional(),
+    collection: z.string().optional(),
+    schema: z.union([z.record(z.string(), z.any()), z.null()]).optional(),
+    meta: z.union([z.record(z.string(), z.any()), z.null()]).optional(),
+});
+export const FieldItemValidateSchema = FieldItemInputSchema;
+// collection
+export const CollectionItemInputSchema = z.object({
+    collection: z.string(),
+    fields: z.array(RawFieldItemInputSchema).optional(),
+    meta: z.union([z.record(z.string(), z.any()), z.null()]).optional(),
+    schema: z
+        .union([z.object({}), z.null()])
+        .optional()
+        .describe('ALWAYS an empty object for new collections. Only send `null` or `undefined` for folder collections.'),
+});
+export const CollectionItemValidateCreateSchema = CollectionItemInputSchema;
+export const CollectionItemValidateUpdateSchema = z.object({
+    collection: z.string(),
+    meta: z.union([z.record(z.string(), z.any()), z.null()]).optional(),
+    schema: z.union([z.record(z.string(), z.any()), z.null()]).optional(),
+});
+// file
+export const FileItemInputSchema = z
+    .object({
+    id: z.string(),
+    storage: z.string(),
+    filename_disk: z.string(),
+    filename_download: z.string(),
+    title: z.union([z.string(), z.null()]),
+    type: z.union([z.string(), z.null()]),
+    folder: z.union([z.string(), z.null()]),
+    created_on: z.string(),
+    uploaded_by: z.union([z.string(), z.null()]),
+    uploaded_on: z.union([z.string(), z.null()]),
+    modified_by: z.union([z.string(), z.null()]),
+    modified_on: z.string(),
+    charset: z.union([z.string(), z.null()]),
+    filesize: z.number(),
+    width: z.union([z.number(), z.null()]),
+    height: z.union([z.number(), z.null()]),
+    duration: z.union([z.number(), z.null()]),
+    embed: z.union([z.string(), z.null()]),
+    description: z.union([z.string(), z.null()]),
+    location: z.union([z.string(), z.null()]),
+    tags: z.union([z.string(), z.null()]),
+    metadata: z.union([z.record(z.string(), z.any()), z.null()]),
+    focal_point_x: z.union([z.number(), z.null()]),
+    focal_point_y: z.union([z.number(), z.null()]),
+    tus_id: z.union([z.string(), z.null()]),
+    tus_data: z.union([z.record(z.string(), z.any()), z.null()]),
+})
+    .partial();
+export const FileItemValidateSchema = FileItemInputSchema;
+export const FileImportItemInputSchema = z.object({
+    url: z.string(),
+    file: FileItemInputSchema,
+});
+export const FileImportItemValidateSchema = z.object({
+    url: z.string(),
+    file: FileItemValidateSchema,
+});
+// opertations
+export const OperationItemInputSchema = z
+    .object({
+    id: z.string(),
+    name: z.union([z.string(), z.null()]),
+    key: z.string(),
+    type: z.string(),
+    position_x: z.number(),
+    position_y: z.number(),
+    options: z.record(z.string(), z.any()),
+    resolve: z.union([z.string(), z.null()]),
+    reject: z.union([z.string(), z.null()]),
+    flow: z.string(),
+    date_created: z.string(),
+    user_created: z.string(),
+})
+    .partial();
+export const OperationItemValidateSchema = OperationItemInputSchema;
+// flow
+export const FlowItemInputSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    icon: z.union([z.string(), z.null()]),
+    color: z.union([z.string(), z.null()]),
+    description: z.union([z.string(), z.null()]),
+    status: z.enum(['active', 'inactive']),
+    trigger: z.union([z.enum(['event', 'schedule', 'operation', 'webhook', 'manual']), z.null()]),
+    options: z.union([z.record(z.string(), z.any()), z.null()]),
+    operation: z.union([z.string(), z.null()]),
+    operations: z.array(OperationItemInputSchema),
+    date_created: z.string(),
+    user_created: z.string(),
+    accountability: z.union([z.enum(['all', 'activity']), z.null()]),
+})
+    .partial();
+export const FlowItemValidateSchema = FlowItemInputSchema;
+// trigger flow
+export const TriggerFlowInputSchema = z.object({
+    id: PrimaryKeyInputSchema,
+    collection: z.string(),
+    keys: z.array(PrimaryKeyInputSchema).optional(),
+    headers: z.record(z.string(), z.any()).optional(),
+    query: z.record(z.string(), z.any()).optional(),
+    data: z.record(z.string(), z.any()).optional(),
+});
+export const TriggerFlowValidateSchema = z.strictObject({
+    id: PrimaryKeyValidateSchema,
+    collection: z.string(),
+    keys: z.array(PrimaryKeyValidateSchema).optional(),
+    query: z.record(z.string(), z.any()).optional(),
+    headers: z.record(z.string(), z.any()).optional(),
+    data: z.record(z.string(), z.any()).optional(),
+});
+// folder
+export const FolderItemInputSchema = z.object({
+    id: PrimaryKeyInputSchema.optional(),
+    name: z.string(),
+    parent: z.string().optional(),
+});
+export const FolderItemValidateSchema = FolderItemInputSchema;
+// relation
+export const RelationItemInputSchema = z.object({
+    collection: z.string(),
+    field: z.string(),
+    related_collection: z.union([z.string(), z.null()]),
+    schema: z.union([z.record(z.string(), z.any()), z.null()]),
+    meta: z.union([z.record(z.string(), z.any()), z.null()]),
+});
+const RelationMetaSchema = z.object({
+    id: z.number(),
+    many_collection: z.string(),
+    many_field: z.string(),
+    one_collection: z.string().nullable(),
+    one_field: z.string().nullable(),
+    one_collection_field: z.string().nullable(),
+    one_allowed_collections: z.array(z.string()).nullable(),
+    one_deselect_action: z.enum(['nullify', 'delete']),
+    junction_field: z.string().nullable(),
+    sort_field: z.string().nullable(),
+    system: z.boolean().optional(),
+});
+const FkActionEnum = z.enum(['NO ACTION', 'RESTRICT', 'CASCADE', 'SET NULL', 'SET DEFAULT']);
+export const ForeignKeySchema = z.object({
+    table: z.string(),
+    column: z.string(),
+    foreign_key_table: z.string(),
+    foreign_key_column: z.string(),
+    foreign_key_schema: z.string().optional(),
+    constraint_name: z.union([z.string(), z.null()]),
+    on_update: z.union([FkActionEnum, z.null()]),
+    on_delete: z.union([FkActionEnum, z.null()]),
+});
+export const RelationItemValidateCreateSchema = z.object({
+    collection: z.string(),
+    field: z.string(),
+    related_collection: z.string().nullable(),
+    schema: ForeignKeySchema.partial().nullable().optional(),
+    meta: RelationMetaSchema.partial().nullable(),
+});
+export const RelationItemValidateUpdateSchema = z
+    .object({
+    collection: z.string(),
+    field: z.string(),
+    related_collection: z.string().nullable().optional(),
+    schema: ForeignKeySchema.partial().nullable().optional(),
+    meta: RelationMetaSchema.partial().nullable().optional(),
+})
+    .optional();

package/dist/mcp/server.d.ts

@@ -0,0 +1,97 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Request, Response } from 'express';
+import type { MCPOptions, ToolConfig, ToolResult } from './types.js';
+export declare class DirectusMCP {
+    promptsCollection?: string | null;
+    systemPrompt?: string | null;
+    systemPromptEnabled?: boolean;
+    server: Server;
+    allowDeletes?: boolean;
+    constructor(options?: MCPOptions);
+    /**
+     * This handleRequest function is not awaiting lower level logic resulting in the actual
+     * response being an asynchronous side effect happening after the function has returned
+     */
+    handleRequest(req: Request, res: Response): void;
+    buildURL(tool: ToolConfig<unknown>, input: unknown, data: unknown): string | undefined;
+    toPromptResponse(result: {
+        description?: string | undefined;
+        messages: GetPromptResult['messages'];
+    }): GetPromptResult;
+    toToolResponse(result?: ToolResult): {
+        [x: string]: unknown;
+        content: ({
+            [x: string]: unknown;
+            type: "text";
+            text: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "image";
+            data: string;
+            mimeType: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "audio";
+            data: string;
+            mimeType: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "resource_link";
+            name: string;
+            uri: string;
+            title?: string | undefined;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            [x: string]: unknown;
+            type: "resource";
+            resource: {
+                [x: string]: unknown;
+                text: string;
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                [x: string]: unknown;
+                blob: string;
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            };
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        structuredContent?: {
+            [x: string]: unknown;
+        } | undefined;
+        isError?: boolean | undefined;
+    };
+    toExecutionError(err: unknown): {
+        isError: boolean;
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    };
+}

package/dist/mcp/server.js

@@ -0,0 +1,310 @@
+import { useEnv } from '@directus/env';
+import { ForbiddenError, InvalidPayloadError, isDirectusError } from '@directus/errors';
+import { isObject, parseJSON, toArray } from '@directus/utils';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, GetPromptRequestSchema, InitializedNotificationSchema, ErrorCode as JSONRPCErrorCode, JSONRPCMessageSchema, ListPromptsRequestSchema, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { render, tokenize } from 'micromustache';
+import { z } from 'zod';
+import { fromZodError } from 'zod-validation-error';
+import { ItemsService } from '../services/index.js';
+import { sanitizeQuery } from '../utils/sanitize-query.js';
+import { Url } from '../utils/url.js';
+import { findMcpTool, getAllMcpTools } from './tools/index.js';
+import { DirectusTransport } from './transport.js';
+export class DirectusMCP {
+    promptsCollection;
+    systemPrompt;
+    systemPromptEnabled;
+    server;
+    allowDeletes;
+    constructor(options = {}) {
+        this.promptsCollection = options.promptsCollection ?? null;
+        this.systemPromptEnabled = options.systemPromptEnabled ?? true;
+        this.systemPrompt = options.systemPrompt ?? null;
+        this.allowDeletes = options.allowDeletes ?? false;
+        this.server = new Server({
+            name: 'directus-mcp',
+            version: '0.1.0',
+        }, {
+            capabilities: {
+                tools: {},
+                prompts: {},
+            },
+        });
+    }
+    /**
+     * This handleRequest function is not awaiting lower level logic resulting in the actual
+     * response being an asynchronous side effect happening after the function has returned
+     */
+    handleRequest(req, res) {
+        if (!req.accountability?.user && !req.accountability?.role && req.accountability?.admin !== true) {
+            throw new ForbiddenError();
+        }
+        if (!req.accepts('application/json')) {
+            // we currently dont support "text/event-stream" requests
+            res.status(405).send();
+            return;
+        }
+        this.server.setNotificationHandler(InitializedNotificationSchema, () => {
+            res.status(202).send();
+        });
+        // list prompts
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            const prompts = [];
+            if (!this.promptsCollection) {
+                throw new McpError(1001, `A prompts collection must be set in settings`);
+            }
+            const service = new ItemsService(this.promptsCollection, {
+                accountability: req.accountability,
+                schema: req.schema,
+            });
+            try {
+                const promptList = await service.readByQuery({
+                    fields: ['name', 'description', 'system_prompt', 'messages'],
+                });
+                for (const prompt of promptList) {
+                    // builds args
+                    const args = [];
+                    // Add system prompt as the first assistant message if it exists
+                    if (prompt.system_prompt) {
+                        for (const varName of tokenize(prompt.system_prompt).varNames) {
+                            args.push({
+                                name: varName,
+                                description: `Value for ${varName}`,
+                                required: false,
+                            });
+                        }
+                    }
+                    for (const message of prompt.messages || []) {
+                        for (const varName of tokenize(message.text).varNames) {
+                            args.push({
+                                name: varName,
+                                description: `Value for ${varName}`,
+                                required: false,
+                            });
+                        }
+                    }
+                    prompts.push({
+                        name: prompt.name,
+                        description: prompt.description,
+                        arguments: args,
+                    });
+                }
+                return { prompts };
+            }
+            catch (error) {
+                return this.toExecutionError(error);
+            }
+        });
+        // get prompt
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            if (!this.promptsCollection) {
+                throw new McpError(1001, `A prompts collection must be set in settings`);
+            }
+            const service = new ItemsService(this.promptsCollection, {
+                accountability: req.accountability,
+                schema: req.schema,
+            });
+            const { name: promptName, arguments: args } = request.params;
+            const promptCommand = await service.readByQuery({
+                fields: ['description', 'system_prompt', 'messages'],
+                filter: {
+                    name: {
+                        _eq: promptName,
+                    },
+                },
+            });
+            const prompt = promptCommand[0];
+            if (!prompt) {
+                throw new McpError(JSONRPCErrorCode.InvalidParams, `Invalid prompt "${promptName}"`);
+            }
+            const messages = [];
+            // Add system prompt as the first assistant message if it exists
+            if (prompt.system_prompt) {
+                messages.push({
+                    role: 'assistant',
+                    content: {
+                        type: 'text',
+                        text: render(prompt.system_prompt, args),
+                    },
+                });
+            }
+            // render any provided args
+            (prompt.messages || []).forEach((message) => {
+                // skip invalid prompts
+                if (!message.role || !message.text)
+                    return;
+                messages.push({
+                    role: message.role,
+                    content: {
+                        type: 'text',
+                        text: render(message.text, args),
+                    },
+                });
+            });
+            return this.toPromptResponse({
+                messages,
+                description: prompt.description,
+            });
+        });
+        // listing tools
+        this.server.setRequestHandler(ListToolsRequestSchema, () => {
+            const tools = [];
+            for (const tool of getAllMcpTools()) {
+                if (req.accountability?.admin !== true && tool.admin === true)
+                    continue;
+                if (tool.name === 'system-prompt' && this.systemPromptEnabled === false)
+                    continue;
+                tools.push({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: z.toJSONSchema(tool.inputSchema),
+                    annotations: tool.annotations,
+                });
+            }
+            return { tools };
+        });
+        // calling tools
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const tool = findMcpTool(request.params.name);
+            let sanitizedQuery = {};
+            try {
+                if (!tool || (tool.name === 'system-prompt' && this.systemPromptEnabled === false)) {
+                    throw new InvalidPayloadError({ reason: `"${request.params.name}" doesn't exist in the toolset` });
+                }
+                if (req.accountability?.admin !== true && tool.admin === true) {
+                    throw new ForbiddenError({ reason: 'You must be an admin to access this tool' });
+                }
+                if (tool.name === 'system-prompt') {
+                    request.params.arguments = { promptOverride: this.systemPrompt };
+                }
+                // ensure json expected fields are not stringified
+                if (request.params.arguments) {
+                    for (const field of ['data', 'keys', 'query']) {
+                        const arg = request.params.arguments[field];
+                        if (typeof arg === 'string') {
+                            request.params.arguments[field] = parseJSON(arg);
+                        }
+                    }
+                }
+                const { error, data: args } = tool.validateSchema?.safeParse(request.params.arguments) ?? {
+                    data: request.params.arguments,
+                };
+                if (error) {
+                    throw new InvalidPayloadError({ reason: fromZodError(error).message });
+                }
+                if (!isObject(args)) {
+                    throw new InvalidPayloadError({ reason: '"arguments" must be an object' });
+                }
+                if ('action' in args && args['action'] === 'delete' && !this.allowDeletes) {
+                    throw new InvalidPayloadError({ reason: 'Delete actions are disabled' });
+                }
+                if ('query' in args && args['query']) {
+                    sanitizedQuery = await sanitizeQuery({
+                        fields: args['query']['fields'] || '*',
+                        ...args['query'],
+                    }, req.schema, req.accountability || null);
+                }
+                const result = await tool.handler({
+                    args,
+                    sanitizedQuery,
+                    schema: req.schema,
+                    accountability: req.accountability,
+                });
+                // if single item and create/read/update/import add url
+                const data = toArray(result?.data);
+                if ('action' in args &&
+                    ['create', 'update', 'read', 'import'].includes(args['action']) &&
+                    result?.data &&
+                    data.length === 1) {
+                    result.url = this.buildURL(tool, args, data[0]);
+                }
+                return this.toToolResponse(result);
+            }
+            catch (error) {
+                return this.toExecutionError(error);
+            }
+        });
+        const transport = new DirectusTransport(res);
+        this.server.connect(transport);
+        try {
+            const parsedMessage = JSONRPCMessageSchema.parse(req.body);
+            transport.onmessage?.(parsedMessage);
+        }
+        catch (error) {
+            transport.onerror?.(error);
+            throw error;
+        }
+    }
+    buildURL(tool, input, data) {
+        const env = useEnv();
+        const publicURL = env['PUBLIC_URL'];
+        if (!publicURL)
+            return;
+        if (!tool.endpoint)
+            return;
+        const path = tool.endpoint({ input, data });
+        if (!path)
+            return;
+        return new Url(env['PUBLIC_URL']).addPath('admin', ...path).toString();
+    }
+    toPromptResponse(result) {
+        const response = {
+            messages: result.messages,
+        };
+        if (result.description) {
+            response.description = result.description;
+        }
+        return response;
+    }
+    toToolResponse(result) {
+        const response = {
+            content: [],
+        };
+        if (!result || typeof result.data === 'undefined' || result.data === null)
+            return response;
+        if (result.type === 'text') {
+            response.content.push({
+                type: 'text',
+                text: JSON.stringify({ raw: result.data, url: result.url }),
+            });
+        }
+        else {
+            response.content.push(result);
+        }
+        return response;
+    }
+    toExecutionError(err) {
+        const errors = [];
+        const receivedErrors = Array.isArray(err) ? err : [err];
+        for (const error of receivedErrors) {
+            if (isDirectusError(error)) {
+                errors.push({
+                    error: error.message || 'Unknown error',
+                    code: error.code,
+                });
+            }
+            else {
+                // Handle generic errors
+                let message = 'An unknown error occurred.';
+                let code;
+                if (error instanceof Error) {
+                    message = error.message;
+                    code = 'code' in error ? String(error.code) : undefined;
+                }
+                else if (typeof error === 'object' && error !== null) {
+                    message = 'message' in error ? String(error.message) : message;
+                    code = 'code' in error ? String(error.code) : undefined;
+                }
+                else if (typeof error === 'string') {
+                    message = error;
+                }
+                errors.push({ error: message, ...(code && { code }) });
+            }
+        }
+        return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(errors) }],
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+export declare const assets: import("../types.js").ToolConfig<{
+    id: string;
+}>;

package/dist/mcp/tools/assets.js

@@ -0,0 +1,54 @@
+import { UnsupportedMediaTypeError } from '@directus/errors';
+import { z } from 'zod';
+import { AssetsService } from '../../services/assets.js';
+import { FilesService } from '../../services/files.js';
+import { defineTool } from '../define.js';
+import prompts from './prompts/index.js';
+const AssetsValidateSchema = z.strictObject({
+    id: z.string(),
+});
+const AssetsInputSchema = z.object({
+    id: z.string(),
+});
+export const assets = defineTool({
+    name: 'assets',
+    description: prompts.assets,
+    annotations: {
+        title: 'Directus - Assets',
+    },
+    inputSchema: AssetsInputSchema,
+    validateSchema: AssetsValidateSchema,
+    async handler({ args, schema, accountability }) {
+        const serviceOptions = {
+            accountability,
+            schema,
+        };
+        const filesService = new FilesService(serviceOptions);
+        const file = await filesService.readOne(args.id, { limit: 1 });
+        if (!file.type || !['image', 'audio'].some((t) => file.type?.startsWith(t))) {
+            throw new UnsupportedMediaTypeError({ mediaType: file.type ?? 'unknown', where: 'asset tool' });
+        }
+        let transformation = undefined;
+        // ensure image dimensions are within allowable LLM limits
+        if (file.type.startsWith('image') && file.width && file.height && (file.width > 1200 || file.height > 1200)) {
+            transformation = {
+                transformationParams: {
+                    transforms: file.width > file.height
+                        ? [['resize', { width: 800, fit: 'contain' }]]
+                        : [['resize', { height: 800, fit: 'contain' }]],
+                },
+            };
+        }
+        const assetsService = new AssetsService(serviceOptions);
+        const asset = await assetsService.getAsset(args.id, transformation);
+        const chunks = [];
+        for await (const chunk of asset.stream) {
+            chunks.push(Buffer.from(chunk));
+        }
+        return {
+            type: file.type.startsWith('image') ? 'image' : 'audio',
+            data: Buffer.concat(chunks).toString('base64'),
+            mimeType: file.type,
+        };
+    },
+});