MongoDB MCP Server

Instructions

Implementation Reference

• src/tools/mongodb/read/export.ts:11-131 (handler)

  The ExportTool class implements the "export" tool. It defines the tool name, description, input schema (argsShape), and the execute method that creates a MongoDB cursor (find or aggregate) and uses exportsManager to export results as JSON, returning resource links.

  export class ExportTool extends MongoDBToolBase {
      public name = "export";
      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."),
          exportTarget: z
              .array(
                  z.discriminatedUnion("name", [
                      z.object({
                          name: z
                              .literal("find")
                              .describe("The literal name 'find' to represent a find cursor as target."),
                          arguments: z
                              .object({
                                  ...FindArgs,
                                  limit: FindArgs.limit.removeDefault(),
                              })
                              .describe("The arguments for 'find' operation."),
                      }),
                      z.object({
                          name: z
                              .literal("aggregate")
                              .describe("The literal name 'aggregate' to represent an aggregation cursor as target."),
                          arguments: z
                              .object(getAggregateArgs(this.isFeatureEnabled("search")))
                              .describe("The arguments for 'aggregate' operation."),
                      }),
                  ])
              )
              .describe("The export target along with its arguments."),
          jsonExportFormat: jsonExportFormat
              .default("relaxed")
              .describe(
                  [
                      "The format to be used when exporting collection data as EJSON with default being relaxed.",
                      "relaxed: A string format that emphasizes readability and interoperability at the expense of type preservation. That is, conversion from relaxed format to BSON can lose type information.",
                      "canonical: A string format that emphasizes type preservation at the expense of readability and interoperability. That is, conversion from canonical to BSON will generally preserve type information except in certain specific cases.",
                  ].join("\n")
              ),
      };
      static operationType: OperationType = "read";
  
      protected async execute({
          database,
          collection,
          jsonExportFormat,
          exportTitle,
          exportTarget: target,
      }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
          const provider = await this.ensureConnected();
          const exportTarget = target[0];
          if (!exportTarget) {
              throw new Error("Export target not provided. Expected one of the following: `aggregate`, `find`");
          }
  
          let cursor: FindCursor | AggregationCursor;
          if (exportTarget.name === "find") {
              const { filter, projection, sort, limit } = exportTarget.arguments;
              cursor = provider.find(database, collection, filter ?? {}, {
                  projection,
                  sort,
                  limit,
                  promoteValues: false,
                  bsonRegExp: true,
              });
          } else {
              const { pipeline } = exportTarget.arguments;
              cursor = provider.aggregate(database, collection, pipeline, {
                  promoteValues: false,
                  bsonRegExp: true,
                  allowDiskUse: true,
              });
          }
  
          const exportName = `${new ObjectId().toString()}.json`;
  
          const { exportURI, exportPath } = await this.session.exportsManager.createJSONExport({
              input: cursor,
              exportName,
              exportTitle:
                  exportTitle ||
                  `Export for namespace ${database}.${collection} requested on ${new Date().toLocaleString()}`,
              jsonExportFormat,
          });
          const toolCallContent: CallToolResult["content"] = [
              // Not all the clients as of this commit understands how to
              // parse a resource_link so we provide a text result for them to
              // understand what to do with the result.
              {
                  type: "text",
                  text: `Data for namespace ${database}.${collection} is being exported and will be made available under resource URI - "${exportURI}".`,
              },
              {
                  type: "resource_link",
                  name: exportName,
                  uri: exportURI,
                  description: "Resource URI for fetching exported data once it is ready.",
                  mimeType: "application/json",
              },
          ];
  
          // This special case is to make it easier to work with exported data for
          // clients that still cannot reference resources (Cursor).
          // More information here: https://jira.mongodb.org/browse/MCP-104
          if (this.isServerRunningLocally()) {
              toolCallContent.push({
                  type: "text",
                  text: `Optionally, when the export is finished, the exported data can also be accessed under path - "${exportPath}"`,
              });
          }
  
          return {
              content: toolCallContent,
          };
      }
  
      private isServerRunningLocally(): boolean {
          return this.config.transport === "stdio" || ["127.0.0.1", "localhost"].includes(this.config.httpHost);
      }
  }

