mcp-mongo-server 1.1.2 → 1.3.0

package/build/schemas/completion.js

@@ -0,0 +1,112 @@
+/**
+ * Handles completion requests from the Model Context Protocol
+ * @param options The request options
+ * @returns Completion result with matching values
+ */
+export async function handleCompletionRequest({ request, client, db, isReadOnlyMode, }) {
+    const { ref, argument } = request.params;
+    // Handle completions for prompts
+    if (ref.type === "ref/prompt") {
+        return handlePromptCompletion(client, db, isReadOnlyMode, ref.name, argument);
+    }
+    // Handle completions for resources
+    if (ref.type === "ref/resource") {
+        return handleResourceCompletion(client, db, isReadOnlyMode, ref.uri, argument);
+    }
+    // Default empty response if reference type is not supported
+    return emptyCompletionResult();
+}
+/**
+ * Handle completion requests for prompts
+ * @param client MongoDB client
+ * @param db MongoDB database
+ * @param isReadOnlyMode Whether the database is in read-only mode
+ * @param promptName Name of the prompt
+ * @param argument Argument being completed
+ * @returns Completion result
+ */
+async function handlePromptCompletion(client, db, isReadOnlyMode, promptName, argument) {
+    if (!promptName) {
+        return emptyCompletionResult();
+    }
+    // Handle collection name completions
+    if (argument.name === "collection") {
+        return await completeCollectionNames(argument.value, db, isReadOnlyMode);
+    }
+    // Add other prompt completions here as needed
+    return emptyCompletionResult();
+}
+/**
+ * Handle completion requests for resources
+ * @param client MongoDB client
+ * @param db MongoDB database
+ * @param isReadOnlyMode Whether the database is in read-only mode
+ * @param uri Resource URI
+ * @param argument Argument being completed
+ * @returns Completion result
+ */
+async function handleResourceCompletion(client, db, isReadOnlyMode, promptName, argument) {
+    if (!promptName) {
+        return emptyCompletionResult();
+    }
+    // Handle collection name completions
+    if (argument.name === "collection") {
+        return await completeCollectionNames(argument.value, db, isReadOnlyMode);
+    }
+    // Add other prompt completions here as needed
+    return emptyCompletionResult();
+}
+/**
+ * Get collection name completions for a partial value
+ * @param partialValue Partial collection name
+ * @param db MongoDB database
+ * @param isReadOnlyMode Whether the database is in read-only mode
+ * @returns Completion result with matching collection names
+ */
+async function completeCollectionNames(partialValue, db, isReadOnlyMode) {
+    try {
+        console.warn(`Completing collection names with partial value: ${partialValue}`);
+        // Get list of collections
+        const collections = await db.listCollections().toArray();
+        // Filter collections by partial value (case insensitive)
+        const matchingCollections = collections
+            .map((c) => c.name)
+            .filter((name) => 
+        // Filter out system collections
+        !name.startsWith("system.") &&
+            // Match partial value
+            name.toLowerCase().includes(partialValue.toLowerCase()))
+            // Sort alphabetically
+            .sort();
+        console.warn(`Found ${matchingCollections.length} matching collections`);
+        // Limit to 100 items as per spec
+        const MAX_ITEMS = 100;
+        const limitedResults = matchingCollections.slice(0, MAX_ITEMS);
+        const hasMore = matchingCollections.length > MAX_ITEMS;
+        return {
+            completion: {
+                values: limitedResults,
+                total: matchingCollections.length,
+                hasMore,
+            },
+        };
+    }
+    catch (error) {
+        console.error("Error completing collection names:", error);
+        // Return empty result on error
+        return emptyCompletionResult();
+    }
+}
+/**
+ * Create an empty completion result
+ * @returns Empty completion result object
+ */
+function emptyCompletionResult() {
+    return {
+        completion: {
+            values: [],
+            total: 0,
+            hasMore: false,
+        },
+    };
+}

package/build/schemas/ping.js

