Directus

Este servidor permite que assistentes de IA e outros clientes MCP interajam programaticamente com instâncias do Directus.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP do Directus

Um servidor Model Context Protocol (MCP) que fornece ferramentas abrangentes para gerenciar o esquema e o conteúdo do Directus. Este servidor permite que assistentes de IA e outros clientes MCP interajam programaticamente com instâncias do Directus.

Instalação

Via npm (quando publicado)

npm install -g directus-mcp-server

A partir do código-fonte

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

Recursos

  • Gerenciamento de Esquema: Criar, ler, atualizar e excluir coleções, campos e relações
  • Gerenciamento de Conteúdo: Operações CRUD completas em itens com consultas avançadas
  • Segurança de Tipos: Construído com TypeScript e validação Zod
  • SDK Oficial: Usa o @directus/sdk oficial para interações confiáveis com a API
  • Autenticação Flexível: Suporta tanto tokens estáticos quanto autenticação por e-mail/senha

Instalação

npm install

Configuração

Crie um arquivo .env no diretório raiz com sua configuração do 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

Opções de Autenticação

  1. Token Estático (Recomendado para produção):

    • Gere um token estático no Directus Admin App
    • Defina a variável de ambiente DIRECTUS_TOKEN

  2. E-mail/Senha:

    • Use para desenvolvimento ou quando tokens estáticos não estiverem disponíveis
    • Defina as variáveis de ambiente DIRECTUS_EMAIL e DIRECTUS_PASSWORD

Configuração de Conjuntos de Ferramentas

O servidor MCP do Directus organiza as ferramentas em conjuntos lógicos, semelhante à implementação MCP do GitHub. Isso permite controlar quais ferramentas são expostas ao cliente MCP.

Conjuntos de Ferramentas Disponíveis:

  • default - Contém ferramentas de coleções, campos, relações e conteúdo (comportamento padrão quando nenhum conjunto é especificado)
  • collections - Ferramentas de gerenciamento de coleções (listar, obter, criar, atualizar, excluir coleções)
  • fields - Ferramentas de gerenciamento de campos (listar, criar, atualizar, excluir campos)
  • relations - Ferramentas de gerenciamento de relações (listar, criar, excluir relações)
  • schema - Ferramentas de snapshot e diff de esquema (obter snapshot, obter diff, aplicar diff) - NÃO incluído no conjunto padrão
  • content - Ferramentas de gerenciamento de conteúdo (operações CRUD de itens)
  • flow - Ferramentas de gerenciamento de fluxos (automação de fluxos de trabalho) - NÃO incluído no conjunto padrão
  • dashboards - Ferramentas de gerenciamento de dashboards e painéis (listar, obter, criar, atualizar, excluir dashboards e painéis) - NÃO incluído no conjunto padrão
  • all - Todas as ferramentas disponíveis, independentemente do conjunto

Comportamento Padrão: Quando MCP_TOOLSETS não está definido ou está vazio, apenas as ferramentas do conjunto default são expostas. O conjunto default contém ferramentas de coleções, campos, relações e conteúdo, mas não ferramentas de esquema, fluxo ou dashboard. As ferramentas de esquema, fluxo e dashboard devem ser solicitadas explicitamente incluindo schema, flow ou dashboards na variável de ambiente MCP_TOOLSETS.

Configuração: Defina a variável de ambiente MCP_TOOLSETS como uma lista de conjuntos separados por vírgula:

# 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

Exemplos:

{
  "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"
      }
    }
  }
}

Observações:

  • Os nomes dos conjuntos não diferenciam maiúsculas de minúsculas
  • Nomes de conjuntos inválidos são ignorados (com um aviso)
  • Se todos os conjuntos solicitados forem inválidos, o servidor usa o conjunto default por padrão
  • Ferramentas de coleções, campos, relações e conteúdo pertencem tanto ao default quanto ao seu conjunto específico
  • Ferramentas de esquema, fluxo e dashboard pertencem SOMENTE aos seus respectivos conjuntos (não no default)

Compilação

npm run build

Uso

Executando o Servidor

npm start

Ou use o binário compilado:

node dist/index.js

Configuração do Cliente MCP

Adicione à configuração do seu cliente MCP (por exemplo, Claude Desktop, Cline):

Opção 1: Usando npx (recomendado - sem necessidade de instalação):

{
  "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"
      }
    }
  }
}

Opção 2: Usando instalação global:

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

Opção 3: Usando código-fonte 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"
      }
    }
  }
}

Ferramentas Disponíveis

Ferramentas de Gerenciamento de Esquema

list_collections

Lista todas as coleções na instância do Directus.

Parâmetros: Nenhum

Exemplo:

{}

get_collection

Obtém informações detalhadas sobre uma coleção específica.

Parâmetros:

  • collection (string): Nome da coleção

Exemplo:

{
  "collection": "articles"
}

create_collection

Cria uma nova coleção (tabela de banco de dados) com campos opcionais. Isso cria automaticamente uma tabela de banco de dados adequada, não apenas uma pasta.

Parâmetros:

  • collection (string): Nome da coleção
  • meta (objeto, opcional): Metadados da coleção (ícone, nota, singleton, etc.)
  • schema (objeto, opcional): Configuração do esquema do banco de dados (definida automaticamente se não for fornecida)
  • fields (array, opcional): Campos iniciais a criar

Exemplo:

