Directus

Este servidor permite que asistentes de IA y otros clientes MCP interactúen programáticamente con instancias de Directus.

GitHub

Documentación

Directus MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona herramientas integrales para gestionar el esquema y el contenido de Directus. Este servidor permite que los asistentes de IA y otros clientes MCP interactúen con instancias de Directus de forma programática.

Instalación

Desde npm (una vez publicado)

npm install -g directus-mcp-server

Desde el código fuente

git clone https://github.com/yourusername/directus-mcp.git
cd directus-mcp
npm install
npm run build

Características

  • Gestión de esquema: Crear, leer, actualizar y eliminar colecciones, campos y relaciones
  • Gestión de contenido: Operaciones CRUD completas sobre elementos con consultas avanzadas
  • Seguridad de tipos: Construido con TypeScript y validación Zod
  • SDK oficial: Utiliza el @directus/sdk oficial para interacciones API fiables
  • Autenticación flexible: Admite tanto tokens estáticos como autenticación por correo electrónico/contraseña

Instalación

npm install

Configuración

Cree un archivo .env en el directorio raíz con su configuración de Directus:

# Directus Instance URL
DIRECTUS_URL=https://your-directus-instance.com

# Authentication - Use either token OR email/password
DIRECTUS_TOKEN=your_static_token_here

# Alternative: Email/Password authentication
# DIRECTUS_EMAIL=admin@example.com
# DIRECTUS_PASSWORD=your_password

Opciones de autenticación

  1. Token estático (recomendado para producción):

    • Genere un token estático en la aplicación de administración de Directus
    • Establezca la variable de entorno DIRECTUS_TOKEN

  2. Correo electrónico/Contraseña:

    • Úselo para desarrollo o cuando los tokens estáticos no estén disponibles
    • Establezca las variables de entorno DIRECTUS_EMAIL y DIRECTUS_PASSWORD

Configuración del conjunto de herramientas

El servidor MCP de Directus organiza las herramientas en conjuntos lógicos, similar a la implementación de MCP de GitHub. Esto le permite controlar qué herramientas se exponen al cliente MCP.

Conjuntos de herramientas disponibles:

  • default - Contiene herramientas de colecciones, campos, relaciones y contenido (comportamiento predeterminado cuando no se especifica ningún conjunto)
  • collections - Herramientas de gestión de colecciones (listar, obtener, crear, actualizar, eliminar colecciones)
  • fields - Herramientas de gestión de campos (listar, crear, actualizar, eliminar campos)
  • relations - Herramientas de gestión de relaciones (listar, crear, eliminar relaciones)
  • schema - Herramientas de instantánea y diff de esquema (obtener instantánea, obtener diff, aplicar diff) - NO incluidas en el conjunto predeterminado
  • content - Herramientas de gestión de contenido (operaciones CRUD de elementos)
  • flow - Herramientas de gestión de flujos (automatización de flujos de trabajo) - NO incluidas en el conjunto predeterminado
  • dashboards - Herramientas de gestión de tableros y paneles (listar, obtener, crear, actualizar, eliminar tableros y paneles) - NO incluidas en el conjunto predeterminado
  • all - Todas las herramientas disponibles independientemente de la pertenencia al conjunto

Comportamiento predeterminado: Cuando MCP_TOOLSETS no está establecido o está vacío, solo se exponen las herramientas del conjunto default. El conjunto default contiene herramientas de colecciones, campos, relaciones y contenido, pero no herramientas de esquema, flujo o tableros. Las herramientas de esquema, flujo y tableros deben solicitarse explícitamente incluyendo schema, flow o dashboards en la variable de entorno MCP_TOOLSETS.

Configuración: Establezca la variable de entorno MCP_TOOLSETS como una lista separada por comas de conjuntos de herramientas:

# Expose only collections tools
MCP_TOOLSETS=collections

# Expose only schema snapshot/diff tools
MCP_TOOLSETS=schema

# Expose collections and fields tools
MCP_TOOLSETS=collections,fields

# Expose only dashboard and panel tools
MCP_TOOLSETS=dashboards

# Expose all schema-related toolsets
MCP_TOOLSETS=collections,fields,relations,schema

