mcp-mongo-server 1.0.0 → 1.1.1

package/README.md

@@ -13,6 +13,12 @@ A Model Context Protocol server that provides access to MongoDB databases. This
 
 ## Features
 
+### Read-Only Mode
+- Connect to MongoDB in read-only mode with `--read-only` or `-r` flag
+- Prevents write operations (update, insert, createIndex)
+- Uses MongoDB's secondary read preference for optimal read performance
+- Provides additional safety for production database connections
+
 ### Resources
 - List and access collections via `mongodb://` URIs
 - Each collection has a name, description and schema
@@ -97,6 +103,14 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
         "mongodb://muhammed:kilic@mongodb.localhost/namespace"
       ]
     },
+    "mongodb-readonly": {
+      "command": "node",
+      "args": [
+        "~/mcp-mongo-server/build/index.js",
+        "mongodb://muhammed:kilic@mongodb.localhost/namespace",
+        "--read-only"
+      ]
+    }
   }
 }
 ```
@@ -139,6 +153,24 @@ To use this server with the Claude Desktop app, add the following configuration
         "mcp-mongo-server",
         "mongodb://muhammed:kilic@mongodb.localhost/sample_namespace"
       ]
+    },
+    "mongodb-readonly": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-mongo-server",
+        "mongodb://muhammed:kilic@mongodb.localhost/sample_namespace",
+        "--read-only"
+      ]
+    },
+    "mongodb-github": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "github:kiliczsh/mcp-mongo-server",
+        "mongodb://muhammed:kilic@mongodb.localhost/sample_namespace",
+        "--read-only"
+      ]
     }
   }
 }
@@ -162,6 +194,21 @@ npx @michaellatman/mcp-get@latest install mcp-mongo-server
 
 Replace `/sample_namespace` with your database name.
 
+## Using Read-Only Mode
+
+You can connect to MongoDB in read-only mode by adding the `--read-only` or `-r` flag when starting the server. This is recommended when you need to protect your data from accidental writes or when connecting to production databases.
+
+```bash
+# Connect in read-only mode using the command line
+npx mcp-mongo-server mongodb://user:password@mongodb.example.com/database --read-only
+```
+
+When in read-only mode:
+1. All write operations (update, insert, createIndex) will be blocked
+2. The server connects using MongoDB's secondary read preference
+3. The connection status indicates read-only mode is active
+4. The `ping` and `serverInfo` responses include read-only status information
+
 ## License
 
 This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

package/build/index.js

@@ -10,19 +10,23 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourceTemplatesRequestSchema, PingRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { MongoClient } from "mongodb";
+import { MongoClient, ReadPreference } from "mongodb";
 /**
  * MongoDB connection client and database reference
  */
 let client = null;
 let db = null;
+/**
+ * Flag indicating whether the connection is in read-only mode
+ */
+let isReadOnlyMode = false;
 /**
  * Create an MCP server with capabilities for resources (to list/read collections),
  * tools (to query data), and prompts (to analyze collections).
  */
 const server = new Server({
     name: "mongodb",
-    version: "1.0.0",
+    version: "1.1.1",
 }, {
     capabilities: {
         resources: {},
@@ -33,11 +37,13 @@ const server = new Server({
 /**
  * Initialize MongoDB connection
  */
-async function connectToMongoDB(url) {
+async function connectToMongoDB(url, readOnly = false) {
     try {
-        client = new MongoClient(url);
+        const options = readOnly ? { readPreference: ReadPreference.SECONDARY } : {};
+        client = new MongoClient(url, options);
         await client.connect();
         db = client.db();
+        isReadOnlyMode = readOnly;
         return true;
     }
     catch (error) {
@@ -56,7 +62,9 @@ server.setRequestHandler(PingRequestSchema, async () => {
         }
         // Ping MongoDB to verify connection
         await db.command({ ping: 1 });
-        return {};
+        return {
+            readOnlyMode: isReadOnlyMode
+        };
     }
     catch (error) {
         if (error instanceof Error) {
@@ -378,6 +386,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["collection"],
                 },
             },
+            {
+                name: "listCollections",
+                description: "List all collections in the MongoDB database",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        nameOnly: {
+                            type: "boolean",
+                            description: "Optional: If true, returns only the collection names instead of full collection info"
+                        },
+                        filter: {
+                            type: "object",
+                            description: "Optional: Filter to apply to the collections"
+                        }
+                    }
+                }
+            },
         ],
     };
 });
@@ -387,6 +412,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
  */
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const collection = db.collection(request.params.arguments?.collection);
+    // Define write operations that should be blocked in read-only mode
+    const writeOperations = ['update', 'insert', 'createIndex'];
+    // Check if the operation is a write operation and we're in read-only mode
+    if (isReadOnlyMode && writeOperations.includes(request.params.name)) {
+        throw new Error(`ReadonlyError: Operation '${request.params.name}' is not allowed in read-only mode`);
+    }
     switch (request.params.name) {
         case "query": {
             const { filter, projection, limit, explain } = request.params.arguments || {};
@@ -607,6 +638,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     bits: buildInfo.bits,
                     ok: buildInfo.ok,
                     status: {},
+                    connectionInfo: {
+                        readOnlyMode: isReadOnlyMode,
+                        readPreference: isReadOnlyMode ? 'secondary' : 'primary'
+                    }
                 };
                 // Add server status information if requested
                 if (serverStatus) {
@@ -816,8 +851,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 throw new Error(`Failed to count documents in collection ${collection.collectionName}: Unknown error`);
             }
         }
+        case "listCollections": {
+            const { nameOnly, filter } = request.params.arguments || {};
+            try {
+                // Get the list of collections
+                const options = filter ? { filter } : {};
+                const collections = await db.listCollections(options).toArray();
+                // If nameOnly is true, return only the collection names
+                const result = nameOnly
+                    ? collections.map((collection) => collection.name)
+                    : collections;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    throw new Error(`Failed to list collections: ${error.message}`);
+                }
+                throw new Error("Failed to list collections: Unknown error");
+            }
+        }
         default:
-            throw new Error("Unknown tool");
+            throw new Error(`Unknown tool: ${request.params.name}`);
     }
 });
 /**
@@ -952,11 +1013,24 @@ Use these patterns to construct MongoDB queries.`,
  */
 async function main() {
     const args = process.argv.slice(2);
-    if (args.length === 0) {
+    let connectionUrl = '';
+    let readOnlyMode = false;
+    // Parse command line arguments
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--read-only' || args[i] === '-r') {
+            readOnlyMode = true;
+        }
+        else if (!connectionUrl) {
+            connectionUrl = args[i];
+        }
+    }
+    if (!connectionUrl) {
         console.error("Please provide a MongoDB connection URL as a command-line argument");
+        console.error("Usage: command <mongodb-url> [--read-only|-r]");
         process.exit(1);
     }
