diff --git a/README.md b/README.md index a556f65b3..d508b755d 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ A Model Context Protocol server for interacting with MongoDB Databases and Mongo - [🛠️ Supported Tools](#supported-tools) - [MongoDB Atlas Tools](#mongodb-atlas-tools) - [MongoDB Database Tools](#mongodb-database-tools) +- [📄 Supported Resources](#supported-resources) - [⚙️ Configuration](#configuration) - [Configuration Options](#configuration-options) - [Atlas API Access](#atlas-api-access) @@ -305,6 +306,13 @@ NOTE: atlas tools are only available when you set credentials on [configuration] - `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. + +## 📄 Supported Resources + +- `config` - Server configuration, supplied by the user either as environment variables or as startup arguments with sensitive parameters redacted. The resource can be accessed under URI `config://config`. +- `debug` - Debugging information for MongoDB connectivity issues. Tracks the last connectivity attempt and error information. The resource can be accessed under URI `debug://mongodb`. +- `exported-data` - A resource template to access the data exported using the export tool. The template can be accessed under URI `exported-data://{exportName}` where `exportName` is the unique name for an export generated by the export tool. ## Configuration @@ -315,22 +323,25 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow ### Configuration Options -| CLI Option | Environment Variable | Default | Description | -| ----------------------- | --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. | -| `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. | -| `loggers` | `MDB_MCP_LOGGERS` | disk,mcp | Comma separated values, possible values are `mcp`, `disk` and `stderr`. See [Logger Options](#logger-options) for details. | -| `logPath` | `MDB_MCP_LOG_PATH` | see note\* | Folder to store logs. | -| `disabledTools` | `MDB_MCP_DISABLED_TOOLS` | | An array of tool names, operation types, and/or categories of tools that will be disabled. | -| `readOnly` | `MDB_MCP_READ_ONLY` | false | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations. | -| `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. | -| `telemetry` | `MDB_MCP_TELEMETRY` | enabled | When set to disabled, disables telemetry collection. | -| `transport` | `MDB_MCP_TRANSPORT` | stdio | Either 'stdio' or 'http'. | -| `httpPort` | `MDB_MCP_HTTP_PORT` | 3000 | Port number. | -| `httpHost` | `MDB_MCP_HTTP_HOST` | 127.0.0.1 | Host to bind the http server. | -| `idleTimeoutMs` | `MDB_MCP_IDLE_TIMEOUT_MS` | 600000 | Idle timeout for a client to disconnect (only applies to http transport). | -| `notificationTimeoutMs` | `MDB_MCP_NOTIFICATION_TIMEOUT_MS` | 540000 | Notification timeout for a client to be aware of diconnect (only applies to http transport). | +| CLI Option | Environment Variable | Default | Description | +| ------------------------- | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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. | +| `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. | +| `loggers` | `MDB_MCP_LOGGERS` | disk,mcp | Comma separated values, possible values are `mcp`, `disk` and `stderr`. See [Logger Options](#logger-options) for details. | +| `logPath` | `MDB_MCP_LOG_PATH` | see note\* | Folder to store logs. | +| `disabledTools` | `MDB_MCP_DISABLED_TOOLS` | | An array of tool names, operation types, and/or categories of tools that will be disabled. | +| `readOnly` | `MDB_MCP_READ_ONLY` | false | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations. | +| `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. | +| `telemetry` | `MDB_MCP_TELEMETRY` | enabled | When set to disabled, disables telemetry collection. | +| `transport` | `MDB_MCP_TRANSPORT` | stdio | Either 'stdio' or 'http'. | +| `httpPort` | `MDB_MCP_HTTP_PORT` | 3000 | Port number. | +| `httpHost` | `MDB_MCP_HTTP_HOST` | 127.0.0.1 | Host to bind the http server. | +| `idleTimeoutMs` | `MDB_MCP_IDLE_TIMEOUT_MS` | 600000 | Idle timeout for a client to disconnect (only applies to http transport). | +| `notificationTimeoutMs` | `MDB_MCP_NOTIFICATION_TIMEOUT_MS` | 540000 | Notification timeout for a client to be aware of diconnect (only applies to http transport). | +| `exportsPath` | `MDB_MCP_EXPORTS_PATH` | see note\* | Folder to store exported data files. | +| `exportTimeoutMs` | `MDB_MCP_EXPORT_TIMEOUT_MS` | 300000 | Time in milliseconds after which an export is considered expired and eligible for cleanup. | +| `exportCleanupIntervalMs` | `MDB_MCP_EXPORT_CLEANUP_INTERVAL_MS` | 120000 | Time in milliseconds between export cleanup cycles that remove expired export files. | #### Logger Options @@ -415,6 +426,17 @@ You can enable index check mode using: When index check mode is active, you'll see an error message if a query is rejected due to not using an index. +#### Exports + +The data exported by the `export` tool is temporarily stored in the configured `exportsPath` on the machine running the MCP server until cleaned up by the export cleanup process. If the `exportsPath` configuration is not provided, the following defaults are used: + +- **Windows:** `%LOCALAPPDATA%\mongodb\mongodb-mcp\exports` +- **macOS/Linux:** `~/.mongodb/mongodb-mcp/exports` + +The `exportTimeoutMs` configuration controls the time after which the exported data is considered expired and eligible for cleanup. By default, exports expire after 5 minutes (300000ms). + +The `exportCleanupIntervalMs` configuration controls how frequently the cleanup process runs to remove expired export files. By default, cleanup runs every 2 minutes (120000ms). + #### Telemetry The `telemetry` configuration option allows you to disable telemetry collection. When enabled, the MCP server will collect usage data and send it to MongoDB. diff --git a/src/resources/common/debug.ts b/src/resources/common/debug.ts index 40be3fc08..c159ebaa9 100644 --- a/src/resources/common/debug.ts +++ b/src/resources/common/debug.ts @@ -21,7 +21,7 @@ export class DebugResource extends ReactiveResource< uri: "debug://mongodb", config: { description: - "Debugging information for MongoDB connectivity issues. Tracks the last connectivity error and attempt information.", + "Debugging information for MongoDB connectivity issues. Tracks the last connectivity attempt and error information.", }, }, options: { diff --git a/src/tools/mongodb/read/export.ts b/src/tools/mongodb/read/export.ts index 2a6097c8e..fabb12eea 100644 --- a/src/tools/mongodb/read/export.ts +++ b/src/tools/mongodb/read/export.ts @@ -10,7 +10,7 @@ import { AggregateArgs } from "./aggregate.js"; export class ExportTool extends MongoDBToolBase { public name = "export"; - protected description = "Export a collection data or query results in the specified EJSON format."; + protected description = "Export a query or aggregation results in the specified EJSON format."; protected argsShape = { ...DbOperationArgs, exportTitle: z.string().describe("A short description to uniquely identify the export."), diff --git a/tests/integration/tools/mongodb/read/export.test.ts b/tests/integration/tools/mongodb/read/export.test.ts index f02460f01..41f627f30 100644 --- a/tests/integration/tools/mongodb/read/export.test.ts +++ b/tests/integration/tools/mongodb/read/export.test.ts @@ -53,7 +53,7 @@ describeWithMongoDB( validateToolMetadata( integration, "export", - "Export a collection data or query results in the specified EJSON format.", + "Export a query or aggregation results in the specified EJSON format.", [ ...databaseCollectionParameters, {