# Expose all toolsets (includes flow and dashboard tools)
MCP_TOOLSETS=default,flow,dashboards
# OR
MCP_TOOLSETS=collections,fields,relations,schema,content,flow,dashboards
# OR simply use 'all' to expose everything
MCP_TOOLSETS=all

Ejemplos:

{
  "mcpServers": {
    "directus-schema": {
      "command": "node",
      "args": ["/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_token",
        "MCP_TOOLSETS": "schema"
      }
    },
    "directus-content": {
      "command": "node",
      "args": ["/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_token",
        "MCP_TOOLSETS": "content"
      }
    }
  }
}

Notas:

  • Los nombres de los conjuntos de herramientas no distinguen entre mayúsculas y minúsculas
  • Los nombres de conjuntos no válidos se ignoran (con una advertencia)
  • Si todos los conjuntos solicitados no son válidos, el servidor utiliza por defecto el conjunto default
  • Las herramientas de colecciones, campos, relaciones y contenido pertenecen tanto a default como a su conjunto específico
  • Las herramientas de esquema, flujo y tableros pertenecen SOLO a sus respectivos conjuntos (no en default)

Compilación

npm run build

Uso

Ejecutar el servidor

npm start

O use el binario compilado:

node dist/index.js

Configuración del cliente MCP

Agregue a su configuración de cliente MCP (por ejemplo, Claude Desktop, Cline):

Opción 1: Usando npx (recomendado - no requiere instalación):

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": ["-y", "directus-mcp-server"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_static_token_here",
        "MCP_TOOLSETS": "default"
      }
    }
  }
}

Opción 2: Usando instalación global:

{
  "mcpServers": {
    "directus": {
      "command": "directus-mcp",
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_static_token_here",
        "MCP_TOOLSETS": "default"
      }
    }
  }
}

Opción 3: Usando el código fuente local:

{
  "mcpServers": {
    "directus": {
      "command": "node",
      "args": ["/absolute/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_static_token_here",
        "MCP_TOOLSETS": "default"
      }
    }
  }
}

Herramientas disponibles

Herramientas de gestión de esquema

list_collections

Lista todas las colecciones en la instancia de Directus.

Parámetros: Ninguno

Ejemplo:

{}

get_collection

Obtiene información detallada sobre una colección específica.

Parámetros:

  • collection (cadena): Nombre de la colección

Ejemplo:

{
  "collection": "articles"
}

create_collection

Crea una nueva colección (tabla de base de datos) con campos opcionales. Esto crea automáticamente una tabla de base de datos adecuada, no solo una carpeta.

Parámetros:

  • collection (cadena): Nombre de la colección
  • meta (objeto, opcional): Metadatos de la colección (icono, nota, singleton, etc.)
  • schema (objeto, opcional): Configuración del esquema de base de datos (se establece automáticamente si no se proporciona)
  • fields (matriz, opcional): Campos iniciales a crear

Ejemplo:

{
  "collection": "articles",
  "meta": {
    "icon": "article",
    "note": "Blog articles collection"
  },
  "fields": [
    {
      "field": "id",
      "type": "integer",
      "schema": {
        "is_primary_key": true,
        "has_auto_increment": true
      }
    },
    {
      "field": "title",
      "type": "string",
      "meta": {
        "required": true
      }
    },
    {
      "field": "status",
      "type": "string",
      "meta": {
        "interface": "select-dropdown",
        "options": {
          "choices": [
            {"text": "Draft", "value": "draft"},
            {"text": "Published", "value": "published"}
          ]
        }
      }
    }
  ]
}

update_collection

Actualiza los metadatos de la colección.

Parámetros:

  • collection (cadena): Nombre de la colección
  • meta (objeto): Metadatos a actualizar

Ejemplo:

{
  "collection": "articles",
  "meta": {
    "icon": "article",
    "note": "Updated description"
  }
}

delete_collection

Elimina una colección y todos sus datos.

Parámetros:

  • collection (cadena): Nombre de la colección

Ejemplo:

{
  "collection": "articles"
}

list_fields

Lista todos los campos de una colección.

Parámetros:

  • collection (cadena): Nombre de la colección

Ejemplo:

{
  "collection": "articles"
}

create_field

Agrega un nuevo campo a una colección.