• src/tools/mongodb/read/export.ts:14-51 (schema)

  Input schema definition (argsShape) for the export tool, including database/collection, exportTitle, exportTarget (find or aggregate args), and jsonExportFormat.

  protected argsShape = {
      ...DbOperationArgs,
      exportTitle: z.string().describe("A short description to uniquely identify the export."),
      exportTarget: z
          .array(
              z.discriminatedUnion("name", [
                  z.object({
                      name: z
                          .literal("find")
                          .describe("The literal name 'find' to represent a find cursor as target."),
                      arguments: z
                          .object({
                              ...FindArgs,
                              limit: FindArgs.limit.removeDefault(),
                          })
                          .describe("The arguments for 'find' operation."),
                  }),
                  z.object({
                      name: z
                          .literal("aggregate")
                          .describe("The literal name 'aggregate' to represent an aggregation cursor as target."),
                      arguments: z
                          .object(getAggregateArgs(this.isFeatureEnabled("search")))
                          .describe("The arguments for 'aggregate' operation."),
                  }),
              ])
          )
          .describe("The export target along with its arguments."),
      jsonExportFormat: jsonExportFormat
          .default("relaxed")
          .describe(
              [
                  "The format to be used when exporting collection data as EJSON with default being relaxed.",
                  "relaxed: A string format that emphasizes readability and interoperability at the expense of type preservation. That is, conversion from relaxed format to BSON can lose type information.",
                  "canonical: A string format that emphasizes type preservation at the expense of readability and interoperability. That is, conversion from canonical to BSON will generally preserve type information except in certain specific cases.",
              ].join("\n")
          ),
  };

• src/tools/mongodb/tools.ts:21-21 (registration)

  Re-export of the ExportTool class for inclusion in the MongoDB tools module.

  export { ExportTool } from "./read/export.js";

• src/tools/index.ts:3-11 (registration)

  Import of MongoDB tools (including export) and inclusion in AllTools array, which is used by the server to register all tools dynamically via ToolBase.register().

  import * as MongoDbTools from "./mongodb/tools.js";
  import type { ToolClass } from "./tool.js";
  
  // Export the collection of tools for easier reference
  export const AllTools: ToolClass[] = Object.values({
      ...MongoDbTools,
      ...AtlasTools,
      ...AtlasLocalTools,
  });

• src/common/exportsManager.ts:157-196 (helper)

  ExportsManager.createJSONExport method called by the export tool handler to asynchronously generate the JSON export file from the MongoDB cursor and provide URI/path for access.

  public async createJSONExport({
      input,
      exportName,
      exportTitle,
      jsonExportFormat,
  }: {
      input: FindCursor | AggregationCursor;
      exportName: string;
      exportTitle: string;
      jsonExportFormat: JSONExportFormat;
  }): Promise<AvailableExport> {
      try {
          this.assertIsNotShuttingDown();
          const exportNameWithExtension = decodeAndNormalize(ensureExtension(exportName, "json"));
          if (this.storedExports[exportNameWithExtension]) {
              return Promise.reject(
                  new Error("Export with same name is either already available or being generated.")
              );
          }
          const exportURI = `exported-data://${encodeURIComponent(exportNameWithExtension)}`;
          const exportFilePath = path.join(this.exportsDirectoryPath, exportNameWithExtension);
          const inProgressExport: InProgressExport = (this.storedExports[exportNameWithExtension] = {
              exportName: exportNameWithExtension,
              exportTitle,
              exportPath: exportFilePath,
              exportURI: exportURI,
              exportStatus: "in-progress",
          });
  
          void this.startExport({ input, jsonExportFormat, inProgressExport });
          return Promise.resolve(inProgressExport);
      } catch (error) {
          this.logger.error({
              id: LogId.exportCreationError,
              context: "Error when registering JSON export request",
              message: error instanceof Error ? error.message : String(error),
          });
          throw error;
      }
  }