@@ -0,0 +1,20 @@
+export async function handlePingRequest({ request, client, db, isReadOnlyMode, }) {
+    try {
+        // Check MongoDB connection
+        if (!client) {
+            throw new Error("MongoDB connection is not available");
+        }
+        // Ping MongoDB to verify connection
+        const pong = await db.command({ ping: 1 });
+        if (pong.ok !== 1) {
+            throw new Error(`MongoDB ping failed: ${pong.errmsg}`);
+        }
+        return {};
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`MongoDB ping failed: ${error.message}`);
+        }
+        throw new Error("MongoDB ping failed: Unknown error");
+    }
+}

package/build/schemas/prompts.js

@@ -0,0 +1,71 @@
+export async function handleListPromptsRequest({ request, client, db, isReadOnlyMode, }) {
+    return {
+        prompts: [
+            {
+                name: "analyze_collection",
+                description: "Analyze a MongoDB collection structure and contents",
+                arguments: [
+                    {
+                        name: "collection",
+                        description: "Name of the collection to analyze",
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    };
+}
+export async function handleGetPromptRequest({ request, client, db, isReadOnlyMode, }) {
+    const { name, arguments: args = {} } = request.params;
+    if (name !== "analyze_collection") {
+        throw new Error("Unknown prompt");
+    }
+    const collectionName = args.collection;
+    if (!collectionName) {
+        throw new Error("Collection name is required");
+    }
+    try {
+        const collection = db.collection(collectionName);
+        if (collection.collectionName.startsWith("system.")) {
+            throw new Error("Access to system collections is not allowed");
+        }
+        const schemaSample = await collection.findOne({});
+        const stats = await collection
+            .aggregate([{ $collStats: { count: {} } }])
+            .toArray();
+        const sampleDocs = await collection.find({}).limit(5).toArray();
+        const documentCount = stats[0]?.count ?? "unknown";
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Please analyze the following MongoDB collection:
+Collection: ${collectionName}
+
+Schema:
+${JSON.stringify(schemaSample, null, 2)}
+
+Stats:
+Document count: ${documentCount}
+
+Sample documents:
+${JSON.stringify(sampleDocs, null, 2)}`,
+                    },
+                },
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: "Provide insights about the collection's structure, data types, and basic statistics.",
+                    },
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : "Unknown error";
+        throw new Error(`Failed to analyze collection ${collectionName}: ${msg}`);
+    }
+}

package/build/schemas/resource.js

@@ -0,0 +1,213 @@
+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);
+        // 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();
+        // 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)';
+            }
+        }
+        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: [
+                {
+                    uri: request.params.uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify(schema, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to read collection ${collectionName}: ${error.message}`);
+        }
+        throw new Error(`Failed to read collection ${collectionName}: Unknown error`);
+    }
+}
+export async function handleListResourcesRequest({ request, client, db, isReadOnlyMode, }) {
+    try {
+        const collections = await db.listCollections().toArray();
+        return {
+            resources: collections.map((collection) => ({
+                uri: `mongodb:///${collection.name}`,
+                mimeType: "application/json",
+                name: collection.name,
+                description: `MongoDB collection: ${collection.name}`,
+            })),
+        };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to list collections: ${error.message}`);
+        }
+        throw new Error("Failed to list collections: Unknown error");
+    }
+}

package/build/schemas/templates.js

@@ -0,0 +1,39 @@
+export async function handleListResourceTemplatesRequest({ request, client, db, isReadOnlyMode, }) {
+    return {
+        resourceTemplates: [
+            {
+                name: "mongodb_query",
+                description: "Template for constructing MongoDB queries",
+                uriTemplate: "mongodb:///{collection}",
+                text: `To query MongoDB collections, you can use these operators:
+
+Filter operators:
+- $eq: Matches values equal to a specified value
+- $gt/$gte: Matches values greater than (or equal to) a specified value
+- $lt/$lte: Matches values less than (or equal to) a specified value
+- $in: Matches any of the values in an array
+- $nin: Matches none of the values in an array
+- $ne: Matches values not equal to a specified value
+- $exists: Matches documents that have the specified field
+
+Example queries:
+1. Find documents where age > 21:
+{ "age": { "$gt": 21 } }
+
+2. Find documents with specific status:
+{ "status": { "$in": ["active", "pending"] } }
+
+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.`,
+            },
+        ],
+    };
+}