# Directory Structure
```
├── .gitignore
├── index.ts
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Logs
2 | logs
3 | *.log
4 | npm-debug.log*
5 | yarn-debug.log*
6 | yarn-error.log*
7 | lerna-debug.log*
8 | .pnpm-debug.log*
9 |
10 | # Diagnostic reports (https://nodejs.org/api/report.html)
11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
12 |
13 | # Runtime data
14 | pids
15 | *.pid
16 | *.seed
17 | *.pid.lock
18 |
19 | # Directory for instrumented libs generated by jscoverage/JSCover
20 | lib-cov
21 |
22 | # Coverage directory used by tools like istanbul
23 | coverage
24 | *.lcov
25 |
26 | # nyc test coverage
27 | .nyc_output
28 |
29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
30 | .grunt
31 |
32 | # Bower dependency directory (https://bower.io/)
33 | bower_components
34 |
35 | # node-waf configuration
36 | .lock-wscript
37 |
38 | # Compiled binary addons (https://nodejs.org/api/addons.html)
39 | build/Release
40 |
41 | # Dependency directories
42 | node_modules/
43 | jspm_packages/
44 |
45 | # Snowpack dependency directory (https://snowpack.dev/)
46 | web_modules/
47 |
48 | # TypeScript cache
49 | *.tsbuildinfo
50 |
51 | # Optional npm cache directory
52 | .npm
53 |
54 | # Optional eslint cache
55 | .eslintcache
56 |
57 | # Optional stylelint cache
58 | .stylelintcache
59 |
60 | # Microbundle cache
61 | .rpt2_cache/
62 | .rts2_cache_cjs/
63 | .rts2_cache_es/
64 | .rts2_cache_umd/
65 |
66 | # Optional REPL history
67 | .node_repl_history
68 |
69 | # Output of 'npm pack'
70 | *.tgz
71 |
72 | # Yarn Integrity file
73 | .yarn-integrity
74 |
75 | # dotenv environment variable files
76 | .env
77 | .env.development.local
78 | .env.test.local
79 | .env.production.local
80 | .env.local
81 |
82 | # parcel-bundler cache (https://parceljs.org/)
83 | .cache
84 | .parcel-cache
85 |
86 | # Next.js build output
87 | .next
88 | out
89 |
90 | # Nuxt.js build / generate output
91 | .nuxt
92 | dist
93 |
94 | # Gatsby files
95 | .cache/
96 | # Comment in the public line in if your project uses Gatsby and not Next.js
97 | # https://nextjs.org/blog/next-9-1#public-directory-support
98 | # public
99 |
100 | # vuepress build output
101 | .vuepress/dist
102 |
103 | # vuepress v2.x temp and cache directory
104 | .temp
105 | .cache
106 |
107 | # Docusaurus cache and generated files
108 | .docusaurus
109 |
110 | # Serverless directories
111 | .serverless/
112 |
113 | # FuseBox cache
114 | .fusebox/
115 |
116 | # DynamoDB Local files
117 | .dynamodb/
118 |
119 | # TernJS port file
120 | .tern-port
121 |
122 | # Stores VSCode versions used for testing VSCode extensions
123 | .vscode-test
124 |
125 | # yarn v2
126 | .yarn/cache
127 | .yarn/unplugged
128 | .yarn/build-state.yml
129 | .yarn/install-state.gz
130 | .pnp.*
131 |
132 | build/
133 |
134 | gcp-oauth.keys.json
135 | .*-server-credentials.json
136 |
137 | # Byte-compiled / optimized / DLL files
138 | __pycache__/
139 | *.py[cod]
140 | *$py.class
141 |
142 | # C extensions
143 | *.so
144 |
145 | # Distribution / packaging
146 | .Python
147 | build/
148 | develop-eggs/
149 | dist/
150 | downloads/
151 | eggs/
152 | .eggs/
153 | lib/
154 | lib64/
155 | parts/
156 | sdist/
157 | var/
158 | wheels/
159 | share/python-wheels/
160 | *.egg-info/
161 | .installed.cfg
162 | *.egg
163 | MANIFEST
164 |
165 | # PyInstaller
166 | # Usually these files are written by a python script from a template
167 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
168 | *.manifest
169 | *.spec
170 |
171 | # Installer logs
172 | pip-log.txt
173 | pip-delete-this-directory.txt
174 |
175 | # Unit test / coverage reports
176 | htmlcov/
177 | .tox/
178 | .nox/
179 | .coverage
180 | .coverage.*
181 | .cache
182 | nosetests.xml
183 | coverage.xml
184 | *.cover
185 | *.py,cover
186 | .hypothesis/
187 | .pytest_cache/
188 | cover/
189 |
190 | # Translations
191 | *.mo
192 | *.pot
193 |
194 | # Django stuff:
195 | *.log
196 | local_settings.py
197 | db.sqlite3
198 | db.sqlite3-journal
199 |
200 | # Flask stuff:
201 | instance/
202 | .webassets-cache
203 |
204 | # Scrapy stuff:
205 | .scrapy
206 |
207 | # Sphinx documentation
208 | docs/_build/
209 |
210 | # PyBuilder
211 | .pybuilder/
212 | target/
213 |
214 | # Jupyter Notebook
215 | .ipynb_checkpoints
216 |
217 | # IPython
218 | profile_default/
219 | ipython_config.py
220 |
221 | # pyenv
222 | # For a library or package, you might want to ignore these files since the code is
223 | # intended to run in multiple environments; otherwise, check them in:
224 | # .python-version
225 |
226 | # pipenv
227 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
228 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
229 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
230 | # install all needed dependencies.
231 | #Pipfile.lock
232 |
233 | # poetry
234 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
235 | # This is especially recommended for binary packages to ensure reproducibility, and is more
236 | # commonly ignored for libraries.
237 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
238 | #poetry.lock
239 |
240 | # pdm
241 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
242 | #pdm.lock
243 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
244 | # in version control.
245 | # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
246 | .pdm.toml
247 | .pdm-python
248 | .pdm-build/
249 |
250 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
251 | __pypackages__/
252 |
253 | # Celery stuff
254 | celerybeat-schedule
255 | celerybeat.pid
256 |
257 | # SageMath parsed files
258 | *.sage.py
259 |
260 | # Environments
261 | .env
262 | .venv
263 | env/
264 | venv/
265 | ENV/
266 | env.bak/
267 | venv.bak/
268 |
269 | # Spyder project settings
270 | .spyderproject
271 | .spyproject
272 |
273 | # Rope project settings
274 | .ropeproject
275 |
276 | # mkdocs documentation
277 | /site
278 |
279 | # mypy
280 | .mypy_cache/
281 | .dmypy.json
282 | dmypy.json
283 |
284 | # Pyre type checker
285 | .pyre/
286 |
287 | # pytype static type analyzer
288 | .pytype/
289 |
290 | # Cython debug symbols
291 | cython_debug/
292 |
293 | .DS_Store
294 |
295 | # PyCharm
296 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
297 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
298 | # and can be added to the global gitignore or merged into this file. For a more nuclear
299 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
300 | #.idea/
301 |
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <h2 align="center">
2 | 📢 <strong>COMMUNITY SERVER NOTICE</strong><br/>
3 | This is a community-maintained MCP Server.<br/>
4 | 👉 For the <strong>official</strong> MongoDB MCP Server, visit
5 | <a href="https://github.com/mongodb-js/mongodb-mcp-server">mongodb-js/mongodb-mcp-server</a>
6 | </h2>
7 |
8 | # MongoDB MCP Server
9 |
10 | A Model Context Protocol server that provides read-only access to MongoDB databases. This server enables LLMs to inspect collection schemas and execute aggregation pipelines.
11 |
12 | ## Components
13 |
14 | ### Tools
15 |
16 | - **aggregate**
17 | - Execute MongoDB aggregation pipelines against the connected database
18 | - Input:
19 | - `collection` (string): The collection to query
20 | - `pipeline` (array): MongoDB aggregation pipeline stages
21 | - `options` (object): Optional aggregation settings
22 | - `allowDiskUse` (boolean): Allow operations that require disk usage
23 | - `maxTimeMS` (number): Maximum execution time in milliseconds
24 | - `comment` (string): Comment to identify the operation
25 | - Default limit of 1000 documents if no limit stage is specified
26 | - Default timeout of 30 seconds
27 |
28 | - **explain**
29 | - Get execution plans for aggregation pipelines
30 | - Input:
31 | - `collection` (string): The collection to analyze
32 | - `pipeline` (array): MongoDB aggregation pipeline stages
33 | - `verbosity` (string): Detail level of the explanation
34 | - Options: "queryPlanner", "executionStats", "allPlansExecution"
35 | - Default: "queryPlanner"
36 |
37 | ### Resources
38 |
39 | The server provides schema information for each collection in the database:
40 |
41 | - **Collection Schemas** (`mongodb://<host>/<collection>/schema`)
42 | - Inferred JSON schema information for each collection
43 | - Includes field names and data types
44 | - Schema is derived from sampling collection documents
45 |
46 | ## Usage with Claude Desktop
47 |
48 | To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your `claude_desktop_config.json`:
49 |
50 | ```json
51 | "mongodb": {
52 | "command": "npx",
53 | "args": [
54 | "-y" ,
55 | "@pash1986/mcp-server-mongodb"
56 | ],
57 | "env" : {
58 | "MONGODB_URI" : "mongodb+srv://<yourcluster>" // 'mongodb://localhost:27017'
59 | }
60 | }
61 | ```
62 |
63 | Replace `mydb` with your database name and adjust the connection string as needed.
64 |
65 | ## Example Usage
66 |
67 | ### Basic Aggregation
68 |
69 | ```javascript
70 | {
71 | "collection": "users",
72 | "pipeline": [
73 | { "$match": { "age": { "$gt": 21 } } },
74 | { "$group": {
75 | "_id": "$city",
76 | "avgAge": { "$avg": "$age" },
77 | "count": { "$sum": 1 }
78 | }},
79 | { "$sort": { "count": -1 } },
80 | { "$limit": 10 }
81 | ],
82 | "options": {
83 | "allowDiskUse": true,
84 | "maxTimeMS": 60000,
85 | "comment": "City-wise user statistics"
86 | }
87 | }
88 | ```
89 |
90 | ### Query Explanation
91 |
92 | ```javascript
93 | {
94 | "collection": "users",
95 | "pipeline": [
96 | { "$match": { "age": { "$gt": 21 } } },
97 | { "$sort": { "age": 1 } }
98 | ],
99 | "verbosity": "executionStats"
100 | }
101 | ```
102 |
103 | ## Safety Features
104 |
105 | - Automatic limit of 1000 documents if no limit is specified in the pipeline
106 | - Default timeout of 30 seconds for all operations
107 | - Read-only operations only
108 | - Safe schema inference from collection samples
109 |
110 | ## License
111 |
112 | 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.
113 |
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2022",
4 | "module": "Node16",
5 | "moduleResolution": "Node16",
6 | "outDir": "./build",
7 | "rootDir": "./",
8 | "strict": true,
9 | "esModuleInterop": true,
10 | "skipLibCheck": true,
11 | "forceConsistentCasingInFileNames": true
12 | },
13 | "include": ["**/*"],
14 | "exclude": ["node_modules"]
15 | }
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "@pash1986/mongodb-mcp-server",
3 | "version": "0.1.7",
4 | "description": "MongoDB MCP server for local mongodb queries",
5 | "type": "module",
6 | "bin": {
7 | "mcp-server-mongodb": "build/index.js"
8 | },
9 | "engines": {
10 | "node": ">=18.0.0"
11 | },
12 | "author": "Pavel Duchovny, MongoDB Inc.",
13 | "homepage": "https://modelcontextprotocol.io",
14 | "bugs": "https://github.com/modelcontextprotocol/servers/issues",
15 | "files": [
16 | "build",
17 | "src",
18 | "README.md",
19 | "LICENSE"
20 | ],
21 | "scripts": {
22 | "start": "node ./build/index.js",
23 | "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
24 | "prepare": "npm run build",
25 | "watch": "tsc --watch",
26 | "inspector": "npx @modelcontextprotocol/inspector build/index.js"
27 | },
28 | "dependencies": {
29 | "@modelcontextprotocol/sdk": "0.6.0",
30 | "axios": "^1.7.8",
31 | "dotenv": "^16.4.5",
32 | "mongodb": "^6.11.0"
33 | },
34 | "devDependencies": {
35 | "@types/mongodb": "^4.0.7",
36 | "@types/node": "^20.11.24",
37 | "typescript": "^5.3.3"
38 | }
39 | }
40 |
```
--------------------------------------------------------------------------------
/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | #!/usr/bin/env node
2 |
3 | import { Server } from "@modelcontextprotocol/sdk/server/index.js";
4 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
5 | import {
6 | CallToolRequestSchema,
7 | ListResourcesRequestSchema,
8 | ListToolsRequestSchema,
9 | ReadResourceRequestSchema,
10 | ErrorCode,
11 | McpError
12 | } from "@modelcontextprotocol/sdk/types.js";
13 | import { MongoClient, Db, Collection, Document, AggregateOptions } from "mongodb";
14 | //import dotenv from "dotenv";
15 | import * as dotenv from 'dotenv';
16 |
17 | dotenv.config();
18 |
19 | const MONGODB_URI = process.env.MONGODB_URI;
20 | if (!MONGODB_URI) {
21 | throw new Error("MONGODB_URI environment variable is required");
22 | }
23 |
24 | interface AggregateToolArguments {
25 | collection: string;
26 | pipeline: Document[];
27 | options?: AggregateOptions & {
28 | allowDiskUse?: boolean;
29 | maxTimeMS?: number;
30 | comment?: string;
31 | };
32 | }
33 |
34 | interface ExplainToolArguments {
35 | collection: string;
36 | pipeline: Document[];
37 | verbosity?: "queryPlanner" | "executionStats" | "allPlansExecution";
38 | }
39 |
40 | interface SampleDocumentsArguments {
41 | collection: string;
42 | count?: number;
43 | }
44 |
45 | class MongoDBServer {
46 | private server: Server;
47 | private client!: MongoClient;
48 | private db!: Db;
49 |
50 | constructor() {
51 | this.server = new Server(
52 | {
53 | name: "example-servers/mongodb",
54 | version: "0.1.0",
55 | description: "MongoDB MCP server providing secure access to MongoDB databases",
56 | },
57 | {
58 | capabilities: {
59 | resources: {
60 | description: "MongoDB collections and their schemas",
61 | mimeTypes: ["application/json"],
62 | },
63 | tools: {
64 | description: "MongoDB aggregation and analysis tools",
65 | },
66 | },
67 | }
68 | );
69 |
70 | this.setupHandlers();
71 | this.setupErrorHandling();
72 | }
73 |
74 | private setupErrorHandling(): void {
75 | this.server.onerror = (error) => {
76 | console.error("[MCP Error]", error);
77 | };
78 |
79 | // Handle both SIGINT (Ctrl+C) and SIGTERM (process termination)
80 | const cleanup = async () => {
81 | console.log("Shutting down MongoDB MCP server...");
82 | try {
83 | await this.close();
84 | process.exit(0);
85 | } catch (error) {
86 | console.error("Error during cleanup:", error);
87 | process.exit(1);
88 | }
89 | };
90 |
91 | process.on('SIGINT', cleanup);
92 | process.on('SIGTERM', cleanup);
93 |
94 | // Handle uncaught exceptions and unhandled rejections
95 | process.on('uncaughtException', async (error) => {
96 | console.error('Uncaught Exception:', error);
97 | await cleanup();
98 | });
99 |
100 | process.on('unhandledRejection', async (reason, promise) => {
101 | console.error('Unhandled Rejection at:', promise, 'reason:', reason);
102 | await cleanup();
103 | });
104 | }
105 |
106 | private setupHandlers(): void {
107 | this.setupResourceHandlers();
108 | this.setupToolHandlers();
109 | }
110 |
111 | private setupResourceHandlers(): void {
112 | this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
113 | const collections = await this.db.listCollections().toArray();
114 | return {
115 | resources: collections.map((collection: Document) => ({
116 | uri: `mcp-mongodb://${collection.name}/schema`,
117 | mimeType: "application/json",
118 | name: `"${collection.name}" collection schema`,
119 | description: `Schema information for the ${collection.name} collection`,
120 | })),
121 | };
122 | });
123 |
124 | this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
125 | const uri = request.params.uri;
126 | const match = uri.match(/^mcp-mongodb:\/\/([^/]+)\/schema$/);
127 |
128 | if (!match) {
129 | throw new McpError(
130 | ErrorCode.InvalidRequest,
131 | "Invalid resource URI"
132 | );
133 | }
134 |
135 | const collectionName = match[1];
136 |
137 | try {
138 | const sampleDoc = await this.db.collection(collectionName).findOne();
139 |
140 | if (!sampleDoc) {
141 | return {
142 | contents: [
143 | {
144 | uri: request.params.uri,
145 | mimeType: "application/json",
146 | text: JSON.stringify({ message: "Collection is empty" }, null, 2),
147 | },
148 | ],
149 | };
150 | }
151 |
152 | const documentSchema = Object.entries(sampleDoc).map(([key, value]) => ({
153 | field_name: key,
154 | field_type: typeof value,
155 | description: `Field ${key} of type ${typeof value}`,
156 | }));
157 |
158 | return {
159 | contents: [
160 | {
161 | uri: request.params.uri,
162 | mimeType: "application/json",
163 | text: JSON.stringify(documentSchema, null, 2),
164 | },
165 | ],
166 | };
167 | } catch (error) {
168 | throw new McpError(
169 | ErrorCode.InternalError,
170 | `MongoDB error: ${error instanceof Error ? error.message : 'Unknown error'}`
171 | );
172 | }
173 | });
174 | }
175 |
176 | private setupToolHandlers(): void {
177 | this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
178 | tools: [
179 | {
180 | name: "aggregate",
181 | description: "Run a MongoDB aggregation pipeline",
182 | inputSchema: {
183 | type: "object",
184 | properties: {
185 | collection: {
186 | type: "string",
187 | description: "Name of the collection to query",
188 | },
189 | pipeline: {
190 | type: "array",
191 | items: { type: "object" },
192 | description: "MongoDB aggregation pipeline stages (e.g., $match, $group, $sort)",
193 | },
194 | options: {
195 | type: "object",
196 | description: "Optional aggregation options",
197 | properties: {
198 | allowDiskUse: {
199 | type: "boolean",
200 | description: "Allow writing to temporary files",
201 | },
202 | maxTimeMS: {
203 | type: "number",
204 | description: "Maximum execution time in milliseconds",
205 | },
206 | comment: {
207 | type: "string",
208 | description: "Optional comment to help trace operations",
209 | }
210 | }
211 | }
212 | },
213 | required: ["collection", "pipeline"],
214 | },
215 | examples: [
216 | {
217 | name: "Count documents by status",
218 | arguments: {
219 | collection: "orders",
220 | pipeline: [
221 | { $group: { _id: "$status", count: { $sum: 1 } } },
222 | { $sort: { count: -1 } }
223 | ]
224 | }
225 | }
226 | ]
227 | },
228 | {
229 | name: "explain",
230 | description: "Get the execution plan for an aggregation pipeline",
231 | inputSchema: {
232 | type: "object",
233 | properties: {
234 | collection: {
235 | type: "string",
236 | description: "Name of the collection to analyze",
237 | },
238 | pipeline: {
239 | type: "array",
240 | items: { type: "object" },
241 | description: "MongoDB aggregation pipeline stages to analyze",
242 | },
243 | verbosity: {
244 | type: "string",
245 | enum: ["queryPlanner", "executionStats", "allPlansExecution"],
246 | default: "queryPlanner",
247 | description: "Level of detail in the execution plan",
248 | }
249 | },
250 | required: ["collection", "pipeline"],
251 | },
252 | examples: [
253 | {
254 | name: "Analyze index usage",
255 | arguments: {
256 | collection: "users",
257 | pipeline: [
258 | { $match: { status: "active" } },
259 | { $sort: { lastLogin: -1 } }
260 | ],
261 | verbosity: "executionStats"
262 | }
263 | }
264 | ]
265 | },
266 | {
267 | name: "sample",
268 | description: "Get random sample documents from a collection",
269 | inputSchema: {
270 | type: "object",
271 | properties: {
272 | collection: {
273 | type: "string",
274 | description: "Name of the collection to sample from",
275 | },
276 | count: {
277 | type: "number",
278 | description: "Number of documents to sample (default: 5, max: 10)",
279 | minimum: 1,
280 | maximum: 10,
281 | default: 5,
282 | }
283 | },
284 | required: ["collection"],
285 | },
286 | examples: [
287 | {
288 | name: "Get 5 random documents",
289 | arguments: {
290 | collection: "listings",
291 | count: 5
292 | }
293 | }
294 | ]
295 | }
296 | ],
297 | }));
298 |
299 | this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
300 | switch (request.params.name) {
301 | case "aggregate": {
302 | if (!this.isAggregateToolArguments(request.params.arguments)) {
303 | return {
304 | content: [{ type: "text", text: "Invalid arguments: expected collection and pipeline parameters" }],
305 | isError: true,
306 | };
307 | }
308 |
309 | const { collection, pipeline, options = {} } = request.params.arguments;
310 |
311 | try {
312 | const hasLimit = pipeline.some(stage => "$limit" in stage);
313 | const safePipeline = hasLimit ? pipeline : [...pipeline, { $limit: 1000 }];
314 |
315 | const result = await this.db
316 | .collection(collection)
317 | .aggregate(safePipeline, {
318 | ...options,
319 | maxTimeMS: options.maxTimeMS || 30000
320 | })
321 | .toArray();
322 |
323 | return {
324 | content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
325 | isError: false,
326 | };
327 | } catch (error) {
328 | return {
329 | content: [{
330 | type: "text",
331 | text: `Aggregation error: ${error instanceof Error ? error.message : 'Unknown error'}`
332 | }],
333 | isError: true,
334 | };
335 | }
336 | }
337 |
338 | case "explain": {
339 | if (!this.isExplainToolArguments(request.params.arguments)) {
340 | return {
341 | content: [{ type: "text", text: "Invalid arguments: expected collection and pipeline parameters" }],
342 | isError: true,
343 | };
344 | }
345 |
346 | const { collection, pipeline } = request.params.arguments;
347 |
348 | try {
349 | const result = await this.db
350 | .collection(collection)
351 | .aggregate(pipeline, { explain: true });
352 |
353 | return {
354 | content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
355 | isError: false,
356 | };
357 | } catch (error) {
358 | return {
359 | content: [{
360 | type: "text",
361 | text: `Explain error: ${error instanceof Error ? error.message : 'Unknown error'}`
362 | }],
363 | isError: true,
364 | };
365 | }
366 | }
367 |
368 | case "sample": {
369 | if (!this.isSampleDocumentsArguments(request.params.arguments)) {
370 | return {
371 | content: [{ type: "text", text: "Invalid arguments: expected collection name" }],
372 | isError: true,
373 | };
374 | }
375 |
376 | const { collection, count = 5 } = request.params.arguments;
377 | const safeCount = Math.min(Math.max(1, count), 10);
378 |
379 | try {
380 | const result = await this.db
381 | .collection(collection)
382 | .aggregate([
383 | { $sample: { size: safeCount } }
384 | ])
385 | .toArray();
386 |
387 | return {
388 | content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
389 | isError: false,
390 | };
391 | } catch (error) {
392 | return {
393 | content: [{
394 | type: "text",
395 | text: `Sample error: ${error instanceof Error ? error.message : 'Unknown error'}`
396 | }],
397 | isError: true,
398 | };
399 | }
400 | }
401 |
402 | default:
403 | throw new McpError(
404 | ErrorCode.MethodNotFound,
405 | `Unknown tool: ${request.params.name}`
406 | );
407 | }
408 | });
409 | }
410 |
411 | private isAggregateToolArguments(value: unknown): value is AggregateToolArguments {
412 | if (!value || typeof value !== 'object') return false;
413 | const obj = value as Record<string, unknown>;
414 | return (
415 | typeof obj.collection === 'string' &&
416 | Array.isArray(obj.pipeline) &&
417 | (!obj.options || typeof obj.options === 'object')
418 | );
419 | }
420 |
421 | private isExplainToolArguments(value: unknown): value is ExplainToolArguments {
422 | if (!value || typeof value !== 'object') return false;
423 | const obj = value as Record<string, unknown>;
424 | return (
425 | typeof obj.collection === 'string' &&
426 | Array.isArray(obj.pipeline) &&
427 | (!obj.verbosity || ["queryPlanner", "executionStats", "allPlansExecution"].includes(obj.verbosity as string))
428 | );
429 | }
430 |
431 | private isSampleDocumentsArguments(value: unknown): value is SampleDocumentsArguments {
432 | if (!value || typeof value !== 'object') return false;
433 | const obj = value as Record<string, unknown>;
434 | return (
435 | typeof obj.collection === 'string' &&
436 | (!obj.count || (typeof obj.count === 'number' && obj.count > 0 && obj.count <= 10))
437 | );
438 | }
439 |
440 | async connect(): Promise<void> {
441 | try {
442 | this.client = new MongoClient(MONGODB_URI!);
443 | await this.client.connect();
444 | this.db = this.client.db();
445 | } catch (error) {
446 | console.error("Failed to connect to MongoDB:", error);
447 | throw error;
448 | }
449 | }
450 |
451 | async close(): Promise<void> {
452 | if (this.client) {
453 | await this.client.close();
454 | }
455 | }
456 |
457 | async run(): Promise<void> {
458 | await this.connect();
459 | const transport = new StdioServerTransport();
460 | await this.server.connect(transport);
461 | }
462 | }
463 |
464 | const server = new MongoDBServer();
465 | server.run().catch((error) => {
466 | console.error(error);
467 | server.close().catch(console.error);
468 | process.exit(1);
469 | });
470 |
```