{
  "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

Atualiza os metadados da coleção.

Parâmetros:

  • collection (string): Nome da coleção
  • meta (objeto): Metadados a atualizar

Exemplo:

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

delete_collection

Exclui uma coleção e todos os seus dados.

Parâmetros:

  • collection (string): Nome da coleção

Exemplo:

{
  "collection": "articles"
}

list_fields

Lista todos os campos em uma coleção.

Parâmetros:

  • collection (string): Nome da coleção

Exemplo:

{
  "collection": "articles"
}

create_field

Adiciona um novo campo a uma coleção.

Parâmetros:

  • collection (string): Nome da coleção
  • field (string): Nome do campo
  • type (string): Tipo do campo (string, integer, text, boolean, json, uuid, timestamp, etc.)
  • meta (objeto, opcional): Metadados do campo
  • schema (objeto, opcional): Configuração do esquema do banco de dados

Exemplo:

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

update_field

Atualiza as propriedades do campo.

Parâmetros:

  • collection (string): Nome da coleção
  • field (string): Nome do campo
  • type (string, opcional): Tipo do campo
  • meta (objeto, opcional): Metadados a atualizar
  • schema (objeto, opcional): Esquema a atualizar

Exemplo:

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

delete_field

Remove um campo de uma coleção.

Parâmetros:

  • collection (string): Nome da coleção
  • field (string): Nome do campo

Exemplo:

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

list_relations

Lista todas as relações na instância do Directus.

Parâmetros: Nenhum

Exemplo:

{}

create_relation

Cria uma relação entre coleções.

Parâmetros:

  • collection (string): Coleção "many" (com chave estrangeira)
  • field (string): Nome do campo na coleção "many"
  • related_collection (string, opcional): Coleção "one"
  • meta (objeto, opcional): Metadados da relação
  • schema (objeto, opcional): Configuração da relação no banco de dados

Exemplo (Muitos-para-Um):

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

Exemplo (Um-para-Muitos):

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

delete_relation

Exclui uma relação.

Parâmetros:

  • collection (string): Nome da coleção
  • field (string): Nome do campo

Exemplo:

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

Ferramentas de Gerenciamento de Conteúdo

query_items

Consulta itens com filtragem, ordenação e paginação.

Parâmetros:

  • collection (string): Nome da coleção
  • fields (array, opcional): Campos a retornar
  • filter (objeto, opcional): Critérios de filtro
  • search (string, opcional): Consulta de busca
  • sort (array, opcional): Campos de ordenação (prefixe com - para ordem decrescente)
  • limit (número, opcional): Quantidade máxima de itens a retornar
  • offset (número, opcional): Itens a pular
  • page (número, opcional): Número da página
  • aggregate (objeto, opcional): Funções de agregação
  • groupBy (array, opcional): Campos de agrupamento
  • deep (objeto, opcional): Consultas relacionais 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

Exemplo:

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

get_item

Obtém um único item pelo ID.

Parâmetros:

  • collection (string): Nome da coleção
  • id (string|number): ID do item
  • fields (array, opcional): Campos a retornar
  • deep (objeto, opcional): Consultas relacionais profundas

Exemplo:

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

create_item

Cria um novo item.

Parâmetros:

  • collection (string): Nome da coleção
  • data (objeto): Dados do item

Exemplo:

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

update_item

Atualiza um item existente.

Parâmetros:

  • collection (string): Nome da coleção
  • id (string|number): ID do item
  • data (objeto): Campos a atualizar

Exemplo:

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

delete_item

Exclui um item.

Parâmetros:

  • collection (string): Nome da coleção
  • id (string|number): ID do item

Exemplo:

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

bulk_create_items

Cria vários itens de uma vez.

Parâmetros:

  • collection (string): Nome da coleção
  • items (array): Matriz de objetos de dados de itens

Exemplo:

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

bulk_update_items

Atualiza vários itens de uma vez.

Parâmetros:

  • collection (string): Nome da coleção
  • items (array): Matriz de itens com id e campos a atualizar

Exemplo:

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

bulk_delete_items

Exclui vários itens de uma vez.

Parâmetros:

  • collection (string): Nome da coleção
  • ids (array): Matriz de IDs de itens

Exemplo:

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

Casos de Uso Comuns

Configurando um novo modelo de conteúdo

  1. Crie uma coleção com create_collection
  2. Adicione campos com create_field
  3. Crie relações com create_relation
  4. Comece a adicionar conteúdo com create_item

Consultando conteúdo com relações

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

Operações em lote

Use bulk_create_items, bulk_update_items ou bulk_delete_items para operações em lote eficientes.

Desenvolvimento

# Watch mode for development
npm run dev

# Build for production
npm run build

Criação de Ferramentas

Este projeto fornece utilitários para agilizar o desenvolvimento de ferramentas MCP e reduzir a duplicação de código:

Auxiliares de Ferramentas

Use createTool para ferramentas que retornam dados e createActionTool para ferramentas que executam ações:

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 Compartilhados

Esquemas Zod comuns estão disponíveis em src/tools/validators.ts:

  • CollectionNameSchema - Para nomes de coleções
  • ItemIdSchema - Para IDs de itens (string | number)
  • FieldsSchema - Para matrizes de campos
  • FilterSchema - Para objetos de filtro do Directus
  • Esquemas de parâmetros de consulta (SortSchema, LimitSchema, etc.)
  • Esquemas relacionados a fluxos (FlowTriggerSchema, FlowStatusSchema, etc.)

Exemplo de uso:

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

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

Fábrica de Recursos do Cliente Directus

O cliente usa um padrão de fábrica de recursos para operações CRUD consistentes. Ao adicionar novos recursos do Directus, defina-os no construtor do cliente usando createResourceMethods().

Tratamento de Erros

Todas as ferramentas incluem tratamento de erros e retornarão mensagens de erro descritivas para:

  • Falhas de autenticação
  • Parâmetros inválidos
  • Erros de API
  • Problemas de rede
  • Erros de validação

Licença

MIT

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.