From fbc59fa0d6c0744e0aa09ad07231d76034885b3d Mon Sep 17 00:00:00 2001 From: gagik Date: Thu, 11 Dec 2025 13:56:42 +0100 Subject: [PATCH 1/6] chore: combine columns --- README.md | 62 ++++++++++++++++++------------------ scripts/generateArguments.ts | 10 +++--- 2 files changed, 36 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index b61353bc..f696f2a2 100644 --- a/README.md +++ b/README.md @@ -345,37 +345,37 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow ### Configuration Options -| CLI Option | Environment Variable | Default | Description | -| -------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `allowRequestOverrides` | `MDB_MCP_ALLOW_REQUEST_OVERRIDES` | `false` | When set to true, allows configuration values to be overridden via request headers and query parameters. | -| `apiClientId` | `MDB_MCP_API_CLIENT_ID` | `` | Atlas API client ID for authentication. Required for running Atlas tools. | -| `apiClientSecret` | `MDB_MCP_API_CLIENT_SECRET` | `` | Atlas API client secret for authentication. Required for running Atlas tools. | -| `atlasTemporaryDatabaseUserLifetimeMs` | `MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS` | `14400000` | Time in milliseconds that temporary database users created when connecting to MongoDB Atlas clusters will remain active before being automatically deleted. | -| `confirmationRequiredTools` | `MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` | `"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index"` | Comma separated values of tool names that require user confirmation before execution. Requires the client to support elicitation. | -| `connectionString` | `MDB_MCP_CONNECTION_STRING` | `` | MongoDB connection string for direct database connections. Optional, if not set, you'll need to call the connect tool before interacting with MongoDB data. | -| `disabledTools` | `MDB_MCP_DISABLED_TOOLS` | `""` | Comma separated values of tool names, operation types, and/or categories of tools that will be disabled. | -| `dryRun` | `MDB_MCP_DRY_RUN` | `false` | When true, runs the server in dry mode: dumps configuration and enabled tools, then exits without starting the server. | -| `embeddingsValidation` | `MDB_MCP_EMBEDDINGS_VALIDATION` | `true` | When set to false, disables validation of embeddings dimensions. | -| `exportCleanupIntervalMs` | `MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` | `120000` | Time in milliseconds between export cleanup cycles that remove expired export files. | -| `exportTimeoutMs` | `MDB_MCP_EXPORT_TIMEOUT_MS` | `300000` | Time in milliseconds after which an export is considered expired and eligible for cleanup. | -| `exportsPath` | `MDB_MCP_EXPORTS_PATH` | see below\* | Folder to store exported data files. | -| `httpHeaders` | `MDB_MCP_HTTP_HEADERS` | `"{}"` | Header that the HTTP server will validate when making requests (only used when transport is 'http'). | -| `httpHost` | `MDB_MCP_HTTP_HOST` | `"127.0.0.1"` | Host address to bind the HTTP server to (only used when transport is 'http'). | -| `httpPort` | `MDB_MCP_HTTP_PORT` | `3000` | Port number for the HTTP server (only used when transport is 'http'). Use 0 for a random port. | -| `idleTimeoutMs` | `MDB_MCP_IDLE_TIMEOUT_MS` | `600000` | Idle timeout for a client to disconnect (only applies to http transport). | -| `indexCheck` | `MDB_MCP_INDEX_CHECK` | `false` | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan. | -| `logPath` | `MDB_MCP_LOG_PATH` | see below\* | Folder to store logs. | -| `loggers` | `MDB_MCP_LOGGERS` | `"disk,mcp"` see below\* | Comma separated values of logger types. | -| `maxBytesPerQuery` | `MDB_MCP_MAX_BYTES_PER_QUERY` | `16777216` | The maximum size in bytes for results from a find or aggregate tool call. This serves as an upper bound for the responseBytesLimit parameter in those tools. | -| `maxDocumentsPerQuery` | `MDB_MCP_MAX_DOCUMENTS_PER_QUERY` | `100` | The maximum number of documents that can be returned by a find or aggregate tool call. For the find tool, the effective limit will be the smaller of this value and the tool's limit parameter. | -| `notificationTimeoutMs` | `MDB_MCP_NOTIFICATION_TIMEOUT_MS` | `540000` | Notification timeout for a client to be aware of disconnect (only applies to http transport). | -| `previewFeatures` | `MDB_MCP_PREVIEW_FEATURES` | `""` | Comma separated values of preview features that are enabled. | -| `readOnly` | `MDB_MCP_READ_ONLY` | `false` | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations. | -| `telemetry` | `MDB_MCP_TELEMETRY` | `"enabled"` | When set to disabled, disables telemetry collection. | -| `transport` | `MDB_MCP_TRANSPORT` | `"stdio"` | Either 'stdio' or 'http'. | -| `vectorSearchDimensions` | `MDB_MCP_VECTOR_SEARCH_DIMENSIONS` | `1024` | Default number of dimensions for vector search embeddings. | -| `vectorSearchSimilarityFunction` | `MDB_MCP_VECTOR_SEARCH_SIMILARITY_FUNCTION` | `"euclidean"` | Default similarity function for vector search: 'euclidean', 'cosine', or 'dotProduct'. | -| `voyageApiKey` | `MDB_MCP_VOYAGE_API_KEY` | `""` | API key for Voyage AI embeddings service (required for vector search operations with text-to-embedding conversion). | +| Option | Default | Description | +| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `MDB_MCP_ALLOW_REQUEST_OVERRIDES` or `--allowRequestOverrides` | `false` | When set to true, allows configuration values to be overridden via request headers and query parameters. | +| `MDB_MCP_API_CLIENT_ID` or `--apiClientId` | `` | Atlas API client ID for authentication. Required for running Atlas tools. | +| `MDB_MCP_API_CLIENT_SECRET` or `--apiClientSecret` | `` | Atlas API client secret for authentication. Required for running Atlas tools. | +| `MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS` or `--atlasTemporaryDatabaseUserLifetimeMs` | `14400000` | Time in milliseconds that temporary database users created when connecting to MongoDB Atlas clusters will remain active before being automatically deleted. | +| `MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` or `--confirmationRequiredTools` | `"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index"` | Comma separated values of tool names that require user confirmation before execution. Requires the client to support elicitation. | +| `MDB_MCP_CONNECTION_STRING` or `--connectionString` | `` | MongoDB connection string for direct database connections. Optional, if not set, you'll need to call the connect tool before interacting with MongoDB data. | +| `MDB_MCP_DISABLED_TOOLS` or `--disabledTools` | `""` | Comma separated values of tool names, operation types, and/or categories of tools that will be disabled. | +| `MDB_MCP_DRY_RUN` or `--dryRun` | `false` | When true, runs the server in dry mode: dumps configuration and enabled tools, then exits without starting the server. | +| `MDB_MCP_EMBEDDINGS_VALIDATION` or `--embeddingsValidation` | `true` | When set to false, disables validation of embeddings dimensions. | +| `MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` or `--exportCleanupIntervalMs` | `120000` | Time in milliseconds between export cleanup cycles that remove expired export files. | +| `MDB_MCP_EXPORT_TIMEOUT_MS` or `--exportTimeoutMs` | `300000` | Time in milliseconds after which an export is considered expired and eligible for cleanup. | +| `MDB_MCP_EXPORTS_PATH` or `--exportsPath` | see below\* | Folder to store exported data files. | +| `MDB_MCP_HTTP_HEADERS` or `--httpHeaders` | `"{}"` | Header that the HTTP server will validate when making requests (only used when transport is 'http'). | +| `MDB_MCP_HTTP_HOST` or `--httpHost` | `"127.0.0.1"` | Host address to bind the HTTP server to (only used when transport is 'http'). | +| `MDB_MCP_HTTP_PORT` or `--httpPort` | `3000` | Port number for the HTTP server (only used when transport is 'http'). Use 0 for a random port. | +| `MDB_MCP_IDLE_TIMEOUT_MS` or `--idleTimeoutMs` | `600000` | Idle timeout for a client to disconnect (only applies to http transport). | +| `MDB_MCP_INDEX_CHECK` or `--indexCheck` | `false` | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan. | +| `MDB_MCP_LOG_PATH` or `--logPath` | see below\* | Folder to store logs. | +| `MDB_MCP_LOGGERS` or `--loggers` | `"disk,mcp"` see below\* | Comma separated values of logger types. | +| `MDB_MCP_MAX_BYTES_PER_QUERY` or `--maxBytesPerQuery` | `16777216` | The maximum size in bytes for results from a find or aggregate tool call. This serves as an upper bound for the responseBytesLimit parameter in those tools. | +| `MDB_MCP_MAX_DOCUMENTS_PER_QUERY` or `--maxDocumentsPerQuery` | `100` | The maximum number of documents that can be returned by a find or aggregate tool call. For the find tool, the effective limit will be the smaller of this value and the tool's limit parameter. | +| `MDB_MCP_NOTIFICATION_TIMEOUT_MS` or `--notificationTimeoutMs` | `540000` | Notification timeout for a client to be aware of disconnect (only applies to http transport). | +| `MDB_MCP_PREVIEW_FEATURES` or `--previewFeatures` | `""` | Comma separated values of preview features that are enabled. | +| `MDB_MCP_READ_ONLY` or `--readOnly` | `false` | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations. | +| `MDB_MCP_TELEMETRY` or `--telemetry` | `"enabled"` | When set to disabled, disables telemetry collection. | +| `MDB_MCP_TRANSPORT` or `--transport` | `"stdio"` | Either 'stdio' or 'http'. | +| `MDB_MCP_VECTOR_SEARCH_DIMENSIONS` or `--vectorSearchDimensions` | `1024` | Default number of dimensions for vector search embeddings. | +| `MDB_MCP_VECTOR_SEARCH_SIMILARITY_FUNCTION` or `--vectorSearchSimilarityFunction` | `"euclidean"` | Default similarity function for vector search: 'euclidean', 'cosine', or 'dotProduct'. | +| `MDB_MCP_VOYAGE_API_KEY` or `--voyageApiKey` | `""` | API key for Voyage AI embeddings service (required for vector search operations with text-to-embedding conversion). | #### Logger Options diff --git a/scripts/generateArguments.ts b/scripts/generateArguments.ts index 2fccd8c1..9032d4c6 100644 --- a/scripts/generateArguments.ts +++ b/scripts/generateArguments.ts @@ -262,15 +262,15 @@ function updateServerJsonEnvVars(envVars: ArgumentInfo[]): void { function generateReadmeConfigTable(argumentInfos: ArgumentInfo[]): string { const rows = [ - "| CLI Option | Environment Variable | Default | Description |", - "| -------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |", + "| Option | Default | Description |", + "| -------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |", ]; // Filter to only include options that are in the Zod schema (documented options) const documentedVars = argumentInfos.filter((v) => !v.description.startsWith("Configuration option:")); for (const argumentInfo of documentedVars) { - const cliOption = `\`${argumentInfo.configKey}\``; + const cliOption = `\`--${argumentInfo.configKey}\``; const envVarName = `\`${argumentInfo.name}\``; const defaultValue = argumentInfo.defaultValue; @@ -302,7 +302,7 @@ function generateReadmeConfigTable(argumentInfos: ArgumentInfo[]): string { const desc = argumentInfo.description.replace(/\|/g, "\\|"); // Escape pipes in description rows.push( - `| ${cliOption.padEnd(38)} | ${envVarName.padEnd(51)} | ${defaultValueString.padEnd(75)} | ${desc.padEnd(199)} |` + `| ${`${envVarName} or ${cliOption}`.padEnd(89)} | ${defaultValueString.padEnd(75)} | ${desc.padEnd(199)} |` ); } @@ -316,7 +316,7 @@ function updateReadmeConfigTable(envVars: ArgumentInfo[]): void { const newTable = generateReadmeConfigTable(envVars); // Find and replace the configuration options table - const tableRegex = /### Configuration Options\n\n\| CLI Option[\s\S]*?\n\n####/; + const tableRegex = /### Configuration Options\n\n\| Option[\s\S]*?\n\n####/; const replacement = `### Configuration Options\n\n${newTable}\n\n####`; content = content.replace(tableRegex, replacement); From a91e08e3dc5e7972bf16f431101fc786a174b30b Mon Sep 17 00:00:00 2001 From: gagik Date: Fri, 12 Dec 2025 14:38:14 +0100 Subject: [PATCH 2/6] docs: list all available tools with a generate script MCP-340 --- README.md | 67 ++++---- package.json | 2 +- scripts/generate/README.md | 17 ++ scripts/{ => generate}/generateArguments.ts | 16 +- scripts/generate/generateToolDocumentation.ts | 149 ++++++++++++++++++ scripts/generate/index.ts | 22 +++ tsconfig.build.json | 3 +- 7 files changed, 233 insertions(+), 43 deletions(-) create mode 100644 scripts/generate/README.md rename scripts/{ => generate}/generateArguments.ts (97%) create mode 100644 scripts/generate/generateToolDocumentation.ts create mode 100644 scripts/generate/index.ts diff --git a/README.md b/README.md index f696f2a2..d89561c8 100644 --- a/README.md +++ b/README.md @@ -283,49 +283,54 @@ npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --httpPort= #### MongoDB Atlas Tools -- `atlas-list-orgs` - Lists MongoDB Atlas organizations -- `atlas-list-projects` - Lists MongoDB Atlas projects -- `atlas-create-project` - Creates a new MongoDB Atlas project -- `atlas-list-clusters` - Lists MongoDB Atlas clusters -- `atlas-inspect-cluster` - Inspect a specific MongoDB Atlas cluster +- `atlas-connect-cluster` - Connect to MongoDB Atlas cluster +- `atlas-create-access-list` - Allow Ip/CIDR ranges to access your MongoDB Atlas clusters. +- `atlas-create-db-user` - Create an MongoDB Atlas database user - `atlas-create-free-cluster` - Create a free MongoDB Atlas cluster -- `atlas-connect-cluster` - Connects to MongoDB Atlas cluster -- `atlas-inspect-access-list` - Inspect IP/CIDR ranges with access to MongoDB Atlas clusters -- `atlas-create-access-list` - Configure IP/CIDR access list for MongoDB Atlas clusters +- `atlas-create-project` - Create a MongoDB Atlas project +- `atlas-get-performance-advisor` - Get MongoDB Atlas performance advisor recommendations, which includes the operations: suggested indexes, drop index suggestions, schema suggestions, and a sample of the most recent (max 50) slow query logs +- `atlas-inspect-access-list` - Inspect Ip/CIDR ranges with access to your MongoDB Atlas clusters. +- `atlas-inspect-cluster` - Inspect MongoDB Atlas cluster +- `atlas-list-alerts` - List MongoDB Atlas alerts +- `atlas-list-clusters` - List MongoDB Atlas clusters - `atlas-list-db-users` - List MongoDB Atlas database users -- `atlas-create-db-user` - Creates a MongoDB Atlas database user -- `atlas-list-alerts` - List MongoDB Atlas Alerts for a Project -- `atlas-get-performance-advisor` - Gets Atlas Performance Advisor recommendations (index suggestions, drop index suggestions, schema suggestions, slow query logs) +- `atlas-list-orgs` - List MongoDB Atlas organizations +- `atlas-list-projects` - List MongoDB Atlas projects NOTE: atlas tools are only available when you set credentials on [configuration](#configuration) section. #### MongoDB Atlas Local Tools -- `atlas-local-list-deployments` - Lists MongoDB Atlas Local deployments -- `atlas-local-create-deployment` - Creates a MongoDB Atlas Local deployment -- `atlas-local-connect-deployment` - Connects to a MongoDB Atlas Local deployment -- `atlas-local-delete-deployment` - Deletes a MongoDB Atlas Local deployment +- `atlas-local-connect-deployment` - Connect to a MongoDB Atlas Local deployment +- `atlas-local-create-deployment` - Create a MongoDB Atlas local deployment +- `atlas-local-delete-deployment` - Delete a MongoDB Atlas local deployment +- `atlas-local-list-deployments` - List MongoDB Atlas local deployments #### MongoDB Database Tools -- `connect` - Connect to a MongoDB instance -- `find` - Run a find query against a MongoDB collection. The number of documents returned is limited by the `limit` parameter and the server's `maxDocumentsPerQuery` configuration, whichever is smaller. The total size of the returned documents is also limited by the `responseBytesLimit` parameter and the server's `maxBytesPerQuery` configuration, whichever is smaller. -- `aggregate` - Run an aggregation against a MongoDB collection. The number of documents returned is limited by the server's `maxDocumentsPerQuery` configuration. The total size of the returned documents is also limited by the `responseBytesLimit` parameter and the server's `maxBytesPerQuery` configuration, whichever is smaller. -- `count` - Get the number of documents in a MongoDB collection -- `insert-many` - Insert multiple documents into a MongoDB collection -- `create-index` - Create an index for a MongoDB collection -- `update-many` - Update multiple documents in a MongoDB collection -- `rename-collection` - Rename a MongoDB collection -- `delete-many` - Delete multiple documents from a MongoDB collection -- `drop-collection` - Remove a collection from a MongoDB database -- `drop-database` - Remove a MongoDB database -- `list-databases` - List all databases for a MongoDB connection -- `list-collections` - List all collections for a given database +- `aggregate` - Run an aggregation against a MongoDB collection - `collection-indexes` - Describe the indexes for a collection - `collection-schema` - Describe the schema for a collection -- `collection-storage-size` - Get the size of a collection in MB -- `db-stats` - Return statistics about a MongoDB database -- `export` - Export query or aggregation results to EJSON format. Creates a uniquely named export accessible via the `exported-data` resource. +- `collection-storage-size` - Gets the size of the collection +- `connect` - Connect to a MongoDB instance +- `count` - Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parameter +- `create-collection` - Creates a new collection in a database. If the database doesn't exist, it will be created automatically. +- `create-index` - Create an index for a collection +- `db-stats` - Returns statistics that reflect the use state of a single database +- `delete-many` - Removes all documents that match the filter from a MongoDB collection +- `drop-collection` - Removes a collection or view from the database. The method also removes any indexes associated with the dropped collection. +- `drop-database` - Removes the specified database, deleting the associated data files +- `drop-index` - Drop an index for the provided database and collection. +- `explain` - Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated method +- `export` - Export a query or aggregation results in the specified EJSON format. +- `find` - Run a find query against a MongoDB collection +- `insert-many` - Insert an array of documents into a MongoDB collection +- `list-collections` - List all collections for a given database +- `list-databases` - List all databases for a MongoDB connection +- `mongodb-logs` - Returns the most recent logged mongod events +- `rename-collection` - Renames a collection in a MongoDB database +- `switch-connection` - Switch to a different MongoDB connection +- `update-many` - Updates all documents that match the specified filter for a collection ## šŸ“„ Supported Resources diff --git a/package.json b/package.json index 3c17458b..c0e49274 100644 --- a/package.json +++ b/package.json @@ -65,7 +65,7 @@ "reformat": "prettier --write .", "generate": "pnpm run generate:api && pnpm run generate:arguments", "generate:api": "./scripts/generate.sh", - "generate:arguments": "tsx scripts/generateArguments.ts", + "generate:arguments": "tsx scripts/generate/index.ts", "pretest": "pnpm run build", "test": "vitest --project eslint-rules --project unit-and-integration --coverage --run", "test:accuracy": "sh ./scripts/accuracy/runAccuracyTests.sh", diff --git a/scripts/generate/README.md b/scripts/generate/README.md new file mode 100644 index 00000000..e7b13c75 --- /dev/null +++ b/scripts/generate/README.md @@ -0,0 +1,17 @@ +# Generate Scripts + +This folder contains a helper script which generates various documentation and configurations based on our code. + +## Files + +- **`index.ts`** - Main entry point that orchestrates all generation tasks +- **`generateArguments.ts`** - Generates CLI arguments, environment variables, and configuration tables from the UserConfig Zod Schema +- **`generateToolDocumentation.ts`** - Generates tool documentation by reading from the AllTools array + +## Usage + +Run all generators: + +```bash +pnpm run generate:arguments +``` \ No newline at end of file diff --git a/scripts/generateArguments.ts b/scripts/generate/generateArguments.ts similarity index 97% rename from scripts/generateArguments.ts rename to scripts/generate/generateArguments.ts index 9032d4c6..ff60c97a 100644 --- a/scripts/generateArguments.ts +++ b/scripts/generate/generateArguments.ts @@ -1,5 +1,3 @@ -#!/usr/bin/env tsx - /** * This script generates argument definitions and updates: * - server.json arrays @@ -11,7 +9,7 @@ import { readFileSync, writeFileSync } from "fs"; import { join, dirname } from "path"; import { fileURLToPath } from "url"; -import { UserConfigSchema, configRegistry } from "../src/common/config/userConfig.js"; +import { UserConfigSchema, configRegistry } from "../../src/common/config/userConfig.js"; import { execSync } from "child_process"; import type { z as z4 } from "zod/v4"; @@ -205,8 +203,8 @@ function generatePackageArguments(envVars: ArgumentInfo[]): unknown[] { } function updateServerJsonEnvVars(envVars: ArgumentInfo[]): void { - const serverJsonPath = join(__dirname, "..", "server.json"); - const packageJsonPath = join(__dirname, "..", "package.json"); + const serverJsonPath = join(__dirname, "..", "..", "server.json"); + const packageJsonPath = join(__dirname, "..", "..", "package.json"); const content = readFileSync(serverJsonPath, "utf-8"); const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as { version: string }; @@ -310,7 +308,7 @@ function generateReadmeConfigTable(argumentInfos: ArgumentInfo[]): string { } function updateReadmeConfigTable(envVars: ArgumentInfo[]): void { - const readmePath = join(__dirname, "..", "README.md"); + const readmePath = join(__dirname, "..", "..", "README.md"); let content = readFileSync(readmePath, "utf-8"); const newTable = generateReadmeConfigTable(envVars); @@ -325,15 +323,13 @@ function updateReadmeConfigTable(envVars: ArgumentInfo[]): void { console.log("āœ“ Updated README.md configuration table"); // Run prettier on the README.md file - execSync("npx prettier --write README.md", { cwd: join(__dirname, "..") }); + execSync("npx prettier --write README.md", { cwd: join(__dirname, "..", "..") }); } -function main(): void { +export function generateArguments(): void { const zodMetadata = extractZodDescriptions(); - const argumentInfo = getArgumentInfo(zodMetadata); updateServerJsonEnvVars(argumentInfo); updateReadmeConfigTable(argumentInfo); } -main(); diff --git a/scripts/generate/generateToolDocumentation.ts b/scripts/generate/generateToolDocumentation.ts new file mode 100644 index 00000000..a06b5b43 --- /dev/null +++ b/scripts/generate/generateToolDocumentation.ts @@ -0,0 +1,149 @@ +/** + * This script generates tool documentation and updates: + * - README.md tools list + * + * It uses the AllTools array from the tools module. + */ + +import { readFileSync, writeFileSync } from "fs"; +import { join, dirname } from "path"; +import { fileURLToPath } from "url"; +import { AllTools } from "../../src/tools/index.js"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +interface ToolInfo { + name: string; + description: string; + category: string; + operationType: string; +} + +const overrides: Record = { + connect: "Connect to a MongoDB instance", + "switch-connection": "Switch to a different MongoDB connection", +}; + +function extractToolInformation(): ToolInfo[] { + const tools: ToolInfo[] = []; + + for (const ToolClass of AllTools) { + // Create a minimal instance to access instance properties + // We need to provide dummy params since we only need name and description + const dummyParams = { + category: ToolClass.category, + operationType: ToolClass.operationType, + session: { + on: () => {}, + off: () => {}, + emit: () => false, + connectionManager: null, + } as never, + config: { + previewFeatures: [], + vectorSearchDimensions: 1024, + vectorSearchModel: "voyage-3-large", + readOnly: false, + disabledTools: [], + } as never, + telemetry: { + emitEvents: () => {}, + } as never, + elicitation: { + requestConfirmation: () => Promise.resolve(false), + } as never, + }; + + try { + const instance = new ToolClass(dummyParams); + // Access the protected description property + const description = + (instance as unknown as { description?: string }).description || "No description available"; + tools.push({ + name: instance.name, + description: overrides[instance.name] || description, + category: ToolClass.category, + operationType: ToolClass.operationType, + }); + } catch (error) { + console.error(`Error instantiating tool ${ToolClass.name}:`, error); + } + } + + // Sort by category first, then by name + return tools.sort((a, b) => { + if (a.category !== b.category) { + return a.category.localeCompare(b.category); + } + return a.name.localeCompare(b.name); + }); +} + +function generateReadmeToolsList(tools: ToolInfo[]): string { + const sections: string[] = []; + + // Group tools by category + const toolsByCategory: Record = {}; + for (const tool of tools) { + if (!toolsByCategory[tool.category]) { + toolsByCategory[tool.category] = []; + } + const categoryTools = toolsByCategory[tool.category]; + if (categoryTools) { + categoryTools.push(tool); + } + } + + // Generate sections for each category + const categoryTitles: Record = { + atlas: "MongoDB Atlas Tools", + "atlas-local": "MongoDB Atlas Local Tools", + mongodb: "MongoDB Database Tools", + }; + + const categoryOrder = ["atlas", "atlas-local", "mongodb"]; + + for (const category of categoryOrder) { + if (!toolsByCategory[category]) continue; + + sections.push(`#### ${categoryTitles[category]}\n`); + + for (const tool of toolsByCategory[category]) { + sections.push(`- \`${tool.name}\` - ${tool.description}`); + } + + // Add note for Atlas tools + if (category === "atlas") { + sections.push( + "\nNOTE: atlas tools are only available when you set credentials on [configuration](#configuration) section.\n" + ); + } else { + sections.push(""); + } + } + + return sections.join("\n"); +} + +function updateReadmeToolsList(tools: ToolInfo[]): void { + const readmePath = join(__dirname, "..", "..", "README.md"); + let content = readFileSync(readmePath, "utf-8"); + + const newToolsList = generateReadmeToolsList(tools); + + // Find and replace the tools list section + // Match from "### Tool List" to the next "## " section + const toolsRegex = /### Tool List\n\n([\s\S]*?)\n\n## šŸ“„ Supported Resources/; + const replacement = `### Tool List\n\n${newToolsList}\n## šŸ“„ Supported Resources`; + + content = content.replace(toolsRegex, replacement); + + writeFileSync(readmePath, content, "utf-8"); + console.log("āœ“ Updated README.md tools list"); +} + +export function generateToolDocumentation(): void { + const toolInfo = extractToolInformation(); + updateReadmeToolsList(toolInfo); +} diff --git a/scripts/generate/index.ts b/scripts/generate/index.ts new file mode 100644 index 00000000..054d3149 --- /dev/null +++ b/scripts/generate/index.ts @@ -0,0 +1,22 @@ +#!/usr/bin/env tsx + +/** + * Main script that generates all documentation and configuration files: + * - CLI arguments and configuration tables + * - Tool documentation + */ + +import { generateArguments } from "./generateArguments.js"; +import { generateToolDocumentation } from "./generateToolDocumentation.js"; + +function main(): void { + console.log("Generating arguments and configuration..."); + generateArguments(); + + console.log("\nGenerating tool documentation..."); + generateToolDocumentation(); + + console.log("\nāœ… All documentation generated successfully!"); +} + +main(); diff --git a/tsconfig.build.json b/tsconfig.build.json index 06089861..685f46ae 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -20,7 +20,8 @@ "declarationMap": true, "paths": { "mongodb-connection-string-url": [ - "./node_modules/mongodb-connection-string-url/lib/index.d.ts" + "./node_modules/mongodb-connection-string-url/lib/index.js", + "./node_modules/mongodb-connection-string-url/lib/index.d.js" ], "ts-levenshtein": ["./node_modules/ts-levenshtein/dist/index.d.mts"] } From e23b83a7ba06b1400ad60aff58c7233096deceb9 Mon Sep 17 00:00:00 2001 From: gagik Date: Fri, 12 Dec 2025 14:47:39 +0100 Subject: [PATCH 3/6] chore: use / --- README.md | 62 +++++++++++++-------------- scripts/generate/generateArguments.ts | 5 +-- tsconfig.build.json | 2 +- 3 files changed, 34 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index d89561c8..a9c896f1 100644 --- a/README.md +++ b/README.md @@ -350,37 +350,37 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow ### Configuration Options -| Option | Default | Description | -| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `MDB_MCP_ALLOW_REQUEST_OVERRIDES` or `--allowRequestOverrides` | `false` | When set to true, allows configuration values to be overridden via request headers and query parameters. | -| `MDB_MCP_API_CLIENT_ID` or `--apiClientId` | `` | Atlas API client ID for authentication. Required for running Atlas tools. | -| `MDB_MCP_API_CLIENT_SECRET` or `--apiClientSecret` | `` | Atlas API client secret for authentication. Required for running Atlas tools. | -| `MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS` or `--atlasTemporaryDatabaseUserLifetimeMs` | `14400000` | Time in milliseconds that temporary database users created when connecting to MongoDB Atlas clusters will remain active before being automatically deleted. | -| `MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` or `--confirmationRequiredTools` | `"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index"` | Comma separated values of tool names that require user confirmation before execution. Requires the client to support elicitation. | -| `MDB_MCP_CONNECTION_STRING` or `--connectionString` | `` | MongoDB connection string for direct database connections. Optional, if not set, you'll need to call the connect tool before interacting with MongoDB data. | -| `MDB_MCP_DISABLED_TOOLS` or `--disabledTools` | `""` | Comma separated values of tool names, operation types, and/or categories of tools that will be disabled. | -| `MDB_MCP_DRY_RUN` or `--dryRun` | `false` | When true, runs the server in dry mode: dumps configuration and enabled tools, then exits without starting the server. | -| `MDB_MCP_EMBEDDINGS_VALIDATION` or `--embeddingsValidation` | `true` | When set to false, disables validation of embeddings dimensions. | -| `MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` or `--exportCleanupIntervalMs` | `120000` | Time in milliseconds between export cleanup cycles that remove expired export files. | -| `MDB_MCP_EXPORT_TIMEOUT_MS` or `--exportTimeoutMs` | `300000` | Time in milliseconds after which an export is considered expired and eligible for cleanup. | -| `MDB_MCP_EXPORTS_PATH` or `--exportsPath` | see below\* | Folder to store exported data files. | -| `MDB_MCP_HTTP_HEADERS` or `--httpHeaders` | `"{}"` | Header that the HTTP server will validate when making requests (only used when transport is 'http'). | -| `MDB_MCP_HTTP_HOST` or `--httpHost` | `"127.0.0.1"` | Host address to bind the HTTP server to (only used when transport is 'http'). | -| `MDB_MCP_HTTP_PORT` or `--httpPort` | `3000` | Port number for the HTTP server (only used when transport is 'http'). Use 0 for a random port. | -| `MDB_MCP_IDLE_TIMEOUT_MS` or `--idleTimeoutMs` | `600000` | Idle timeout for a client to disconnect (only applies to http transport). | -| `MDB_MCP_INDEX_CHECK` or `--indexCheck` | `false` | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan. | -| `MDB_MCP_LOG_PATH` or `--logPath` | see below\* | Folder to store logs. | -| `MDB_MCP_LOGGERS` or `--loggers` | `"disk,mcp"` see below\* | Comma separated values of logger types. | -| `MDB_MCP_MAX_BYTES_PER_QUERY` or `--maxBytesPerQuery` | `16777216` | The maximum size in bytes for results from a find or aggregate tool call. This serves as an upper bound for the responseBytesLimit parameter in those tools. | -| `MDB_MCP_MAX_DOCUMENTS_PER_QUERY` or `--maxDocumentsPerQuery` | `100` | The maximum number of documents that can be returned by a find or aggregate tool call. For the find tool, the effective limit will be the smaller of this value and the tool's limit parameter. | -| `MDB_MCP_NOTIFICATION_TIMEOUT_MS` or `--notificationTimeoutMs` | `540000` | Notification timeout for a client to be aware of disconnect (only applies to http transport). | -| `MDB_MCP_PREVIEW_FEATURES` or `--previewFeatures` | `""` | Comma separated values of preview features that are enabled. | -| `MDB_MCP_READ_ONLY` or `--readOnly` | `false` | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations. | -| `MDB_MCP_TELEMETRY` or `--telemetry` | `"enabled"` | When set to disabled, disables telemetry collection. | -| `MDB_MCP_TRANSPORT` or `--transport` | `"stdio"` | Either 'stdio' or 'http'. | -| `MDB_MCP_VECTOR_SEARCH_DIMENSIONS` or `--vectorSearchDimensions` | `1024` | Default number of dimensions for vector search embeddings. | -| `MDB_MCP_VECTOR_SEARCH_SIMILARITY_FUNCTION` or `--vectorSearchSimilarityFunction` | `"euclidean"` | Default similarity function for vector search: 'euclidean', 'cosine', or 'dotProduct'. | -| `MDB_MCP_VOYAGE_API_KEY` or `--voyageApiKey` | `""` | API key for Voyage AI embeddings service (required for vector search operations with text-to-embedding conversion). | +| Environment Variable / CLI Option | Default | Description | +| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `MDB_MCP_ALLOW_REQUEST_OVERRIDES` / `--allowRequestOverrides` | `false` | When set to true, allows configuration values to be overridden via request headers and query parameters. | +| `MDB_MCP_API_CLIENT_ID` / `--apiClientId` | `` | Atlas API client ID for authentication. Required for running Atlas tools. | +| `MDB_MCP_API_CLIENT_SECRET` / `--apiClientSecret` | `` | Atlas API client secret for authentication. Required for running Atlas tools. | +| `MDB_MCP_ATLAS_TEMPORARY_DATABASE_USER_LIFETIME_MS` / `--atlasTemporaryDatabaseUserLifetimeMs` | `14400000` | Time in milliseconds that temporary database users created when connecting to MongoDB Atlas clusters will remain active before being automatically deleted. | +| `MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` / `--confirmationRequiredTools` | `"atlas-create-access-list,atlas-create-db-user,drop-database,drop-collection,delete-many,drop-index"` | Comma separated values of tool names that require user confirmation before execution. Requires the client to support elicitation. | +| `MDB_MCP_CONNECTION_STRING` / `--connectionString` | `` | MongoDB connection string for direct database connections. Optional, if not set, you'll need to call the connect tool before interacting with MongoDB data. | +| `MDB_MCP_DISABLED_TOOLS` / `--disabledTools` | `""` | Comma separated values of tool names, operation types, and/or categories of tools that will be disabled. | +| `MDB_MCP_DRY_RUN` / `--dryRun` | `false` | When true, runs the server in dry mode: dumps configuration and enabled tools, then exits without starting the server. | +| `MDB_MCP_EMBEDDINGS_VALIDATION` / `--embeddingsValidation` | `true` | When set to false, disables validation of embeddings dimensions. | +| `MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` / `--exportCleanupIntervalMs` | `120000` | Time in milliseconds between export cleanup cycles that remove expired export files. | +| `MDB_MCP_EXPORT_TIMEOUT_MS` / `--exportTimeoutMs` | `300000` | Time in milliseconds after which an export is considered expired and eligible for cleanup. | +| `MDB_MCP_EXPORTS_PATH` / `--exportsPath` | see below\* | Folder to store exported data files. | +| `MDB_MCP_HTTP_HEADERS` / `--httpHeaders` | `"{}"` | Header that the HTTP server will validate when making requests (only used when transport is 'http'). | +| `MDB_MCP_HTTP_HOST` / `--httpHost` | `"127.0.0.1"` | Host address to bind the HTTP server to (only used when transport is 'http'). | +| `MDB_MCP_HTTP_PORT` / `--httpPort` | `3000` | Port number for the HTTP server (only used when transport is 'http'). Use 0 for a random port. | +| `MDB_MCP_IDLE_TIMEOUT_MS` / `--idleTimeoutMs` | `600000` | Idle timeout for a client to disconnect (only applies to http transport). | +| `MDB_MCP_INDEX_CHECK` / `--indexCheck` | `false` | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan. | +| `MDB_MCP_LOG_PATH` / `--logPath` | see below\* | Folder to store logs. | +| `MDB_MCP_LOGGERS` / `--loggers` | `"disk,mcp"` see below\* | Comma separated values of logger types. | +| `MDB_MCP_MAX_BYTES_PER_QUERY` / `--maxBytesPerQuery` | `16777216` | The maximum size in bytes for results from a find or aggregate tool call. This serves as an upper bound for the responseBytesLimit parameter in those tools. | +| `MDB_MCP_MAX_DOCUMENTS_PER_QUERY` / `--maxDocumentsPerQuery` | `100` | The maximum number of documents that can be returned by a find or aggregate tool call. For the find tool, the effective limit will be the smaller of this value and the tool's limit parameter. | +| `MDB_MCP_NOTIFICATION_TIMEOUT_MS` / `--notificationTimeoutMs` | `540000` | Notification timeout for a client to be aware of disconnect (only applies to http transport). | +| `MDB_MCP_PREVIEW_FEATURES` / `--previewFeatures` | `""` | Comma separated values of preview features that are enabled. | +| `MDB_MCP_READ_ONLY` / `--readOnly` | `false` | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations. | +| `MDB_MCP_TELEMETRY` / `--telemetry` | `"enabled"` | When set to disabled, disables telemetry collection. | +| `MDB_MCP_TRANSPORT` / `--transport` | `"stdio"` | Either 'stdio' or 'http'. | +| `MDB_MCP_VECTOR_SEARCH_DIMENSIONS` / `--vectorSearchDimensions` | `1024` | Default number of dimensions for vector search embeddings. | +| `MDB_MCP_VECTOR_SEARCH_SIMILARITY_FUNCTION` / `--vectorSearchSimilarityFunction` | `"euclidean"` | Default similarity function for vector search: 'euclidean', 'cosine', or 'dotProduct'. | +| `MDB_MCP_VOYAGE_API_KEY` / `--voyageApiKey` | `""` | API key for Voyage AI embeddings service (required for vector search operations with text-to-embedding conversion). | #### Logger Options diff --git a/scripts/generate/generateArguments.ts b/scripts/generate/generateArguments.ts index ff60c97a..ffd6f0a3 100644 --- a/scripts/generate/generateArguments.ts +++ b/scripts/generate/generateArguments.ts @@ -260,7 +260,7 @@ function updateServerJsonEnvVars(envVars: ArgumentInfo[]): void { function generateReadmeConfigTable(argumentInfos: ArgumentInfo[]): string { const rows = [ - "| Option | Default | Description |", + "| Environment Variable / CLI Option | Default | Description |", "| -------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |", ]; @@ -300,7 +300,7 @@ function generateReadmeConfigTable(argumentInfos: ArgumentInfo[]): string { const desc = argumentInfo.description.replace(/\|/g, "\\|"); // Escape pipes in description rows.push( - `| ${`${envVarName} or ${cliOption}`.padEnd(89)} | ${defaultValueString.padEnd(75)} | ${desc.padEnd(199)} |` + `| ${`${envVarName} / ${cliOption}`.padEnd(89)} | ${defaultValueString.padEnd(75)} | ${desc.padEnd(199)} |` ); } @@ -332,4 +332,3 @@ export function generateArguments(): void { updateServerJsonEnvVars(argumentInfo); updateReadmeConfigTable(argumentInfo); } - diff --git a/tsconfig.build.json b/tsconfig.build.json index 685f46ae..407e21f2 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -21,7 +21,7 @@ "paths": { "mongodb-connection-string-url": [ "./node_modules/mongodb-connection-string-url/lib/index.js", - "./node_modules/mongodb-connection-string-url/lib/index.d.js" + "./node_modules/mongodb-connection-string-url/lib/index.d.ts" ], "ts-levenshtein": ["./node_modules/ts-levenshtein/dist/index.d.mts"] } From d1ff8f3e79763add834d15cdd57429e3369263d4 Mon Sep 17 00:00:00 2001 From: gagik Date: Fri, 12 Dec 2025 14:50:39 +0100 Subject: [PATCH 4/6] chore: remove type setting --- tsconfig.build.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/tsconfig.build.json b/tsconfig.build.json index 407e21f2..7d26a473 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -19,10 +19,6 @@ "declaration": true, "declarationMap": true, "paths": { - "mongodb-connection-string-url": [ - "./node_modules/mongodb-connection-string-url/lib/index.js", - "./node_modules/mongodb-connection-string-url/lib/index.d.ts" - ], "ts-levenshtein": ["./node_modules/ts-levenshtein/dist/index.d.mts"] } }, From 26b7b5123a1c81f22c97820c4ed67ecbb2143158 Mon Sep 17 00:00:00 2001 From: gagik Date: Fri, 12 Dec 2025 15:11:56 +0100 Subject: [PATCH 5/6] chore: fixup script issues --- package.json | 2 +- scripts/generate/index.ts | 14 +++++--------- scripts/generate/tsconfig.json | 11 +++++++++++ tsconfig.build.json | 5 ++++- tsconfig.test.json | 8 -------- 5 files changed, 21 insertions(+), 19 deletions(-) create mode 100644 scripts/generate/tsconfig.json delete mode 100644 tsconfig.test.json diff --git a/package.json b/package.json index c0e49274..e31de41a 100644 --- a/package.json +++ b/package.json @@ -65,7 +65,7 @@ "reformat": "prettier --write .", "generate": "pnpm run generate:api && pnpm run generate:arguments", "generate:api": "./scripts/generate.sh", - "generate:arguments": "tsx scripts/generate/index.ts", + "generate:arguments": "tsx --tsconfig scripts/generate/tsconfig.json scripts/generate/index.ts", "pretest": "pnpm run build", "test": "vitest --project eslint-rules --project unit-and-integration --coverage --run", "test:accuracy": "sh ./scripts/accuracy/runAccuracyTests.sh", diff --git a/scripts/generate/index.ts b/scripts/generate/index.ts index 054d3149..505dc629 100644 --- a/scripts/generate/index.ts +++ b/scripts/generate/index.ts @@ -9,14 +9,10 @@ import { generateArguments } from "./generateArguments.js"; import { generateToolDocumentation } from "./generateToolDocumentation.js"; -function main(): void { - console.log("Generating arguments and configuration..."); - generateArguments(); +console.log("Generating arguments and configuration..."); +generateArguments(); - console.log("\nGenerating tool documentation..."); - generateToolDocumentation(); +console.log("\nGenerating tool documentation..."); +generateToolDocumentation(); - console.log("\nāœ… All documentation generated successfully!"); -} - -main(); +console.log("\nāœ… All documentation generated successfully!"); diff --git a/scripts/generate/tsconfig.json b/scripts/generate/tsconfig.json new file mode 100644 index 00000000..f4b83377 --- /dev/null +++ b/scripts/generate/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../tsconfig.build.json", + "compilerOptions": { + "rootDir": ".", + "noEmit": true, + "paths": { + "ts-levenshtein": ["../node_modules/ts-levenshtein/dist/index.d.mts"] + } + }, + "include": ["**/*.ts"] +} diff --git a/tsconfig.build.json b/tsconfig.build.json index 7d26a473..b4cfc778 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -19,7 +19,10 @@ "declaration": true, "declarationMap": true, "paths": { - "ts-levenshtein": ["./node_modules/ts-levenshtein/dist/index.d.mts"] + "ts-levenshtein": ["./node_modules/ts-levenshtein/dist/index.d.mts"], + "mongodb-connection-string-url": [ + "./node_modules/mongodb-connection-string-url/lib/index.d.ts" + ] } }, "include": ["src/**/*.ts"] diff --git a/tsconfig.test.json b/tsconfig.test.json deleted file mode 100644 index 388094c3..00000000 --- a/tsconfig.test.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "extends": "./tsconfig.build.json", - "compilerOptions": { - "isolatedModules": true, - "allowSyntheticDefaultImports": true - }, - "include": ["src/**/*.ts", "tests/**/*.ts"] -} From df1be813de3a07a88babfb88f0c4018954e4a574 Mon Sep 17 00:00:00 2001 From: gagik Date: Fri, 12 Dec 2025 15:14:31 +0100 Subject: [PATCH 6/6] chore: format --- scripts/generate/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/generate/README.md b/scripts/generate/README.md index e7b13c75..1eb43386 100644 --- a/scripts/generate/README.md +++ b/scripts/generate/README.md @@ -14,4 +14,4 @@ Run all generators: ```bash pnpm run generate:arguments -``` \ No newline at end of file +```