# Directus Schema Management System
This document provides a comprehensive guide for managing Directus database schemas using our custom schema management tools.
## 📁 Project Structure
```
tpl.mcp-server/
├── schemas/ # Schema definition files
│ └── tasks.json # Task collection schema
├── scripts/ # Management scripts
│ └── upload-schema.js # Schema upload utility
├── src/
│ └── models/
│ └── Task.ts # TypeScript model definitions
├── .env # Environment configuration
└── package.json # Project dependencies and scripts
```
## 🚀 Quick Start
### Prerequisites
1. **Environment Setup**: Ensure your `.env` file contains:
```env
DIRECTUS_URL=https://your-directus-instance.com/
DIRECTUS_TOKEN=your-admin-token-here
NODE_ENV=development
```
2. **Dependencies**: Install required packages:
```bash
npm install
```
### Creating Your First Schema
1. **Create a schema file** in the `schemas/` directory:
```bash
# Example: schemas/my-collection.json
```
2. **Upload the schema** to Directus:
```bash
npm run upload-schema schemas/my-collection.json
```
## 📋 Schema File Format
Schema files use a simple JSON format that defines collections and their fields:
### Basic Structure
```json
{
"name": "collection_name",
"comment": "Description of the collection",
"fields": [
{
"field": "field_name",
"type": "field_type",
"required": true,
"comment": "Field description"
}
]
}
```
### Field Types
| Type | Description | Database Type |
|------|-------------|---------------|
| `uuid` | UUID primary key | `uuid` |
| `string` | Text field with length limit | `varchar` |
| `text` | Long text field | `text` |
| `integer` | Whole numbers | `integer` |
| `decimal` | Decimal numbers | `decimal` |
| `float` | Floating point numbers | `real` |
| `boolean` | True/false values | `boolean` |
| `date` | Date only | `date` |
| `timestamp` | Date and time | `timestamp` |
| `json` | JSON data | `json` |
### Field Properties
| Property | Type | Description | Example |
|----------|------|-------------|---------|
| `field` | string | Field name (required) | `"title"` |
| `type` | string | Field type (required) | `"string"` |
| `required` | boolean | Field is required | `true` |
| `nullable` | boolean | Field can be null | `false` |
| `primary` | boolean | Primary key field | `true` |
| `unique` | boolean | Unique constraint | `true` |
| `readonly` | boolean | Read-only in UI | `true` |
| `hidden` | boolean | Hidden in UI | `true` |
| `length` | number | Max length for strings | `255` |
| `default_value` | any | Default value | `"draft"` |
| `enum` | array | Allowed values | `["draft", "published"]` |
| `comment` | string | Field description | `"User's email address"` |
### Special Fields
#### Primary Key (UUID)
```json
{
"field": "id",
"type": "uuid",
"primary": true,
"required": true,
"readonly": true,
"hidden": true,
"comment": "Primary key"
}
```
#### Enum/Select Field
```json
{
"field": "status",
"type": "string",
"length": 50,
"required": true,
"enum": ["draft", "published", "archived"],
"default_value": "draft",
"comment": "Content status"
}
```
#### Timestamps
```json
{
"field": "created_at",
"type": "timestamp",
"required": true,
"readonly": true,
"hidden": true,
"comment": "Creation timestamp"
}
```
## 📖 Complete Example: Tasks Collection
Here's the complete `schemas/tasks.json` file as a reference:
```json
{
"name": "tasks",
"comment": "Task management collection for MCP server",
"fields": [
{
"field": "id",
"type": "uuid",
"primary": true,
"required": true,
"readonly": true,
"hidden": true,
"comment": "Primary key"
},
{
"field": "title",
"type": "string",
"length": 255,
"required": true,
"comment": "Task title"
},
{
"field": "description",
"type": "text",
"nullable": true,
"comment": "Task description"
},
{
"field": "status",
"type": "string",
"length": 50,
"default_value": "todo",
"required": true,
"enum": ["todo", "in_progress", "completed"],
"comment": "Task status"
},
{
"field": "priority",
"type": "string",
"length": 20,
"default_value": "medium",
"required": true,
"enum": ["low", "medium", "high"],
"comment": "Task priority"
},
{
"field": "due_date",
"type": "timestamp",
"nullable": true,
"comment": "Task due date"
},
{
"field": "created_at",
"type": "timestamp",
"required": true,
"readonly": true,
"hidden": true,
"comment": "Creation timestamp"
},
{
"field": "updated_at",
"type": "timestamp",
"required": true,
"readonly": true,
"hidden": true,
"comment": "Last update timestamp"
}
]
}
```
## 🛠️ Upload Script Usage
### Basic Upload
```bash
npm run upload-schema schemas/my-collection.json
```
### Direct Script Usage
```bash
node scripts/upload-schema.js schemas/my-collection.json
```
### Script Features
- ✅ **Connection Testing**: Verifies Directus connection before upload
- ✅ **Collision Detection**: Checks if collection already exists
- ✅ **Field Creation**: Creates all fields with proper types and constraints
- ✅ **Error Handling**: Continues with other fields if one fails
- ✅ **Enum Support**: Automatically creates dropdown interfaces for enum fields
- ✅ **Special Fields**: Handles UUIDs, timestamps, and other special field types
### Upload Output Example
```
🚀 Starting schema upload: schemas/tasks.json
🔗 Directus URL: https://your-directus-instance.com/
🔑 Using token: ***Wq8y
📋 Schema loaded: tasks
📝 Fields: 8
✅ Connected to Directus successfully
🔍 Checking if collection "tasks" exists...
📝 Collection "tasks" does not exist - will create
📦 Creating collection: tasks
✅ Collection created successfully
📝 Creating 8 fields...
📝 Creating field: id (uuid)
❌ Field creation failed: id - Field "id" already exists
📝 Creating field: title (string)
✅ Field created: title
📝 Creating field: description (text)
✅ Field created: description
📝 Creating field: status (string)
✅ Field created: status
📝 Creating field: priority (string)
✅ Field created: priority
📝 Creating field: due_date (timestamp)
✅ Field created: due_date
📝 Creating field: created_at (timestamp)
✅ Field created: created_at
📝 Creating field: updated_at (timestamp)
✅ Field created: updated_at
🎉 Schema upload completed successfully!
📊 Collection: tasks
📝 Fields processed: 8
🔗 Access at: https://your-directus-instance.com/admin/content/tasks
```
## 🔧 Advanced Usage
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `DIRECTUS_URL` | Directus instance URL | Required |
| `DIRECTUS_TOKEN` | Admin API token | Required |
| `NODE_ENV` | Environment mode | `development` |
### Token Requirements
The `DIRECTUS_TOKEN` must have the following permissions:
- **Collections**: Create, Read, Update
- **Fields**: Create, Read, Update
- **Schema**: Read access to `/server/info`
### Creating Admin Tokens
1. Log into your Directus admin panel
2. Go to **Settings** → **Access Tokens**
3. Create a new token with **Admin** role
4. Copy the token to your `.env` file
## 📚 Best Practices
### Schema Design
1. **Use descriptive field names**: `user_email` instead of `email`
2. **Add comments**: Document the purpose of each field
3. **Set appropriate lengths**: Don't use unlimited text for short strings
4. **Use enums for fixed values**: Status fields, categories, etc.
5. **Include timestamps**: `created_at` and `updated_at` for audit trails
### File Organization
1. **One collection per file**: `schemas/users.json`, `schemas/posts.json`
2. **Descriptive filenames**: Match the collection name
3. **Version control**: Commit schema files to track changes
4. **Backup before changes**: Test on development environment first
### Development Workflow
1. **Design the schema** in your preferred tool
2. **Create the JSON file** following our format
3. **Test upload** on development environment
4. **Verify in Directus UI** that fields appear correctly
5. **Test data entry** to ensure validation works
6. **Deploy to production** when ready
## 🚨 Troubleshooting
### Common Issues
#### Authentication Errors
```
❌ Failed to connect to Directus: 401 Unauthorized
```
**Solution**: Check your `DIRECTUS_TOKEN` in the `.env` file
#### Collection Already Exists
```
⚠️ Collection "tasks" already exists. Skipping creation.
```
**Solution**: This is normal. The script will add missing fields to existing collections.
#### Field Creation Fails
```
❌ Field creation failed: title - Invalid field type
```
**Solution**: Check the field type is supported (see Field Types table above)
#### Permission Errors
```
❌ Error creating collection: 403 Forbidden
```
**Solution**: Ensure your token has admin permissions
### Debug Mode
For detailed error information, check the full error response in the console output. The script shows complete API responses for debugging.
## 🔄 Migration and Updates
### Adding Fields to Existing Collections
1. Add the new field to your schema JSON file
2. Run the upload script again
3. Only new fields will be created; existing fields are skipped
### Modifying Existing Fields
⚠️ **Warning**: The upload script doesn't modify existing fields. To change field properties:
1. Use the Directus admin interface, or
2. Create a new collection with the updated schema, or
3. Manually update via the Directus API
### Schema Versioning
Consider maintaining schema versions:
```
schemas/
├── v1/
│ └── tasks.json
├── v2/
│ └── tasks.json
└── current/
└── tasks.json → ../v2/tasks.json
```
## 📞 Support
For issues or questions about the schema management system:
1. Check this documentation first
2. Review the console output for specific error messages
3. Verify your Directus permissions and token
4. Test with a simple schema first
## 🔗 Related Files
- **`schemas/tasks.json`**: Example schema file
- **`scripts/upload-schema.js`**: Upload utility script
- **`src/models/Task.ts`**: TypeScript model definitions
- **`.env`**: Environment configuration
- **`package.json`**: NPM scripts and dependencies
---
*This documentation covers the complete Directus schema management workflow. Keep this file updated as the system evolves.*
