mcp-mongo-server 1.2.0 → 1.3.0

package/README.md

@@ -124,9 +124,14 @@ Using environment variables in Claude Desktop configuration:
 Using environment variables with Docker:
 
 ```bash
-docker run -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" \
-           -e MCP_MONGODB_READONLY="true" \
-           mcp-mongo-server
+# Build
+docker build -t mcp-mongo-server .
+
+# Run
+docker run -it -d -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" -e MCP_MONGODB_READONLY="true" mcp-mongo-server
+
+# or edit docker-compose.yml and run
+docker-compose up -d
 ```
 
 ## Integration with Claude Desktop
@@ -192,6 +197,7 @@ Add the server configuration to Claude Desktop's config file:
     }
   }
 }
+```
 
 ### GitHub Package Usage:
 

package/build/schemas/call.js

@@ -22,6 +22,10 @@ export async function handleCallToolRequest({ request, client, db, isReadOnlyMod
             filteredArgs[key] = value;
         }
     }
+    // Checking whether sort option provided is valid
+    if (args.sort) {
+        args.sort = parseSort(args.sort);
+    }
     // Replace the original args with the filtered version
     Object.assign(args, filteredArgs);
     // Validate operation name
@@ -90,6 +94,20 @@ function checkReadOnlyMode(operation, isReadOnlyMode) {
         throw new Error(`ReadonlyError: Operation '${operation}' is not allowed in read-only mode`);
     }
 }
+function parseSort(sort) {
+    if (!sort)
+        return null;
+    if (typeof sort !== 'object' || sort === null || Array.isArray(sort)) {
+        return null;
+    }
+    const validSort = {};
+    for (const [key, value] of Object.entries(sort)) {
+        if (typeof value === 'number' && (value === 1 || value === -1)) {
+            validSort[key] = value;
+        }
+    }
+    return Object.keys(validSort).length > 0 ? validSort : null;
+}
 function parseFilter(filter, objectIdMode = "auto") {
     if (!filter) {
         return {};
@@ -122,7 +140,47 @@ function isObjectIdField(fieldName) {
 function processObjectIdInFilter(filter, objectIdMode = "auto") {
     // If objectIdMode is "none", don't convert any strings to ObjectIds
     if (objectIdMode === "none") {
-        return filter;
+        // Create a new filter object to handle dates
+        const result = {};
+        for (const [key, value] of Object.entries(filter)) {
+            if (typeof value === "string" && isISODateString(value)) {
+                // Convert ISO date string to Date object
+                result[key] = new Date(value);
+            }
+            else if (typeof value === "string" && value.startsWith("ISODate(") && value.endsWith(")")) {
+                // Handle ISODate("2025-01-01T00:00:00Z") format
+                const dateString = value.substring(8, value.length - 2);
+                if (isISODateString(dateString)) {
+                    result[key] = new Date(dateString);
+                }
+                else {
+                    result[key] = value;
+                }
+            }
+            else if (typeof value === "object" && value !== null) {
+                if (Array.isArray(value)) {
+                    // For arrays, apply date conversion to each item
+                    result[key] = value.map((item) => {
+                        if (typeof item === "string" && isISODateString(item)) {
+                            return new Date(item);
+                        }
+                        else if (typeof item === "string" && item.startsWith("ISODate(") && item.endsWith(")")) {
+                            const dateString = item.substring(8, item.length - 2);
+                            return isISODateString(dateString) ? new Date(dateString) : item;
+                        }
+                        return item;
+                    });
+                }
+                else {
+                    // Process nested objects
+                    result[key] = processObjectIdInFilter(value, "none");
+                }
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
     }
     const result = {};
     for (const [key, value] of Object.entries(filter)) {
@@ -138,18 +196,37 @@ function processObjectIdInFilter(filter, objectIdMode = "auto") {
                 result[key] = value;
             }
         }
+        else if (typeof value === "string" && isISODateString(value)) {
+            // Convert ISO date string to Date object
+            result[key] = new Date(value);
+        }
+        else if (typeof value === "string" && value.startsWith("ISODate(") && value.endsWith(")")) {
+            // Handle ISODate("2025-01-01T00:00:00Z") format
+            const dateString = value.substring(8, value.length - 2);
+            if (isISODateString(dateString)) {
+                result[key] = new Date(dateString);
+            }
+            else {
+                result[key] = value;
+            }
+        }
         else if (typeof value === "object" && value !== null) {
             if (Array.isArray(value)) {
                 // For arrays, apply the same logic to each item
-                if (objectIdMode === "force" ||
-                    (objectIdMode === "auto" && isObjectIdField(key))) {
-                    result[key] = value.map((item) => typeof item === "string" && isObjectIdString(item)
-                        ? new ObjectId(item)
-                        : item);
-                }
-                else {
-                    result[key] = value;
-                }
+                result[key] = value.map((item) => {
+                    if (typeof item === "string" && isObjectIdString(item) &&
+                        (objectIdMode === "force" || (objectIdMode === "auto" && isObjectIdField(key)))) {
+                        return new ObjectId(item);
+                    }
+                    else if (typeof item === "string" && isISODateString(item)) {
+                        return new Date(item);
+                    }
+                    else if (typeof item === "string" && item.startsWith("ISODate(") && item.endsWith(")")) {
+                        const dateString = item.substring(8, item.length - 2);
+                        return isISODateString(dateString) ? new Date(dateString) : item;
+                    }
+                    return item;
+                });
             }
             else {
                 // Process nested objects
@@ -167,6 +244,11 @@ function isObjectIdString(str) {
     // MongoDB ObjectId is typically a 24-character hex string
     return /^[0-9a-fA-F]{24}$/.test(str);
 }
+// Helper function to check if a string is in ISO date format
+function isISODateString(str) {
+    // Check if string matches ISO 8601 format
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/.test(str);
+}
 function formatResponse(data) {
     return {
         content: [
@@ -189,7 +271,7 @@ async function handleQuery(collection, args, objectIdMode = "auto") {
     if (!collection) {
         throw new Error("Collection is required for query operation");
     }
-    const { filter, projection, limit, explain } = args;
+    const { filter, projection, limit, explain, sort } = args;
     const queryFilter = parseFilter(filter, objectIdMode);
     try {
         if (explain) {
@@ -197,6 +279,7 @@ async function handleQuery(collection, args, objectIdMode = "auto") {
                 .find(queryFilter, {
                 projection,
                 limit: limit || 100,
+                sort,
             })
                 .explain(explain);
             return formatResponse(explainResult);
@@ -204,6 +287,7 @@ async function handleQuery(collection, args, objectIdMode = "auto") {
         const cursor = collection.find(queryFilter, {
             projection,
             limit: limit || 100,
+            sort,
         });
         const results = await cursor.toArray();
         return formatResponse(results);

package/build/schemas/resource.js

@@ -1,29 +1,180 @@
+import { ObjectId } from "mongodb";
+/**
+ * Detects the MongoDB-specific type of a value
+ * @param value The value to detect the type of
+ * @returns A string representing the detected type
+ */
+function detectMongoType(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (value instanceof ObjectId)
+        return 'ObjectId';
+    if (value instanceof Date)
+        return 'Date';
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return 'Array';
+        // Check if array has consistent types
+        const elementTypes = new Set(value.map(item => detectMongoType(item)));
+        if (elementTypes.size === 1) {
+            return `Array<${Array.from(elementTypes)[0]}>`;
+        }
+        return 'Array<mixed>';
+    }
+    if (typeof value === 'object') {
+        // Handle nested documents
+        return 'Document';
+    }
+    return typeof value;
+}
+/**
+ * Helper function to infer a schema from multiple documents
+ * @param documents Array of sample documents from the collection
+ * @returns Inferred schema with field names and types
+ */
+function inferSchemaFromSamples(documents) {
+    if (!documents || documents.length === 0) {
+        return { fields: [] };
+    }
+    // Use a Map to store field information, with the key being the field name
+    const fieldMap = new Map();
+    // Process each document to collect field information
+    for (const doc of documents) {
+        for (const [key, value] of Object.entries(doc)) {
+            if (!fieldMap.has(key)) {
+                // Initialize field info if we haven't seen this field before
+                fieldMap.set(key, {
+                    name: key,
+                    types: new Set([detectMongoType(value)]),
+                    nullable: false,
+                    // Store sample values for complex types
+                    samples: [value],
+                });
+            }
+            else {
+                // Update existing field info
+                const fieldInfo = fieldMap.get(key);
+                fieldInfo.types.add(detectMongoType(value));
+                // Store up to 3 different sample values
+                if (fieldInfo.samples.length < 3 &&
+                    !fieldInfo.samples.some((sample) => JSON.stringify(sample) === JSON.stringify(value))) {
+                    fieldInfo.samples.push(value);
+                }
+            }
+        }
+    }
+    // Check for nullable fields by seeing which fields are missing in some documents
+    for (const doc of documents) {
+        for (const [key] of fieldMap.entries()) {
+            if (!(key in doc)) {
+                const fieldInfo = fieldMap.get(key);
+                fieldInfo.nullable = true;
+            }
+        }
+    }
+    // Process nested document schemas
+    for (const [key, fieldInfo] of fieldMap.entries()) {
+        if (fieldInfo.types.has('Document')) {
+            // Extract nested documents for this field
+            const nestedDocs = documents
+                .filter(doc => doc[key] && typeof doc[key] === 'object' && !Array.isArray(doc[key]))
+                .map(doc => doc[key]);
+            if (nestedDocs.length > 0) {
+                // Recursively infer schema for nested documents
+                fieldInfo.nestedSchema = inferSchemaFromSamples(nestedDocs);
+            }
+        }
+    }
+    // Convert the Map to an array of field objects with additional info
+    const fields = Array.from(fieldMap.values()).map(fieldInfo => {
+        const result = {
+            name: fieldInfo.name,
+            types: Array.from(fieldInfo.types),
+            nullable: fieldInfo.nullable,
+            prevalence: Math.round((documents.filter(doc => fieldInfo.name in doc).length / documents.length) * 100) + '%',
+            examples: [],
+        };
+        // Include nested schema if available
+        if (fieldInfo.nestedSchema) {
+            result.nestedSchema = fieldInfo.nestedSchema;
+        }
+        // Include simplified sample values
+        const sampleValues = fieldInfo.samples.map((sample) => {
+            if (sample instanceof ObjectId)
+                return sample.toString();
+            if (sample instanceof Date)
+                return sample.toISOString();
+            if (typeof sample === 'object') {
+                // For objects/arrays, just indicate type rather than full structure
+                return Array.isArray(sample) ? '[...]' : '{...}';
+            }
+            return sample;
+        });
+        result.examples = sampleValues;
+        return result;
+    });
+    return { fields };
+}
 export async function handleReadResourceRequest({ request, client, db, isReadOnlyMode, }) {
     const url = new URL(request.params.uri);
     const collectionName = url.pathname.replace(/^\//, "");
     try {
         const collection = db.collection(collectionName);
-        const sample = await collection.findOne({});
+        // Set sample size for schema inference
+        const sampleSize = 100;
+        let sampleDocuments = [];
+        try {
+            // First try using MongoDB's $sample aggregation to get a diverse set of documents
+            sampleDocuments = await collection
+                .aggregate([{ $sample: { size: sampleSize } }])
+                .toArray();
+        }
+        catch (sampleError) {
+            // Fallback to sequential scan if $sample is not available
+            console.warn(`$sample aggregation failed for ${collectionName}, falling back to sequential scan: ${sampleError}`);
+            sampleDocuments = await collection
+                .find({})
+                .limit(sampleSize)
+                .toArray();
+        }
+        // Get indexes for the collection
         const indexes = await collection.indexes();
-        const schema = sample
-            ? {
-                type: "collection",
-                name: collectionName,
-                fields: Object.entries(sample).map(([key, value]) => ({
-                    name: key,
-                    type: typeof value,
-                })),
-                indexes: indexes.map((idx) => ({
-                    name: idx.name,
-                    keys: idx.key,
-                })),
+        // Infer schema from samples
+        const inferredSchema = inferSchemaFromSamples(sampleDocuments);
+        // Get document count with timeout protection
+        let documentCount = null;
+        try {
+            // Set a timeout for the count operation
+            documentCount = await Promise.race([
+                collection.countDocuments(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Count operation timed out')), 5000))
+            ]);
+        }
+        catch (countError) {
+            console.warn(`Count operation failed or timed out for ${collectionName}: ${countError}`);
+            // Estimate count based on sample size and collection stats
+            try {
+                const stats = await db.command({ collStats: collectionName });
+                documentCount = stats.count;
+            }
+            catch {
+                documentCount = 'unknown (count operation timed out)';
             }
-            : {
-                type: "collection",
-                name: collectionName,
-                fields: [],
-                indexes: [],
-            };
+        }
+        const schema = {
+            type: "collection",
+            name: collectionName,
+            fields: inferredSchema.fields,
+            indexes: indexes.map((idx) => ({
+                name: idx.name,
+                keys: idx.key,
+            })),
+            documentCount: documentCount,
+            sampleSize: sampleDocuments.length,
+            lastUpdated: new Date().toISOString(),
+        };
         return {
             contents: [
                 {

package/build/schemas/templates.js

@@ -26,6 +26,12 @@ Example queries:
 3. Find documents with existing email:
 { "email": { "$exists": true } }
 
+4. Find documents with dates:
+// Using ISO date string format
+{ "createdAt": { "$gt": "2023-01-01T00:00:00Z" } }
+// Using ISODate syntax
+{ "createdAt": { "$gt": ISODate("2023-01-01T00:00:00Z") } }
+
 Use these patterns to construct MongoDB queries.`,
             },
         ],

