creatuluw/tpl.mcp-server

Directus Task MCP Server

A Model Context Protocol (MCP) server for managing tasks in Directus with automatic schema synchronization. This server allows you to interact with your Directus PostgreSQL database through AI assistants like Claude or Cursor.

Features

• Task Management: Create, read, update, and delete tasks
• Schema Management: Automatically sync TypeScript models to Directus collections
• Filtering: Filter tasks by status, priority, and other criteria
• Validation: Built-in validation using Zod schemas
• Type Safety: Full TypeScript support with proper typing

Prerequisites

• Node.js 18+
• A Directus instance (local or hosted)
• Directus API token or user credentials

Installation

1. Clone and setup the project:

   npm install
   npm run build
   

2. Configure your Directus connection:

   The server uses the following environment variables:

   • DIRECTUS_URL: Your Directus instance URL (default: https://te9-pg-api.up.railway.app/)
   • DIRECTUS_TOKEN: Your Directus API token (default: mo7tahjWjKgHW-42_tEMThJiqBstu2V_)
   • DIRECTUS_USER_EMAIL: Alternative to token - user email
   • DIRECTUS_USER_PASSWORD: Alternative to token - user password

Configuration

For Cursor

1. Create a .cursor/mcp.json file in your project root:

   {
     "mcpServers": {
       "directus-tasks": {
         "command": "node",
         "args": ["dist/index.js"],
         "env": {
           "DIRECTUS_URL": "https://te9-pg-api.up.railway.app/",
           "DIRECTUS_TOKEN": "mo7tahjWjKgHW-42_tEMThJiqBstu2V_"
         }
       }
     }
   }
   

For Claude Desktop

1. Open Claude Desktop settings
2. Navigate to Developer tab and click "Edit Config"
3. Add the following configuration:

   {
     "mcpServers": {
       "directus-tasks": {
         "command": "node",
         "args": ["/absolute/path/to/your/project/dist/index.js"],
         "env": {
           "DIRECTUS_URL": "https://te9-pg-api.up.railway.app/",
           "DIRECTUS_TOKEN": "mo7tahjWjKgHW-42_tEMThJiqBstu2V_"
         }
       }
     }
   }
   

Important: Replace /absolute/path/to/your/project with the actual absolute path to your project directory.

Available Tools

The MCP server provides the following tools:

Schema Management

• sync-task-schema: Synchronizes the Task model schema with your Directus database

Task Management

• list-tasks: List all tasks with optional filtering by status, priority, and limit
• get-task: Get a specific task by ID
• create-task: Create a new task
• update-task: Update an existing task
• delete-task: Delete a task

User Management

• get-user-info: Get current user information

Task Model

The Task model includes the following fields:

interface Task {
  id?: string;              // UUID primary key
  title: string;            // Required task title
  description?: string;     // Optional description
  status: 'todo' | 'in_progress' | 'completed';  // Task status
  priority: 'low' | 'medium' | 'high';           // Task priority
  due_date?: string;        // Optional due date (ISO format)
  created_at?: string;      // Auto-generated creation timestamp
  updated_at?: string;      // Auto-generated update timestamp
  user_created?: string;    // Auto-generated user who created
  user_updated?: string;    // Auto-generated user who updated
}

Usage Examples

1. First Time Setup

Please sync the task schema with the database

2. Create a Task

Create a new task with title "Implement user authentication" and high priority

3. List Tasks

Show me all tasks with status "in_progress"

4. Update a Task

Update task with ID [task-id] to completed status

5. Get Task Details

Show me details for task [task-id]

Development

Project Structure

src/
├── models/
│   └── Task.ts           # Task model with TypeScript interfaces and Zod schemas
├── services/
│   └── SchemaManager.ts  # Schema management service
└── index.ts              # Main MCP server implementation

Adding New Models

1. Create a new model file in src/models/
2. Define TypeScript interfaces and Zod schemas
3. Export field definitions for Directus
4. Add tools to the main server for the new model
5. Use SchemaManager to sync the schema

Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Development mode (watch for changes)
npm run dev

# Start the server directly
npm start

Troubleshooting

Common Issues

1. Authentication Errors: Verify your Directus URL and token are correct
2. Schema Sync Failures: Ensure your Directus user has admin permissions
3. Connection Issues: Check that your Directus instance is accessible

Debugging

The server logs errors to stderr. You can check the logs in your AI assistant's console or terminal.

Security Notes

• Store your Directus token securely
• Use environment variables for sensitive configuration
• Consider using a dedicated service account for the MCP server
• Regularly rotate your API tokens

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details