mcp-mongo-server 0.1.1

package/README.md

@@ -0,0 +1,123 @@
+# MCP MongoDB Server
+---
+![NPM Version](https://img.shields.io/npm/v/mcp-mongo-server)
+![NPM Downloads](https://img.shields.io/npm/dm/mcp-mongo-server)
+![NPM License](https://img.shields.io/npm/l/mcp-mongo-server)
+
+A Model Context Protocol server that provides access to MongoDB databases. This server enables LLMs to inspect collection schemas and execute read-only queries.
+
+## Features
+
+### Resources
+- List and access collections via `mongodb://` URIs
+- Each collection has a name, description and schema
+- JSON mime type for schema access
+
+### Tools
+- **query**
+  - Execute read-only MongoDB queries against the connected database
+  - Input: `query` (object): The MongoDB query to execute
+  - All queries are executed with read-only permissions
+
+- **aggregate**
+  - Execute read-only MongoDB queries against the connected database
+  - Input: `aggregate` (object): The MongoDB query to execute
+  - All queries are executed with read-only permissions
+
+### Prompts
+- `query` - Provide insights about the collection's structure, data types, and basic statistics
+  - Input: `collection` (string): The name of the collection to analyze
+  - Output: `text` (string): A summary of the collection's structure, data types, and basic statistics
+- `aggregate` - Provide insights about the collection's structure, data types, and basic statistics
+  - Input: `collection` (string): The name of the collection to analyze
+  - Output: `text` (string): A summary of the collection's structure, data types, and basic statistics
+
+
+
+## Development
+
+Install dependencies:
+```bash
+npm install
+```
+
+Build the server:
+```bash
+npm run build
+```
+
+For development with auto-rebuild:
+```bash
+npm run watch
+```
+
+## Installation
+
+To use with Claude Desktop, add the server config:
+
+On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "mongodb": {
+      "command": "node",
+      "args": [
+        "~/mcp-mongo-server/build/index.js",
+        "mongodb://muhammed:kilic@mongodb.localhost/namespace"
+      ]
+    },
+  }
+}
+```
+
+
+### Debugging
+
+Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
+
+```bash
+npm run inspector
+```
+
+The Inspector will provide a URL to access debugging tools in your browser.
+
+## Components
+
+
+### Resources
+
+The server provides schema information for each collection in the database:
+
+- **Collection Schemas** (`mongodb://<host>/<collection>/schema`)
+  - JSON schema information for each collection
+  - Includes field names and data types
+  - Automatically inferred from collection documents
+
+
+## Usage with Claude Desktop
+
+To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mongodb": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-mongo-server",
+        "mongodb://muhammed:kilic@mongodb.localhost/sample_namespace"
+      ]
+    }
+  }
+}
+```
+
+Replace `/sample_namespace` with your database name.
+
+## 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

@@ -0,0 +1,420 @@
+#!/usr/bin/env node
+/**
+ * This is an MCP server that implements a MongoDB interface.
+ * It demonstrates core MCP concepts by allowing:
+ * - Listing collections as resources
+ * - Reading collection schemas and contents
+ * - Executing MongoDB queries via tools
+ * - Providing collection summaries via prompts
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourceTemplatesRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { MongoClient, ServerApiVersion } from "mongodb";
+/**
+ * MongoDB connection client and database reference
+ */
+let client = null;
+let db = null;
+/**
+ * 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: "0.1.0",
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+        prompts: {},
+    },
+});
+/**
+ * Initialize MongoDB connection
+ */
+async function connectToMongoDB(url) {
+    try {
+        client = new MongoClient(url, {
+            serverApi: {
+                version: ServerApiVersion.v1,
+                strict: true,
+                deprecationErrors: true,
+            },
+        });
+        await client.connect();
+        db = client.db();
+        return true;
+    }
+    catch (error) {
+        console.error("Failed to connect to MongoDB:", error);
+        return false;
+    }
+}
+/**
+ * Handler for listing available collections as resources.
+ * Each collection is exposed as a resource with:
+ * - A mongodb:// URI scheme
+ * - JSON MIME type
+ * - Collection name and description
+ */
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    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');
+    }
+});
+/**
+ * Handler for reading a collection's schema or contents.
+ * Takes a mongodb:// URI and returns the collection info as JSON.
+ */
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    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();
+        // Infer schema from sample document
+        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`);
+    }
+});
+/**
+ * Handler that lists available tools.
+ * Exposes MongoDB query tools for interacting with collections.
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "query",
+                description: "Execute a MongoDB query",
+                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"
+                        }
+                    },
+                    required: ["collection"]
+                }
+            },
+            {
+                name: "aggregate",
+                description: "Execute a MongoDB aggregation pipeline",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        collection: {
+                            type: "string",
+                            description: "Name of the collection to aggregate"
+                        },
+                        pipeline: {
+                            type: "array",
+                            description: "Aggregation pipeline stages"
+                        }
+                    },
+                    required: ["collection", "pipeline"]
+                }
+            }
+        ]
+    };
+});
+/**
+ * Handler for MongoDB tools.
+ * Executes queries and returns results.
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const collection = db.collection(request.params.arguments?.collection);
+    switch (request.params.name) {
+        case "query": {
+            const { filter, projection, limit } = request.params.arguments || {};
+            // Validate collection name to prevent access to system collections
+            if (collection.collectionName.startsWith('system.')) {
+                throw new Error('Access to system collections is not allowed');
+            }
+            // Validate and parse filter
+            let queryFilter = {};
+            if (filter) {
+                if (typeof filter === 'string') {
+                    try {
+                        queryFilter = JSON.parse(filter);
+                    }
+                    catch (e) {
+                        throw new Error('Invalid filter format: must be a valid JSON object');
+                    }
+                }
+                else if (typeof filter === 'object' && filter !== null && !Array.isArray(filter)) {
+                    queryFilter = filter;
+                }
+                else {
+                    throw new Error('Query filter must be a plain object or ObjectId');
+                }
+            }
+            // Execute the find operation with error handling
+            try {
+                const cursor = collection.find(queryFilter, {
+                    projection,
+                    limit: limit || 100
+                });
+                const results = await cursor.toArray();
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(results, null, 2)
+                        }]
+                };
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    throw new Error(`Failed to query collection ${collection.collectionName}: ${error.message}`);
+                }
+                throw new Error(`Failed to query collection ${collection.collectionName}: Unknown error`);
+            }
+        }
+        case "aggregate": {
+            const { pipeline } = request.params.arguments || {};
+            if (!Array.isArray(pipeline)) {
+                throw new Error("Pipeline must be an array");
+            }
+            // Validate collection name to prevent access to system collections
+            if (collection.collectionName.startsWith('system.')) {
+                throw new Error('Access to system collections is not allowed');
+            }
+            // Execute the aggregation operation with error handling
+            try {
+                const results = await collection.aggregate(pipeline).toArray();
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify(results, null, 2)
+                        }]
+                };
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    throw new Error(`Failed to aggregate collection ${collection.collectionName}: ${error.message}`);
+                }
+                throw new Error(`Failed to aggregate collection ${collection.collectionName}: Unknown error`);
+            }
+        }
+        default:
+            throw new Error("Unknown tool");
+    }
+});
+/**
+ * Handler that lists available prompts.
+ * Exposes prompts for analyzing collections.
+ */
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    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
+                    }
+                ]
+            }
+        ]
+    };
+});
+/**
+ * Handler for collection analysis prompt.
+ * Returns a prompt that requests analysis of a collection's structure and data.
+ */
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "analyze_collection") {
+        throw new Error("Unknown prompt");
+    }
+    const collectionName = request.params.arguments?.collection;
+    if (!collectionName) {
+        throw new Error("Collection name is required");
+    }
+    try {
+        const collection = db.collection(collectionName);
+        // Validate collection name to prevent access to system collections
+        if (collection.collectionName.startsWith('system.')) {
+            throw new Error('Access to system collections is not allowed');
+        }
+        const schema = await collection.findOne({});
+        // Get basic collection stats - just count in API v1
+        const stats = await collection.aggregate([
+            {
+                $collStats: {
+                    count: {}
+                }
+            }
+        ]).toArray();
+        // Also get a sample of documents to show data distribution
+        const sampleDocs = await collection.find({})
+            .limit(5)
+            .toArray();
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Please analyze the following MongoDB collection:
+Collection: ${collectionName}
+
+Schema:
+${JSON.stringify(schema, null, 2)}
+
+Stats:
+Document count: ${stats[0]?.count || 'unknown'}
+
+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) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to analyze collection ${collectionName}: ${error.message}`);
+        }
+        else {
+            throw new Error(`Failed to analyze collection ${collectionName}: Unknown error`);
+        }
+    }
+});
+/**
+ * Handler for listing templates.
+ * Exposes templates for constructing MongoDB queries.
+ */
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+    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.`
+            }
+        ]
+    };
+});
+/**
+ * Start the server using stdio transport and initialize MongoDB connection.
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.error("Please provide a MongoDB connection URL as a command-line argument");
+        process.exit(1);
+    }
+    const connected = await connectToMongoDB(args[0]);
+    if (!connected) {
+        console.error("Failed to connect to MongoDB");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// Handle cleanup
+process.on("SIGINT", async () => {
+    if (client) {
+        await client.close();
+    }
+    process.exit(0);
+});
+process.on("SIGTERM", async () => {
+    if (client) {
+        await client.close();
+    }
+    process.exit(0);
+});
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/build/types.js

@@ -0,0 +1,143 @@
+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", "count", "distinct"]),
+        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(),
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "mcp-mongo-server",
+  "version": "0.1.1",
+  "description": "A Model Context Protocol server for MongoDB connections",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "mongodb": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "0.6.0",
+    "@types/mongodb": "^4.0.6",
+    "mongodb": "^6.11.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude",
+    "claude-desktop",
+    "mcp",
+    "mongo",
+    "mongodb",
+    "model-context-protocol",
+    "llm",
+    "mcp-server",
+    "mcp-protocol",
+    "mcp-connector",
+    "mcp-connector-mongodb"
+  ],
+  "author": "Muhammed Kilic <kiliczsh>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kiliczsh/mcp-mongo-server"
+  },
+  "homepage": "https://github.com/kiliczsh/mcp-mongo-server"
+}