Directus Extension MCP Customization

Directus MCP定制扩展

此扩展允许其他Directus扩展通过挂接到Directus的事件发射器系统来添加自定义MCP（模型上下文协议）工具。

目的

Directus具有内置的MCP支持，但它只公开了自己的内部工具。此扩展拦截 /mcp 端点允许其他扩展：

1. 将他们自己的工具添加到MCP工具列表中
2. 处理这些自定义工具的执行

与其他扩展一起使用

要从另一个扩展添加自定义MCP工具，请使用Directus的 孤立事件发射器系统.

重要提示： 出于安全原因，MCP功能使用与核心Directus事件系统分离的隔离事件发射器。你 必须 使用 emitter.onFilter() 直接而不是 filter() 回拨来自 defineHook.

1.向列表中添加工具

听听 mcp.tools.list 过滤事件以注入您的工具：

import { defineHook } from "@directus/extensions-sdk";

export default defineHook((_, { emitter }) => {
  emitter.onFilter("mcp.tools.list", (tools) => {
    // Add your custom tool to the array
    return [
      ...tools,
      {
        name: "my_custom_tool",
        description: "Does something useful",
        inputSchema: {
          type: "object",
          properties: {
            param1: { type: "string" }
          },
          required: ["param1"]
        }
      }
    ];
  });
});

2.搬运工具执行

听一个特定于工具的过滤器事件来处理工具的执行：

import { defineHook } from "@directus/extensions-sdk";

export default defineHook((_, { emitter, services, getSchema }) => {
  emitter.onFilter("my_custom_tool.mcp.tools.call", async (toolCall, meta) => {
    // Access user accountability from meta parameter
    const { accountability } = meta;

    // Get schema and create service with accountability
    const schema = await getSchema();
    const { ItemsService } = services;

    const itemsService = new ItemsService("my_collection", {
      schema,
      accountability, // Pass accountability for permission checks
    });

    // Execute your tool logic with proper permissions
    const result = await itemsService.readByQuery({
      filter: { status: { _eq: toolCall.arguments.status } }
    });

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result)
        }
      ]
    };
  });
});

重要提示： 筛选器事件签名为：

async (toolCall, meta, context) => { ... }

• toolCall -包含 name 和 arguments 来自MCP请求
• meta -包含 accountability 从Express请求中提取
• context -全钩子扩展上下文（服务、getSchema等）

这 accountability 对象包含用户的身份验证和授权上下文，允许Directus服务强制执行适当的权限。

或者，使用通用 mcp.tools.call 事件并检查工具名称：

emitter.onFilter("mcp.tools.call", async (toolCall, meta) => {
  if (toolCall.name === "my_custom_tool") {
    // Handle your specific tool with accountability
    const { accountability } = meta;
    return { content: [{ type: "text", text: "Result" }] };
  }
});

完整示例

下面是一个完整的示例，显示了添加工具和处理其执行：

import { defineHook } from "@directus/extensions-sdk";

export default defineHook((_, { logger, emitter, services, getSchema }) => {
  // Add tool to the list
  emitter.onFilter("mcp.tools.list", (tools) => {
    return [
      ...tools,
      {
        name: "my_custom_tool",
        description: "Does something useful",
        inputSchema: {
          type: "object",
          properties: {
            input: { type: "string", description: "Input parameter" }
          },
          required: ["input"]
        }
      }
    ];
  });

  // Handle tool execution with accountability
  emitter.onFilter("my_custom_tool.mcp.tools.call", async (toolCall, meta) => {
    const { input } = toolCall.arguments;
    const { accountability } = meta;

    // Use accountability for any service that needs permissions
    const schema = await getSchema();
    const { ItemsService } = services;

    const itemsService = new ItemsService("my_collection", {
      schema,
      accountability,
    });

    return {
      content: [
        {
          type: "text",
          text: `Processed: ${input}`
        }
      ]
    };
  });
});

运作原理

1. 延长线钩入 routes.before 拦截 /mcp 端点
2. 对于 tools/list 请求时，它会覆盖响应以发出 mcp.tools.list 过滤器
3. 对于 tools/call 请求，它：

- 提取物 accountability 来自Express请求(req.accountability) - 创建一个 meta 包含责任的对象 - 发出特定于工具的筛选器事件： {toolName}.mcp.tools.call with（工具调用、元、上下文） - 回到通用 mcp.tools.call 如果没有特定的处理程序响应 - 通过以下方式将控制权传递给内置的Directus处理程序 next() 如果没有自定义处理程序响应

1. 其他扩展注册过滤器监听器以添加工具和处理调用

责任流程

MCP Request → Express Middleware (adds req.accountability)
     ↓
Customization Extension (extracts req.accountability)
     ↓
Filter Event Emitted with meta = { accountability }
     ↓
Custom Tool Handler (receives accountability via meta parameter)
     ↓
Directus Service (uses accountability for permission checks)

问责对象对于以下方面至关重要：

• 用户身份验证和授权
• Directus服务中的权限执行
• 审计日志和活动跟踪
• 多租户数据隔离

安装

必须在安装任何其他要添加自定义MCP工具的扩展之前安装此扩展。

通过npm安装：

npm install directus-extension-mcp-customization

或手动：

npm install
npm run build

然后重新启动Directus实例。

相关扩展

基于此自定义框架构建的扩展：

• directus-extension-mcp-comments -向Directus MCP添加用于管理评论的工具
• directus-extension-mcp-presets -为Directus MCP添加管理预设/书签的工具
• directus-extension-mcp-hello-world -自定义MCP工具示例