mcp-mongo-server 1.1.2 → 1.3.0

package/build/schemas/tools.js

@@ -0,0 +1,281 @@
+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. 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",
+                        },
+                        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. Supports date strings in ISO format ('2025-01-01T00:00:00Z') and ISODate('2025-01-01T00:00:00Z') notation",
+                            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. Supports date strings in ISO format ('2025-01-01T00:00:00Z') and ISODate('2025-01-01T00:00:00Z') notation",
+                        },
+                        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.3.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.2",
+    "version": "1.3.0",
     "description": "A Model Context Protocol server for MongoDB connections",
     "private": false,
     "type": "module",

package/build/types.js

@@ -1,169 +0,0 @@
-import { z } from "zod";
-import { CallToolRequestSchema, ToolSchema, ResourceSchema, TextResourceContentsSchema, } from "@modelcontextprotocol/sdk/types.js";
-// MongoDB Collection Schema
-export const MongoCollectionSchema = ResourceSchema.extend({
-    collectionName: z.string(),
-    databaseName: z.string(),
-    indexes: z
-        .array(z.object({
-        name: z.string(),
-        keys: z.record(z.union([z.number(), z.string()])),
-        unique: z.optional(z.boolean()),
-    }))
-        .optional(),
-});
-// MongoDB Document Schema
-export const MongoDocumentSchema = TextResourceContentsSchema.extend({
-    document: z.record(z.unknown()),
-});
-// MongoDB Query Operators
-export const MongoQueryOperatorSchema = z.object({
-    $eq: z.unknown().optional(),
-    $gt: z.unknown().optional(),
-    $gte: z.unknown().optional(),
-    $in: z.array(z.unknown()).optional(),
-    $lt: z.unknown().optional(),
-    $lte: z.unknown().optional(),
-    $ne: z.unknown().optional(),
-    $nin: z.array(z.unknown()).optional(),
-    $and: z.array(z.unknown()).optional(),
-    $not: z.unknown().optional(),
-    $nor: z.array(z.unknown()).optional(),
-    $or: z.array(z.unknown()).optional(),
-    $exists: z.boolean().optional(),
-    $type: z.union([z.string(), z.number()]).optional(),
-    $expr: z.unknown().optional(),
-    $regex: z.string().optional(),
-    $options: z.string().optional(),
-});
-// MongoDB Sort Options
-export const MongoSortSchema = z.record(z.union([z.literal(1), z.literal(-1)]));
-// MongoDB Query Tool Schema
-export const MongoQueryToolSchema = ToolSchema.extend({
-    inputSchema: z.object({
-        type: z.literal("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(),
-        required: z.array(z.literal("collection")),
-    }),
-});
-// MongoDB Aggregate Tool Schema
-export const MongoAggregateToolSchema = ToolSchema.extend({
-    inputSchema: z.object({
-        type: z.literal("object"),
-        properties: z
-            .object({
-            collection: z.string(),
-            pipeline: z.array(z.record(z.unknown())),
-        })
-            .passthrough(),
-        required: z.array(z.literal("collection")),
-    }),
-});
-// MongoDB Count Tool Schema
-export const MongoCountToolSchema = ToolSchema.extend({
-    inputSchema: z.object({
-        type: z.literal("object"),
-        properties: z
-            .object({
-            collection: z.string(),
-            filter: z
-                .record(z.union([z.unknown(), MongoQueryOperatorSchema]))
-                .optional(),
-        })
-            .passthrough(),
-        required: z.array(z.literal("collection")),
-    }),
-});
-// MongoDB Distinct Tool Schema
-export const MongoDistinctToolSchema = ToolSchema.extend({
-    inputSchema: z.object({
-        type: z.literal("object"),
-        properties: z
-            .object({
-            collection: z.string(),
-            field: z.string(),
-            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",
-            "update",
-            "serverInfo",
-            "insert",
-            "createIndex",
-            "count",
-            "distinct",
-            "listCollections",
-        ]),
-        arguments: z.union([
-            MongoQueryToolSchema.shape.inputSchema,
-            MongoAggregateToolSchema.shape.inputSchema,
-            MongoCountToolSchema.shape.inputSchema,
-            MongoDistinctToolSchema.shape.inputSchema,
-        ]),
-    }),
-});
-// MongoDB Error Types
-export const MongoErrorCodeSchema = z.enum([
-    "INVALID_QUERY",
-    "COLLECTION_NOT_FOUND",
-    "DATABASE_NOT_FOUND",
-    "INVALID_PIPELINE",
-    "INVALID_PROJECTION",
-    "INVALID_SORT",
-    "CONNECTION_ERROR",
-    "TIMEOUT",
-    "UNAUTHORIZED",
-]);
-export const MongoErrorSchema = z.object({
-    code: MongoErrorCodeSchema,
-    message: z.string(),
-    details: z.unknown().optional(),
-});
-// MongoDB Schema Inference Types
-export const MongoFieldSchemaSchema = z.object({
-    type: z.union([
-        z.literal("string"),
-        z.literal("number"),
-        z.literal("boolean"),
-        z.literal("date"),
-        z.literal("objectId"),
-        z.literal("array"),
-        z.literal("object"),
-        z.literal("null"),
-        z.literal("mixed"),
-    ]),
-    required: z.boolean().optional(),
-    unique: z.boolean().optional(),
-    indexed: z.boolean().optional(),
-    items: z.lazy(() => MongoFieldSchemaSchema).optional(),
-    properties: z.record(z.lazy(() => MongoFieldSchemaSchema)).optional(),
-});
-export const MongoCollectionSchemaSchema = z.object({
-    name: z.string(),
-    fields: z.record(MongoFieldSchemaSchema),
-    options: z
-        .object({
-        timestamps: z.boolean().optional(),
-        strict: z.boolean().optional(),
-    })
-        .optional(),
-});