Parámetros:

  • collection (cadena): Nombre de la colección
  • field (cadena): Nombre del campo
  • type (cadena): Tipo de campo (string, integer, text, boolean, json, uuid, timestamp, etc.)
  • meta (objeto, opcional): Metadatos del campo
  • schema (objeto, opcional): Configuración del esquema de base de datos

Ejemplo:

{
  "collection": "articles",
  "field": "author",
  "type": "uuid",
  "meta": {
    "interface": "select-dropdown-m2o",
    "required": true,
    "special": ["m2o"]
  }
}

update_field

Actualiza las propiedades del campo.

Parámetros:

  • collection (cadena): Nombre de la colección
  • field (cadena): Nombre del campo
  • type (cadena, opcional): Tipo de campo
  • meta (objeto, opcional): Metadatos a actualizar
  • schema (objeto, opcional): Esquema a actualizar

Ejemplo:

{
  "collection": "articles",
  "field": "title",
  "meta": {
    "note": "Article title (required)"
  }
}

delete_field

Elimina un campo de una colección.

Parámetros:

  • collection (cadena): Nombre de la colección
  • field (cadena): Nombre del campo

Ejemplo:

{
  "collection": "articles",
  "field": "old_field"
}

list_relations

Lista todas las relaciones en la instancia de Directus.

Parámetros: Ninguno

Ejemplo:

{}

create_relation

Crea una relación entre colecciones.

Parámetros:

  • collection (cadena): Colección "muchos" (con clave externa)
  • field (cadena): Nombre del campo en la colección "muchos"
  • related_collection (cadena, opcional): Colección "uno"
  • meta (objeto, opcional): Metadatos de la relación
  • schema (objeto, opcional): Configuración de la relación de base de datos

Ejemplo (Muchos a uno):

{
  "collection": "articles",
  "field": "author",
  "related_collection": "users",
  "schema": {
    "on_delete": "SET NULL"
  }
}

Ejemplo (Uno a muchos):

{
  "collection": "articles",
  "field": "author",
  "related_collection": "users",
  "meta": {
    "one_field": "articles"
  }
}

delete_relation

Elimina una relación.

Parámetros:

  • collection (cadena): Nombre de la colección
  • field (cadena): Nombre del campo

Ejemplo:

{
  "collection": "articles",
  "field": "author"
}

Herramientas de gestión de contenido

query_items

Consulta elementos con filtrado, ordenación y paginación.

Parámetros:

  • collection (cadena): Nombre de la colección
  • fields (matriz, opcional): Campos a devolver
  • filter (objeto, opcional): Criterios de filtro
  • search (cadena, opcional): Consulta de búsqueda
  • sort (matriz, opcional): Campos de ordenación (prefijo con - para descendente)
  • limit (número, opcional): Número máximo de elementos a devolver
  • offset (número, opcional): Elementos a omitir
  • page (número, opcional): Número de página
  • aggregate (objeto, opcional): Funciones de agregación
  • groupBy (matriz, opcional): Campos de agrupación
  • deep (objeto, opcional): Consultas relacionales profundas

Operadores de filtro: _eq, _neq, _lt, _lte, _gt, _gte, _in, _nin, _null, _nnull, _contains, _ncontains, _starts_with, _nstarts_with, _ends_with, _nends_with, _between, _nbetween

Ejemplo:

{
  "collection": "articles",
  "filter": {
    "status": {"_eq": "published"},
    "date_created": {"_gte": "2024-01-01"}
  },
  "sort": ["-date_created"],
  "limit": 10
}

get_item

Obtiene un solo elemento por ID.

Parámetros:

  • collection (cadena): Nombre de la colección
  • id (cadena|número): ID del elemento
  • fields (matriz, opcional): Campos a devolver
  • deep (objeto, opcional): Consultas relacionales profundas

Ejemplo:

{
  "collection": "articles",
  "id": 1,
  "fields": ["id", "title", "status", "author.first_name"]
}

create_item

Crea un nuevo elemento.

Parámetros:

  • collection (cadena): Nombre de la colección
  • data (objeto): Datos del elemento

Ejemplo:

{
  "collection": "articles",
  "data": {
    "title": "My New Article",
    "status": "draft",
    "body": "Article content here...",
    "author": "user-uuid-here"
  }
}

update_item

Actualiza un elemento existente.