package/build/schemas/tools.js

@@ -11,7 +11,10 @@ export async function handleListToolsRequest({ request, client, db, isReadOnlyMo
                             type: "string",
                             description: "Name of the collection to query",
                         },
-                        filter: { type: "object", description: "MongoDB query filter" },
+                        filter: {
+                            type: "object",
+                            description: "MongoDB query filter. Supports date strings in ISO format ('2025-01-01T00:00:00Z') and ISODate('2025-01-01T00:00:00Z') notation"
+                        },
                         projection: {
                             type: "object",
                             description: "Fields to include/exclude",
@@ -48,7 +51,7 @@ export async function handleListToolsRequest({ request, client, db, isReadOnlyMo
                         },
                         pipeline: {
                             type: "array",
-                            description: "Aggregation pipeline stages",
+                            description: "Aggregation pipeline stages. Supports date strings in ISO format ('2025-01-01T00:00:00Z') and ISODate('2025-01-01T00:00:00Z') notation",
                             items: {
                                 type: "object",
                             },
@@ -80,7 +83,7 @@ export async function handleListToolsRequest({ request, client, db, isReadOnlyMo
                         },
                         filter: {
                             type: "object",
-                            description: "Filter to select documents to update",
+                            description: "Filter to select documents to update. Supports date strings in ISO format ('2025-01-01T00:00:00Z') and ISODate('2025-01-01T00:00:00Z') notation",
                         },
                         update: {
                             type: "object",

package/build/server.js

@@ -15,7 +15,7 @@ import { handleCompletionRequest } from "./schemas/completion.js";
 export function createServer(client, db, isReadOnlyMode = false, options = {}) {
     const server = new Server({
         name: "mongodb",
-        version: "1.2.0",
+        version: "1.3.0",
         ...options,
     }, {
         capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mcp-mongo-server",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "description": "A Model Context Protocol server for MongoDB connections",
     "private": false,
     "type": "module",