-    const connected = await connectToMongoDB(args[0]);
+    console.log(`Connecting to MongoDB${readOnlyMode ? ' in read-only mode' : ''}...`);
+    const connected = await connectToMongoDB(connectionUrl, readOnlyMode);
     if (!connected) {
         console.error("Failed to connect to MongoDB");
         process.exit(1);

package/build/types.js

@@ -4,11 +4,13 @@ import { CallToolRequestSchema, ToolSchema, ResourceSchema, TextResourceContents
 export const MongoCollectionSchema = ResourceSchema.extend({
     collectionName: z.string(),
     databaseName: z.string(),
-    indexes: z.array(z.object({
+    indexes: z
+        .array(z.object({
         name: z.string(),
         keys: z.record(z.union([z.number(), z.string()])),
         unique: z.optional(z.boolean()),
-    })).optional(),
+    }))
+        .optional(),
 });
 // MongoDB Document Schema
 export const MongoDocumentSchema = TextResourceContentsSchema.extend({
@@ -40,14 +42,16 @@ export const MongoSortSchema = z.record(z.union([z.literal(1), z.literal(-1)]));
 export const MongoQueryToolSchema = ToolSchema.extend({
     inputSchema: z.object({
         type: z.literal("object"),
-        properties: z.object({
+        properties: z
+            .object({
             collection: z.string(),
             filter: z.record(z.union([z.unknown(), MongoQueryOperatorSchema])),
             projection: z.record(z.union([z.literal(0), z.literal(1)])).optional(),
             sort: MongoSortSchema.optional(),
             limit: z.number().int().positive().optional(),
             skip: z.number().int().nonnegative().optional(),
-        }).passthrough(),
+        })
+            .passthrough(),
         required: z.array(z.literal("collection")),
     }),
 });
@@ -55,10 +59,12 @@ export const MongoQueryToolSchema = ToolSchema.extend({
 export const MongoAggregateToolSchema = ToolSchema.extend({
     inputSchema: z.object({
         type: z.literal("object"),
-        properties: z.object({
+        properties: z
+            .object({
             collection: z.string(),
             pipeline: z.array(z.record(z.unknown())),
-        }).passthrough(),
+        })
+            .passthrough(),
         required: z.array(z.literal("collection")),
     }),
 });
@@ -66,10 +72,14 @@ export const MongoAggregateToolSchema = ToolSchema.extend({
 export const MongoCountToolSchema = ToolSchema.extend({
     inputSchema: z.object({
         type: z.literal("object"),
-        properties: z.object({
+        properties: z
+            .object({
             collection: z.string(),
-            filter: z.record(z.union([z.unknown(), MongoQueryOperatorSchema])).optional(),
-        }).passthrough(),
+            filter: z
+                .record(z.union([z.unknown(), MongoQueryOperatorSchema]))
+                .optional(),
+        })
+            .passthrough(),
         required: z.array(z.literal("collection")),
     }),
 });
@@ -77,18 +87,32 @@ export const MongoCountToolSchema = ToolSchema.extend({
 export const MongoDistinctToolSchema = ToolSchema.extend({
     inputSchema: z.object({
         type: z.literal("object"),
-        properties: z.object({
+        properties: z
+            .object({
             collection: z.string(),
             field: z.string(),
-            filter: z.record(z.union([z.unknown(), MongoQueryOperatorSchema])).optional(),
-        }).passthrough(),
+            filter: z
+                .record(z.union([z.unknown(), MongoQueryOperatorSchema]))
+                .optional(),
+        })
+            .passthrough(),
         required: z.array(z.literal("collection")),
     }),
 });
 // MongoDB Call Tool Request Schema
 export const MongoCallToolRequestSchema = CallToolRequestSchema.extend({
     params: z.object({
-        name: z.enum(["query", "aggregate", "count", "distinct"]),
+        name: z.enum([
+            "query",
+            "aggregate",
+            "update",
+            "serverInfo",
+            "insert",
+            "createIndex",
+            "count",
+            "distinct",
+            "listCollections",
+        ]),
         arguments: z.union([
             MongoQueryToolSchema.shape.inputSchema,
             MongoAggregateToolSchema.shape.inputSchema,
@@ -136,8 +160,10 @@ export const MongoFieldSchemaSchema = z.object({
 export const MongoCollectionSchemaSchema = z.object({
     name: z.string(),
     fields: z.record(MongoFieldSchemaSchema),
-    options: z.object({
+    options: z
+        .object({
         timestamps: z.boolean().optional(),
         strict: z.boolean().optional(),
-    }).optional(),
+    })
+        .optional(),
 });

package/package.json

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