lokicms-plugin-mongodb

MongoDB migration and synchronization plugin for LokiCMS. Enables seamless migration from LokiJS to MongoDB with real-time sync support.

Features

• One-time Migration: Migrate all data from LokiJS to MongoDB
• Real-time Sync: Keep MongoDB in sync with LokiJS changes
• Batch Sync: Queue changes and sync periodically for better performance
• Conflict Resolution: Multiple strategies for handling sync conflicts
• Query Translation: Automatic translation of LokiJS queries to MongoDB
• MCP Tools: 10 MCP tools for agents to manage migration and sync

Installation

npm install lokicms-plugin-mongodb

Configuration

Add the MongoDB plugin configuration to your LokiCMS config:

{
  plugins: {
    mongodb: {
      uri: 'mongodb://localhost:27017',
      database: 'lokicms',
      enableSync: true,
      syncMode: 'realtime', // 'realtime' | 'batch'
      batchInterval: 5000,  // ms, for batch mode
      conflictResolution: 'last-write-wins'
    }
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | uri | string | required | MongoDB connection URI | | database | string | required | Database name | | enableSync | boolean | false | Enable real-time sync on startup | | syncMode | string | 'realtime' | Sync mode: 'realtime' or 'batch' | | batchInterval | number | 5000 | Batch sync interval in ms | | conflictResolution | string | 'last-write-wins' | Conflict resolution strategy | | debug | boolean | false | Enable debug logging |

Connection Options

{
  mongodb: {
    uri: 'mongodb://localhost:27017',
    database: 'lokicms',
    connectionOptions: {
      maxPoolSize: 10,
      minPoolSize: 2,
      connectTimeoutMS: 10000,
      socketTimeoutMS: 45000,
      retryWrites: true,
      writeConcern: 'majority'
    }
  }
}

MCP Tools

mongodb_status

Get MongoDB connection and sync status.

await callTool('mongodb_status', {});

mongodb_connect

Connect to MongoDB database.

await callTool('mongodb_connect', {
  uri: 'mongodb://localhost:27017',  // optional, uses config if not provided
  database: 'lokicms'                // optional
});

mongodb_disconnect

Disconnect from MongoDB database.

await callTool('mongodb_disconnect', {});

mongodb_migrate_all

Migrate all data from LokiJS to MongoDB.

await callTool('mongodb_migrate_all', {
  dropExisting: true,  // Drop existing collections before migration
  batchSize: 100       // Documents per batch
});

mongodb_migrate_collection

Migrate a specific collection.

await callTool('mongodb_migrate_collection', {
  collection: 'entries',  // contentTypes, entries, taxonomies, terms, users
  dropExisting: true
});

mongodb_sync_enable

Enable real-time synchronization.

await callTool('mongodb_sync_enable', {
  mode: 'realtime',                    // 'realtime' | 'batch'
  batchIntervalMs: 5000,               // for batch mode
  conflictResolution: 'last-write-wins' // see below
});

mongodb_sync_disable

Disable synchronization.

await callTool('mongodb_sync_disable', {});

mongodb_sync_status

Get detailed sync status and statistics.

await callTool('mongodb_sync_status', {});

mongodb_conflicts_list

List pending conflicts that need manual resolution.

await callTool('mongodb_conflicts_list', {});

mongodb_conflict_resolve

Resolve a sync conflict manually.

await callTool('mongodb_conflict_resolve', {
  conflictId: 'evt_123456_abc',
  resolution: 'use-loki'  // 'use-loki' | 'use-mongo' | 'merge'
});

Conflict Resolution Strategies

| Strategy | Description | |----------|-------------| | last-write-wins | Most recent update wins (based on timestamp) | | source-wins | LokiJS version always wins | | target-wins | MongoDB version always wins | | merge | Attempt to merge both versions | | manual | Queue for manual resolution |

Collection Mappings

| LokiJS Collection | MongoDB Collection | Indices | |-------------------|-------------------|---------| | contentTypes | content_types | slug (unique), name | | entries | entries | contentTypeSlug+slug (unique), status, authorId, createdAt | | taxonomies | taxonomies | slug (unique), name | | terms | terms | taxonomySlug, parentId, slug | | users | users | email (unique), role, isActive |

Query Translation

LokiJS queries are automatically translated to MongoDB format:

| LokiJS | MongoDB | Notes | |--------|---------|-------| | $eq, $ne, $gt, $gte, $lt, $lte | Same | Identical | | $in, $nin | Same | Identical | | $between: [a, b] | { $gte: a, $lte: b } | Transformed | | $contains | $elemMatch or $regex | Context-dependent | | $containsAny | $in | For arrays | | $regex | $regex | Identical | | $exists | $exists | Identical | | $and, $or, $not | Same | Identical |

Migration Workflow

1. Initial Setup

// Connect to MongoDB
await callTool('mongodb_connect', {});

// Check connection status
const status = await callTool('mongodb_status', {});
console.log(status);

2. Migrate Data

// Migrate all collections
const result = await callTool('mongodb_migrate_all', {
  dropExisting: true,
  batchSize: 100
});

console.log(`Migrated ${result.summary.totalMigrated} documents`);

3. Enable Sync

// Enable real-time sync
await callTool('mongodb_sync_enable', {
  mode: 'realtime',
  conflictResolution: 'last-write-wins'
});

4. Monitor

// Check sync status periodically
const syncStatus = await callTool('mongodb_sync_status', {});
console.log(`Synced: ${syncStatus.stats.totalSynced}`);
console.log(`Errors: ${syncStatus.stats.errors}`);
console.log(`Pending conflicts: ${syncStatus.conflicts.length}`);

5. Handle Conflicts

// List conflicts
const conflicts = await callTool('mongodb_conflicts_list', {});

// Resolve each conflict
for (const conflict of conflicts.conflicts) {
  await callTool('mongodb_conflict_resolve', {
    conflictId: conflict.id,
    resolution: 'use-loki'
  });
}

TypeScript

import type {
  MongoDBPluginConfig,
  MigrationResult,
  SyncStatus,
  SyncConflict,
  CollectionName,
} from 'lokicms-plugin-mongodb';

import {
  translateQuery,
  translateDocumentToMongo,
  translateDocumentToLoki,
  COLLECTION_MAPPINGS,
} from 'lokicms-plugin-mongodb';

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      LokiCMS Services                        │
│  (EntryService, ContentTypeService, TaxonomyService, etc.)   │
└─────────────────────────────┬───────────────────────────────┘
                              │ Hooks (afterCreate, afterUpdate, afterDelete)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    MongoDB Plugin                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ SyncEngine  │  │  Migrator   │  │  Query Translator   │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│         └────────────────┼─────────────────────┘             │
│                          ▼                                   │
│                ┌─────────────────┐                          │
│                │  MongoClient    │                          │
│                │    Manager      │                          │
│                └────────┬────────┘                          │
└─────────────────────────┼───────────────────────────────────┘
                          ▼
              ┌───────────────────────┐
              │       MongoDB         │
              │  (content_types,      │
              │   entries, users,     │
              │   taxonomies, terms)  │
              └───────────────────────┘

License

MIT