mcp-mongo-server 1.1.1 → 1.2.0

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,62 @@
+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({});
+        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,
+                })),
+            }
+            : {
+                type: "collection",
+                name: collectionName,
+                fields: [],
+                indexes: [],
+            };
+        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,33 @@
+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 } }
+
+Use these patterns to construct MongoDB queries.`,
+            },
+        ],
+    };
+}

package/build/schemas/tools.js

@@ -0,0 +1,278 @@
+export async function handleListToolsRequest({ request, client, db, isReadOnlyMode, }) {
+    return {
+        tools: [
+            {
+                name: "query",
+                description: "Execute a MongoDB query with optional execution plan analysis",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        collection: {
+                            type: "string",
+                            description: "Name of the collection to query",
+                        },
+                        filter: { type: "object", description: "MongoDB query filter" },
+                        projection: {
+                            type: "object",
+                            description: "Fields to include/exclude",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of documents to return",
+                            default: 10,
+                        },
+                        explain: {
+                            type: "string",
+                            description: "Optional: Get query execution information",
+                            enum: ["queryPlanner", "executionStats", "allPlansExecution"],
+                        },
+                        objectIdMode: {
+                            type: "string",
+                            description: "Control how 24-character hex strings are handled",
+                            enum: ["auto", "none", "force"],
+                            default: "auto",
+                        },
+                    },
+                    required: ["collection"],
+                },
+            },
+            {
+                name: "aggregate",
+                description: "Execute a MongoDB aggregation pipeline with optional execution plan analysis",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        collection: {
+                            type: "string",
+                            description: "Name of the collection to aggregate",
+                        },
+                        pipeline: {
+                            type: "array",
+                            description: "Aggregation pipeline stages",
+                            items: {
+                                type: "object",
+                            },
+                        },
+                        explain: {
+                            type: "string",
+                            description: "Optional: Get aggregation execution information (queryPlanner, executionStats, or allPlansExecution)",
+                            enum: ["queryPlanner", "executionStats", "allPlansExecution"],
+                        },
+                        objectIdMode: {
+                            type: "string",
+                            description: "Control how 24-character hex strings are handled",
+                            enum: ["auto", "none", "force"],
+                            default: "auto",
+                        },
+                    },
+                    required: ["collection", "pipeline"],
+                },
+            },
+            {
+                name: "update",
+                description: "Update documents in a MongoDB collection",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        collection: {
+                            type: "string",
+                            description: "Name of the collection to update",
+                        },
+                        filter: {
+                            type: "object",
+                            description: "Filter to select documents to update",
+                        },
+                        update: {
+                            type: "object",
+                            description: "Update operations to apply ($set, $unset, $inc, etc.)",
+                        },
+                        upsert: {
+                            type: "boolean",
+                            description: "Create a new document if no documents match the filter",
+                        },
+                        multi: {
+                            type: "boolean",
+                            description: "Update multiple documents that match the filter",
+                        },
+                        objectIdMode: {
+                            type: "string",
+                            description: "Control how 24-character hex strings are handled",
+                            enum: ["auto", "none", "force"],
+                            default: "auto",
+                        },
+                    },
+                    required: ["collection", "filter", "update"],
+                },
+            },
+            {
+                name: "serverInfo",
+                description: "Get MongoDB server information including version, storage engine, and other details",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        includeDebugInfo: {
+                            type: "boolean",
+                            description: "Include additional debug information about the server",
+                        },
+                    },
+                },
+            },
+            {
+                name: "insert",
+                description: "Insert one or more documents into a MongoDB collection",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        collection: {
+                            type: "string",
+                            description: "Name of the collection to insert into",
+                        },
+                        documents: {
+                            type: "array",
+                            description: "Array of documents to insert",
+                            items: { type: "object" },
+                        },
+                        ordered: {
+                            type: "boolean",
+                            description: "If true, perform ordered insert. If false, insert unordered",
+                        },
+                        writeConcern: {
+                            type: "object",
+                            description: "Write concern for the insert operation",
+                        },
+                        bypassDocumentValidation: {
+                            type: "boolean",
+                            description: "Allow insert to bypass schema validation",
+                        },
+                        objectIdMode: {
+                            type: "string",
+                            description: "Control how 24-character hex strings are handled",
+                            enum: ["auto", "none", "force"],
+                            default: "auto",
+                        },
+                    },
+                    required: ["collection", "documents"],
+                },
+            },
+            {
+                name: "createIndex",
+                description: "Create one or more indexes on a MongoDB collection",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        collection: {
+                            type: "string",
+                            description: "Name of the collection to create indexes on",
+                        },
+                        indexes: {
+                            type: "array",
+                            description: "Array of index specifications",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    key: {
+                                        type: "object",
+                                        description: "Index key pattern, e.g. { field: 1 }",
+                                    },
+                                    name: {
+                                        type: "string",
+                                        description: "Optional: Name of the index",
+                                    },
+                                    unique: {
+                                        type: "boolean",
+                                        description: "Optional: Creates a unique index",
+                                    },
+                                    sparse: {
+                                        type: "boolean",
+                                        description: "Optional: Creates a sparse index",
+                                    },
+                                    background: {
+                                        type: "boolean",
+                                        description: "Optional: Builds index in background",
+                                    },
+                                    expireAfterSeconds: {
+                                        type: "number",
+                                        description: "TTL in seconds for documents",
+                                    },
+                                    partialFilterExpression: {
+                                        type: "object",
+                                        description: "Filter expression for partial indexes",
+                                    },
+                                },
+                                required: ["key"],
+                            },
+                        },
+                        writeConcern: {
+                            type: "object",
+                            description: "Write concern for index creation",
+                        },
+                        commitQuorum: {
+                            type: "string",
+                            description: "Number of members required to create the index",
+                        },
+                        objectIdMode: {
+                            type: "string",
+                            description: "Control how 24-character hex strings are handled",
+                            enum: ["auto", "none", "force"],
+                            default: "auto",
+                        },
+                    },
+                    required: ["collection", "indexes"],
+                },
+            },
+            {
+                name: "count",
+                description: "Count documents in a collection matching a query",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        collection: { type: "string", description: "Collection name" },
+                        query: { type: "object", description: "Query filter to count" },
+                        limit: { type: "integer", description: "Max documents to count" },
+                        skip: {
+                            type: "integer",
+                            description: "Docs to skip before counting",
+                        },
+                        hint: { type: "object", description: "Index hint" },
+                        readConcern: { type: "object", description: "Read concern option" },
+                        maxTimeMS: { type: "integer", description: "Max execution time" },
+                        collation: {
+                            type: "object",
+                            description: "Collation rules for comparison",
+                        },
+                        objectIdMode: {
+                            type: "string",
+                            description: "Control how 24-character hex strings are handled",
+                            enum: ["auto", "none", "force"],
+                            default: "auto",
+                        },
+                    },
+                    required: ["collection"],
+                },
+            },
+            {
+                name: "listCollections",
+                description: "List all collections in the MongoDB database",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        nameOnly: {
+                            type: "boolean",
+                            description: "If true, return only collection names",
+                        },
+                        filter: {
+                            type: "object",
+                            description: "Filter for collections",
+                        },
+                        objectIdMode: {
+                            type: "string",
+                            description: "Control how 24-character hex strings are handled",
+                            enum: ["auto", "none", "force"],
+                            default: "auto",
+                        },
+                    },
+                },
+            },
+        ],
+    };
+}

package/build/server.js

@@ -0,0 +1,65 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourceTemplatesRequestSchema, PingRequestSchema, CompleteRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { handleReadResourceRequest, handleListResourcesRequest, } from "./schemas/resource.js";
+import { handlePingRequest } from "./schemas/ping.js";
+import { handleListToolsRequest } from "./schemas/tools.js";
+import { handleListPromptsRequest } from "./schemas/prompts.js";
+import { handleCallToolRequest } from "./schemas/call.js";
+import { handleListResourceTemplatesRequest } from "./schemas/templates.js";
+import { handleGetPromptRequest } from "./schemas/prompts.js";
+import { handleCompletionRequest } from "./schemas/completion.js";
+/**
+ * Create an MCP server with capabilities for resources (to list/read collections),
+ * tools (to query data), and prompts (to analyze collections).
+ */
+export function createServer(client, db, isReadOnlyMode = false, options = {}) {
+    const server = new Server({
+        name: "mongodb",
+        version: "1.2.0",
+        ...options,
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+            prompts: {},
+        },
+        ...options,
+    });
+    /**
+     * Handler for ping requests to check server health
+     */
+    server.setRequestHandler(PingRequestSchema, (request) => handlePingRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler for listing available collections as resources.
+     */
+    server.setRequestHandler(ListResourcesRequestSchema, (request) => handleListResourcesRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler for reading a collection's schema or contents.
+     */
+    server.setRequestHandler(ReadResourceRequestSchema, (request) => handleReadResourceRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler that lists available tools.
+     */
+    server.setRequestHandler(ListToolsRequestSchema, (request) => handleListToolsRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler for MongoDB tools.
+     */
+    server.setRequestHandler(CallToolRequestSchema, (request) => handleCallToolRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler that lists available prompts.
+     */
+    server.setRequestHandler(ListPromptsRequestSchema, (request) => handleListPromptsRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler for collection analysis prompt.
+     */
+    server.setRequestHandler(GetPromptRequestSchema, (request) => handleGetPromptRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler for listing templates.
+     */
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, (request) => handleListResourceTemplatesRequest({ request, client, db, isReadOnlyMode }));
+    /**
+     * Handler for completion requests.
+     */
+    server.setRequestHandler(CompleteRequestSchema, (request) => handleCompletionRequest({ request, client, db, isReadOnlyMode }));
+    return server;
+}

package/package.json

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