Parámetros:

  • collection (cadena): Nombre de la colección
  • id (cadena|número): ID del elemento
  • data (objeto): Campos a actualizar

Ejemplo:

{
  "collection": "articles",
  "id": 1,
  "data": {
    "status": "published"
  }
}

delete_item

Elimina un elemento.

Parámetros:

  • collection (cadena): Nombre de la colección
  • id (cadena|número): ID del elemento

Ejemplo:

{
  "collection": "articles",
  "id": 1
}

bulk_create_items

Crea varios elementos a la vez.

Parámetros:

  • collection (cadena): Nombre de la colección
  • items (matriz): Matriz de objetos de datos de elementos

Ejemplo:

{
  "collection": "articles",
  "items": [
    {"title": "Article 1", "status": "draft"},
    {"title": "Article 2", "status": "draft"}
  ]
}

bulk_update_items

Actualiza varios elementos a la vez.

Parámetros:

  • collection (cadena): Nombre de la colección
  • items (matriz): Matriz de elementos con id y campos a actualizar

Ejemplo:

{
  "collection": "articles",
  "items": [
    {"id": 1, "status": "published"},
    {"id": 2, "status": "published"}
  ]
}

bulk_delete_items

Elimina varios elementos a la vez.

Parámetros:

  • collection (cadena): Nombre de la colección
  • ids (matriz): Matriz de IDs de elementos

Ejemplo:

{
  "collection": "articles",
  "ids": [1, 2, 3]
}

Casos de uso comunes

Configurar un nuevo modelo de contenido

  1. Cree una colección con create_collection
  2. Agregue campos con create_field
  3. Cree relaciones con create_relation
  4. Comience a agregar contenido con create_item

Consultar contenido con relaciones

{
  "collection": "articles",
  "fields": ["*", "author.first_name", "author.last_name"],
  "filter": {"status": {"_eq": "published"}},
  "sort": ["-date_created"],
  "limit": 10
}

Operaciones masivas

Use bulk_create_items, bulk_update_items o bulk_delete_items para operaciones por lotes eficientes.

Desarrollo

# Watch mode for development
npm run dev

# Build for production
npm run build

Creación de herramientas

Este proyecto proporciona utilidades para optimizar el desarrollo de herramientas MCP y reducir la duplicación de código:

Ayudantes de herramientas

Use createTool para herramientas que devuelven datos, y createActionTool para herramientas que realizan acciones:

import { createTool, createActionTool } from './tools/tool-helpers.js';

// Data-returning tool
const myTool = createTool({
  name: 'my_tool',
  description: 'Description of what the tool does',
  inputSchema: MySchema,
  toolsets: ['default', 'my-category'],
  handler: async (client, args) => client.someMethod(args)
});

// Action tool (returns success message)
const myActionTool = createActionTool({
  name: 'delete_something',
  description: 'Delete something',
  inputSchema: DeleteSchema,
  toolsets: ['default'],
  handler: async (client, args) => client.deleteMethod(args.id),
  successMessage: (args) => `Successfully deleted item ${args.id}`
});

Validadores compartidos

Los esquemas Zod comunes están disponibles en src/tools/validators.ts:

  • CollectionNameSchema - Para nombres de colecciones
  • ItemIdSchema - Para IDs de elementos (cadena | número)
  • FieldsSchema - Para matrices de campos
  • FilterSchema - Para objetos de filtro de Directus
  • Esquemas de parámetros de consulta (SortSchema, LimitSchema, etc.)
  • Esquemas relacionados con flujos (FlowTriggerSchema, FlowStatusSchema, etc.)

Ejemplo de uso:

import { CollectionNameSchema, ItemIdSchema } from './tools/validators.js';

const MyToolSchema = z.object({
  collection: CollectionNameSchema,
  id: ItemIdSchema,
  // ... other fields
});

Fábrica de recursos del cliente Directus

El cliente utiliza un patrón de fábrica de recursos para operaciones CRUD consistentes. Al agregar nuevos recursos de Directus, defínalos en el constructor del cliente usando createResourceMethods().

Manejo de errores

Todas las herramientas incluyen manejo de errores y devolverán mensajes de error descriptivos para:

  • Fallos de autenticación
  • Parámetros no válidos
  • Errores de API
  • Problemas de red
  • Errores de validación

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una solicitud de extracción (Pull Request).